1. Introduction

1.1. License

Flowable is distributed under the Apache V2 license.

1.3. Sources

The distribution contains most of the sources as JAR files. The source code of Flowable can be found on https://github.com/flowable/flowable-engine

1.4. Required software

1.4.1. JDK 7+

Flowable runs on a JDK higher than or equal to version 7. Go to Oracle Java SE downloads and click on button "Download JDK". There are installation instructions on that page as well. To verify that your installation was successful, run java -version on the command line. That should print the installed version of your JDK.

1.4.2. IDE

Flowable development can be done with the IDE of your choice. If you would like to use the Flowable Designer then you need Eclipse Mars or Neon. Download the Eclipse distribution of your choice from the Eclipse download page. Unzip the downloaded file and then you should be able to start it with the eclipse file in the directory eclipse. Further in this user guide, there is a section on installing our eclipse designer plugin.

1.5. Reporting problems

We expect developers to have have read How to ask questions the smart way.

After you’ve done that you can post questions and comments on the Users forum, and create issues in our Github issue tracker.

1.6. Experimental features

Sections marked with [EXPERIMENTAL] should not be considered stable.

All classes that have .impl. in the package name are internal implementation classes and cannot be considered stable. However, if the user guide mentions those classes as configuration values, they are supported and can be considered stable.

1.7. Internal implementation classes

In the JAR file, all classes in packages that have .impl. (e.g. org.flowable.form.engine.impl.db) in them are implementation classes and should be considered internal. No stability guarantees are given on classes or interfaces that are in implementation classes.

2. Configuration

2.1. Creating a Form Engine

The Flowable Form engine is structured in a very similar way to the Flowable process engine. As a result parts of the documentation have a resemblance with their process engine counterpart.

The Flowable Form engine is configured through an XML file named flowable.form.cfg.xml. Note that this is not applicable if you’re using the Spring style of building a Form engine.

The easiest way to obtain a FormEngine, is to use the org.flowable.form.engine.FormEngines class:

1
FormEngine formEngine = FormEngines.getDefaultFormEngine()

This will look for a flowable.form.cfg.xml file on the classpath and construct an engine based on the configuration in that file. The following snippet shows an example configuration. The following sections will give a detailed overview of the configuration properties.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <bean id="formEngineConfiguration" class="org.flowable.dmn.engine.impl.cfg.StandaloneFormEngineConfiguration"> <property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000" /> <property name="jdbcDriver" value="org.h2.Driver" /> <property name="jdbcUsername" value="sa" /> <property name="jdbcPassword" value="" /> <property name="databaseSchemaUpdate" value="true" /> </bean> </beans>

Note that the configuration XML is, in fact, a Spring configuration. This does not mean that Flowable Form can only be used in a Spring environment! We are simply leveraging the parsing and dependency injection capabilities of Spring internally for building up the engine.

The FormEngineConfiguration object can also be created programmatically using the configuration file. It is also possible to use a different bean id (for example, see line 3).

1 2 3 4 5 6
FormEngineConfiguration. createFormEngineConfigurationFromResourceDefault(); createFormEngineConfigurationFromResource(String resource); createFormEngineConfigurationFromResource(String resource, String beanName); createFormEngineConfigurationFromInputStream(InputStream inputStream); createFormEngineConfigurationFromInputStream(InputStream inputStream, String beanName);

It is also possible not to use a configuration file, and create a configuration based on defaults (see the different supported classes for more information).

1 2
FormEngineConfiguration.createStandaloneFormEngineConfiguration(); FormEngineConfiguration.createStandaloneInMemFormEngineConfiguration();

All these FormEngineConfiguration.createXXX() methods return a FormEngineConfiguration that can further be tweaked if needed. After calling the buildFormEngine() operation, a FormEngine is created:

1 2 3 4
FormEngine formEngine = FormEngineConfiguration.createStandaloneInMemFormEngineConfiguration() .setDatabaseSchemaUpdate(FormEngineConfiguration.DB_SCHEMA_UPDATE_FALSE) .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000") .buildFormEngine();

2.2. FormEngineConfiguration bean

The flowable.form.cfg.xml must contain a bean that has the id 'formEngineConfiguration'.

1
<bean id="formEngineConfiguration" class="org.flowable.form.engine.impl.cfg.StandaloneFormEngineConfiguration">

This bean is then used to construct the FormEngine. There are multiple classes available that can be used to define the formEngineConfiguration. These classes represent different environments, and set defaults accordingly. It’s best practice to select the class that matches your environment the most, to minimalise the number of properties needed to configure the engine. The following classes are currently available:

  • org.flowable.form.engine.impl.cfg.StandaloneFormEngineConfiguration: the process engine is used in a standalone way. Flowable will take care of the transactions. By default, the database will only be checked when the engine boots (and an exception is thrown if there is no Flowable Form schema or the schema version is incorrect).

  • org.flowable.form.engine.impl.cfg.StandaloneInMemFormEngineConfiguration: this is a convenience class for unit testing purposes. Flowable Form will take care of the transactions. An H2 in-memory database is used by default. The database will be created and dropped when the engine boots and shuts down. When using this, probably no additional configuration is needed).

  • org.flowable.form.spring.SpringFormEngineConfiguration: To be used when the Form engine is used in a Spring environment. See the Spring integration section for more information.

2.3. Plug into Process Engine

In addition to running in standalone mode, it’s also possible to plug the Form engine into the Process engine. This makes the Process engine aware of it and other engines. This enables, for example, deploying artifacts containing not only BPMN models, but also DMN models, to the Process engine’s deployment service API.

To make the Process engine aware of the Form engine, the org.flowable.dmn.engine.configurator.FormEngineConfigurator needs to be added to list of configurators in the process engine configuration. This configurator is part of the flowable-form-engine-configurator module.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
<bean id="processEngineConfiguration" class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration"> <property name="configurators"> <list> <ref bean="formEngineConfigurator" /> </list> </property> ... </bean> <bean id="formEngineConfiguration" class="org.flowable.form.engine.impl.cfg.StandaloneFormEngineConfiguration"> <property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000" /> <property name="jdbcDriver" value="org.h2.Driver" /> <property name="jdbcUsername" value="sa" /> <property name="jdbcPassword" value="" /> </bean> <bean id="formEngineConfigurator" class="org.flowable.form.engine.configurator.FormEngineConfigurator"> <property name="formEngineConfiguration" ref="formEngineConfiguration" /> </bean>

2.4. Database configuration

There are two ways to configure the database that the Flowable Form engine will use. The first option is to define the JDBC properties of the database:

  • jdbcUrl: JDBC URL of the database.

  • jdbcDriver: implementation of the driver for the specific database type.

  • jdbcUsername: username to connect to the database.

  • jdbcPassword: password to connect to the database.

