Admin Guide
Table of Contents

Version 1.4.0, December 2015

1. Introduction

This guide describes how to install and configure the Alfresco Activiti BPM Suite, a commercially supported suite of components built by Alfresco on top of the Activiti process engine (see Activiti Community BPM Platform).

2. Upgrading from a previous release

The easiest and safest way to upgrade the application is as follows:

  • Stop all the webservers running the application.

  • Deploy the new WAR file in your webserver (for Tomcat, this means for example putting it in /webapps).

  • Boot one web server. The database upgrade changes will now be applied.

  • When the first server is correctly booted up and you have verified the application works correctly, boot up the other servers.

2.1. Upgrading to 1.4.0

In version 1.4.0, the Elasticsearch library dependency has been upgraded to 1.7.3:

  • When using Elasticsearch in the embedded mode, no changes are required. The existing data will be upgraded automatically.

  • When connecting to an external Elasticsearch cluster, it is advised to upgrade those Elasticsearch servers to version 1.7.3.

3. Admin checklist for a new installation

Activiti ships with defaults for most configuration settings. The first thing to configure is the connection to the database. See the section Database Configuration how to configure that.

You can now deploy the WAR file into your web server (for example for Tomcat dropping it in the webapps folder) and verify if the application works correctly.

Further things to consider from that point on:

  • The users and groups are stored by default in database tables. Most likely in your company the users and groups are stored in a LDAP or Active Directory system. See the section on External Identity Management (LDAP/Active Directory) to learn how to connect this system with the Activiti BPM Suite.

  • By default, the system won’t send any emails. Check the section Email Server Configuration to learn how to configure the email server settings.

  • By default, uploaded content, script files, and other content are stored on the file system on the same machine as where the application is running. When using multiple servers, it is important that the location on the file system is actually a mounted shared drive, such that all server nodes can access it. Read the section Content Storage for configuration options on this.

  • Elasticsearch is used to store historical information about process execution and to generate reports from it. By default, an embedded Elasticsearch server is used. It is possible to switch this to connect to cluster of Elasticsearch nodes external to the Activiti BPM Suite (for performance or because such a cluster already exists in your organisation). See the section Elasticsearch Configuration for more information on this.

4. High Level Architecture

The following diagram gives a high level overview of the technical components in the Activiti BPM Suite:

high level architecture

The Alfresco Activiti BPM Suite is packaged as a standard Java Web application (WAR file) that can be deployed in any supported Java web container. The WAR file contains both the Java logic, the REST API resources and the user interface HTML and JavaScript files. The application is stateless, which means it does not use any sessions, and requests can be handled by any node in a clustered setup (see Cluster Configuration and Monitoring for more information on multi-node setup).

Some technical implementation details:

  • The Activiti process engine (enterprise edition) is embedded within the Alfresco Activiti BPM Suite and directly used through its Java API.

  • The REST API has two parts:

    • The REST API that exposes operations in the context of the applications that are part of the Alfresco Activiti BPM suite application. This REST API is used by the Alfresco Activiti BPM Suite user interface and should be used in most cases

    • The REST API that exposes the core engine Actviti API directly (see the Activiti User Guide). Note that this interface is intended for highly custom applications as it exposes the full capabilities and data within the Activiti engine. Consequently, a user with the tenant admin or tenant manager role is needed to access this part of the REST API for security reasons.

  • The application requires Java 7 and is compliant with JEE 6 technologies. The Activiti Engine itself also supports Java 6, however for components such as Elasticsearch, the Alfresco Activiti BPM Suite requires Java 7 or Java 8. See for more information on supported platforms.

  • The backend logic specific to the Alfresco Activiti BPM Suite logic is implemented using Spring 4 and JPA (Hibernate).

  • All user interfaces are written using HTML5 and AngularJS

The Alfresco Activiti BPM Suite uses the following external systems:

  • A relational database

  • An Elasticsearch installation. Note that the application ships with an embedded Elasticsearch by default, which requires little configuration.

  • A file system (shared file system in multi-node setup) where content is stored

  • An identity management store (LDAP or Active Directory) is optional. By default, a database-backed user and group store is used.

The Activiti process engine used within the Alfresco Activiti BPM Suite can be managed using the Activiti Administrator application. This is also provided as a WAR file with Alfresco Activiti BPM Suite distributions.

The Activiti Designer is an Eclipse plugin that can be used by developers to create BPMN 2.0 process definitions within their Eclipse IDE. It is possible to configure the plugin so that it can pull and push process definitions model to the Alfresco Activiti BPM Suite application. For more information on the Designer plugin, see the Activiti Designer User Guide.

The application can also connect to other on-premise or cloud systems, such as Alfresco One, Box and Google Drive (not shown on the diagram).

5. Licensing

The Alfresco Activiti BPM Suite needs a valid license to work properly. This license is provided by Alfresco in the form of a file named activiti.lic. This file should be placed either:

  • on the classpath of the web application

  • in the home folder of the user used to start the web container, in the $USER_HOME/.activiti/enterprise-license/ (note the dot before activiti) folder.

6. Installing Alfresco Activiti

If you have signed up for the Alfresco Activiti 30-day trial, you will have received an email containing links to the installers and your trial license file.

If you want to set up Alfresco Activiti using your own web application container and database product, download the WAR distribution and follow the Installing using the WAR distribution

6.1. Installing using an installer

The installer for Windows, OSX, or Linux installs an evaluation copy of Alfresco Activiti that should only be used for quick trials and experimentation. The installer will install all the prerequisite software that Alfresco Activiti needs on your platform. You will need to add a license file, which will have been provided with the download links.

The installed Alfresco Activiti runs in its own Apache Tomcat container, and uses a built-in h2 database. This database is not suitable for production use.

6.1.1. Using the Windows installer

Install Alfresco Activiti on Windows using these steps.

  1. Download the installer by clicking on the link in the Alfresco Activiti 30-day trial email.

  2. Download the license file.

  3. Find the installer, and double-click to launch.

  4. Click yes if a User Account Control dialog is displayed

  5. Follow the instructions in the installer dialogs.

    You can choose your own installation folder in the second dialog.

  6. Install the license file.

    Copy the activiti.lic file to the <ActivitiInstall>/tomcat/lib folder.

6.1.2. Using the OSX installer

Install Alfresco Activiti on OSX using these steps.

  1. Download the installer zip file by clicking on the link in the Alfresco Activiti 30-day trial email.

  2. Download the license file.

  3. In Finder, locate the zip or dmg file and double-click to open the archive.

  4. Find the unzipped installer, and double-click to launch.

  5. If you see the message "can’t be opened because it is from an unidentified developer”, control-click the installer and choose Open. Click Open in the warning dialog to launch the installer.

  6. Follow the instructions in the installer dialogs.

    You can choose your own installation folder in the second dialog.

  7. Install the license file.

    Copy the activiti.lic file to the <ActivitiInstall>/tomcat/lib folder.

6.1.3. Using the Linux installer

Install Alfresco Activiti on Linux using these steps.

  1. Download the installer by clicking on the link in the Alfresco Activiti 30-day trial email.

  2. Download the license file.

  3. Using the command line, find the installer, and change the permissions on the file as follows:

    chmod 777 <installer-file-name>
  4. Run the installer from the command line.

  5. Follow the instructions in the installer dialogs.

    You can choose your own installation folder in the second dialog.

  6. Install the license file.

    Copy the activiti.lic file to the <ActivitiInstall>/tomcat/lib folder.

6.2. Installing using the WAR distribution

Alfresco Activiti is installed as two web applications. You can install the two applications in the same web container, although in production configurations it is more usual to use separate containers. For example, if you run them in separate Tomcat instances, you can stop the user webapp running, while continuing to use the administration webapp to change configurations or perform other operations on one or multiple Activiti servers.


This contains the Alfresco Activiti Administrator webapp. You use this to administer and monitor your Alfresco Activiti engines.


This contains the Alfresco Activiti webapp. This webapp is also the user interface for people involved in the task and processes running in the Activiti engine. You also use this webapp to create and manage process definitions, and to display and define analytics reports on users' tasks and processes.

6.2.1. Software requirements

The Alfresco Activiti WAR (Web Application Archive) files are installed in a Java web container. Alfresco Activiti uses a database to store data.

Please refer to the Alfresco website for a list of supported combinations of Web containers and database products.

6.2.2. Installing the Alfresco Activiti App

Perform these steps to install Alfresco Activiti webapp, activiti-app.

  1. Install your Web container and database.

    These instructions use Tomcat and MySQL as examples.

  2. Create a MySQL schema.

    The default name is activiti.

    For example in the mysql utility, issue the following

    create database activiti;
  3. Copy the activiti-app WAR file into your web container.

    The default application name is alfresco-app You can change this name, and if you do, you will need to update the configuration to the correct context root.

    For example, for Tomcat copy the alfresco-app.war to the webapps folder.

  4. Edit the properties in the example provided with the WAR file

    1. Uncomment and modify JDBC details as necessary for your type of database and the schema to be used.

    2. Modify the contentstorage.fs.rootFolder to specify a location for file content to be stored.

    3. Modify the to specify a location for the search and analytics indexes.

    4. Copy the file onto the container classpath, for example the <ActivitiInstall>/tomcat/lib folder

