Skip to main content

App Deployment

What is a Flowable App?​

A Flowable App is a packaged deployment unit (essentially a ZIP archive) that contains a collection of related models and resources for the Flowable platform. These models can include BPMN process definitions, CMMN case models, DMN decision tables, form models, service configurations, document templates and many other assets needed for a Flowable business application (also known as FlowApp). All models that logically belong together are grouped into an app, making it easier to manage and deploy as a single artifact. When such a FlowApp is deployed to the Flowable Runtime (e.g. Flowable Work), the contained models become available as definitions that can be executed (for example, a BPMN model becomes a process definition that users can start instances of).

In Flowable Design (the modeling environment), apps are the primary containers for organizing models. An app can be exported as a ZIP file (sometimes also called a business archive or bar file), which can be imported into other Flowable Design environments or used for deployment.

Flowable provides a seamless way to deploy an app directly from Flowable Design to Flowable Work: by using the Publish button in Flowable Design, the app is directly deployed to the configured Flowable Work server via REST API. This means modelers can design an app and publish it with one click, without manual exporting importing. Under the hood, Flowable Design is configured with the REST endpoint of Flowable Work to perform this deployment operation. This fast publish mechanism allows for fast cycle of model development in Flowable Design and model verification in Flowable Work.

Additionally, FlowApps provide version consistency by making sure that models within an app reference versions of other models that were deployed in the same app version (same deployment). That way, for example a task in a process by default uses the version of the form definition that was deployed together with the definition of the process when the process instance was created, even if newer versions of the same form were deployed later.

note

More information on model versioning can be found in the Modeler Documentation.

Deployment Approaches​

When planning to deploy a Flowable App to the Flowable Work platform (or an embedded Flowable Work), there are two primary approaches to consider:

  1. Classpath Deployment (Auto-Deployment at Startup): Package the app (or its model files) with the application’s code so that the Flowable engine deploys it on startup by scanning the classpath. This ties the app deployment to your Java application lifecycle.
  2. REST API Deployment (Runtime Deployment): Deploy the app at runtime by calling Flowable’s REST API to upload the app package. This decouples the app’s lifecycle from the application startup, allowing on-demand deployments to a running Flowable server.

Each approach has its use cases, advantages, and trade-offs, which are discussed below.

Classpath Deployment (Auto-Deployment)​

In the classpath deployment model, the app archive is placed on the Java application's classpath so that Flowable will discover and deploy it automatically during application startup. Flowable Work (and the Flowable engines in general) has an auto-deployment feature that scans specific classpath locations for process definitions, case models, decision tables, and app packages. For apps, by default Flowable will look into certain folders on the classpath (such as the /apps/ directory or other configured paths) and automatically deploy any .zip or .bar app files found there. This happens when the Flowable engine initializes. In effect, the application code and the Flowable app models are bundled together - when your application (or Flowable Work server) starts up, it will load and deploy the app if it hasn't been deployed before.

Advantages:

  • Versioned with Application Code: This approach ensures that the models are deployed in lockstep with the backend application code. The models live alongside the source code and can be managed in the same version control repository. This is often considered a good practice for traceability – the models that go to production are versioned and released together with the corresponding code (e.g. any Java delegates or services), ensuring consistency across environments.
  • Single Artifact Management: All business logic (Java code, if any) and Flowable models are packaged in one deployment artifact. This simplifies deployment management since you deploy one combined application. It also means developers can treat the models as part of the application’s source, benefiting from the same CI/CD pipeline.

Disadvantages:

  • Shared Lifecycle with Backend: The app’s lifecycle is tied to the lifecycle of the containing application. You cannot deploy, update, or roll back the business apps independently of the core application. This tight coupling can reduce flexibility when business logic needs to change more frequently than the code. Having multiple apps is possible, but all apps need to be deployed together. That can be challenging when multiple apps are developed in parallel that should be promoted through the environments up to production with different release cycles.
  • Requires Application Restart for Updates: Because auto-deployment is performed at startup time, any new or updated app placed on the classpath will only take effect upon restarting the application/server. In other words, deploying a new version of an app in this manner typically means rolling out a new version of the entire application. Additionally, if the app includes usage of new Java delegates or service tasks, those classes must be present on the classpath at runtime, necessitating a redeploy of the codebase anyway.
