Activiti
Admin Guide
Table of Contents

Version 1.3.2, September 2015

1. Introduction

This guide describes how to set up 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).

This guide describes the various configuration options possible for the Alfresco Activiti BPM Suite. All engine-related topics such as how to use the BPMN 2.0 language to create process definitions, integrate with external systems, unit test your processes, and so on are documented in the Activiti Community User Guide, blogs or online articles.

2. High Level Architecture

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 regular Java Web application (WAR file) that is deployable on 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 later 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 the Actviti API directly (see the Activiti User Guide) . Note that a user with a specific role (tenant admin or tenant manager) is needed to access this part of the REST API, for security reasons.

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

  • The application requires Java 7 and is compliant with JEE 6 technologies. The Activiti Engine itself also supports Java 6, but due to components such as Elasticsearch, the Alfresco Activiti BPM Suite requires Java 7.

  • 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 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 manager 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 in such a way 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 an Alfresco One installation or to Google Drive (not shown on the diagram).

3. 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.

4. 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.

5. Configuration properties file

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

  • An activiti-app.properties 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 activiti-app.properties 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/activiti-app.properties file.

6. 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.

7. 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

server.contextroot

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

activiti-app

security.rememberme.key

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

somekey

8. Database Configuration

8.1. Using JDBC Connection Parameters

Following properties need to be set to change the database:

Property Description

datasource.driver

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

datasource.url

The JDBC url used to connect to the database

datasource.username

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

datasource.password

The password of the above user

Example:

1 2 3 4 5
datasource.driver=com.mysql.jdbc.Driver datasource.url=jdbc:mysql://127.0.0.1:3306/activiti?characterEncoding=UTF-8 datasource.username=alfresco datasource.password=alfresco

8.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

datasource.min-pool-size

The minimum number of connections in the connection pool.

5

datasource.max-pool-size

The maximum number of connections in the connection pool.

100

datasource.acquire-increment

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

5

datasource.preferred-test-query

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.

datasource.test-connection-on-checkin

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.

true

datasource.test-connection-on-checkout

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.

true

datasource.max-idle-time

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

1800

datasource.max-idle-time-excess-connections

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.

1800

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

8.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

datasource.jndi.name

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

jdbc/activitiDS

datasource.jndi.resourceRef

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.

true

Example (on JBoss EAP 6.3):

1
datasource.jndi.name=java:jboss/datasources/activitiDS

8.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

hibernate.dialect

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

H2

org.hibernate.dialect.H2Dialect

MySQL

org.hibernate.dialect.MySQLDialect

Oracle

org.hibernate.dialect.Oracle10gDialect

SQL Server

org.hibernate.dialect.SQLServerDialect

DB2

org.hibernate.dialect.DB2Dialect

PostgresQL

org.hibernate.dialect.PostgreSQLDialect

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

9. 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

10. 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 admin@app.activiti.com 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

admin.email

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

admin.group

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'.

11. 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

email.enabled

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

email.host

The host address of the email server.

email.port

The port on which the email server is running.

email.useCredentials

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

email.username

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

email.password

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

email.ssl

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

email.tls

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.

email.from.default

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

email.from.default.name

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

email.feedback.default

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

email.base.url

http://localhost:8080/activiti-app

12. Elasticsearch Configuration

Elastic search 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. Multiple instances of this application will also have multiple instances of Elasticsearch. These Elasticsearch servers will also find each other and act like a regular Elasticsearch cluster.

  • 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.

12.1. General Settings

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

Property Description Default

elastic-search.cluster.name

The name of the Elasticsearch cluster to connect to

activiti-elastic-search-cluster

elastic-search.node.name

The name of the node. 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.

activiti

elastic-search.default.index.name

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

activiti

elastic-search.tenant.index.prefix

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.

activiti_tenant_

elastic-search.enable.http

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.

false

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. By default, it will use multicast to discover what other nodes are available on the network. This is the default. Alternatively, unicast can also be used or the multicast settings can be tweaked.

To change the type of discovery:

Property Description Default

elastic-search.discovery.type