6.2.3. Installing the Alfresco Activiti Administrator webapp

Perform these steps to install Alfresco Activiti Administrator webapp, activiti-admin.

  1. Install your Web container.

    These instructions use Tomcat as an example. You can use the same web container that you use for the Alfresco Activiti webapp.

  2. Install your database.

    These instructions use MySQL as an example. You can use the same database instance that you created for the Alfresco Activiti webapp.

  3. Create a MySQL schema.

    The default name is activitiadmin.

    For example in the mysql utility, issue the following

    create database activitiadmin;
  4. Copy the activiti-admin WAR file into your web container.

    The default application name is alfresco-admin You can change this name, and if you do, you will need to update the configuration to the correct context root.

    For example, for Tomcat copy the alfresco-admin.war to the webapps folder.

  5. Edit the properties in the example provided with the WAR file

    1. Uncomment and modify JDBC details as necessary for your type of database and the schema to be used.

    2. Copy the file onto the container classpath, for example the <ActivitiInstall>/tomcat/lib folder

6.3. Starting the Alfresco app

Perform the following steps to start Alfresco Activiti.

Note: If you are using Java 1.7, use the following JVM options as a minimum when starting your web container. This is not necessary for Java 1.8 and above: -Xms1024m -Xmx2048m -XX:MaxPermSize=512m

  1. Start your web container.

    For example to start Tomcat, run bin/ or bin/startup.bat

6.4. Stopping the Alfresco app

Perform the following steps to stop Alfresco Activiti.

  1. Stop your web container.

    For example to stop Tomcat, run bin/ or bin/shutdown.bat

6.5. Multi-tenant post-installation

If you have purchased a multi-tenant license, you need to sign on as the default admin user and perform some minimum configuration after installation. You do not need to complete this configuration for the 30-day trial or standard installation, as these are not multi-tenant.

To fully utilize the capabilities of Activiti, you should create a tenant and add users to that tenant. This allows the use of user groups and enables auto-complete of user names.

  1. In your web browser go to the Alfresco Activiti app, http://localhost:8089/activiti-app

    The first time you do this, you will see the login panel.

  2. Log in as the default administration user, using the password admin .

  3. Click the Identity management tile.

  4. Click the Tenants menu item.

  5. Click Create tenant .

  6. Provide a name for the tenant and click Save .

When you create users, you can specify your new tenant name.

7. Multi Node Clustered Setup

Running the application on multiple servers, for performance, resilience or failover reasons, is straightforward. The application is architected to be stateless. This means that any server can handle any request from any user. When using multiple servers, it is enough to have a traditional load balancer (or proxy) in front of the servers running the Alfresco Activiti BPM Suite application. Scaling out is done in a "horizontal" way, by simply adding more servers behind the load balancer.

multi node setup

Do note that each of the servers will connect to the same relational database. While scaling out by adding more servers, do not forget to also make sure the database can handle the additional load.

8. Activiti Application

The Alfresco Activiti BPM Suite is configured through a properties file named This file must be on the classpath to be found. The following options are possible in relation to this properties file:

  • An file with default values can be found in the WAR file (or exploded WAR folder) in the WEB-INF/classes/META-INF/activiti-app folder.

  • An file with custom values can be placed on the classpath. For example: the WEB-INF/classes folder of the WAR, the /lib folder of Tomcat or other places specific to the web container being used.

The values of a configuration file on the classpath have precedence over the values in the WEB-INF/classes/META-INF/activiti-app/ file.

For the Alfresco Activiti BPM Suite’s web user interface there is an additional configuration file named app-cfg.js. This file is located inside the .war file’s script directory.

8.1. Minimal configuration

Minimally, the application needs the following settings to run:

All the other properties have defaults that should not stop the application from starting and working.

8.2. General Server settings

The following properties are general server settings. While they do have defaults, it might be necessary to change them:

Property Description Default


The context root on which the user accesses the application. This is used in various places to generate urls to correct resources.



A key that is used for cookie validation. In a multi node setup, all nodes must have the same value for this property.


8.3. Database Configuration

8.3.1. Using JDBC Connection Parameters

Following properties need to be set to change the database:

Property Description


The JDBC driver used to connect to the database. Note that the driver must be on the classpath of the web application


The JDBC url used to connect to the database


The user of the database system that is used to connect to the database


The password of the above user


1 2 3 4 5
datasource.driver=com.mysql.jdbc.Driver datasource.url=jdbc:mysql:// datasource.username=alfresco datasource.password=alfresco

8.3.2. Connection Pooling

When using JDBC parameters to connect to the database, it is also possible to tweak the connection pooling settings to better suit the anticipated load. Following properties can be set:

Property Description Default


The minimum number of connections in the connection pool.



The maximum number of connections in the connection pool.



The number of additional connections the system will try to acquire each time the connection pool is exhausted.



The query used to verify that the connection is still valid

No default value (not a required property). The value depends on the database: select 1 for H2, MySQL, PostgreSQL and Microsoft SQL Server, SELECT 1 FROM DUAL for Oracle and SELECT current date FROM sysibm.sysdummy1 for DB2.


Boolean value. If true, an operation will be performed asynchronously on every connection checkin to verify that the connection is valid. For best performance, a proper datasource.preferred-test-query should be set.



Boolean value. If true, an operation will be performed asynchronously on every connection checkout to verify that the connection is valid. Testing Connections on checkout is the simplest and most reliable form of Connection testing. For best performance, a proper datasource.preferred-test-query should be set.



The number of seconds a connection can be pooled before being discarded.



Number of seconds that connections in excess of minPoolSize should be permitted to remain idle in the pool before being discarded. The intention is that connections remain in the pool during a load spike.


The connection pooling framework used is C3P0. It has extensive documentation on the settings described above.

8.3.3. Using a JNDI Datasource

When a JNDI datasource is configured in the web container or application server, the JNDI name needs to be configured with following properties:

Property Description Default

The JNDI name of the datasource. This varies depending on the application server or web container.



Set whether the lookup occurs in a J2EE container, i.e. if the prefix "java:comp/env/" needs to be added if the JNDI name doesn’t already contain it.


Example (on JBoss EAP 6.3):


8.3.4. Hibernate Settings

The Alfresco Activti BPM Suite specific logic is written using JPA 2.0 with Hibernate as implementation. Note that the Activiti Process Engine itself uses MyBatis for full control of each SQL query.

The following settings need to be set:

Property Description Mandatory


The dialect implementation that Hibernate uses. This is database specific.

Yes. Very important to set the correct dialect, or the app might not even boot up!

The following values are those that are used to test the Alfresco Activiti BPM Suite:

Database Dialect







SQL Server






Optionally, the hibernate.show_sql property can be set to true if the SQL being executed needs to be printed to the log.

8.4. Business Calendar Settings

Business Calendar is used to calculate tasks' relative due dates. To exclude weekends when calculating tasks' relative due dates, calendar.weekends property can be set as follows:

1 2
# Weekend days comma separated (day's first 3 letters in capital) calendar.weekends=SAT,SUN

8.5. Initial User Created on First Start Up

When the application starts for the first time, it will verify that there is at least one user in the system. If not, a user with superuser rights will be created.

The default user id to sign in with is using password admin. This should be changed after signing in for the first time.

The initial user details can be modified (must be done before first start up) with following properties:

Property Description

The email address used to create the first user, which also acts as the sign in identifier.

Capabilities in the Alfresco Activiti BPM Suite are managed by adding users into certain groups. The first user will have all capabilities enabled. This property defines the name of the group to which the first user will be added. By default 'Superusers'.

8.6. Email Server Configuration

The application sends out emails to users on various events (for example, when a task is assigned to the user).

Following properties must be set to configure the email server:

Property Description


Enables or disables the email functionality as a whole. By default false, so make sure to set it to true when needing email functionality.

The host address of the email server.


The port on which the email server is running.


Boolean value. Indicates if the email server needs credentials to make a connection. If so, both username and password need to be set.


The username used as credentials when email.useCredentials is true.


The password used as credentials when email.useCredentials is true.


Defines if SSL is needed for the connection to the email server.


Defines if TLS is needed for the connection to the email server. This needs to be true when Google mail is used as the mail server for example.


The email address that is used in the from field of any email sent.

The name that is used in the from field of the email sent.

Some emails will have a feedback email address that people can use to send feedback. This property defines this.

Emails are created by a templating engine. The emails can contain various links to the runtime system to bring the user straight to the correct page in the web application.

The following property need to be set to make these links correct. The example in the table below uses 'localhost' as host address and 'activiti-app' as the context root:

Property Example



8.7. Elasticsearch Configuration

Elasticsearch is an open source data store for json documents. Its main features include fast full text search and analytics.

Elasticsearch is used within the Alfresco Activiti BPM Suite as a data store for generating analytics and reports. The full text search capabilities are not currently used, but will be in a future release.

