Skip to main content

Installation Options

This section provides information about additional installation options for Flowable and its components.

Development Environment Setup​

To develop customizations or extensions to Flowable, the following are some guidelines on creating a development environment.

Using JMS​

Chat capabilities Only

The Flowable application uses JMS to communicate with the adapters that are responsible for communicating with the third party external systems (e.g., WhatsApp, WeChat, LINE, etc.).

note

Flowable listens to the defined queues only if the appropriate external system dependency is present.

Queues​

These are the queues that the Flowable Application is subscribed to:

Flowable Queues​
Third Party SystemPropertyDefault Value
WhatsAppflowable.external-system.whatsapp.inbound-payloadwhatsapp-inbound-payload
WhatsAppflowable.external-system.whatsapp.inboundwhatsapp-inbound
WhatsAppflowable.external-system.whatsapp.inbound-statuswhatsapp-inbound-status
WhatsAppflowable.external-system.whatsapp.inbound-errorwhatsapp-inbound-error
WeChatflowable.external-system.wechat.inboundwechat-inbound
WeChatflowable.external-system.wechat.inbound-statuswechat-inbound-status
WeChatflowable.external-system.wechat.inbound-errorwechat-inbound-error
WeChatflowable.external-system.wechat.get-access-tokenwechat-get-access-token
WeChatflowable.external-system.wechat.store-access-tokenwechat-store-access-token
LINEflowable.external-system.line.inbound-payloadline-inbound-payload
LINEflowable.external-system.line.inboundline-inbound
LINEflowable.external-system.line.inbound-statusline-inbound-status
LINEflowable.external-system.line.inbound-errorline-inbound-error
Flowable WhatsApp Adapter Queues​
PropertyDefault Value
flowable.adapter.whatsapp.jms.outboundwhatsapp-outbound
Flowable WeChat Adapter Queues​
PropertyDefault Value
flowable.adapter.wechat.jms.outboundwechat-outbound
Flowable LINE Adapter Queues​
PropertyDefault Value
flowable.adapter.line.jms.outboundline-outbound

These are the JMS queues (and properties) that the Flowable applications are sending to:

Flowable destination queues​
Third Party systemPropertyDefault Value
WhatsAppflowable.external-system.whatsapp.outboundwhatsapp-outbound
WeChatflowable.external-system.wechat.outboundwechat-inbound
LINEflowable.external-system.line.outboundline-inbound
Flowable WhatsApp Adapter destination queues​
PropertyDefault Value
flowable.adapter.whatsapp.jms.inbound-payload-destinationwhatsapp-inbound-payload
flowable.adapter.whatsapp.jms.inbound-message-destinationwhatsapp-inbound
flowable.adapter.whatsapp.jms.inbound-status-destinationwhatsapp-inbound-status
flowable.adapter.whatsapp.jms.inbound-error-destinationwhatsapp-inbound-error
Flowable WeChat Adapter destination queues​
PropertyDefault Value
flowable.adapter.wechat.jms.inbound-message-destinationwechat-inbound
flowable.adapter.wechat.jms.inbound-status-destinationwechat-inbound-status
flowable.adapter.wechat.jms.inbound-error-destinationwechat-inbound-error
flowable.adapter.wechat.jms.inbound-get-access-token-destinationwechat-get-access-token
flowable.adapter.wechat.jms.inbound-store-access-token-destinationwechat-store-access-token
Flowable LINE Adapter destination queues​
PropertyDefault Value
flowable.adapter.line.jms.inbound-payload-destinationline-inbound-payload
flowable.adapter.line.jms.inbound-message-destinationline-inbound
flowable.adapter.line.jms.inbound-status-destinationline-inbound-status
flowable.adapter.line.jms.inbound-error-destinationline-inbound-error

IBM MQ​

Flowable provides out of the box support for using the IBM MQ client. In order to use the IBM client you need to add the following dependency:

<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-spring-boot-starter-ibm-mq</artifactId>
    <version>${com.flowable.platform.version}</version>
</dependency>

This dependency pulls in the needed transitive dependencies for communicating with IBM MQ.

important

When using IBM MQ the values for the queues should be changed. The reason for the changes is that IBM MQ does not support the use of the "-" character in the name of the queue.