The data source that is constructed based on the provided JDBC properties will have the default MyBatis connection pool settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):

  • jdbcMaxActiveConnections: The maximum number of active connections that the connection pool can contain at any time. Default is 10.

  • jdbcMaxIdleConnections: The maximum number of idle connections that the connection pool can contain at any time.

  • jdbcMaxCheckoutTime: The amount of time, in milliseconds, a connection can be checked out from the connection pool before it is forcefully returned. Default is 20000 (20 seconds).

  • jdbcMaxWaitTime: This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it is taking unusually long (to avoid failing silently forever if the pool is misconfigured). Default is 20000 (20 seconds).

Example database configuration:

1 2 3 4
<property name="jdbcUrl" value="jdbc:h2:mem:flowable_dmn;DB_CLOSE_DELAY=1000" /> <property name="jdbcDriver" value="org.h2.Driver" /> <property name="jdbcUsername" value="sa" /> <property name="jdbcPassword" value="" />

Our benchmarks have shown that the MyBatis connection pool is not the most efficient or resilient when dealing with a lot of concurrent requests. As such, we advise the use of a javax.sql.DataSource implementation and inject it into the process engine configuration (ror example DBCP, C3P0, Hikari, Tomcat Connection Pool, and so on):

1 2 3 4 5 6 7 8 9 10 11 12
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" > <property name="driverClassName" value="com.mysql.jdbc.Driver" /> <property name="url" value="jdbc:mysql://localhost:3306/flowable_dmn" /> <property name="username" value="flowable" /> <property name="password" value="flowable" /> <property name="defaultAutoCommit" value="false" /> </bean> <bean id="formEngineConfiguration" class="org.flowable.form.engine.impl.cfg.StandaloneFormEngineConfiguration"> <property name="dataSource" ref="dataSource" /> ...

Note that Flowable Form does not ship with a library that allows you to define such a data source. So you have to make sure that the libraries are on your classpath.

The following properties can be set, regardless of whether you are using the JDBC or data source approach:

  • databaseType: it’s normally not necessary to specify this property as it’s automatically identified from the database connection metadata. Should only be specified in case automatic detection fails. Possible values: {h2, mysql, oracle, postgres, mssql, db2}. This setting will determine which create/drop scripts and queries will be used. See the supported databases section for an overview of which types are supported.

  • databaseSchemaUpdate: allows you to set the strategy to handle the database schema on form engine boot and shutdown.

    • false (default): Checks the version of the DB schema against the library when the form engine is being created and throws an exception if the versions don’t match.

    • true: Upon building the form engine, a check is performed and an update of the schema is performed if it is necessary. If the schema doesn’t exist, it is created.

    • create-drop: Creates the schema when the form engine is being created and drops the schema when the process engine is being closed.

2.5. JNDI Datasource Configuration

By default, the database configuration for Flowable Form is contained within the db.properties files in the WEB-INF/classes of each web application. This isn’t always ideal because it requires users to either modify the db.properties in the Flowable source and recompile the WAR file, or explode the WAR and modify the db.properties on every deployment.

By using JNDI (Java Naming and Directory Interface) to obtain the database connection, the connection is fully managed by the Servlet Container and the configuration can be managed outside the WAR deployment. This also allows more control over the connection parameters than that provided by the db.properties file.

2.5.1. Configuration

Configuration of the JNDI datasource will differ depending on what servlet container application you are using. The instructions below will work for Tomcat, but for other container applications, please refer to the documentation for your container app.

If using Tomcat, the JNDI resource is configured within $CATALINA_BASE/conf/[enginename]/[hostname]/[warname].xml (for the Flowable UI this will usually be $CATALINA_BASE/conf/Catalina/localhost/flowable-app.xml). The default context is copied from the Flowable WAR file when the application is first deployed, so if it already exists, you will need to replace it. To change the JNDI resource so that the application connects to MySQL instead of H2, for example, change the file to the following:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<?xml version="1.0" encoding="UTF-8"?> <Context antiJARLocking="true" path="/flowable-app"> <Resource auth="Container" name="jdbc/flowableDB" type="javax.sql.DataSource" description="JDBC DataSource" url="jdbc:mysql://localhost:3306/flowable" driverClassName="com.mysql.jdbc.Driver" username="sa" password="" defaultAutoCommit="false" initialSize="5" maxWait="5000" maxActive="120" maxIdle="5"/> </Context>

2.5.2. JNDI properties

To configure a JNDI Datasource, use following properties in the properties file for the Flowable UI:

  • datasource.jndi.name: the JNDI name of the Datasource.

  • datasource.jndi.resourceRef: Set whether the lookup occurs in a J2EE container, in other words, if the prefix "java:comp/env/" needs to be added if the JNDI name doesn’t already contain it. Default is "true".

2.6. Supported databases

Listed below are the types (case sensitive!) that Flowable uses to refer to databases.

Flowable Form database type Example JDBC URL Notes

h2

jdbc:h2:tcp://localhost/flowable_form

Default configured database

mysql

jdbc:mysql://localhost:3306/flowable_form?autoReconnect=true

Tested using mysql-connector-java database driver

oracle

jdbc:oracle:thin:@localhost:1521:xe

postgres

jdbc:postgresql://localhost:5432/flowable_form

db2

jdbc:db2://localhost:50000/flowable_form

mssql

jdbc:sqlserver://localhost:1433;databaseName=flowable_form (jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver) OR jdbc:jtds:sqlserver://localhost:1433/flowable_form (jdbc.driver=net.sourceforge.jtds.jdbc.Driver)

Tested using Microsoft JDBC Driver 4.0 (sqljdbc4.jar) and JTDS Driver

2.7. Creating the database tables

Flowable Form uses Liquibase for tracking, managing and applying database schema changes.

The easiest way to create the database tables for your database is to:

  • Add the flowable-form-engine JARs to your classpath

  • Add a suitable database driver

  • Add a Flowable configuration file (flowable.form.cfg.xml) to your classpath, pointing to your database (see database configuration section)

  • Execute the main method of the DbSchemaCreate class

2.8. Database table names explained

The database names of Flowable Form all start with ACT_FO_.

  • ACT_FO_DATABASECHANGELOG: This table is used by Liquibase to track which changesets have been run.

  • ACT_FO_DATABASECHANGELOGLOCK: This table is used by Liquibase to ensure only one instance of Liquibase is running at one time.

  • ACT_FO_FORM_DEFINITION: This table contains the definition info of the deployed form definitions.

  • ACT_FO_FORM_INSTANCE: This table contains the form instances with the values that have been filled in by a user.

  • ACT_FO_FORM_DEPLOYMENT: This table contains the deployment metadata.

  • ACT_FO_FORM_RESOURCE: This table contains the Form definition resource.