There are two ways Elasticsearch can be configured in the application:

  • Embedded: the Elasticsearch server starts up embedded within the Alfresco Activiti BPM Suite. The embedded instances can be configured to autodiscover other nodes (but this is disabled by default!).

  • Client: the application only creates a client, which connects to an Elasticsearch cluster. This approach is much like connecting to a relational database.

One thing to keep in mind is that an Elasticsearch client will always be created. In the Client use case, this is all that will be instantiated. In the Embedded setup, an Elasticsearch client will be created that connects to a cluster of which the local node is part. In Elasticsearch terminology, a client node and a data node.

8.7.1. General Settings

The following properties are applicable to both the embedded and client setup:

Property Description Default

The name of the Elasticsearch cluster to connect to


The name of the specific node of this server. The client node will have this name plus the suffix -client. In the embedded setup there will also be a data node with a -data suffix.


The name of the index in which the data will be stored. Only change this if there is a nameclash for some reason in your Elasticsearch installation



When running the Alfresco Activiti BPM Suite with multi-tenancy, each tenant has its own index alias. Change this value to change the prefix applied to the alias.



Enables the HTTP REST API of Elasticsearch. It is advised not to set this to true, unless traffic to it is strictly controlled by firewall rules.



Enables (when elastic-search.enable.http is true) cross-origin resource sharing, i.e. whether a browser on another origin can do requests to Elasticsearch.


Elasticsearch nodes (both client and data Elasticsearch nodes, so this applies for both embedded and client setups) need to find each other to work in a clustered setup. This can be configured using multicast or unicast:

To change the type of discovery:

Property Description Default


The way nodes find each other: multicast or unicast.


When using multicast, the following properties can be set:

Property Description Default

The multicast group address to use.


The multicast port to use.



The time-to-live of the multicast message.



The address to bind to.

All available network interfaces (

When using unicast, only one property needs to be set:

Property Description Default


The way nodes find each other: multicast or unicast.

Either an array setting or a comma delimited setting. Each value is either in the form of host:port, or in the form of host[port1-port2]

8.7.2. Embedded Setup

This is the default configuration. The following properties need to be set when using Elasticsearch in an embedded setup:

Property Description Default




Defines where Elasticsearch will store its data on disk. $user_home$ can be used in the path. Make sure the application or application server has the right privileges to write to this path. To backup the Elasticsearch data easily, simply backup the content of this folder.


Note that when booting up multiple Activiti BPM Suite instances with Elasticsearch configured to be embedded, they will not cluster. Out of the box clustering has been disabled. To enable it, set the elastic-search.discovery.type to the wanted type and configure it appropiately.

8.7.3. Client Setup

To connect to an externally running Elasticsearch cluster, set following property. Combined with the general settings above, that’s all that is needed.

Property Description



Note that no data is stored on the server on which the application is running (contrary to the embedded setup). The data fully resides within the externally managed Elasticsearch cluster.

The version used in the application is Elasticsearch 1.7.3. It is recommended that you use the same version as the library JAR.

8.7.4. Disabling Elasticsearch

To disable Elasticsearch (embedded or the client), set the elastic-search.server.type property to none.

Note that the Analytics component will no longer work.

8.7.5. Event Processing for analytics

The event processing is closely related to the Elasticsearch configuration. The main concept is depicted in the diagram below.

analytics event processing
  1. The Activiti Process Engine is configured in such a way that it generates events for everything happening related to process execution (processes started, task completed, etc). These events are stored in the database (such that there is no problem with transactionality, in the sense that writing the events to the database succeeds or fails with the regular Activiti process execution data).

  2. A component called event processor will asynchronously check for new entries in the database table for the events. The events will be processed and transformed to JSON.

  3. The JSON event is asynchronously sent to Elasticsearch. From that point on the data will show up in the reports.

The event processor is architected in a way that it works without collisions in a multi node clustered setup. Each of the event processors will first try to lock events before processing them. If a node goes down during event processing (after locking), an expired events processor component will pick them up and process them as regular events.

The event processing can be configured, but leaving the default values should cater for typical scenarios.

Property Description Default


Set to false if no Activiti events need to be generated. Do note that the reporting/analytics event data is then lost forever.



Set to false to not to event processing. This can be useful in a clustered setup where only sone nodes do the processing.



The number of events that are attempted to be locked and fetched to be processed in one transaction. Larger values equate to more memory usage, but less database traffic.



The cron expression that defines how often the events generated by the Activiti process engine are processed (i.e. read from the database and fed into Elastic Search). By default 30 seconds. If events do not need to appear quickly in the analytics, it is advised to make this less frequent to put less load on the database.

0/30 * * * * ?


The cron expression that defines how often 'expired' events are processed. These are events that were locked, but never processed (such as when the node processing them went down).

0 0/30 * * * ?


The maximum time an event can be 'locked' before it is seen as expired. After that it can be taken by another processor. Expressed in milliseconds.


To keep the database table where the Activiti Process Engine writes the events small and efficient, processed events are either moved to another table or deleted. Possible values are move and delete. Move is the safe option, as it allows for reconstructing the Elasticsearch index if the index was to get corrupted for some reason.



The cron expression that defines how often the action above happens.

0 25/45 * * * ?

8.7.6. Backing up Elasticsearch data

Backing up the data stored in Elasticsearch is a topic described in detail in de Elastic search documentation. Do note that when using the snapshot functionality of ElasticSearch, this means the HTTP interface needs to be enabled and firewall rules need to be in place to avoid access from the general public.

When running Elasticsearch in embedded mode, the folder configured to store the Elaticsearch data can also be backed up. Note that this might not included the latest changes (as they might not yet have been flushed to disk).

8.7.7. Rebuilding the Elasticsearch indices

In very exceptional scenarios it might happen that an Elasticsearch index gets corrupted and becomes unusable. All data that has been sent to Elasticsearch is stored in the relational database (except if the property has been set to delete, in which case the data is gone).

Rebuilding the indices also might be needed if changing some core Elasticsearch settings (for example number of shards).

Events are stored in the ACT_EVT_LOG table before they are processed. The IS_PROCESSED_ flag is set to 0 when the event is inserted and changed to 1 when the event is processed and sent to ElasticSearch. An asynchronous component will move those table rows with '1' for the flag to the PROCESSED_ACTIVITI_EVENTS.

So, given this information, it is clear that rebuilding the Elasticsearch index means doing the following :

  • Remove the data from Elasticsearch (deleting the data folders for example in the embedded mode)

  • Copy the rows from PROCESSED_ACTIVITI_EVENTS to ACT_EVT_LOG and setting the IS_PROCESSED flag to 0 again.

To make things a little bit complex, due to historical reasons, the DATA_ column has different types in ACT_EVT_LOG (byte array) and PROCESSED_ACTIVITI_EVENTS (long text). So a data type conversion is needed when moving rows between those tables.

The following code example does that (using Java, but could be done with other languages). It also first writes the content of PROCESSED_ACTIVITI_EVENTS to a .csv file. This is also useful when this table becomes too big in size: store the data in a file and remove the rows from the database table.

8.8. Application Access and default example app

It is possible to configure whether users get access to the model editors (the Kickstart application) and the analytics application.

Access to the default application is configured through capabilities. In the admin UI, it is possible to create so-called 'system groups'. These groups have a set of capabilities. All users part of that group have those capabilities.

The following settings configure app access when a new user is created in the system (manuall or through LDAP sync). To enable access, set the property app.[APP-NAME].default.enabled to true. If true, a newly created user will be given access to this app.

The access is configured by adding the user to a group with a certain capability that enabled the app. The name of that group can be configured using the app.[APP-NAME] property. If this property is set, and the app.[APP-NAME].default.enabled property is set to true, the group with this name will be used to add the user to and provide access to the app. If the group does not exist, it is created. If the property is commented, and app.[APP-NAME].default.enabled property, a default name is used.

Currently possible app names: { analytics | kickstart }

Property default






The following setting, if set to 'true', will create a default example app with some simple review and approve processes for every newly created user.

Property default


8.9. Activiti Process Definition Cache

The Activiti Process Engine operates in a stateless way. But there is, of course, data that will never change, which makes it a prime candidate for caching.

A process definition is an example of such ‘static data’. When you deploy a BPMN 2.0 XML file to the Activiti engine, the engine parses it to something it can execute, and stores the xml and some data, such as the description, business key, in the database. Such a process definition will never change. Once it’s in the database, the stored data will remain the same until the process definition is deleted.

On top of that, parsing a BPMN 2.0 XML to something executable is quite a costly operation compared with other engine operations. This is why the Activiti engine internally uses a process definition cache to store the parsed version of the BPMN 2.0 XML.

activiti proc def cache

In a multi node setup, each node will have a cache of process definitions. When a node goes down and comes up, it will rebuild the cache as it handles process instances, tasks. and so on.

The process definition cache size can be set by the following property:

Property Description Default


The number of process definitions kept in memory. When the system needs to cope with many process definitions concurrently, it is advised to make this value higher than the default.


8.10. Content Storage

In various places in the Alfresco Activiti BPM Suite it is possible to upload content, such as attaching a file to a task or a form. This content is stored on disk, with the path being configured as follows:


Very important when using multiple instances of the application is that this path references a shared network drive. The reason is that all nodes must be able to access all content (as the application is stateless and any server can handle any request).

8.11. Microsoft Office Integration

The Microsoft Office integration (opening an Office document directly from the browser) doesn’t need any specific configuration. However, the protocol used to do this does mandates the use of HTTPS servers by default. This means that the Alfresco Activiti BPM Suite needs to run on a server that has HTTPS and its certificates correctly configured.

If this is not possible for some reason, a setting will need to be changed on the machines for each user to make this feature work.

For OS X, execute following terminal command:

defaults -currentHost write hkey_current_user\\hkey_local_machine\\software\\microsoft\\office\\14.0\\common\\internet\\basicauthlevel -int 2

Note that this is not advised from a security point of view.

8.12. Logging

The application uses SLF4J bounded to Log4j. The configuration file can be found in the WEB-INF/classes folder of the WAR file.

8.12.1. Logging Backend Metrics

For all REST API endpoints available in the application, metrics are gathered about runtime performance. These statistics can be written to the log.

Property Description Default


Boolean value. If true, the REST API endpoint statistics will be logged.



The interval of logging in seconds. Do note that these logs are quite large, so this should not be set to be too frequent.


Note that the statistics are based on the runtime timings since the last start up. When the server goes down, the metrics are lost.

Example output for one REST API endpoint:
  count = 4
  mean rate = 0.03 calls/second
  1-minute rate = 0.03 calls/second
  5-minute rate = 0.01 calls/second
  15-minute rate = 0.00 calls/second
  min = 5.28 milliseconds
  max = 186.55 milliseconds
  mean = 50.74 milliseconds
  stddev = 90.54 milliseconds
  median = 5.57 milliseconds
  75% <= 141.34 milliseconds
  95% <= 186.55 milliseconds
  98% <= 186.55 milliseconds
  99% <= 186.55 milliseconds
  99.9% <= 186.55 milliseconds

8.13. External Identity Management (LDAP/Active Directory)

It’s possible to hook up a centralized user data store with the Alfresco Activiti BPM Suite. Any server supporting the LDAP protocol can be used. Special configuration options and logic has been included to work with Active Directory (AD) systems too.

From a high-level point of view, the external Identity Management (IDM) integration works as follows:

  • Periodically, all user and group information is synchronized asynchronically. This means that all data for users (name, email address, group membership, etc) is copied to the Activiti database.

  • The is done is both for performance and to be able to efficiently store more data about the user that doesn’t belong in the IDM system.

  • If the user signs into the Alfresco Activiti BPM Suite, the authentication request is passed to the IDM system. On successful authentication there, the user data corresponding to that user is fetched from the Activiti database and used for the various requests. Note that no passwords are saved in the Activiti database when using an external IDM.

Note that the LDAP sync only needs to be activated and configured on one node in the cluster (but it works when activated on multiple nodes, but this will of course lead to higher traffic for both the LDAP system and the database).

8.13.1. Configuration

The configuration of the external IDM authentication/synchronization is done in the same way as the regular properties. There is a properties file named in the WEB-INF/classes/META-INF/ folder in the WAR file. The values in a file with the same name on the classpath have precedence over the default values in the former file.

In the same folder, there is also a file '' which contains an example configruation for an Active Directory system.

8.13.2. Server Connection Configuration

The following snippet shows the properties involved in configuring a connection to an LDAP server (Activity Directory is similar). These are the typical parameters used when connecting with an LDAP server. Advanced parameters are commented out in the example below.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
# The URL to connect to the LDAP server # The default principal to use (only used for LDAP sync),ou=system # The password for the default principal (only used for LDAP sync) # The authentication mechanism to use for synchronization # LDAPS truststore configuration properties #ldap.authentication.truststore.path= #ldap.authentication.truststore.passphrase= #ldap.authentication.truststore.type= # Set to 'ssl' to enable truststore configuration via subsystem's properties # The LDAP context factory to use # Requests timeout, in miliseconds, use 0 for none (default) # See

It is possible to configure connection pooling for the LDAP/AD connections. This is an advanced feature and only needed when creating a connection to the IDM system has an impact on system performance.

The connection pooling is implemented using the Spring-LDAP framework. Below are all the properties possible to configure. These follow the semantics of the properties possible for Spring-LDAP and are are described here.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
# ----------------------- # LDAP CONNECTION POOLING # ----------------------- # Options= # nothing filled in: no connection pooling # 'jdk': use the default jdk pooling mechanism # 'spring': use the spring ldap connection pooling facilities. These can be configured further below #ldap.synchronization.pooling.type=spring # Following settings follow the semantics of org.springframework.ldap.pool.factory.PoolingContextSource #ldap.synchronization.pooling.minIdle=0 #ldap.synchronization.pooling.maxIdle=8 #ldap.synchronization.pooling.maxActive=0 #ldap.synchronization.pooling.maxTotal=-1 #ldap.synchronization.pooling.maxWait=-1 # Options for exhausted action: fail | block | grow #ldap.synchronization.pooling.whenExhaustedAction=block #ldap.synchronization.pooling.testOnBorrow=false #ldap.synchronization.pooling.testOnReturn=false #ldap.synchronization.pooling.testWhileIdle=false #ldap.synchronization.pooling.timeBetweenEvictionRunsMillis=-1 #ldap.synchronization.pooling.minEvictableIdleTimeMillis=1800000 #ldap.synchronization.pooling.numTestsPerEvictionRun=3 # Connection pool validation (see for semantics) # Used when any of the testXXX above are set to true #ldap.synchronization.pooling.validation.base= #ldap.synchronization.pooling.validation.filter= # Search control: object, oneLevel, subTree #ldap.synchronization.pooling.validation.searchControlsRefs=

8.13.3. Authentication

To enable authentication via LDAP or AD, set the following property:


In some organisations, a case insensitive login is allowed with the ldap id. By default , this is disabled. To enable, set following property to false.


Next, a property ldap.authentication.dnPattern can be set:


If the users are in a flat list (e.g. one organizational unit), it’s easy: simply set the property to a value, (uid={0},ou=users,dc=alfresco,dc=com). This is also the most performant way, as the LDAP bind can be done directly.

The ID with which the user signs in will be passed into the template above (the {0} will be replaced) and the password will be validated.

However, if the users are in structured folders (organizational units for example), a direct pattern cannot be used. In this case, leave the property either empty or comment it out. Now, a query will be performed using the ldap.synchronization.personQuery (see below) with the ldap.synchronization.userIdAttributeName to find the user and their distinguished (DN) name. That DN will then be used to sign in.

When using Active Directory, two additional properties need to be set:

1 2

The first property enables Active Directory support. The second one is the domain that needs to be added to the user ID (i.e. userId@domain) to sign in using Active Directory.

In case the domain does not match with the rootDn, it is possible to set is explicitly:,DC=com

And also the filter that is used(which defaults to a userPrincipalName comparison) can be changed:{0}))