note

More Information on classpath deployments can be found in the auto deployment documentation

REST API Deployment (Runtime Deployment)​

In the REST deployment model, a FlowApp is deployed to a running Flowable Work instance via HTTP REST calls, without requiring a restart. Flowable Work’s REST API includes endpoints to manage app deployments. Using a REST call, you can upload an app ZIP file to the engine, which will then deploy the models contained in that package on-the-fly. Flowable Work provides the endpoint

POST /app-api/app-repository/deployments

to create a new app deployment (Endpoint documentation). This endpoint expects a multipart file upload (the app .zip) and will deploy the uploaded app into the system. The Publish function in Flowable Design uses this same REST API under the hood to push apps to Flowable Work. In practice, you can call this yourself using an HTTP client or a script. The user performing the call must have administrator privileges to deploy applications on the server.

Advantages:

  • Decoupled from Application Code: Deploying via REST keeps the model lifecycle independent of the application’s deployment cycle. You can update process models, case definitions, forms, etc. without redeploying or touching the underlying Java application. This decoupling is beneficial when business processes change frequently or independently of code releases. Each app can be managed on its own schedule (versioning, promotion between environments, rollback if needed) without forcing a service restart.
  • Independent App Lifecycle: Since each app is deployed individually, you can have separate versioning and lifecycle for each app. One app can be updated to a new version while others remain unchanged on the same server. It also means a failure in deploying one app (due to a model error, for example) doesn’t affect the deployment of the core application (which is already running).
  • Live Deployments with No Downtime: New apps or updates to existing apps can be applied to a running Flowable Work instance without restarting services. The engine immediately makes the new definitions available to users. This facilitates continuous delivery of model changes. For example, you might automate deployments so that whenever a modeler creates a new revision of an app, a CI/CD pipeline calls the Flowable REST API to deploy it to a dev or test environment.
note

It is possible to hook into the creation of a new FlowApp revision by listening to the PackageRevisionCreatedEvent event in Flowable Design. This could for example be used to trigger your own pipeline logic on revision creation. More information on this can be found in the Design Customizations section.

Disadvantages:

  • Need for Deployment Tooling: Using the REST API for deployments introduces the need for external tooling or scripts. Organizations typically need to set up automation (scripts, CI/CD jobs, or custom utilities) that retrieve the FlowApp ZIP files and invoke the REST endpoint. Unlike the classpath method (which deploys automatically on startup), the responsibility is on the deployment pipeline to push the app at the right time. This adds complexity to release management – for example, you must handle authentication, versioning of the app artifact, and potentially logging or error handling for the deployment calls.
  • Version Compatibility Management: When deploying apps independently, it’s important to ensure that the app artifact is compatible with the Flowable Work version. Flowable’s model definitions can evolve with new product versions, so an app exported from a newer Flowable Design might not work on an older Flowable Work runtime. (Flowable generally recommends that apps be deployed on the same or newer version of the engine that understands those models. This means that the responsibility lies with the development/DevOps team to coordinate Flowable platform upgrades with app releases. In practice, this is usually straightforward (e.g., using matching versioned Design and Work), but it requires awareness. Before deploying via REST, you may need to validate that the Flowable Work instance supports all the elements used in the models. That also is relevant for any custom services, e.g. if an app is using a Spring bean in an expression you need to verify that that service is available in the correct version in the back-end. In summary, the app and engine lifecycles are separate, so you must manage their compatibility - whereas in the classpath approach, the models are part of the application build which usually targets a specific engine version.

Further Customization​

Under the hood, both approaches utilize the Flowable Java API to deploy an app to the Flowable engines. That API (e.g. CoreAppRepositoryService) can also be used directly to deploy with your own deployment mechanism.