2.9. Database upgrade

Make sure you make a backup of your database (using your database backup capabilities) before you run an upgrade.

By default, a version check will be performed each time a process engine is created. This typically happens once at boot time of your application or the Flowable webapps. If the Flowable library notices a difference between the library version and the version of the Flowable database tables, then an exception is thrown.

To upgrade, you have to start with putting the following configuration property in your flowable.form.cfg.xml configuration file:

1 2 3 4 5 6 7 8 9
<beans > <bean id="formEngineConfiguration" class="org.flowable.form.engine.impl.cfg.StandaloneFormEngineConfiguration"> <!-- ... --> <property name="databaseSchemaUpdate" value="true" /> <!-- ... --> </bean> </beans>

Also, include a suitable database driver for your database to the classpath. Upgrade the Flowable Form libraries in your application. Or start up a new version of Flowable Form and point it to a database that contains an older version. With databaseSchemaUpdate set to true, Flowable Form will automatically upgrade the DB schema to the newer version the first time when it notices that libraries and DB schema are out of sync.

2.10. Deployment cache configuration

All definitions are cached (after they’re parsed) to avoid hitting the database every time a form is needed and because form data doesn’t change. By default, there is no limit on this cache. To limit the forms cache, add following property

1
<property name="formCacheLimit" value="10" />

Setting this property will swap the default hashmap cache with a LRU cache that has the provided hard limit. Of course, the best value of this property depends on the total amount of forms stored and the number of forms actually used at runtime.

You can also inject your own cache implementation. This must be a bean that implements the org.flowable.form.engine.impl.persistence.deploy.DeploymentCache interface:

1 2 3
<property name="formCache"> <bean class="org.flowable.MyCache" /> </property>

2.11. Logging

All logging (flowable, spring, mybatis, …​) is routed through SLF4J and allows the selection of the logging-implementation of your choice.

By default no SFL4J-binding jar is present in the flowable-dmn-engine dependencies, this should be added in your project in order to use the logging framework of your choice. If no implementation jar is added, SLF4J will use a NOP-logger, not logging anything at all, other than a warning that nothing will be logged. For more info on these bindings http://www.slf4j.org/codes.html#StaticLoggerBinder.

With Maven, add for example a dependency like this (here using log4j), note that you still need to add a version:

1 2 3 4
<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> </dependency>

The flowable-ui and flowable-rest webapps are configured to use Log4j binding. Log4j is also used when running the tests for all the flowable-* modules.

Important note when using a container with commons-logging in the classpath: In order to route the spring-logging through SLF4J, a bridge is used (see http://www.slf4j.org/legacy.html#jclOverSLF4J). If your container provides a commons-logging implementation, please follow directions on this page: http://www.slf4j.org/codes.html#release to ensure stability.

Example when using Maven (version omitted):

1 2 3 4
<dependency> <groupId>org.slf4j</groupId> <artifactId>jcl-over-slf4j</artifactId> </dependency>

3. The Flowable Form API

3.1. The Form Engine API and services

The Form engine API is the most common way of interacting with Flowable Form. The central starting point is the FormEngine, which can be created in several ways as described in the configuration section. From the FormEngine, you can obtain the various other services. FormEngine and the services objects are thread safe, so you can keep a reference to one of those for a whole server.

api.services
1 2 3 4 5
FormEngine formEngine = FormEngines.getDefaultFormEngine(); FormRuleService formRuleService = formEngine.getFormRuleService(); FormRepositoryService formRepositoryService = formEngine.getFormRepositoryService(); FormService formService = formEngine.getFormService(); FormManagementService formManagementService = formEngine.getFormManagementService();

FormEngines.getDefaultFormEngine() will initialize and build a Form engine the first time it is called and afterwards always return the same Form engine. Proper creation and closing of all Form engines can be done with FormEngines.init() and FormEngines.destroy().

The FormEngines class will scan for all flowable.form.cfg.xml and flowable-form-context.xml files. For all flowable.form.cfg.xml files, the Form engine will be built in the typical Flowable way: FormEngineConfiguration.createFormEngineConfigurationFromInputStream(inputStream).buildFormEngine(). For all flowable-form-context.xml files, the Form engine will be built in the Spring way: First the Spring application context is created and then the Form engine is obtained from that application context.

All services are stateless. This means that you can easily run Flowable Form on multiple nodes in a cluster, each going to the same database, without having to worry about which machine actually executed previous calls. Any call to any service is idempotent, regardless of where it is executed.

The FormRepositoryService is probably the first service needed when working with the Flowable Form engine. This service offers operations for managing and manipulating deployments and Form definitions. A Form definition is the root concept of a Form model. (The main concepts of a form definition are explained in the <form-introduction, Form introduction section>). A deployment is the unit of packaging within the Flowable Form engine. A deployment can contain multiple Form definition JSON files. Deploying a deployment means it is uploaded to the engine, where all Form definitions are inspected and parsed before being stored in the database. From that point on, the deployment is known to the system and any form included in the deployment can now be executed.

Furthermore, this service allows you to:

  • Query deployments for Form definitions known to the engine.

  • Retrieve a POJO version of the Form definition that can be used to introspect using Java rather than JSON.

The FormService provides methods for creating a form instance with the values that a user has filled in for a specific form definition. It can also be use to query form instances.

The FormManagementService is typically not needed when coding custom application using Flowable Form. It allows you to retrieve information about the engine version, database tables and table metadata.

3.2. Exception strategy

The base exception in Flowable is the org.flowable.engine.FlowableException, an unchecked exception. This exception can be thrown at all times by the API, but expected exceptions that happen in specific methods are documented in the the javadocs. For example, an extract from FormRuleService:

Even though we want to avoid a big exception hierarchy, the following subclasses are thrown in specific cases. All other errors that occur during process-execution or API-invocation that don’t fit into the possible exceptions below, are thrown as regular FlowableExceptionss.

  • FlowableOptimisticLockingException: Thrown when an optimistic lock occurs in the data store caused by concurrent access of the same data entry.

  • FlowableClassLoadingException: Thrown when a class requested to load was not found or when an error occurred while loading it.

  • FlowableObjectNotFoundException: Thrown when an object that is requested or acted on does not exist.

  • FlowableIllegalArgumentException: An exception indicating that an illegal argument has been supplied in a Flowable Form API-call, an illegal value was configured in the engine’s configuration or an illegal value has been supplied.

3.3. Query API

There are two ways of querying data from the engine: The query API and native queries. The Query API allows you to program completely typesafe queries with a fluent API. You can add various conditions to your queries (all of which are applied together as a logical AND) and precisely one ordering. The following code shows an example:

1 2 3 4
List<FormDeployment> formDeployments = formRepositoryService.createDeploymentQuery() .deploymentNameLike("deployment%") .orderByDeployTime() .list();

Sometimes you need more powerful queries, for example, queries using an OR operator or restrictions you cannot express using the Query API. For these cases, we introduced native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects, such as Deployment, FormInstance, and so on. As the query will be fired at the database, you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended that native queries are used with care. The table names can be retrieved through the API to keep the dependency as small as possible.

1 2 3 4 5 6 7
long count = formRepositoryService.createNativeDeploymentQuery() .sql("SELECT count(*) FROM " + formManagementService.getTableName(FormDeploymentEntity.class) + " D1, " + formManagementService.getTableName(FormDefinitionEntity.class) + " D2 " + "WHERE D1.ID_ = D2.DEPLOYMENT_ID_ " + "AND D1.ID_ = #{deploymentId}") .parameter("deploymentId", deployment.getId()) .count();

3.4. Unit testing

As Flowable Form is an embeddable Java engine, writing unit tests for Form definitions is as simple as writing regular unit tests.

Flowable supports JUnit version 4 styles of unit testing. When writing JUnit 4 unit tests, the org.flowable.form.engine.test.FlowableFormRule Rule can be used. Through this rule, the Form engine and services are available through getters. Including this Rule will enable the use of the org.flowable.form.engine.test.FormDeploymentAnnotation annotation (see above for an explanation of its use and configuration) and it will look for the default configuration file on the classpath. Form engines are statically cached over multiple unit tests when using the same configuration resource. It’s also possible to provide a custom engine configuration to the rule.

The following code snippet shows an example of using the JUnit 4 style of testing and the usage of the FlowableFormRule (and passing an optional custom configuration)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
public class MyFormDefinitionTest { @Rule public FlowableFormRule flowableFormRule = new FlowableFormRule("custom1.flowable.form.cfg.xml"); @Test @FormDeploymentAnnotation public void formUsageExample() { FormEngine formEngine = flowableFormRule.getFormEngine(); FormService formService = dmnEngine.getFormService(); FormInstance result = formService.getFormInstanceModelById( "f7689f79-f1cc-11e6-8549-acde48001122", null); Assert.assertNotNull(result)); } }