8.13.4. Synchronization

The synchronization component will periodically query the IDM system and change the Actviti user and group database. There are two synchronization 'modes': full and differential.

Full synchronization queries all data from the IDM and checks every user, group and membership to be valid. In terms of resource usage, it is obviously heavier than the differential synchronization. On a first start up of the Alfresco Activiti BPM Suite configured to use an external IDM, the full synchronization will be run so all user and group data is available in the database.

Full synchronization needs to be enabled. The frequency in which it runs is set using a cron expression:

1 2
ldap.synchronization.full.enabled=true ldap.synchronization.full.cronExpression=0 0 0 * * ?

Differential synchronization is 'lighter', in terms of performance, as it only queries the users and groups that have changed since the last synchronization. One downside is that it cannot detect deletions of users and groups. Consequently, a full synchronization needs to run periodically (but less than a differential synchronization typically) to account for these deletions.

1 2
ldap.synchronization.differential.enabled=true ldap.synchronization.differential.cronExpression=0 0 */4 * * ?

Do note that all synchronization results are logged, both in the regular logging and in a database table named IDM_SYNC_LOG

The synchronization logic builds on two elements:

  • Queries that return the correct user/group/membership data

  • A mapping of LDAP attributes to attributes used within the Activiti system

There are a lot of properties to configure, so do base your configuration on one of the two files in the META-INF folder, as these contain default values. You only need to add the specific properties to your custom configuration file if the default values are not appropriate.

Generic Synchronization settings

These are settings that are generic or shared between user and group objects. For each property, an example setting of a 'regular' LDAP system (i.e. ApacheDS) and Active Directory is shown.

Property Description LDAP Example Active Directory Example


The attribute that is the 'disinguished name' in the system.




The name of the operational attribute recording the last update time for a group or user. Important for the differential query.




The name of the operational attribute recording the create time for a group or user. Important for the differential query.




The timestamp format. This is specific to the directory servers and can vary.




The timestamp format locale language for parsing. Follows the java.util.Locale semantics.



The timestamp format locale country. Follows the java.util.Locale semantics.