The way nodes find each other: multicast or unicast.

multicast

When using multicast, the following properties can be set:

Property Description Default

elastic-search.discovery.multicast.group

The multicast group address to use.

224.2.2.4

elastic-search.discovery.multicast.port

The multicast port to use.

54328

elastic-search.discovery.multicast.ttl

The time-to-live of the multicast message.

3

elastic-search.discovery.multicast.address

The address to bind to.

All available network interfaces (0.0.0.0)

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

Property Description Default

elastic-search.discovery.hosts

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]

12.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

elastic-search.server.type

embedded

embedded

elastic-search.data.path

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.

$user_home$/activiti-elastic-search-data

Each embedded Elasticsearch server will behave as a regular Elasticsearch server. For example, when running multiple nodes, the embedded Elasticsearch servers will distribute the data and make sure queries on the data are routed to the correct server.

12.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 Default

elastic-search.server.type

multicast-cluster

multicast-cluster

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

The version used in the application is Elasticsearch 1.3.2. While not mandatory, it is recommended to use the same version as the library JAR.

12.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.

12.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

event.generation.enabled

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

true

event.processing.enabled

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

true

event.processing.blocksize

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.

100

event.processing.cronExpression

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 * * * * ?

event.processing.expired.cronExpression

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 * * * ?

event.processing.max.locktime

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.

600000

event.processing.processed.events.action

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.

move

event.processing.processed.action.cronExpression

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

0 25/45 * * * ?

13. 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].default.capabilities.group 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

app.analytics.default.enabled

true

app.analytics.default.capabilities.group

analytics-users

app.kickstart.default.enabled

true

app.kickstart.default.capabilities.group

kickstart-users

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

app.review-workflows.enabled

false

14. 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

activiti.process-definitions.cache.max

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.

128

15. 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:

1
contentstorage.fs.rootFolder=data/

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).

16. 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 com.microsoft.registrationDB 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.

17. Logging

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

17.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

metrics.console.reporter.enabled

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

false

metrics.console.reporter.interval

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

60

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:

com.activiti.runtime.rest.TaskQueryResource.listTasks
  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

18. 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).

18.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 activiti-ldap.properties 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 'example-activiti-ldap-for-ad.properties' which contains an example configruation for an Active Directory system.

18.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 ldap.authentication.java.naming.provider.url=ldap://localhost:10389 # The default principal to use (only used for LDAP sync) ldap.synchronization.java.naming.security.principal=uid=admin,ou=system # The password for the default principal (only used for LDAP sync) ldap.synchronization.java.naming.security.credentials=secret # The authentication mechanism to use for synchronization #ldap.synchronization.java.naming.security.authentication=simple # 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 #ldap.authentication.java.naming.security.protocol=ssl # The LDAP context factory to use #ldap.authentication.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory # Requests timeout, in miliseconds, use 0 for none (default) #ldap.authentication.java.naming.read.timeout=0 # See http://docs.oracle.com/javase/jndi/tutorial/ldap/referral/jndi.html #ldap.synchronization.java.naming.referral=follow

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 http://docs.spring.io/spring-ldap/docs/2.0.2.RELEASE/reference/#pooling 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=

18.3. Authentication

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

1
ldap.authentication.enabled=true

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.

1
ldap.authentication.casesensitive=false

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

1
ldap.authentication.dnPattern=uid={0},ou=users,dc=alfresco,dc=com

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
ldap.authentication.active-directory.enabled=true ldap.authentication.active-directory.domain=alfresco.com

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:

ldap.authentication.active-directory.rootDn=DC=somethingElse,DC=com

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

ldap.authentication.active-directory.searchFilter=(&(objectClass=user)(userPrincipalName={0}))

18.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.

18.4.1. 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

ldap.synchronization.distinguishedNameAttributeName

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

dn

dn

ldap.synchronization.modifyTimestampAttributeName

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

modifyTimestamp

whenChanged

ldap.synchronization.createTimestampAttributeName

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

createTimestamp

whenCreated

ldap.synchronization.timestampFormat

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

yyyyMMddHHmmss.SSS’Z'