3.5. The Form engine in a web application

The FormEngine is a thread-safe class and can easily be shared among multiple threads. In a web application, this means it is possible to create the Form engine once when the container boots, and shut down the engine when the container goes down.

The following code snippet shows how you can write a simple ServletContextListener to initialize and destroy form engines in a plain Servlet environment:

1 2 3 4 5 6 7 8 9 10 11
public class FormEnginesServletContextListener implements ServletContextListener { public void contextInitialized(ServletContextEvent servletContextEvent) { FormEngines.init(); } public void contextDestroyed(ServletContextEvent servletContextEvent) { FormEngines.destroy(); } }

The contextInitialized method will delegate to FormEngines.init(). This will look for flowable.form.cfg.xml resource files on the classpath, and create a FormEngine for the given configurations (for example, multiple JARs with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the Form engine is needed, it can be fetched using:

1
FormEngines.getDefaultFormEngine()

or

1
FormEngines.getFormEngine("myName");

Of course, it’s also possible to use any of the variants of creating a Form engine, as described in the configuration section.

The contextDestroyed method of the context-listener delegates to FormEngines.destroy(). This will properly close all initialized Form engines.

4. Spring integration

While you can definitely use Flowable Form without Spring, we’ve provided some very nice integration features that are explained in this chapter.

4.1. FormEngineFactoryBean

The ~FormEngine can be configured as a regular Spring bean. The starting point of the integration is the class org.flowable.form.spring.FormEngineFactoryBean. This bean takes a Form engine configuration and creates the Form engine. This means that the creation and configuration of properties for Spring is the same as documented in the configuration section. For Spring integration, the configuration and engine beans will look like this:

1 2 3 4 5 6 7
<bean id="formEngineConfiguration" class="org.flowable.form.spring.SpringFormEngineConfiguration"> ... </bean> <bean id="formEngine" class="org.flowable.form.spring.FormEngineFactoryBean"> <property name="formEngineConfiguration" ref="formEngineConfiguration" /> </bean>

Note that the formEngineConfiguration bean now uses the org.flowable.form.spring.SpringFormEngineConfiguration class.

4.2. Automatic resource deployment

Spring integration also has a special feature for deploying resources. In the Form engine configuration, you can specify a set of resources. When the Form engine is created, all those resources will be scanned and deployed. There is filtering in place that prevents duplicate deployments. Only when the resources actually have changed will new deployments be deployed to the Flowable Form DB. This makes sense in a lot of use cases, where the Spring container is rebooted often (for example, testing).

Here’s an example:

1 2 3 4 5 6 7 8 9
<bean id="formEngineConfiguration" class="org.flowable.spring.SpringFormEngineConfiguration"> ... <property name="deploymentResources" value="classpath*:/org/flowable/spring/test/autodeployment/autodeploy/*.form" /> </bean> <bean id="formEngine" class="org.flowable.form.spring.FormEngineFactoryBean"> <property name="formEngineConfiguration" ref="formEngineConfiguration" /> </bean>

By default, the configuration above will group all of the resources matching the filtering into a single deployment to the Flowable Form engine. The duplicate filtering to prevent re-deployment of unchanged resources applies to the whole deployment. In some cases, this may not be what you want. For instance, if you deploy a set of Form resources this way and only a single Form definition in those resources has changed, the deployment as a whole will be considered new and all of the process definitions in that deployment will be re-deployed, resulting in new versions of each of the Form definitions, even though only one was actually changed.

To be able to customize the way deployments are determined, you can specify an additional property in the SpringFormEngineConfiguration, deploymentMode. This property defines the way deployments will be determined from the set of resources that match the filter. There are 3 values that are supported by default for this property:

  • default: Group all resources into a single deployment and apply duplicate filtering to that deployment. This is the default value and it will be used if you don’t specify a value.

  • single-resource: Create a separate deployment for each individual resource and apply duplicate filtering to that deployment. This is the value you would use to have each Form definition be deployed separately and only create a new Form definition version if it has changed.

  • resource-parent-folder: Create a separate deployment for resources that share the same parent folder and apply duplicate filtering to that deployment. This value can be used to create separate deployments for most resources, but still be able to group some by placing them in a shared folder. Here’s an example of how to specify the single-resource configuration for deploymentMode:

1 2 3 4 5 6
<bean id="formEngineConfiguration" class="org.flowable.form.spring.SpringFormEngineConfiguration"> ... <property name="deploymentResources" value="classpath*:/flowable/*.form" /> <property name="deploymentMode" value="single-resource" /> </bean>

In addition to using the values listed above for deploymentMode, you may require customized behavior towards determining deployments. If so, you can create a subclass of SpringFormEngineConfiguration and override the getAutoDeploymentStrategy(String deploymentMode) method. This method determines which deployment strategy is used for a certain value of the deploymentMode configuration.

4.3. Unit testing

When integrating with Spring, forms can be tested very easily using the standard Flowable testing facilities. The following example shows how a form is tested in a typical Spring-based unit test:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
@RunWith(SpringJUnit4ClassRunner.class) @ContextConfiguration("classpath:org/flowable/spring/test/junit4/springTypicalUsageTest-context.xml") public class SpringJunit4Test { @Autowired private FormEngine formEngine; @Autowired private FormService formService; @Autowired @Rule public FlowableFormRule flowableSpringRule; @Test @FormDeploymentAnnotation public void simpleFormInstanceTest() { FormInstance result = formService.getFormInstanceModelById( "f7689f79-f1cc-11e6-8549-acde48001122", null); Assert.assertNotNull(result)); } }