Default Configuration​

The selected default options have been set in order to match the IBM MQ Docker Container development configuration. The created MQConnectionFactory is by default wrapped in a Spring CachingConnectionFactory.

The default values are:

flowable.ibm.mq.host=localhost
flowable.ibm.mq.port=1414
flowable.ibm.mq.channel=DEV.APP.SVRCONN
flowable.ibm.mq.queue-manager=QM1
flowable.ibm.mq.application-name=
flowable.ibm.mq.user=app
flowable.ibm.mq.password=

Extended Configuration Options​

Changing the default configuration is done by defining your properties in an application.properties file, environment properties, system properties, etc. For more information see Using Spring Boot Properties.

Pooled Connection Factory Options​

There is an option to enable using the JmsPoolConnectionFactory. This is disabled by default. It can be configured by using the following properties:

IBM MQ Pool Connection Factory properties
PropertyDescriptionDefault Value

flowable.ibm.mq.pool.enabled

Use JmsPoolConnectionFactory.

false

flowable.ibm.mq.pool.block-if-full

Block a connection when the pool is full.

true

flowable.ibm.mq.pool.block-if-full-timeout

Blocking period before throwing an exception if the pool is still full.

-1

flowable.ibm.mq.pool.idle-timeout

Connection idle timeout.

30 seconds

flowable.ibm.mq.pool.max-connections

Maximum number of pooled connections.

1

flowable.ibm.mq.pool.max-sessions-per-connection

Maximum number of pooled sessions per connection in the pool.

500

flowable.ibm.mq.pool.time-between-expiration-check

Time to sleep between runs of the idle connection eviction thread. When negative, no idle connection eviction thread runs.

-1

flowable.ibm.mq.pool.use-anonymous-producers

Whether to use only one anonymous "MessageProducer" instance. Set it to false to create one "MessageProducer" every time one is required.

true

Cached Connection Factory Options​

By default the Spring CachingConnectionFactory is used with the following properties:

IBM MQ Cached Connection Factory properties
PropertyDescriptionDefault Value

spring.jms.cache.enabled

Whether to cache sessions.

true

spring.jms.cache.consumers

Whether to cache message consumers.

false

spring.jms.cache.producers

Whether to cache message producers.

true

spring.jms.cache.session-cache-size

Size of the session cache (per JMS Session type).

-1

ActiveMQ​

Chat capabilities Only

Flowable provides out of the box support (via Spring Boot) for using the ActiveMQ client. In order to use ActiveMQ add the following dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-activemq</artifactId>
</dependency>

This dependency pulls in the needed transitive dependencies for communicating with ActiveMQ.

Configuration Options​

Configuring the connection with ActiveMQ is done by defining your properties in an application.properties file, environment properties, system properties, etc. For more information see Using Spring Boot Properties.

ActiveMQ Connection Factory Options​
ActiveMQ Connection Factory properties
PropertyDescriptionDefault Value

spring.activemq.broker-url

URL of the ActiveMQ broker. Auto-generated by default.

-

spring.activemq.in-memory

Whether the default broker URL should be in memory. Ignored if an explicit broker has been specified.

true

spring.activemq.user

Login user of the broker.

-

spring.activemq.password

Login password of the broker.

-

spring.activemq.close-timeout

Time to wait before considering a close complete.

15 seconds

spring.activemq.non-blocking-delivery

Whether to stop message delivery before re-delivering messages from a rolled back transaction. This implies that message order is not preserved when this is enabled.

false

spring.activemq.non-blocking-delivery

Time to wait on message sends for a response. Set it to 0 to wait forever.

0

spring.activemq.package.trust-all

Whether to trust all packages.

-

spring.activemq.package.trusted

Comma-separated list of specific packages to trust (when not trusting all packages).

-

Pooled Connection Factory Options​

There is an option to enable using the JmsPoolConnectionFactory. This is disabled by default. It can be configured by using the following properties:

ActiveMQ Pool Connection Factory properties
PropertyDescriptionDefault Value

spring.activemq.pool.enabled

Use JmsPoolConnectionFactory.

false

spring.activemq.pool.block-if-full