The timestamp format timezone. Follows the java.text.SimpleDateFormat semantics.



User Synchronization Settings
Property Description LDAP Example Active Directory Example


The user search base restricts the LDAP user query to a sub section of a tree on the LDAP server.




The query to select all objects that represent the users to import (used in the *full synchronization query*ß).




The query to select objects that represent the users to import that have changed since a certain time (used in the differential synchronization query).




The attribute name on people objects found in LDAP to use as the user ID in Alfresco




The attribute on person objects in LDAP to map to the first name property of a user




The attribute on person objects in LDAP to map to the last name property of a user




The attribute on person objects in LDAP to map to the email property of a user




The person type in the directory server.



It is also possible configure what users should be made administrators in the system. Delimit multiple entries with ; as commas can’t be used. Note: no trimming of spaces will be applied.

Note: The property value has to be an exact string match to the user DN value not an LDAP/AD query string.


When using multi-tenancy, the administrator of all tenants can be configured as follows. Similar rules for delimiting apply as above.

Note: The property value has to be an exact string match to the user DN value not an LDAP/AD query string.


It’s important to set at least 1 user with admin rights. Otherwise no user will be able to sign into the system and administer it.

Group Synchronization Settings
Property Description LDAP Example Active Directory Example


The group search base restricts the LDAP group query to a sub section of a tree on the LDAP server.




The query to select all objects that represent the groups to import (used in full synchronization).




The query to select objects that represent the groups to import that have changed since a certain time (used in the differential synchronization).




The attribute on LDAP group objects to map to the authority name property in Activiti.




The attribute in LDAP on group objects that defines the DN for its members. This is an important setting as is defines group memberships of users and parent-child relations between groups.




The group type in LDAP.




It is possible to use paging when connecting to an LDAP server (some even mandate this).

To enable paging when fetching users or groups, set following properties:

1 2
ldap.synchronization.paging.enabled=true ldap.synchronization.paging.size=500

By default, paging is disabled

Batch insert

It is possible to tweak the batch size when doing an LDAP sync.

The insert batch size limits the amount of data being inserted in one transaction (e.g. 100 users per transactions are inserted). By default, this is 5. The query batch size is used when data is fetched from the Activiti database (e.g. fetching users to check for deletions when doing a full sync).

1 2
ldap.synchronization.db.insert.batch.size=100 ldap.synchronization.db.query.batch.size=100

8.14. Integration With External Systems

8.14.1. Alfresco One

The Alfresco One (on premises) integration can be used to: * Upload or link related content (e.g. for a task) * Upload or link content in a form

The connection for an Alfresco installation is created by an administrator through the user interface. Accounts for connecting to an Alfresco installation are created by the user themself.

Passwords are stored encrypted in the database. An init vector and secret key are used for the encryption. These keys can be changed from the default values as follows:

1 2 3 4 5
# Passwords for non-OAuth services (eg. on-premise alfresco) are encrypted using AES/CBC/PKCS5PADDING # It needs a 128-bit initialization vector ( and a 128-bit secret key # represented as 16 ascii characters below security.useraccount.credentialsIVSpec=9kje56fqwX8lk1Z0 security.useraccount.credentialsSecretSpec=wTy53pl09aN4iOkL

Note: See the Alfresco Share Connector section for information on a deeper level of integration between the Activiti BPM Suite and Alfresco One. With the connector installed on your Alfresco One server you will be able to use the Activiti BPM Suite’s Task application from within Alfresco Share. If you are using Activiti BPM Suite 1.3.2 and the Share connector there is no longer any need to have your users create the Alfresco accounts in Activiti as mentioned above since an SSO connection is established between the systems.

8.14.2. Alfresco Cloud

The Alfresco Cloud integration can be used to: * Upload or link related content (eg. for a task) * Upload or link content in a form

To integrate with the Alfresco Cloud, an account is needed that provides API access. Such an account can be created here.

The following properties need to be set. Note that the redirectUri must match the host on which the Alfresco Activiti BPM Suite is running. The app/rest/integration/alfresco-cloud/confirm-auth-request can be copied as-is.

1 2 3

By default, the Alfresco Cloud support is disabled so that it won’t show up in the upload widget. To enable Alfresco Cloud support changed the property.


8.14.3. Google Drive

The Google Drive integration can be used to:

  • Upload related content (eg. for a task)

  • Upload content in a form

The Google Drive integration needs a valid development account to access the API. Also, see this link for more information.

Such an account also has a secret, x509 certificate url and client id. These settings are provided by the Google Drive Dev Account.

1 2 3 4 5 6 7 8 9 10 11 12 13 14
# No need to change these properties googledrive.web.auth_uri= googledrive.web.token_uri= googledrive.web.auth_provider_x509_cert_url= # Following properties need to be changed to map to the correct url googledrive.web.redirect_uris=http://localhost:8080/activiti-app/app/rest/integration/google-drive/confirm-auth-request googledrive.web.javascript_origins=http://localhost:8080/activiti-app # Following properties are provided by Google googledrive.web.client_secret=aabbcc googledrive.web.client_email=bla googledrive.web.client_x509_cert_url=bla googledrive.web.client_id=bla

By default, the Google Drive support is disabled so that it won’t show up in the upload widget. To enable Google Drive support changed the google.web.disabled property.


8.14.4. Box

The Box integration can be used to:

  • Upload related content (eg. for a task)

  • Upload content in a form

The Box integration needs a valid development account to access the API.

Such an account also has a secret, authentication urls and client id. These settings are provided by the Box Dev Account.

1 2 3 4 5 6 7 8 9 10 11
# No need to change these properties box.web.auth_uri= box.web.token_uri= # Following properties need to be changed to map to the correct url box.web.redirect_uris=http://localhost:8080/activiti-app/app/rest/integration/box/confirm-auth-request box.web.javascript_origins=http://localhost:8080 # Following properties are provided by Box box.web.client_id=RegisterWithBoxForYourClientId box.web.client_secret=RegisterWithBoxForYourSecret

By default, the Box support is disabled so that it won’t show up in the upload widget. To enable Box support changed the box.disabled property.


8.15. Validator configuration

By default, the Activiti BPM Suite is configured in such a way that process modelers have access to all powerful features of the Activiti engine. In many companies this is not a problem, as the people who are modeling are truested IT people or business analysts.

However, some organisations expose the modeling tools of the Activiti BPM Suite directly to all end users. Giving them acces to the full array of Activiti capabilities might be a dangerous thing to do in that case: they could use it to gather sensitive data or swamp the resources of the servers. For that purpose, various 'validators' have been introduced that can be enabled or disabled. These validators are run before a process model is deployed to the engine and will block deployment in case of a validation error.

8.15.1. Disabling tasks

The following validators disable the usage of certain tasks. The various validators are configured through the regular Activiti properties. The default value for these validators is 'false'. Set the property to 'true' to enable the validator.

validator.editor.bpmn.disable.startevent.timer|signal|message|error: Disables the usage of the timer, signal, message or error start event in a process definition.

validator.editor.bpmn.disable.scripttask: Disables the usage of the script task in a process definition. Disabling script tasks is typically something you’ll want to do when exposing the modeling tools to any end users. Scripts, contrary to the service tasks, don’t need any class on the classpath to be executed. As such, it’s very easy with scripts to execute code with bad intentions.

validator.editor.bpmn.disable.servicetask: Disable the usage of the service task in a process definition. Service tasks are used to call custom logic when the process instance executes the service task. A service task is configured to either use a class that needs to be put on the classpath or an expression. This setting disables the usage of service tasks completely.

validator.editor.bpmn.disable.executionlistener: Disables the possibility to define execution listeners in a BPMN process definition. Execution listeners allow to add custom logic to the process diagram that is not visible in the diagram. This setting also disables task listeners on tasks.

validator.editor.bpmn.disable.mailtask: Disable the mail task that is used to send out emails.

validator.editor.bpmn.disable.intermediatethrowevent: Disables the usage of all intermediate throw events (none, signal, message, error). They can be used to create infinite loops in processes.

validator.editor.bpmn.disable.manualtask: Disables the usage of the manual task task in a process definition.

validator.editor.bpmn.disable.businessruletask: Disables the usage of the business rule task in a process definition.

validator.editor.bpmn.disable.cameltask: Disables the usage of the Camel task in a process definition. Camel tasks can interact with Apache Camel for various system integrations and have, like regular JavaDelegate classes access to the whole engine.

validator.editor.bpmn.disable.muletask: Disable the usage of the Mule task in a process definition. Mule tasks are used to interact with a Mule server.

8.15.2. Limit functionality

The following validators don’t disable a task as a whole, but rather a feature:

validator.editor.bpmn.disable.startevent.timecycle: Allows the usage of a timer start event, but not with a timeCycle attribute, as it could be used to create process instances or tasks for many people very quickly, or simply to stress the system resources.

validator.editor.bpmn.limit.servicetask.only-class: Limits the service task to only be configured with a class attribute (so no expression or delegate expression is allowed). Since the available classes are restricted by what is on the classpath, there is a strict control over which logic is exposed.