Note that for this to work, you need to define a org.flowable.form.engine.test.FlowableFormRule bean in the Spring configuration (which is injected by auto-wiring in the example above).

1 2 3
<bean id="flowableFormRule" class="org.flowable.form.engine.test.FlowableFormRule"> <property name="formEngine" ref="formEngine"/> </bean>

5. Deployment

5.1. Form Definitions

Form Definitions with .form extension can be deployed to the Form engine.

When the Form engine is plugged into the Process engine, the Form definitions can be packed into a business archive (BAR) together with other process related resources. The Process engine deployment service will take care of deploying the Form resources to the Form engine when the flowable-form-engine-configurator or flowable-form-spring-configurator modules are used.

5.1.1. Form Definitions

A Form definition consists of one or more form field definitions. When deploying a Form definition, it is inserted into the ACT_FO_FORM_DEFINITION table.

5.1.2. Deploying programmatically

Deploying a Form definition can be done like this:

1 2 3 4 5 6 7
String formDefinition = "path/to/definition-one.form"; ZipInputStream inputStream = new ZipInputStream(new FileInputStream(barFileName)); formRepositoryService.createDeployment() .name("definition-one") .addClasspathResource(formDefinition) .deploy();

5.2. Versioning of Form definitions

Versions of Form definitions are created during deployment, where Flowable will assign a version to the form definition before it is stored in the Flowable Form DB.

For each Form definition, the following steps are performed to initialize the properties key, version, name and id:

  • The form definition key attribute in the definition JSON file is used as the form definition key property.

  • The form definition name attribute in the JSON file is used as the form definition name property.

  • The first time a form definition with a particular key is deployed, version 1 is assigned. For all subsequent deployments of form definition with the same key, the version will be set 1 higher than the maximum currently deployed version. The key property is used to distinguish form definition.

  • The id property is a unique number to guarantee uniqueness of the form definition id for the form definition caches in a clustered environment.

Take, for example, the following form definition:

1 2 3 4 5 6 7 8 9 10 11 12 13
{ "key": "form1", "name": "My first form", "fields": [ { "id": "input1", "name": "Input1", "type": "text", "required": false, "placeholder": "empty" } ] }

When deploying this form definition, the form definition table in the database will look like this:

id key name version

e29d4126-ed4d-11e6-9e00-7282cbd6ce64

form1

My first form

1

Suppose we now deploy an updated version of the same form definition (for example, changing the text field), but the key of the form definition remains the same. The form definition table will now contain the following entries:

id key name version

e29d4126-ed4d-11e6-9e00-7282cbd6ce64

form1

My first form

1

e9c2a6c0-c085-11e6-9096-6ab56fad108a

form1

My first form

2

Should we create a second form definition, as defined below, and deploy this to Flowable Form Engine, a third row will be added to the table.

1 2 3 4 5 6 7 8 9 10 11 12 13
{ "key": "form2", "name": "My second form", "fields": [ { "id": "input2", "name": "Input2", "type": "text", "required": false, "placeholder": "empty" } ] }

The table will look like this:

id key name version

e29d4126-ed4d-11e6-9e00-7282cbd6ce64

form1

My first form

1

e9c2a6c0-c085-11e6-9096-6ab56fad108a

form1

My first form

2

d317d3f7-e948-11e6-9ce6-b28c070b517d

form2

My second form

1

Note how the key for the new form definition is different from our first form definition. The Flowable Form engine only considers the key attribute when distinguishing form definitions. The new form definition is therefore deployed with version 1.

5.3. Category

Both Form deployments and form definitions can have user-defined categories. The deployment category can be specified in the API like this:

1 2 3 4 5
formRepository .createDeployment() .category("yourCategory") ... .deploy();

The form definition category can be specified in the API like this:

1
formRepository.setFormDefinitionCategory("e9c2a6c0-c085-11e6-9096-6ab56fad108a", "yourCategory");

[[form introduction]]

6. Form Introduction

6.1. What is a form definition?

For the BPMN engine, we adhere to the BPMN specification and for the DMN engine we use the DMN specification. For start and task forms there’s no Oasis specification that can be used. Therefore, we have defined a JSON-based form definition structure that we use as an output format for the Flowable Form Editor and is used to render start and task forms in the Flowable Task application.

6.2. Defining a form

Create a new JSON file using your favourite text or JSON editor and give it a name. Make sure that the file ends with .form, as otherwise the Form engine won’t pick up the file for deployment.

The form definition JSON starts with a key, name and description. The key property is used by the Form engine to identify the form definition across the whole Form engine. The versioning system is also based on the key property being identical for form definitions that have the same origin. The second part is the array of fields that defines the form fields of the form definition. Optionally, there’s a third part that defines the form outcomes.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
{ "key": "form1", "name": "My first form", "fields": [ { "id": "input1", "name": "Input1", "type": "text", "required": false, "placeholder": "empty" } ], "outcomes": [ { "id": "null", "name": "Accept" }, { "id": "null", "name": "Reject" } ] }

Each form field has an id, name and type property. The id should be unique within the same form definition and is used as the variable name when a form is completed by a user. In this small example, an input1 process variable is created with the value of the text field the user has filled in. The outcomes are also mapped to a variable based on the form’s identifier, in the format of "form_<form-identifier>_outcome". For the example above, the selected outcome will be set for a variable named "form_form1_outcome". In an expression, you can test if the outcome was Accept using ${form_form1_outcome == "Accept"}.