yyyyMMddHHmmss'.0Z'

ldap.synchronization.timestampFormat.locale.language

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

en

en

ldap.synchronization.timestampFormat.locale.country

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

GB

GB

ldap.synchronization.timestampFormat.timezone

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

GMT

GMT

18.4.2. User Synchronization Settings

Property Description LDAP Example Active Directory Example

ldap.synchronization.userSearchBase

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

ou=users,dc=alfresco,dc=com

ou=users,dc=alfresco,dc=com

ldap.synchronization.personQuery

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

(objectclass\=inetOrgPerson)

(&(objectclass\=user)(userAccountControl\:1.2.840.113556.1.4.803\:\=512))

ldap.synchronization.personDifferentialQuery

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

(&(objectclass\=inetOrgPerson)(!(modifyTimestamp<\={0})))

(&(objectclass\=user)(userAccountControl\:1.2.840.113556.1.4.803\:\=512)(!(whenChanged<\={0})))

ldap.synchronization.userIdAttributeName

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

uid

cn

ldap.synchronization.userFirstNameAttributeName

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

givenName

givenName

ldap.synchronization.userLastNameAttributeName

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

sn

cn

ldap.synchronization.userEmailAttributeName

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

mail

mail

ldap.synchronization.userType

The person type in the directory server.

inetOrgPerson

user

It is also possible configure what users should be made administrators in the system. When using multi-tenancy, the administrator of all tenants can be configured as follows. Delimit multiple entries with ; as commas can’t be used. Note: no trimming of spaces will be applied.

1
ldap.synchronization.tenantAdminDn=uid=joram,ou=users,dc=alfresco,dc=com;uid=tijs,ou=users,dc=alfresco,dc=com

Add specific people who need to become tenant admins, or when not using multi-tenancy. Similar rules for delimiting apply as above.

1
ldap.synchronization.tenantManagerDn=uid=joram,ou=users,dc=alfresco,dc=com

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.

18.4.3. Group Synchronization Settings

Property Description LDAP Example Active Directory Example

ldap.synchronization.groupSearchBase

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

ou=groups,dc=alfresco,dc=com

ou=groups,dc=alfresco,dc=com

ldap.synchronization.groupQuery

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

(objectclass\=groupOfNames)

(objectclass\=group)

ldap.synchronization.groupDifferentialQuery

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

(&(objectclass\=groupOfNames)(!(modifyTimestamp<\={0})))

(&(objectclass\=group)(!(whenChanged<\={0})))

ldap.synchronization.groupIdAttributeName

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

cn

cn

ldap.synchronization.groupMemberAttributeName

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.

member

member

ldap.synchronization.groupType

The group type in LDAP.

groupOfNames

group

18.4.4. Paging

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

18.4.5. 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

19. Integration With External Systems

19.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 (http://en.wikipedia.org/wiki/Initialization_vector) and a 128-bit secret key # represented as 16 ascii characters below security.useraccount.credentialsIVSpec=9kje56fqwX8lk1Z0 security.useraccount.credentialsSecretSpec=wTy53pl09aN4iOkL

19.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
alfresco.cloud.clientId=abc alfresco.cloud.secret=abc alfresco.cloud.redirectUri=http://localhost:8080/activiti-app/app/rest/integration/alfresco-cloud/confirm-auth-request

It’s possible to disable the Alfresco Cloud support so that it won’t show up in the upload widget. By default it’s enabled.

1
alfresco.cloud.disabled=true

19.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=https://accounts.google.com/o/oauth2/auth googledrive.web.token_uri=https://accounts.google.com/o/oauth2/token googledrive.web.auth_provider_x509_cert_url=https://www.googleapis.com/oauth2/v1/certs # 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

It’s possible to disable the Google Drive support so that it won’t show up in the upload widget. By default it’s enabled.

1
googledrive.web.disabled=true

20. 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.

20.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 activiti-admin.properties 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.

20.2. 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://127.0.0.1:3306/activitiadmin?characterEncoding=UTF-8 datasource.username=alfresco datasource.password=alfresco hibernate.dialect=org.hibernate.dialect.MySQLDialect

20.3. 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.

20.3.1. Architecture

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

20.3.2. 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.name=development 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
cluster.config.app.metricsendingcronexpression=0/30 * * * * ?

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.

20.4. 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 applicatio will show a warning for that node too in the 'monitoring' tab, saying the master configuration currently being used is incorrect.

20.5. 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.

20.6. 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/db.properties 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/engine.properties. 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 org.springframework.security.authentication.AuthenticationProvider 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/

21. Activiti Share Connector

21.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.

21.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.

21.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

21.3.1. LDAP

Both Alfresco One and Alfresco Activiti require a common LDAP user database for the integration to work. 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).

