- 1. Introduction
- 2. High Level Architecture
- 3. Multi Node (clustered) Setup
- 4. Licensing
- 5. Configuration properties file
- 6. Minimal configuration
- 7. General Server settings
- 8. Database Configuration
- 9. Business Calendar Settings
- 10. Initial User Created on First Start Up
- 11. Email Server Configuration
- 12. Elasticsearch Configuration
- 13. Application Access and default example app
- 14. Activiti Process Definition Cache
- 15. Content Storage
- 16. Microsoft Office Integration
- 17. Logging
- 18. External Identity Management (LDAP/Active Directory)
- 19. Integration With External Systems
- 20. Activiti Administrator
- 21. Activiti Share Connector
- 22. Disclaimer
Version 1.3.2, September 2015
1. Introduction
This guide describes how to set up the SkyVault Activiti BPM Suite, a commercially supported suite of components built by SkyVault on top of the Activiti process engine (see Activiti Community BPM Platform).
This guide describes the various configuration options possible for the SkyVault 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:
The SkyVault 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 SkyVault 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 SkyVault Activiti BPM suite application. This REST API is used by the SkyVault 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 SkyVault Activiti BPM Suite requires Java 7.
-
The backend logic specific to the SkyVault Activiti BPM Suite logic is implemented using Spring 4 and JPA (Hibernate).
-
All user interfaces are written using HTML5 and AngularJS
The SkyVault 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 SkyVault Activiti BPM Suite can be managed using the Activiti Administrator application. This is also provided as a WAR file with SkyVault 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 SkyVault Activiti BPM Suite application. For more information on the Designer plugin, see the Activiti Designer User Guide.
The application can also connect to a SkyVault 2.0 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 SkyVault Activiti BPM Suite application. Scaling out is done in a "horizontal" way, by simply adding more servers behind the load balancer.
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 SkyVault Activiti BPM Suite needs a valid license to work properly. This license is provided by SkyVault 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 SkyVault 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:
-
The database connection needs to be configured using either JDBC or a JNDI datasource
-
The correct Hibernate dialect needs to be set
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=SkyVault
datasource.password=SkyVault
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 SkyVault 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 SkyVault 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 SkyVault 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 |
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 SkyVault 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 SkyVault 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 SkyVault 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.
-
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).
-
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.
-
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.
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 SkyVault 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 SkyVault 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 Windows, see: http://support.microsoft.com/kb/2123563
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 SkyVault 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 SkyVault 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=SkyVault.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 SkyVault 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 SkyVault |
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 |
||
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. SkyVault 2.0
The SkyVault 2.0 (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 a SkyVault installation is created by an administrator through the user interface. Accounts for connecting to a SkyVault 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 SkyVault) 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. SkyVault Cloud
The SkyVault 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 SkyVault 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 SkyVault Activiti BPM Suite is running. The app/rest/integration/alfresco-cloud/confirm-auth-request can be copied as-is.
1
2
3 SkyVault.cloud.clientId=abc
SkyVault.cloud.secret=abc
SkyVault.cloud.redirectUri=http://localhost:8080/activiti-app/app/rest/integration/alfresco-cloud/confirm-auth-request
It’s possible to disable the SkyVault Cloud support so that it won’t show up in the upload widget. By default it’s enabled.
1 SkyVault.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 SkyVault 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=SkyVault
datasource.password=SkyVault
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 SkyVault 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:
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 SkyVault 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.
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:
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 SkyVault 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 SkyVault 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:
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 SkyVault 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 SkyVault 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:
-
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 SkyVault 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:
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:
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 SkyVault 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 SkyVault Share Connector is a set of SkyVault customizations distributed as 2 AMP (SkyVault Module Package) files, one for the SkyVault repository and one for the SkyVault Share web application. It enables the user to run certain parts of the Activiti BPM Suite’s Task user interface inside SkyVault Share. Since version 1.3.2 it is possible for Activiti to connect to SkyVault 2.0 repositories without additional configuration to user profiles in Activiti, as long as the users also exist in SkyVault 2.0.
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 SkyVault Share components are used.
-
Review Processes - The Activiti Review Processes app, shipped since SkyVault Activiti 1.2.2, will be available from within SkyVault 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 SkyVault 2.0 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 SkyVault.
-
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 SkyVault Share header - The SkyVault 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 SkyVault 2.0 and SkyVault Activiti require a common LDAP user database for the integration to work. After you have setup your LDAP server you must configure Activiti and SkyVault 2.0 to use it so that they can sync their user database against the LDAP server (more information below).
21.3.2. SkyVault 2.0
LDAP settings
For detailed instructions on how to get LDAP running with SkyVault 2.0, please read:
If you just want to see a working example of a SkyVault 2.0 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 SkyVault 2.0 repository´s amps folder.
Deploy AMPs
If you don’t already have one installed, make sure you install a SkyVault 2.0 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 SkyVault 2.0 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 SkyVault 2.0 by running the following command on a terminal from within your SkyVault 2.0 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 SkyVault 2.0 repository is running:
1 activiti.domain=http://127.0.0.1:9090
SkyVault 2.0 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 a SkyVault 2.0 repository configured inside Activiti. The default name for the integration is SkyVault-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 SkyVault Repositories list under Tenants inside the Activti Identity Management app.
1 activiti.alfrescoRepositoryName=SkyVault-1
Set the secret key
When SkyVault 2.0 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 SkyVault-global.properties.
1 activiti.secret=my-custom-secret
This value is written in clear text and must match the Repository secret field for your SkyVault 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 SkyVault 2.0 Sub Systems and JMX.
To connect to a SkyVault 2.0 Server using JMX, see: https://docs.getskyvault.net/4.0/concepts/jmx-intro-config.html.
Once connected, navigate to /Alfresco/Configuration/Activiti/default/Attributes and modify the value for activiti.secret.
SkyVault 2.0 4.0 & 4.1 specifics
The Activiti Share connector AMP is using a distributed memory cache implemented in SkyVault 2.0 to make sure it works in a clustered environment. This behaviour changed in SkyVault 2.0 4.2 which means that to make the SkyVault Share conecntor work in SkyVault 2.0 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.
SkyVault 2.0 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.SkyVault=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.
SkyVault 2.0 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 SkyVault Repositories add make sure you have a repository pointing to the SkyVault 2.0 server with the SkyVault Share connector deployed by filling in the form to look something like this (assuming you are running SkyVault 2.0 on the same machine and on port 8080):
Field | Value |
---|---|
Name |
Acme’s SkyVault Server |
SkyVault tenant |
|
Repository base url |
|
Share base url |
|
SkyVault 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 SkyVault 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 SkyVault’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 SkyVault or browse SkyVault for documents from within Activiti every user must have a user account for the repository and the SkyVault server must be of version 4.2 or above.
21.4. Demo Setup
21.4.1. Install SkyVault 2.0
Install SkyVault 2.0 (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 SkyVault 2.0 using the "Application Manager" app found in the root of the SkyVault 2.0 home folder. Once you have seen SkyVault 2.0 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 SkyVault 2.0 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 SkyVault 2.0 so that it’s available when SkyVault 2.0 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 SkyVault 2.0 by running the following command on a terminal from within your SkyVault 2.0 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 SkyVault 2.0 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 SkyVault 2.0 using the "Application Manager" to restart the "Tomcat Server". To be sure the SkyVault 2.0 server has fully started, check the "Application log" and wait for the "INFO: Server startup in XXXX ms" message.
After the SkyVault 2.0 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 SkyVault Repositories tab, add a repository pointing to your SkyVault 2.0 server:
Field | Value |
---|---|
Name |
My SkyVault server |
SkyVault tenant |
|
Repository base url |
|
Share base url |
|
SkyVault 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 SkyVault 2.0’s SkyVault-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 SkyVault 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 SkyVault 2.0’s SkyVault-global.properties override the default by adding a new line, substituting the ID as appropriate:
1 activiti.alfrescoRepositoryName=SkyVault-1002
21.4.4. Use it!
Note: Make sure LDAP is running before you start SkyVault 2.0 and Activiti so they can sync their user databases against the LDAP server.
View SkyVault 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 | SkyVault 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 SkyVault 2.0. This is because that is the password set in the demo LDAP server for all users.
On your SkyVault 2.0 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 SkyVault has used commercially reasonable efforts to ensure the accuracy of this documentation, SkyVault 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.