validator.editor.bpmn.limit.usertask.assignment.only-idm: Limits the user task assignment to only the values that can be selected using the 'Identity Store' option in the assignment popup. The reasoning to do this, is that this is the only way 'safe' values can be selected. Otherwise, by allowing fixed values like expression, a random bean could be invoked or used to get system information.

validator.editor.bpmn.disable.loopback: Disables looping back with a sequence flow from an element to itself. If enabled, it is possible this way to create infinite loops (if not applied correctly).

validator.editor.bpmn.limit.multiinstance.loop: Limits the loop functionality of a multi instance: only a loop cardinality between 1 and 10 is allowed and a collection nor completion condition is allowed. So basically, only very simple loops are permitted. Currently applied to call activities, sub processes and service tasks.

validator.editor.dmn.expression: Validates the expressions in the decision tables to be correct according to the DMN specification. By default this is 'true' (unlike the others!). This means that by default, the DMN decision tables are checked for correctness. If using the structured expression editor to fill in the decision tables, the resulting expressions will be valid. However,if you want to type any MVEL expressions, this property needs to be set to '_false'.

8.16. License configuration

It is possible to start up the application without a license (it will then enter read only mode) and later upload one from the user interface. See below for settings that apply to that scenario.

Property Description Default


If no license is available on first bootstrap this property decides if system will go into single or multi tenant mode



If no license is available on first bootstrap this property decides the name of the default tenant



Decides if license uploads should be allowed in the system or not


9. Activiti Administrator

This is an application that can be used to inspect and manage the data for an Activiti Enterprise engine (or cluster of engines). It also is used for cluster configuration and monitoring. It is distributed as a separate web application (WAR file).

Typically, there is one single Activiti Administrator application for multiple environments (e.g. development, testing, production, and so on), which is accessed by a handful of users (system administrators). As such, it is generally not necessary to have multiple instances of this application running (although it is certainly technically possible).

The Activiti Enterprise engine is cluster-enabled in the sense that, together with the Activiti Administrator, a user can configure and monitor a cluster (or multiple different clusters) through a graphical user interface. The clustered engines will use the same configuration and will report metrics and status back to the Activiti Administrator where they are displayed.

9.1. Installation

The Activiti Administrator is distributed as a regular WAR (Web Application ARchive) file that can be dropped in any Java web container.

Simply drop the activiti-admin.war file into the web container and start the web container. To make the application use your database, you must

  • copy the correct JDBC database driver to the classpath of the web application

  • create a property file called that must be on the classpath of the web application. The properties must point to the correct environment settings. Note that there is such a file in the WEB-INF/classes/META-INF/activiti-admin that is used when no other properties file is found on the classpath.

9.1.1. Database configuration

The database is configured exactly the same as the Alfresco Activiti BPM Suite. See the database configuration section Activiti BPM Suite.

For example (using MySQL):

1 2 3 4 5 6
datasource.driver=com.mysql.jdbc.Driver datasource.url=jdbc:mysql:// datasource.username=alfresco datasource.password=alfresco hibernate.dialect=org.hibernate.dialect.MySQLDialect

9.1.2. Cluster Configuration and Monitoring

The Activiti Administrator can show the process data and manage the configuration of multiple clusters. In this context a cluster is a number of Activiti Enterprise engines that logically belong together. Note that this does not relate to the way that these engines are architecturally set up: embedded, exposed through REST, with or without a load balancer in front, and so on.

Also note that the Activiti Administrator is capable of inspecting the information of each enterprise Activiti Process Engine (if configured correctly). Thus, it is not solely bound to using the process engine within the Alfresco Activiti BPM Suite, but to all enterprise Activiti process engines.


Multiple clusters can be configured and managed through the Activiti Administrator. This is displayed in the drop-down in the top-right corner:

cluster dropdown

Each of the engines in a cluster should point to the same database schema. To access the data of a cluster, the Administrator application uses one Activiti REST application per cluster (to avoid direct access to the database from the Activiti Administrator or potentially to manage different engine versions).

The REST API endpoints can be included in your application using the Maven artifact com.activiti.activiti-rest. It is configured in a similar way as the Activiti Administrator.

No special setup is needed when using the Alfresco Activiti BPM Suite, as it contains the necessary REST API endpoints out of the box.

As shown in the diagram below, any cluster can consist of multiple Activiti engine nodes (pointing to the same database schema), the data that is managed in the Activiti Administrator is fetched through an Activiti REST application only.

admin app architecture

In the same dropdown as shown above, a new cluster can be created. Note that a user will be created when doing so. This user is configured with the role of 'cluster manager' and is used to send information to the HTTP REST API of the Admin application, but it cannot log in into the Admin application as a regular user for safety reasons.

The REST endpoint for each cluster can be configured through the Activiti Administrator. Simply change the settings for the endpoint on the Configuration > Engine page while the cluster of choice is selected in the drop-down in the top-right corner. The current endpoint configuration is also shown on this page:

endpoint config
Configuration Settings

Information between an Activiti Process Engine and the Admin app is done through HTTP REST calls. To send or get information from the Admin Application, an Activiti Process Engine needs to be configured with a correct url and credentials.

For the engine, this can be done programmatically:

1 2 3 4 5 6
processEngineConfig.enableClusterConfig(); processEngineConfig.setEnterpriseAdminAppUrl("http://localhost:8081/activiti-admin"); processEngineConfig.setEnterpriseClusterName("development"); processEngineConfig.setEnterpriseClusterUserName("dev"); processEngineConfig.setEnterpriseClusterPassword("dev"); processEngineConfig.setEnterpriseMetricSendingInterval(30);

This configures the base HTTP API url, the name of the cluster that the engine is part of, the credentials of the user allowed to send data to the API and the time interval between sending data to the Admin application (in seconds).

The Alfresco Activiti BPM Suite includes the Activiti Process Engine. To enable engine clustering you can set the properties (similar to the programmatical approach) directly in the configuration file:

1 2 3 4 5 6
cluster.enable=true cluster.config.adminapp.url=http://localhost:8081/activiti-admin cluster.config.username=dev cluster.config.password=dev cluster.config.metricsendinginterval=30

The Alfresco Activiti BPM Suite also sends extra metrics to the Admin application. To configure the rate of sending, a cron expression can be set (by default the same as the rate of sending for the Process Engine):

1 * * * * ?

Alternatively, it is possible to generate a jar file with these settings through the Configuration > Generate cluster jar button. This jar file can be placed on the classpath (or used as a Maven dependency in case of using a local Maven reposioty) of an engine or BPM Suite application and it will have precedence over the properties files.

Once the application is running, metrics for that node in the cluster are shown in the Admin application:

node joined cluster

On the Admin application side of things, there are two settings that can be changed:

1 2
cluster.monitoring.max.inactive.time=600000 cluster.monitoring.inactive.check.cronexpression=0 0/5 * * * ?
  • cluster.monitoring.max.inactive.time : This a period of time, expressed in milliseconds, that indicates when a node is deemed to be inactive and is removed from the list of nodes of a cluster (nor will it appear in the 'monitoring' section of the application). When a node is properly shut down, it will send out an event indicating it is shut down. From that point on, the data will be kept in memory for the amount of time indicated here. When a node is not properly shut down (eg hardware failure), this is the period of time before removal, since the time the last event is received. Make sure the value here is higher than the sending interval of the nodes, to avoid that nodes incorrectly removed. By default 10 minutes.

  • cluster.monitoring.inactive.check.cronexpression ; A cron expression that configures when the check for inactive nodes is made. When executed, this will mark any node that hasn’t been active for 'cluster.monitoring.max.inactive.time' seconds, as an inactive node. Default: every 5 minutes.

9.1.3. Master Configuration

For each cluster, a master configuration can be defined. When the instance boots up, it will request the master configuration data from the Activiti Admin application. For this to work, the cluster.x properties (or equivalent programmatic setters) listed above need to be set correctly.

There is one additional property that can be set: cluster.master.cfg.required=. This is a boolean value, which if set to true will stop the instance from booting up when the Admin app could not be reached or no master configuration is defined. In case of false, the instance will boot up using the local properties file instead of the master configuration.

The master configuration works for both clusters of embedded Activiti engines or Alfresco Activiti BPM Suite instances. The two can not be mixed within the same cluster though.

Note: when changing the master configuration, the cluster instances would need a reboot. The Admin application will show a warning for that node too in the 'monitoring' tab, saying the master configuration currently being used is incorrect.

9.1.4. HTTP Communication overview

Communication with the Admin Application is done using HTTP REST calls. The calls use HTTP Basic Authentication for security, but do use different users, depending on the user case.

The Alfresco Activiti BPM Suite and Activiti Admin Application do not share user stores. The reason for that is that

  • there is only a handful of users typically involved with the Admin Application.

  • the Admin Application can be used independently from the Suite Application.

The following pictures gives a high-level overview:

admin app communication01
  • The Activiti Engine pushes and pulls data to and from the Admin Application REST API. These calls use basic authentication with a user defined in the Activiti Admin Application user store (relational database). Such a user is automatically created when a new cluster configuration is created (see above), but its credentials need to be configured on the engine/Suite app side (see the cluster.xx properties.

  • The Activiti Admin Application allows to browse and manage data in an Activiti Enterprise Engine. It calls the REST API to do so, using a user defined in the user store of the Suite Application (or any other authentication mechanism for the embedded engine use case).

For the Alfresco Activiti BPM Suite: this user needs to have a Tenant Admin or Tenant Manager role, as the Admin Application gives access to all data of the engine.

Let’s now focus on what this means for an end user:

admin app communication02

An end user logs in through the UI, both on the Suite as the Admin Application. Again, the user store is not shared between the two.

It’s important to understand that the HTTP REST calls done against the Suite REST API, are done using the credentials of the Suite application using a user defined in the user store of the Suite Application. This user can be configured through the Admin Application UI.

In case of using LDAP, a equivalent reasonining is made:

admin app communication03

The user that logs into the Admin Application is defined in the relational database of the Admin Application. However, the HTTP REST call will now use a user that is defined in LDAP.

9.1.5. Configuring the Activiti Rest app for usage with the Activiti Admin app

When using the Activiti engine embedded in a custom application (or multiple embedded engines), it is still needed to set up a REST endpoint that the Activiti Admin app can use to communicate with to see and manage data in the engines cluster.

The Alfresco Activiti BPM Suite already contains this REST api, so it is not necessary to add this additional REST app in that case.

Out of the box, the Activiti Rest application is configured to have a default admin user for authentication and uses an in memory H2 database. The latter of course needs to be changed to point to the same database as the engines are using.

The easiest way to do this, is to change the properties in the /WEB-INF/classes/META-INF/ file with the correct datasource parameters. Make sure the driver jar is on the classpath.

To change the user that is created by default, change the settings in /WEB-INF/classes/META-INF/ In the same file, basic engine settings can be configured:

  • engine.schema.update: whether the database schema must be upgraded on boot (if this is needed). Default true.

  • engine.asyncexecutor.enabled: whether the async job executor is enabled. Default false, as this is better done on the engine nodes itself, as otherwise you would have to make sure the classpath has all the delegates used in the various processes.

  • engine.asyncexecutor.activate: whether the async job executor is enabled. Default false, as this is better done on the engine nodes itself, as otherwise you would have to make sure the classpath has all the delegates used in the various processes.

  • engine.history.level: The history level of the process engine. Make sure this matches the history level in the other engines in the cluster, as otherwise this might lead to inconsistent data. Default 'full'.

In case these two property files are insufficient in configuring the process engine, it is possible to override the process engine configuration completely. This is done in a Spring xml file found at /WEB-INF/classes/META-INF/activiti-custom-context.xml. Uncomment the bean definitions and configure the engine without restrictions, similar to a normal Activiti Process Engine configuration.

The out of the box datasource uses C3P0 as connection pooling framework. In the same file, this datasource (and transaction manager) can also be configured.

The application uses Spring Security for authentication. By default, it will use the Activiti identityService to store and validate the user. In case this needs to be changed, add a bean with id 'authenticationProvider' to /WEB-INF/classes/META-INF/activiti-custom-context.xml. The class should implement the interface (see Spring docs, multiple implementations available).

Note: the Rest app is not compatible with using a master configuration. It needs to be configured through the properties or the spring context xml/

10. Activiti Share Connector

10.1. Introduction

The Alfresco Share Connector is a set of Alfresco customizations distributed as 2 AMP (Alfresco Module Package) files, one for the Alfresco repository and one for the Alfresco Share web application. It enables the user to run certain parts of the Activiti BPM Suite’s Task user interface inside Alfresco Share. Since version 1.3.2 it is possible for Activiti to connect to Alfresco One repositories without additional configuration to user profiles in Activiti, as long as the users also exist in Alfresco One.

10.2. Features

  • Integrated UI - The Activiti user interface for working with processes and tasks is embedded into Share’s user interface exposing processes from the Activiti app named Review Processes. When selecting people and documents native Alfresco Share components are used.

  • Review Processes - The Activiti Review Processes app, shipped since Alfresco Activiti 1.2.2, will be available from within Alfresco Share, including 4 processes: Ad hoc Task, Group ad hoc task, Review and Approve - Group and Review and Approve - Single person.

  • Site Specific Processes - You can change the default process for a Site to those of a specific Process App in Activiti. To do this, you need to add an aspect included in the Share Connector to the Site’s documentLibrary folder. The aspect ID is abs:activitiProcessApp and the property that needs to be set is abs:appDefinitionName. The property value should be set to the exact same text as the Process App’s name. The easiest way to do this is to use the Repository view within Alfresco One and navigate to the desired site’s documentLibrary folder. From its Details page, select the Manage Aspects action and add the Activiti Process App aspect. Then edit the folder’s properties and enter the name of the Process App in the Process App Definition Name field.

  • My Activiti Tasks dashlet - Lists new tasks created using the Activiti Share connector. Gives you the possibility to filter tasks by: Active Tasks, Completed Tasks, Tasks Due Today, Tasks Assigned to Me, Unassigned (Pooled Tasks), Overdue Tasks.

  • Starting processes - Clicking Start workflow in the Document Library, Document details page and My Activiti Tasks will now create new external Activiti processes rather than old internal workflows in Alfresco.

  • Activiti Task list view - A new My Tasks page now lists new external Activiti tasks using the Activiti user interface.

  • Activiti Process list view - A new Processes page now lists new external Activiti processes using the Activiti user interface.

  • Customized Alfresco Share header - The Alfresco header’s menu links now point to new Activiti pages for processes and tasks instead of the old pages. A link to the Activiti user interface will also become present in the same menu.

  • You can still reach your old internal workflows and create new ones:

    • The original My Tasks dashlet is still available, making it possible to list old internal workflows but also receive new site invitations.

    • The original My Tasks page can still be accessed by clicking the Internal Tasks link on the new Activiti My Tasks page, making it possible to continue working with the internal workflows.

    • The original My Workflows page can still be accessed by clicking the Internal Workflows link on the new Activiti Processes page, making it possible to continue working with the internal workflows.

    • The original Start Workflow page can still be accessed by clicking the Start Workflow link on the new Activiti Start Process page, making it possible to continue creating new internal workflows.

    • The Workflows panel on the Document details page will list both internal and external workflows.

10.3. Production Setup

This section describes how to install the connector in a production environment. If you want to get it up and running as quickly as possible please read the instructions in the Demo Setup

10.3.1. LDAP

To make the integration between Alfresco One and Alfresco Activiti work a user’s username must be identical in both systems. The easiest way of achieving this is to use a common LDAP user database. After you have setup your LDAP server you must configure Activiti and Alfresco One to use it so that they can sync their user database against the LDAP server (more information below).

Note! It is still possible to make the integration work without using an LDAP server. What it all comes down to is that the external_id column in Activiti’s USERS table must match the username in Alfresco. As long as these match Alfresco and Activiti can be configured to use whatever user database they wish and the communication between the systems will still work.

10.3.2. Alfresco One

LDAP settings

For detailed instructions on how to get LDAP running with Alfresco One, please read:

If you just want to see a working example of an Alfresco One LDAP subsystem you can inspect the ldap demo provided in the This amp file (only) contains sample ldap configuration files for getting Alfresco setup up with an LDAP (it contains no Share connector files).

Unzip the activiti.alfresco.repo-demo-ldap-X.X.X.amp file (by renaming it from .amp to .zip) and take a look at the files, the settings you should pay most attention to are the ones marked with ACTIVITI SHARE CONNECTOR DEMO inside the file. Configure it to match your own LDAP, turn it back into an amp by zipping the files again and rename it back to .amp before droping it back into your Alfresco One’s amps folder.. Note! When you zip it, make sure to get the same same structure as the original .amp file and pay special attention that no new root folder has been introduced in your new .zip file.

Deploy AMPs

If you don’t already have one installed, make sure you install an Alfresco One 4.0, 4.1, 4.2 or 5.0 server.

From the copy the amps to the correct amps folder in your Alfresco One installation:

  • <zip>/alfresco/amps/activiti.alfresco.repo-X.X.X.amp to <alfresco-dir>/amps

  • <zip>/alfresco/amps_share/activiti.alfresco.share-X.X.X.amp to <alfresco-dir>/amps_share

Install the amps into Alfresco One by running the following command on a terminal from within your Alfresco One installation directory, and then follow its instructions:

Activiti settings
Activiti port

The default settings assume that Activiti is running on if that is the case you don’t have to do anything.

If you have Activiti running on another domain or port (i.e. 9090) you can override the default setting by adding the following line in the bottom of your <alfresco-tomcat>/shared/classes/ file inside the Tomcat that your Alfresco One repository is running:

Alfresco One repository

In the same file it is also possible to modify the name of the integration by setting the value of activiti.alfrescoRepositoryName. This value must correspond to an Alfresco One repository configured inside Activiti. The default name for the integration is alfresco-1. To change it add the following line but make sure the value after the - sign is a number matching the "Id" of the repository which you can see as a column Alfresco Repositories list under Tenants inside the Activti Identity Management app.

Activiti app name

In the same file it is also possible to modify the name of the "Activiti app" to view in Alfresco by setting the exact name of the app to view in Share as the value of the property below.

activiti.appDefinitionName=Some Custom App
Set the secret key

When Alfresco One is communicating with Activiti it sends a secret token and username to Activiti and switches it for user specific Activiti token.

To override the default secret, simply specify a activiti.secret property in


This value is written in clear text and must match the Repository secret field for your Alfresco repository in the Activiti IDM app.

To avoid saving the secret in clear text you can also override the value (and all other Activiti properties) using Alfresco One Sub Systems and JMX.

To connect to an Alfresco One Server using JMX, see:

Once connected, navigate to /Alfresco/Configuration/Activiti/default/Attributes and modify the value for activiti.secret.

Alfresco One 4.0 & 4.1 specifics

The Activiti Share connector AMP is using a distributed memory cache implemented in Alfresco One to make sure it works in a clustered environment. This behaviour changed in Alfresco One 4.2 which means that to make the Alfresco Share conecntor work in Alfresco One 4.0 or 4.1 you must modify some settings inside /tomcat/webapps/alfresco/WEB-INF/classes/alfresco/module/activiti.alfresco.repo/module-context.xml.

The only thing that needs to be done is to comment out the current activitiTokensCache bean and activate the section with the 4.0 or 4.1 version of the same bean.

Alfresco One trouble shooting

If you want to see debug messages printed out by the Share connector rename tomcat/shared/classes/alfresco/extension/ by removing the .sample suffix and add the following line:


10.3.3. Activiti

Install the Activiti BPM Suite (version 1.2.2 or higher) using the standard installer.

Remember that you need to add your license file before you start Activiti. The license file should be added to <activiti-dir>/tomcat/lib

LDAP settings

You can find Activiti’s LDAP settings in Activiti’s expanded webapp folder: webapps/activiti-app/WEB-INF/classes/META-INF/activiti-app/ They are configured to work with the provided sample LDAP but you can easily override them by creating a new file <activiti-tomcat>/lib/ and override the properties that requires changing.

For further details about configuring LDAP for Activiti read the External Identity Management section.

Alfresco One settings
Enable the bundled Review & Approve

By default Activiti’s bundled Review Processes app is not created, to make it so just add the following file into the <activiti-tomcat>/lib/ (requires a restart).

1 2
# Enable the bundled Review & Workflows app
Add a repository

Start your Activiti server and login as administrator and navigate to the Profile Management (Identity Management) application and its Tenants page. Under the section Alfresco Repositories add make sure you have a repository pointing to the Alfresco One server with the Alfresco Share connector deployed by filling in the form to look something like this (assuming you are running Alfresco One on the same machine and on port 8080):

Field Value


Acme’s Alfresco Server

Alfresco tenant

Repository base url

Share base url

Alfresco Share connector




Note! When the repository has been created and the dialog is closed you can see your new repository in the Alfresco Repositories list. If the id set to "1" you are good to go and all default values are fine, if however it is set to something else, i.e. "1002", you will need to stop your servers and make sure your id is reflected as "alfresco-1002" in the following files and then restart your servers:

  • In Activiti’s tomcat/shared/classes/ - Override the default by adding a new line with activiti.alfrescoRepositoryName=alfresco-1002

  • In Alfresco’s tomcat/lib/ - The property named integration.login.alfresco-1.secret should be named integration.login.alfresco-1002.secret

Note! To make this repository work for features such as Publish to Alfresco or browse Alfresco for documents from within Activiti every user must have a user account for the repository and the Alfresco server must be of version 4.2 or above.

10.4. Demo Setup

10.4.1. Install Alfresco One

Install Alfresco One (5.0 or above) using the installer in "Advanced" mode. On "Tomcat Port Configuration" make sure you bump up each port by 10, i.e. 8080 becomes 8090 and so on.

Once the installer is finished, start Alfresco One using the "Application Manager" app found in the root of the Alfresco One home folder. Once you have seen Alfresco One working on, logout and stop just the "Tomcat Server" using the "Application Manager" app.

Now copy all the following files from the into their corresponding folder inside the Alfresco One installation directory:

  • <zip>/alfresco/amps/activiti.alfresco.repo-X.X.X.amp to <alfresco-dir>/amps

  • <zip>/alfresco/amps/activiti.alfresco.repo-demo-ldap-X.X.X.amp to <alfresco-dir>/amps

  • <zip>/alfresco/amps_share/activiti.alfresco.share-X.X.X.amp to <alfresco-dir>/amps_share

  • <zip>/alfresco/tomcat/webapps-ldap (copy the folder) to <alfresco-dir>/tomcat

The reason we have a separate webapps-ldap folder is to ensure that it boots up before Alfresco One so that it’s available when Alfresco One tries syncing its database against the LDAP server.

To configure the webapps-ldap folder to get picked up and run before webapps by Tomcat, copy the xml snippet in <zip>/alfresco/tomcat/conf/server-ldap-snippet.xml into your <alfresco-dir>/tomcat/conf/server.xml and make sure it’s placed above the existing <Service> element.

Install the amps into Alfresco One by running the following command on a terminal from within your Alfresco One installation directory, and then follow its instructions:


Note! With the standard installs you are likely to have OutOfMemoryExceptions due to Perm Gen space issues if you run Java 1.6 or 1.7. To avoid this, edit tomcat/bin/ or equivalent and make sure to set XX:MaxPermSize to 512M making the file have a line looking something like below.

JAVA_OPTS="-XX:MaxPermSize=512M -Xms512M -Xmx8192M $JAVA_OPTS"

10.4.2. Install Activiti BPM Suite

Install Activiti BMP Suite (1.2.2 or higher) using the installer. Remember, the demo H2 database is used by default, so you may wish to configure Activiti to use the same database as your Alfresco One installation. We suggest you create a new database schema for Activiti to use, then configure Activiti as described in Database Configuration,

To use the same demo LDAP server, copy the following file from the into its corresponding folder inside the Activiti installation directory:

  • <zip>/activiti/tomcat/lib/ to <activiti-dir>/tomcat/lib

Now, uncomment or add the following lines at the bottom of the tomcat/lib/ file inside the Activiti installation folder.

1 2
# Enable the bundled Review & Workflows app

Remember that you need to add your license file before you start Activiti. The license file should be added to <activiti-dir>/tomcat/lib

10.4.3. Startup the servers

Restart Alfresco One using the "Application Manager" to restart the "Tomcat Server". To be sure the Alfresco One server has fully started, check the "Application log" and wait for the "INFO: Server startup in XXXX ms" message.

After the Alfresco One server has started (and more importantly the demo LDAP server), start Activiti as instructed by the installer and navigate to the Identity Management app and login with admin/password (a user defined in the demo LDAP). On the Tenants page Under the Alfresco Repositories tab, add a repository pointing to your Alfresco One server:

Field Value


My Alfresco server

Alfresco tenant

Repository base url

Share base url

Alfresco Share connector




Note! The default secret is the text activiti-share-connector-secret, which can be changed to a different value in Alfresco One’s by the property activiti.secret. See Set the secret key for more details.

Note! When the repository has been created and the dialog is closed you can see your new repository in the Alfresco Repositories list. If the ID is set to "1" then all default values are fine. If, however, it is set to something else, e.g. "1002", you will need to stop your servers and make sure your ID is reflected as "alfresco-1002" in the following files and then restart your servers:

  • In Alfresco One’s override the default by adding a new line, substituting the ID as appropriate:


10.4.4. Use it!

Note: Make sure LDAP is running before you start Alfresco One and Activiti so they can sync their user databases against the LDAP server.

View Alfresco Share on and Activiti on

You must now login as a user that exist in the demo LDAP system:

Username Password Activiti role Alfresco role



tenant manager




tenant admin










Note: The password for the admin user is now "password" (literally) instead of what else you might have typed in when installing Alfresco One. This is because that is the password set in the demo LDAP server for all users.

On your Alfresco One personal dashboard page, go into customize dashboard by clicking on the cogwheel and make sure to add the My Activiti Tasks dashlet.

When logging into Activiti as admin it is possible to view the Process definitions and Review Processes app inside the Kickstart application by selecting the Shared with Me filter.

10.4.5. Activiti Administrator Application

If you wish to use the Activiti Administrator application with the demo setup you also need to update the Activiti endpoint in the Activiti Administrator app. Open the app on and sign in with the default admin/admin. You will see a message that an error occurred getting data from the server. Click the Edit Activiti REST endpoint button and set the Username to admin and Password to password, then save. You will get a green confirmation message showing it was successfully updated.

11. Disclaimer

While Alfresco has used commercially reasonable efforts to ensure the accuracy of this documentation, Alfresco assumes no responsibility for the accuracy, completeness, or usefulness of any information or for damages resulting from the procedures provided.

Furthermore, this documentation is supplied "as is" without guarantee or warranty, expressed or implied, including without limitation, any warranty of fitness for a specific purpose.