21.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 activiti-share-connector.zip.

Unzip the activiti.alfresco.repo-demo-ldap-X.X.X.amp file 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 ldap-authentication.properties file. Configure it to match your own LDAP, turn it back into an amp and finally drop it into your Alfresco One repository´s amps folder.

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 activiti-share-connector.zip 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:

bin/apply_amps.sh
Activiti settings
Activiti port

The default settings assume that Activiti is running on http://127.0.0.1:8080/ 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/alfresco-global.properties file inside the Tomcat that your Alfresco One repository is running:

1
activiti.domain=http://127.0.0.1:9090
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.

1
activiti.alfrescoRepositoryName=alfresco-1
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 alfresco-global.properties.

1
activiti.secret=my-custom-secret

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: http://docs.alfresco.com/4.0/concepts/jmx-intro-config.html.

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/custom-log4j.properties.sample by removing the .sample suffix and add the following line:

1
log4j.logger.com.activiti.alfresco=debug

21.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/activiti-ldap.properties. They are configured to work with the provided sample LDAP but you can easily override them by creating a new file <activiti-tomcat>/lib/activiti-ldap.properties 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/activiti-app.properties (requires a restart).

1 2
# Enable the bundled Review & Workflows app app.review-workflows.enabled=true
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

Name

Acme’s Alfresco Server

Alfresco tenant

Repository base url

http://127.0.0.1:8080/alfresco/

Share base url

http://127.0.0.1:8080/share/

Alfresco Share connector

(enabled)

Secret

activiti-share-connector-secret

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/alfresco-global.properties - Override the default by adding a new line with activiti.alfrescoRepositoryName=alfresco-1002

  • In Alfresco’s tomcat/lib/activiti-app.properties - The property named integration.login.alfresco-1.secret should be named integration.login.alfresco-1000.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.

21.4. Demo Setup

21.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 http://127.0.0.1:8090/share/, logout and stop just the "Tomcat Server" using the "Application Manager" app.

Now copy all the following files from the activiti-share-connector.zip 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:

bin/apply_amps.sh

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/setenv.sh 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"

21.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 activiti-share-connector.zip into its corresponding folder inside the Activiti installation directory:

  • <zip>/activiti/tomcat/lib/activiti-ldap.properties to <activiti-dir>/tomcat/lib

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

1 2
# Enable the bundled Review & Workflows app app.review-workflows.enabled=true

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

21.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 http://127.0.0.1:8080/activiti-app/idm/ 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

Name

My Alfresco server

Alfresco tenant

Repository base url

http://127.0.0.1:8090/alfresco/

Share base url

http://127.0.0.1:8090/share/

Alfresco Share connector

(enabled)

Secret

activiti-share-connector-secret

Note! The default secret is the text activiti-share-connector-secret, which can be changed to a different value in Alfresco One’s alfresco-global.properties 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 alfresco-global.properties override the default by adding a new line, substituting the ID as appropriate:

1
activiti.alfrescoRepositoryName=alfresco-1002

21.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 http://127.0.0.1:8090/share/ and Activiti on http://127.0.0.1:8080/activiti-app/

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

Username Password Activiti role Alfresco role

jluc

password

tenant manager

user

kirk

password

tenant admin

user

wesley

password

user

user

admin

password

admin

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.

21.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 http://127.0.0.1:8080/activiti-admin/ 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.

22. 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.