The following form field types are supported:

  • text: rendered as a text field

  • multi-line-text: rendered as a text area field

  • integer: rendered as a text field, but only allows numeric values

  • boolean: rendered as a checkbox field

  • date: rendered as a date field

  • dropdown: rendered as a select field with the option values configured in the field definition

  • radio-buttons: rendered as a radio field with the option values configured in the field definition

  • people: rendered as a select field where a person from the Identity user table can be selected

  • functional-group: rendered as a select field where a group from the Identity group table can be selected

  • upload: rendered as an upload field

  • expression: rendered as a label and allows you to use JUEL expressions to use variables and/or other dynamic values in the label text

7. REST API

7.1. General Flowable REST principles

7.1.1. Installation and Authentication

Flowable includes a REST API to the Flowable engine that can be installed by deploying the flowable-rest.war file to a servlet container like Apache Tomcat. However, it can also be used in another web-application by including the servlet and its mapping in your application and add all flowable-rest dependencies to the classpath.

By default the Flowable engine will connect to an in-memory H2 database. You can change the database settings in the db.properties file in the WEB-INF/classes folder. The REST API uses JSON format (http://www.json.org) and is built upon the Spring MVC (http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html).

All REST-resources require a valid Flowable-user to be authenticated by default. Basic HTTP access authentication is used, so you should always include a Authorization: Basic …​== HTTP-header when performing requests or include the username and password in the request-url (for example, http://username:password@localhost:8080/xyz).

We recommend that you use Basic Authentication in combination with HTTPS.

7.1.2. Configuration

The Flowable REST web application uses Spring Java Configuration for starting the Flowable Form engine, defining the basic authentication security using Spring security, and to define the variable converters for specific variable handling. A small number of properties can be defined by changing the engine.properties file you can find in the WEB-INF/classes folder. If you need more advanced configuration options there’s the possibility to override the default Spring beans in XML in the flowable-custom-context.xml file you can also find in the WEB-INF/classes folder. An example configuration is already in comments in this file. This is also the place to override the default RestResponseFactory by defining a new Spring bean with the name restResponsefactory and use your custom implementation class for it.

7.1.3. Usage in Tomcat

Due to default security properties on Tomcat, escaped forward slashes (%2F and %5C) are not allowed by default (400-result is returned). This may have an impact on the deployment resources and their data-URL, as the URL can potentially contain escaped forward slashes.

When issues are experienced with unexpected 400-results, set the following system-property:

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

It’s best practice to always set the Accept and Content-Type (in case of posting/putting JSON) headers to application/json on the HTTP requests described below.

7.1.4. Methods and return-codes

Table 1. HTTP-methods and corresponding operations
Method Operations

GET

Get a single resource or get a collection of resources.

POST

Create a new resource. Also used for executing resource-queries which have a too complex request-structure to fit in the query-URL of a GET-request.

PUT

Update properties of an existing resource. Also used for invoking actions on an existing resource.

DELETE

Delete an existing resource.

Table 2. HTTP-methods response codes
Response Description

200 - Ok

The operation was successful and a response has been returned (GET and PUT requests).

201 - Created

The operation was successful and the entity has been created and is returned in the response-body (POST request).

204 - No content

The operation was successful and entity has been deleted and therefore there is no response-body returned (DELETE request).

401 - Unauthorized

The operation failed. The operation requires an Authentication header to be set. If this was present in the request, the supplied credentials are not valid or the user is not authorized to perform this operation.

403 - Forbidden

The operation is forbidden and should not be re-attempted. This implies an issue with authorization not authentication, it’s an operation that is not allowed. Example: deleting a task that is part of a running process is not allowed and will never be allowed, regardless of the user or process/task state.

404 - Not found

The operation failed. The requested resource was not found.

405 - Method not allowed

The operation failed. The method is not allowed for this resource. For example, trying to update (PUT) a deployment-resource will result in a 405 status.

409 - Conflict

The operation failed. The operation causes an update of a resource that has been updated by another operation, which makes the update no longer valid. Can also indicate a resource that is being created in a collection where a resource with that identifier already exists.

415 - Unsupported Media Type

The operation failed. The request body contains an unsupported media type. Also occurs when the request-body JSON contains an unknown attribute or value that doesn’t have the right format/type to be accepted.

500 - Internal server error

The operation failed. An unexpected exception occurred while executing the operation. The response-body contains details about the error.

The media-type of the HTTP-responses is always application/json unless binary content is requested (for example, deployment resource data), the media-type of the content is used.

7.1.5. Error response body

When an error occurs (both client and server, 4XX and 5XX status-codes) the response body contains an object describing the error that occurred. An example for a 404-status when a task is not found:

1 2 3 4
{ "statusCode" : 404, "errorMessage" : "Could not find a task with id '444'." }

7.1.6. Request parameters

URL fragments

Parameters that are part of the URL (for example, the deploymentId parameter in http://host/flowable-rest/form-api/form-repository/deployments/{deploymentId}) need to be properly escaped (see URL-encoding or Percent-encoding) in case the segment contains special characters. Most frameworks have this functionality built in, but it should be taken into account. Especially for segments that can contain forward-slashes (for example, deployment resource), this is required.

Rest URL query parameters

Parameters added as query-string in the URL (for example, the name parameter used in http://host/flowable-rest/form-api/form-repository/deployments?name=Deployment) can have the following types and are mentioned in the corresponding REST-API documentation:

Table 3. URL query parameter types
Type Format

String

Plain text parameters. Can contain any valid characters that are allowed in URLs. In the case of a XXXLike parameter, the string should contain the wildcard character % (properly URL-encoded). This allows you to specify the intent of the like-search. For example, Tas% matches all values, starting with Tas.

Integer

Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647.

Long

Parameter representing a long value. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.

Boolean

Parameter representing a boolean value. Can be either true or false. All other values other than these will cause a 405 - Bad request response.

Date

Parameter representing a date value. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (e.g. 2013-04-03T23:45Z).

JSON body parameters
Table 4. JSON parameter types
Type Format

String

Plain text parameters. In the case of a XXXLike parameter, the string should contain the wildcard character %. This allows you to specify the intent of the like-search. For example, Tas% matches all values, starting with Tas.

Integer

Parameter representing an integer value, using a JSON number. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647.

Long

Parameter representing a long value, using a JSON number. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.

Date

Parameter representing a date value, using a JSON text. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (for example, 2013-04-03T23:45Z).

Paging and sorting

Paging and order parameters can be added as query-string in the URL (for example, the name parameter used in http://host/flowable-rest/form-api/form-repository/deployments?sort=name).

Table 5. Variable query JSON parameters
Parameter Default value Description

sort

different per query implementation

Name of the sort key, for which the default value and the allowed values are different per query implementation.

order

asc

Sorting order which can be asc or desc.

start

0

Parameter to allow for paging of the result. By default the result will start at 0.

size

10

Parameter to allow for paging of the result. By default the size will be 10.

7.2. Deployment

When using tomcat, please read Usage in Tomcat.

7.2.1. List of Deployments

GET form-repository/deployments
Table 6. URL query parameters
Parameter Required Value Description

name

No

String

Only return deployments with the given name.

nameLike

No

String

Only return deployments with a name like the given name.

category

No

String

Only return deployments with the given category.

categoryNotEquals

No

String

Only return deployments which don’t have the given category.

tenantId

No

String

Only return deployments with the given tenantId.

tenantIdLike

No

String

Only return deployments with a tenantId like the given value.

withoutTenantId

No

Boolean

If true, only returns deployments without a tenantId set. If false, the withoutTenantId parameter is ignored.

sort

No

id (default), name, deploytime or tenantId

Property to sort on, to be used together with the order.

Table 7. REST Response codes
Response code Description

200

Indicates the request was successful.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "data": [ { "id": "10", "name": "flowable-form-examples", "deploymentTime": "2010-10-13T14:54:26.750+02:00", "category": "examples", "url": "http://localhost:8081/form-api/form-repository/deployments/10", "tenantId": null } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

7.2.2. Get a deployment

GET form-repository/deployments/{deploymentId}
Table 8. Get a deployment - URL parameters
Parameter Required Value Description

deploymentId

Yes

String

The ID of the deployment to get.

Table 9. Get a deployment - Response codes
Response code Description

200

Indicates the deployment was found and returned.

404

Indicates the requested deployment was not found.

Success response body:

1 2 3 4 5 6 7 8
{ "id": "10", "name": "flowable-form-examples", "deploymentTime": "2010-10-13T14:54:26.750+02:00", "category": "examples", "url": "http://localhost:8081/form-api/form-repository/deployments/10", "tenantId" : null }

7.2.3. Create a new deployment

POST form-repository/deployments

Request body:

The request body should contain data of type multipart/form-data. There should be exactly one file in the request, any additional files will be ignored. The deployment name is the name of the file-field passed in.

An additional parameter (form-field) can be passed in the request body with name tenantId. The value of this field will be used as the identifier of the tenant in which this deployment is done.

Table 10. Create a new deployment - Response codes
Response code Description

201

Indicates the deployment was created.

400

Indicates there was no content present in the request body or the content mime-type is not supported for deployment. The status-description contains additional information.

Success response body:

1 2 3 4 5 6 7 8
{ "id": "10", "name": "simple.form", "deploymentTime": "2010-10-13T14:54:26.750+02:00", "category": null, "url": "http://localhost:8081/form-api/form-repository/deployments/10", "tenantId" : "myTenant" }

7.2.4. Delete a deployment

DELETE form-repository/deployments/{deploymentId}
Table 11. Delete a deployment - URL parameters
Parameter Required Value Description

deploymentId

Yes

String

The identifier of the deployment to delete.

Table 12. Delete a deployment - Response codes
Response code Description

204

Indicates the deployment was found and has been deleted. Response-body is intentionally empty.

404

Indicates the requested deployment was not found.

7.2.5. Get a deployment resource content

GET form-repository/deployments/{deploymentId}/resourcedata/{resourceId}
Table 13. Get a deployment resource content - URL parameters
Parameter Required Value Description

deploymentId

Yes

String

The identifier of the deployment the requested resource is part of.

resourceId

Yes

String

The identifier of the resource to get the data for. Make sure you URL-encode the resourceId in case it contains forward slashes. Fro example, use forms%2Fmy-form.form instead of forms/my-form.form.

Table 14. Get a deployment resource content - Response codes
Response code Description

200

Indicates both deployment and resource have been found and the resource data has been returned.

404

Indicates the requested deployment was not found or there is no resource with the given ID present in the deployment. The status-description contains additional information.

Success response body:

The response body will contain the binary resource-content for the requested resource. The response content-type will be the same as the type returned in the resources mimeType property. Also, a content-disposition header is set, allowing browsers to download the file instead of displaying it.

7.3. Form Definitions

7.3.1. List of Form definitions

GET form-repository/form-definitions
Table 15. List of form definitions - URL parameters
Parameter Required Value Description

version

No

integer

Only return form definitions with the given version.

name

No

String

Only return form definitions with the given name.

nameLike

No

String

Only return form definitions with a name like the given name.

key

No

String

Only return form definitions with the given key.

keyLike

No

String

Only return form definitions with a name like the given key.

resourceName

No

String

Only return form definitions with the given resource name.

resourceNameLike

No

String

Only return form definitions with a name like the given resource name.

category

No

String

Only return form definitions with the given category.

categoryLike

No

String

Only return form definitions with a category like the given name.

categoryNotEquals

No

String

Only return form definitions which don’t have the given category.

deploymentId

No

String

Only return form definitions which are part of a deployment with the given identifier.

latest

No

Boolean

Only return the latest form definition versions. Can only be used together with key and keyLike parameters, using any other parameter will result in a 400-response.

sort

No

name (default), id, key, category, deploymentId and version

Property to sort on, to be used together with the order.

Table 16. List of form definitions - Response codes
Response code Description

200

Indicates request was successful and the form definitions are returned

400

Indicates a parameter was passed in the wrong format or that latest is used with other parameters other than key and keyLike. The status-message contains additional information.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
{ "data": [ { "id" : "818e4703-f1d2-11e6-8549-acde48001122", "url" : "http://localhost:8182/form-repository/form-definitions/simpleForm", "version" : 1, "key" : "simpleForm", "category" : "Examples", "deploymentId" : "818e4703-f1d2-11e6-8549-acde48001121", "parentDeploymentId" : "2", "name" : "The Simple Form", "description" : "This is a form for testing purposes", } ], "total": 1, "start": 0, "sort": "name", "order": "asc", "size": 1 }

7.3.2. Get a form definition

GET repository/form-definitions/{formDefinitionId}
Table 17. Get a form definition - URL parameters
Parameter Required Value Description

formDefinitionId

Yes

String

The identifier of the process definition to get.

Table 18. Get a form definition - Response codes
Response code Description

200

Indicates the form definition was found and returned.

404

Indicates the requested form definition was not found.

Success response body:

1 2 3 4 5 6 7 8 9 10 11
{ "id" : "818e4703-f1d2-11e6-8549-acde48001122", "url" : "http://localhost:8182/form-repository/form-definitions/simpleForm", "version" : 1, "key" : "simpleForm", "category" : "Examples", "deploymentId" : "818e4703-f1d2-11e6-8549-acde48001121", "parentDeploymentId" : "2", "name" : "The Simple Form", "description" : "This is a form for testing purposes", }

7.3.3. Get a form definition resource content

GET repository/form-definitions/{formDefinitionId}/resourcedata
Table 19. Get a form definition resource content - URL parameters
Parameter Required Value Description

formDefinitionId

Yes

String

The identifier of the form definition to get the resource data for.

Response:

Exactly the same response codes/boy as GET form-repository/deployment/{deploymentId}/resourcedata/{resourceId}.

7.3.4. Get a form definition Form model

GET form-repository/form-definitions/{formDefinitionId}/model
Table 20. Get a form definition Form model - URL parameters
Parameter Required Value Description

formDefinitionId

Yes

String

The identifier of the form definition to get the model for.

Table 21. Get a form definition Form model - Response codes
Response code Description

200

Indicates the form definition was found and the model is returned.

404

Indicates the requested form definition was not found.

Response body: The response body is a JSON representation of the org.flowable.form.model.FormModel and contains the full form definition model.

7.4. Form Instances

7.4.1. Get a form instance

GET form/form-instances/{formInstanceId}
Table 22. Get a form instance - URL parameters
Parameter Required Value Description

formInstanceId

Yes

String

The identifier of the form instance to get.

Table 23. Get a form instance - Response codes
Response code Description

200

Indicates the form instance was found and returned.

404

Indicates the requested form instance was not found.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12
{ "id":"48b9ac82-f1d3-11e6-8549-acde48001122", "url":"http://localhost:8182/form/form-instances/48b9ac82-f1d3-11e6-8549-acde48001122", "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "submittedDate":"2013-04-17T10:17:43.902+0000", "submittedBy":"testUser", "formValuesId":"818e4703-f1d2-11e6-8549-acde48001110", "tenantId": null }

7.4.2. Store a form instance

POST form/form-instances

Request body (start by process definition id):

1 2 3 4 5 6 7 8 9 10 11 12 13
{ "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "businessKey":"myBusinessKey", "variables": [ { "name":"input1", "value":"test", } ] }

Request body (start by form definition key):

1 2 3 4 5 6 7 8 9 10 11 12 13
{ "formDefinitionKey":"simpleForm", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "businessKey":"myBusinessKey", "variables": [ { "name":"input1", "value":"test", } ] }

Only one of formDefinitionId or formDefinitionKey can be used in the request body. Parameters variables and tenantId are optional. If tenantId is omitted, the default tenant will be used. More information about the variable format can be found in the REST variables section.

Table 24. Store a form instance - Response codes
Response code Description

201

Indicates the form instance was created.

400

Indicates either the form definition was not found (based on identifier or key), no form instance was stored by sending the given message, or an invalid variable has been passed. Status description contains additional information about the error.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12
{ "id":"48b9ac82-f1d3-11e6-8549-acde48001122", "url":"http://localhost:8182/form/form-instances/48b9ac82-f1d3-11e6-8549-acde48001122", "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "submittedDate":"2013-04-17T10:17:43.902+0000", "submittedBy":"testUser", "formValuesId":"818e4703-f1d2-11e6-8549-acde48001110", "tenantId": null }

7.4.3. List of form instances

GET form/form-instances
Table 25. List of form instances - URL query parameters
Parameter Required Value Description

id

No

String

Only return process instance with the given identifier.

formDefinitionId

No

String

Only return form instances with the given form definition identifier.

formDefinitionIdLike

No

String

Only return form instances with a form definition identifier like the given value.

taskId

No

String

Only return form instances with the given task identifier.

taskIdLike

No

String

Only return form instances with a task identifier like the given value.

processInstanceId

No

String

Only return form instances with the given process instance identifier.

processInstanceIdLike

No

String

Only return form instances with a process instance identifier like the given value.

processDefinitionId

No

String

Only return form instances with the given process definition identifier.

processDefinitionIdLike

No

String

Only return form instances with a process definition identifier like the given value.

submittedBy

No

String

Only return form instances with the given submitted by.

submittedByLike

No

String

Only return form instances with a submitted by like the given value.

tenantId

No

String

Only return process instances with the given tenantId.

tenantIdLike

No

String

Only return process instances with a tenantId like the given value.

withoutTenantId

No

Boolean

If true, only returns process instances without a tenantId set. If false, the withoutTenantId parameter is ignored.

sort

No

String

Sort field, should be either one of submittedDate (default) or tenantId.

Table 26. List of form instances - Response codes
Response code Description

200

Indicates request was successful and the form instances are returned

400

Indicates a parameter was passed in the wrong format. The status message contains additional information.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "data":[ { "id":"48b9ac82-f1d3-11e6-8549-acde48001122", "url":"http://localhost:8182/form/form-instances/48b9ac82-f1d3-11e6-8549-acde48001122", "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "submittedDate":"2013-04-17T10:17:43.902+0000", "submittedBy":"testUser", "formValuesId":"818e4703-f1d2-11e6-8549-acde48001110", "tenantId": null } ], "total":1, "start":0, "sort":"submittedDate", "order":"asc", "size":1 }

7.4.4. Query form instances

POST query/form-instances

Request body:

1 2 3
{ "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122" }

The request body can contain all possible filters that can be used in the List process instances URL query.

The general paging and sorting query-parameters can be used for this URL.

Table 27. Query form instances - Response codes
Response code Description

200

Indicates request was successful and the form instances are returned

400

Indicates a parameter was passed in the wrong format. The status message contains additional information.

Success response body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "data":[ { "id":"48b9ac82-f1d3-11e6-8549-acde48001122", "url":"http://localhost:8182/form/form-instances/48b9ac82-f1d3-11e6-8549-acde48001122", "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122", "taskId":"88", "processInstanceId":"66", "processDefinitionId":"oneTaskProcess:1:158", "submittedDate":"2013-04-17T10:17:43.902+0000", "submittedBy":"testUser", "formValuesId":"818e4703-f1d2-11e6-8549-acde48001110", "tenantId": null } ], "total":1, "start":0, "sort":"submittedDate", "order":"asc", "size":1 }

7.5. Form Engine

7.5.1. Get form engine info

GET form-management/engine

Returns a read-only view of the engine that is used in this REST-service.

Success response body:

1 2 3 4 5 6
{ "name":"default", "version":"6.2.0", "resourceUrl":"file://flowable/flowable.form.cfg.xml", "exception":null }
Table 28. Get engine information - Response codes
Response code Description

200

Indicates the form engine information is returned.