Block a connection when the pool is full.

true.

spring.activemq.pool.block-if-full-timeout

Blocking period before throwing an exception if the pool is still full.

-1

spring.activemq.pool.idle-timeout

Connection idle timeout.

30 seconds

spring.activemq.pool.max-connections

Maximum number of pooled connections.

1

spring.activemq.pool.max-sessions-per-connection

Maximum number of pooled sessions per connection in the pool.

500

spring.activemq.pool.time-between-expiration-check

Time to sleep between runs of the idle connection eviction thread. When negative, no idle connection eviction thread runs.

-1

spring.activemq.pool.use-anonymous-producers

Whether to use only one anonymous "MessageProducer" instance. Set it to false to create one "MessageProducer" every time one is required.

true

Cached Connection Factory Options​

By default the Spring CachingConnectionFactory is used with the following properties:

ActiveMQ Cached Connection Factory properties
PropertyDescriptionDefault Value

spring.jms.cache.enabled

Whether to cache sessions.

true

spring.jms.cache.consumers

Whether to cache message consumers.

false

spring.jms.cache.producers

Whether to cache message producers.

true

spring.jms.cache.session-cache-size

Size of the session cache (per JMS Session type).

-1

Spring Boot Skeleton​

Flowable Work is based on Spring Boot and therefore requires it as a base for any development environment.

The easiest way to setup a Flowable development project is to use the Flowable Initializr.

Choose the following options and hit "Generate Project" to get a Flowable skeleton for a Flowable development project:

Spring Initilizr

You can now import the project into the IDE of your choice (like IntelliJ IDEA or Eclipse).

Dependency Management​

With the help of Maven dependency management you can delegate the specifying the correct versions of all the dependencies to a BOM (Bill of Materials). The BOM defines and provides all the specific version information for all direct and transient dependencies. You just need to define the to-be-used Flowable version one by to use the the correct BOM.

Add the following section to the pom.xml file of the project you just created as a child tag of the <project> tag:

<dependencyManagement>
    <dependencies>
        <!-- Imports the bill-of-materials POM. -->
        <dependency>
            <groupId>com.flowable</groupId>
            <artifactId>flowable-platform-bom</artifactId>
            <version>${com.flowable.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Choose the Flowable version either by replacing the ${com.flowable.platform.version} part with a Flowable version number or by defining an appropriate Maven parameter specifying version you require.

Flowable Dependencies​

Flowable utilizes multiple Maven dependencies to access the required Flowable services.

Add the following dependencies as children of the existing <dependencies> tag of the pom.xml file to set up Flowable Work:

<!-- Flowable -->
<!-- =============== -->
<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-spring-boot-starter-platform-rest</artifactId>
</dependency>
<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-tenant-setup</artifactId>
</dependency>
<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-platform-default-models</artifactId>
</dependency>

Flowable with Chat capabilities Dependencies​

Flowable with chat capabilities utilizes multiple Maven dependencies to access the required Flowable services.

Add the following dependencies as children of the existing <dependencies> tag of the pom.xml file to set up Flowable with chat capabilities:

<!-- Flowable -->
<!-- =============== -->
<dependency>
    <groupId>com.flowable.engage</groupId>
    <artifactId>flowable-spring-boot-starter-engage-rest</artifactId>
</dependency>
<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-tenant-setup</artifactId>
</dependency>
<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-platform-default-models</artifactId>
</dependency>
<dependency>
    <groupId>com.flowable.engage</groupId>
    <artifactId>flowable-engage-default-models</artifactId>
</dependency>

<!-- Spring Boot -->
<!-- =========== -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-activemq</artifactId>
</dependency>

Flowable Inspect Dependencies​

To add Flowable Inspect to your application, add the following dependency:

<dependency>
    <groupId>com.flowable.inspect</groupId>
    <artifactId>flowable-spring-boot-starter-inspect-rest</artifactId>
</dependency>

Note that you need an appropriate license to enable Flowable Inspect.

Flowable User Definitions​

Flowable manages features and permissions of an application user by defining user definitions.

User definitions follow a "template" pattern for each different types of user using the system. Example include: administrators, superusers, operators, client advisers, clients, etc. They all have different feature sets available, different member groups, different permissions, etc.

To define the user definitions for your Flowable Work setup create a file like:

src/main/resources/com/flowable/users/custom/<users>-definitions.user.json

where <users> is a meaningful name for the set of user definitions.

Use the following content to define an admin user with full permissions to the Flowable:

[
  {
    "key": "admin",
    "name": "Flowable Administration User",
    "description": "Creates a new administration user.",
    "allowedFeatures": [
      "contacts",
      "createUser",
      "reports",
      "reportsMetrics",
      "actuators",
      "user-mgmt",
      "search-api",
      "templateManagement",
      "work",
      "tasks",
      "cases",
      "editAvatar"
    ]
  }
]

Flowable with chat capabilities User Definitions​

Flowable with chat capabilities manages features and permissions of an application user by defining user definitions.

User definitions follow a "template" pattern for each different types of user using the system. Example include: administrators, superusers, operators, client advisers, clients, etc. They all have different feature sets available, different member groups, different permissions, etc.

To define the user definitions for your Flowable with chat capabilities setup create a file like:

src/main/resources/com/flowable/users/custom/<users>-definitions.user.json

where <users> is a meaningful name for the set of user definitions.

Use the following content to define an admin user with full permissions to the Flowable with chat capabilities:

[
  {
    "key": "admin",
    "name": "Flowable Administration User",
    "description": "Creates a new, administration user.",
    "allowedFeatures": [
      "contacts",
      "createUser",
      "reports",
      "reportsMetrics",
      "actuators",
      "user-mgmt",
      "search-api",
      "templateManagement",
      "conversations",
      "websockets",
      "createConversation",
      "sendMessageFromProfile",
      "emojiPicker",
      "markdownInput",
      "editMessage",
      "deleteMessage",
      "fileUpload",
      "audioMessage",
      "videoMessage",
      "slashActions",
      "work",
      "tasks",
      "editAvatar"
    ]
  }
]

Flowable with chat capabilities Configuration​

Flowable with chat capabilities uses Spring Messaging for real time communication and needs an additional annotation to initialize the messaging components.

For this, you need to add the @EnableWebSocketMessageBroker annotation to your Spring Boot application class so it looks like this:

@SpringBootApplication
@EnableWebSocketMessageBroker
public class <MainClass>Application {
    public static void main(String[] args) {
        SpringApplication.run(<mainclass>Application.class, args);
    }
}

where <mainclass> is the name of the main class specific to your application.

Embedded Front End​

Flowable provides a dedicated JavaScript front end that can either be deployed to any HTML capable server or run embedded directly within the Flowable Server.

To run the front end embedded within the Flowable Server add the following dependency to the pom.xml file of the project:

<dependency>
    <groupId>com.flowable.work</groupId>
    <artifactId>flowable-work-frontend</artifactId>
</dependency>

In addition, you need to provide the correct Spring Boot Security configuration to allow access to the embedded front end. This is done by adding a class e.g., called SecurityConfiguration as a sibling of the Spring Boot Application class containing the following configuration:

import static org.springframework.security.web.util.matcher.AntPathRequestMatcher.antMatcher;

import org.springframework.beans.factory.ObjectProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.HttpStatusEntryPoint;
import org.springframework.security.web.util.matcher.AnyRequestMatcher;

import com.flowable.autoconfigure.security.FlowableHttpSecurityCustomizer;
import com.flowable.core.spring.security.web.authentication.AjaxAuthenticationFailureHandler;
import com.flowable.core.spring.security.web.authentication.AjaxAuthenticationSuccessHandler;
import com.flowable.platform.common.security.SecurityConstants;

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
public class SecurityConfiguration {

    @Bean
    @Order(10)
    public SecurityFilterChain basicDefaultSecurity(HttpSecurity http, ObjectProvider<FlowableHttpSecurityCustomizer> httpSecurityCustomizers) throws Exception {

        for (FlowableHttpSecurityCustomizer customizer : httpSecurityCustomizers.orderedStream().toList()) {
            customizer.customize(http);
        }

        http
            .logout(logout -> logout.logoutUrl("/auth/logout").logoutSuccessUrl("/"))
            // Non authenticated exception handling. The formLogin and httpBasic configure the exceptionHandling
            // We have to initialize the exception handling with a default authentication entry point in order to return 401 each time and not have a
            // forward due to the formLogin or the http basic popup due to the httpBasic
            .exceptionHandling(exceptionHandling -> exceptionHandling.defaultAuthenticationEntryPointFor(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED),
                    AnyRequestMatcher.INSTANCE))
            .formLogin(formLogin -> formLogin
                    .loginProcessingUrl("/auth/login")
                    .successHandler(new AjaxAuthenticationSuccessHandler())
                    .failureHandler(new AjaxAuthenticationFailureHandler()))
            .authorizeHttpRequests(configurer -> configurer
                    .requestMatchers(antMatcher("/analytics-api/**")).hasAuthority(SecurityConstants.ACCESS_REPORTS_METRICS)
                    // allow context root for all (it triggers the loading of the initial page)
                    .requestMatchers(antMatcher("/")).permitAll()
                    .requestMatchers(
                            antMatcher("/**/*.svg"), antMatcher("/**/*.ico"), antMatcher("/**/*.png"),
                            antMatcher("/**/*.woff2"), antMatcher("/**/*.woff"),
                            antMatcher("/**/*.css"), antMatcher("/**/*.html"), antMatcher("/**/*.js"),
                            antMatcher("/**/flowable-frontend-configuration"),
                            antMatcher("/**/index.html")).permitAll()
                    .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }

}

Tenant File​

Flowable provides an internal identity management (IDM) component that can manage tenants, users and groups. The internal IDM component is populated with tenants, users and groups defined in a tenant file. This file is read and loaded at initial system startup.

To use the internal IDM add the following dependency to the pom.xml file of the project:

<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-tenant-setup</artifactId>
</dependency>

To populate the internal IDM at database initialization create a file of the form:

src/main/resources/com/flowable/tenant-setup/custom/<tenants>.json

where <tenants> is a meaningful name for the set of tenant definitions.

For example, the tenant json file for the 'demo' tenant is named demo.json. A tenantKey is defined in the file that is unique to this group of users for this tenant. The file is similar to:

{
  "name": "Flowable Demo",
  "tenantKey": "demo",
  "groups": [
    {
      {"key": "flowableAdministrator", "name": "Flowable Administrator"},
      {"key": "flowableUser", "name": "Flowable User"},
  ],
  "users": [
    {
      "firstName": "Flowable",
      "lastName": "Admin",
      "login": "admin",
      "email": "admin@demo.flowable.io",
      "language": "en",
      "theme": "flowable",
      "userDefinitionKey": "admin"
    }
  ]
}

Note: A tenant setup file without tenantKey has all the users and groups created in the default tenant.

Infrastructure and Initial Startup​

You now have a minimal setup with which to run the application. But first you have to setup the appropriate infrastructure to get Flowable running. Please review Step-by-Step Installation for a description on how to set up the proper infrastructure for Flowable.

For the current development setup at least one instance of Elasticsearch is needed. A docker image can be helpful to get the environment up and running quickly. The following docker-compose.yml file provides an Elasticsearch instance running locally on port 9200 and an ActiveMQ running on ports 61616 (JMS) and 616163 (STOMP).

version: "3.4"

elasticsearch01:
  image: docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.0
  ports:
    - 9200:9200
    - 9300:9300
  ulimits:
    memlock:
      soft: -1
      hard: -1

activemq01:
  image: rmohr/activemq
  ports:
    - 8161:8161
    - 61616:61616
    - 61613:61613

After you started Elasticsearch/ActiveMQ and the Spring Boot project from your IDE an Elasticsearch instance running locally on port 9200.

version: "3.4"

elasticsearch01:
  image: docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.0
  ports:
    - 9200:9200
    - 9300:9300
  ulimits:
    memlock:
      soft: -1
      hard: -1

After you started Elasticsearch and the Spring Boot project from your IDE, Flowable is available at http://localhost:8080.

You can login with the administrator user you created in the tenant file.

  • Username: admin

  • Password: test

Running Behind a Proxy​

When running behind a proxy or a load balancer Flowable uses the X-Forwarded headers in order to provide better linking support and to create secure cookies.

Therefore, when running behind a proxy or load balancer it is important that the proxy is properly setting the different X-Forwarded headers. The crucial headers are:

  • X-Forwarded-For - This helps identity the IP address of the original request.

  • X-Forwarded-Proto - This helps identify the protocol of the original request.

  • X-Forwarded-Port - This helps identify the destination port of the original request.

Apart from configuring the proxy or load balancer the application needs to be configured as well.

Embedded Mode​

When running the application in an embedded mode (as a Spring Boot application with java -jar) the property server.forward-headers-strategy needs to be set to native. This property ensures that the X-Forwarded-* headers are applied to the HttpRequest.

Running Within Tomcat​

When running the application as a WAR withing Tomcat you need to configure the Remote IP Valve.

Flowable Design​

This section describes how Flowable Design can be installed and configured to be able to create models and deploy them as Apps to Flowable.

  1. Download Tomcat 8.5.x (latest version of the 8.5.x line) from: https://tomcat.apache.org/download-80.cgi or Tomcat 9.x from https://tomcat.apache.org/download-90.cgi. Once you downloaded the package you should unpack it. Do no run the Tomcat yet, first follow the steps for the installing the Flowable Design WAR.

  2. Download the Flowable Design WAR file from the Flowable Maven Repository (appropriate access credentials are needed): Flowable Design.

  3. Rename the .war file to flowable-design.war and copy it into the Tomcat’s webapps folder.

  4. Flowable requires that you have a valid license for the Product. The license is either stored on the file system or in the database. If the license is provided as a file then it is typically located in the .flowable folder of your home directory. On Unix or macOS the file is ~/.flowable/flowable.license. The location of the license file can be changed in the application.properties file (see below).

    flowable.design.license-location=file:/myCustomLocation/flowable.license

    To store the license in the database then the following property must be set in the applications.properties file:

    flowable.design.db-store-enabled=true

    With the license database store mode enabled a license is uploaded using the Flowable Design application.

  5. Add a file named application.properties in the Tomcat’s lib folder. The file is used later to configure Flowable Design.

  6. To be able to deploy/undeploy Apps directly into an instance of Flowable add the following properties to the application.properties file you just created. Remember to adapt the values (e.g., server, port, context, etc.) to your specific installation values:

    flowable.design.deployment-api-url=http://localhost:8080/flowable-work/app-api
    flowable.design.undeployment-api-url=http://localhost:8080/flowable-work/platform-api/app-deployments
    flowable.design.remote.authentication.user=admin
    flowable.design.remote.authentication.password=test

  7. To be able to select users / groups in the Design Assignment section add the following to the application.properties. Remember to adapt the values (e.g., server, port, context, etc.) to your specific values.

    flowable.common.app.idm-url=http://localhost:8080/flowable-work

  8. If you are manually creating the Database tables for Design, and you don't want Flowable to validate you can add the following to the application.properties

    flowable.design.database-schema-update=ignore

  9. You can now start the Tomcat by running bin/catalina.sh (bin\catalina.bat on Windows). Alternatively you can run bin/catalina.sh run to have it run in the foreground.

  10. You can now access Flowable Design by going to: http://localhost:8080/flowable-design.

  11. You can login with the user admin and password test.

Flowable Control​

This section describes how Flowable Control can be installed and configured to be able to monitor instances of Flowable.

  1. Download Tomcat 8.5.x (latest version of the 8.5.x line) from: https://tomcat.apache.org/download-80.cgi or Tomcat 9.x from https://tomcat.apache.org/download-90.cgi. Once you downloaded the package you should unpack it. Do not run the Tomcat yet, first follow the steps for the installing the Flowable Control WAR.

  2. Download the Flowable Control WAR file from the Flowable Maven Repository (appropriate access credentials are required): Flowable Control.

  3. Rename the .war file into flowable-control.war and copy it into the Tomcat’s webapps folder.

  4. Flowable Control requires that you have a valid license for the product. The license is either stored on the file system or in the database. If the license is provided as a file then it is typically located in the .flowable folder of your home directory. On Unix or macOS the file is ~/.flowable/flowable.license. The location of the license file can be changed in the application.properties file (see below).

    flowable.control.app.license-location=file:/myCustomLocation/flowable.license

    To store the license in the database then the following property must be set in the applications.properties file:

    flowable.control.app.db-store-enabled=true

    With the license database store mode enabled a license is uploaded using the Flowable Control application.

  5. Add a file named application.properties in the Tomcat’s lib folder. The file is used to configure Flowable Control and other applications.

  6. To manage apps from an instance of Flowable add the following properties to the application.properties file just created. The properties defined below are used to create the initial data values and are typically used during initial system startup. After that the values are stored internally and these properties are not used.

    flowable.control.app.cluster-config.name=Default Cluster
    flowable.control.app.cluster-config.description=Default Flowable Cluster
    flowable.control.app.cluster-config.server-address=http://localhost
    flowable.control.app.cluster-config.port=8090
    flowable.control.app.cluster-config.context-root=flowable-work
    flowable.control.app.cluster-config.user-name=admin
    flowable.control.app.cluster-config.password=test

Remember to adapt the values (e.g., server, port, context, etc.) to your specific installation values.

  1. If you are manually creating the Database tables for Control, and you don't want Flowable to validate you can add the following to the application.properties

    flowable.control.app.database-schema-update=ignore

  2. You can now start the Tomcat by running bin/catalina.sh (bin\catalina.bat on Windows). Alternatively you can run bin/catalina.sh run to have it run in the foreground.

  3. You should now be able to access Flowable Control by going to: http://localhost:8080/flowable-control.

  4. You can login with the user admin and password test.

Flowable Actuators​

Spring Boot Actuators​

As a Spring Boot 2 application Flowable supports Spring Boot Actuators which provide production ready features such as health and metrics endpoints.

To have Spring Boot base support for actuate you need to add the Spring Boot actuator dependency (if not already added by choosing it in the Spring Initializer):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Additional configuration properties in the application.properties file are needed to be able to access the actuator endpoints:

# Enable actuator endpoints over HTTP
management.endpoints.web.exposure.include=*
management.endpoint.health.show-details=ALWAYS

Actuator endpoints are queried by opening the following URLs in the browser:

For a full list of endpoints please check the Spring Boot Actuator documentation. Also remember to adjust the host and port as needed for your site.

Flowable Actuator Extensions​

Flowable provides additional extensions to the default Spring Boot Actuators by adding the following dependency:

<dependency>
    <groupId>com.flowable.platform</groupId>
    <artifactId>flowable-platform-actuate-autoconfigure</artifactId>
</dependency>

Adding this dependency adds a health endpoint at:

which provides information about the health of the connected Elasticsearch cluster.

Securing the Actuator Endpoints​

To secure the endpoints provided by the actuators some additional Spring Security configuration code is needed. This is accomplished by adding file named SecurityActuatorConfiguration.java to your Spring Boot project. The Java file contains the following code:

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.boot.actuate.health.HealthEndpoint;
import org.springframework.boot.actuate.info.InfoEndpoint;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

import com.flowable.actuate.autoconfigure.security.servlet.ActuatorRequestMatcher;
import com.flowable.platform.common.security.SecurityConstants;

@Configuration
public class SecurityActuatorConfiguration {

    @Bean
    @Order(6) // Actuator configuration should kick in before the Form Login there should always be HTTP basic for the endpoints
    public SecurityFilterChain basicActuatorSecurity(HttpSecurity http) throws Exception {

        http
            .sessionManagement(sessionManagement -> sessionManagement.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .csrf(AbstractHttpConfigurer::disable);

        http
            .securityMatcher(new ActuatorRequestMatcher())
            .authorizeHttpRequests(configurer -> configurer
                    .requestMatchers(EndpointRequest.to(InfoEndpoint.class, HealthEndpoint.class)).permitAll()
                    .requestMatchers(EndpointRequest.toAnyEndpoint()).hasAuthority(SecurityConstants.ACCESS_ACTUATORS)
                    .anyRequest().denyAll())
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }
}

This enables unauthorized access to the health and info endpoints and activates basic authentication for the other actuator endpoints.