To install SkyVault Activiti on Windows:

To install SkyVault Activiti on OSX:

To install SkyVault Activiti on Linux:

Important: By default, the SkyVault Activiti installer does not deploy the activiti-admin app. Therefore, to get the activiti-admin app up and running, perform the following addtional steps after installing Activiti:

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

Refer to the SkyVault website for a list of supported combinations of Web containers and database products.

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

Perform the following steps to install SkyVault Activiti Administrator webapp, activiti-admin.

Set the following properties to change the database.

Example:

When using JDBC parameters to connect to the database, you can configure the following connection pool settings to suit the anticipated load.

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

If a JNDI datasource is configured in the web container or application server, the JNDI name should be set with the following properties:

Example (on JBoss EAP 6.3):

The SkyVault Activiti 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.

Set the following properties.

The following values are used to test SkyVault Activiti.

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

The following properties are applicable to both embedded and client setup.

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

To change the type of discovery:

When using multicast, the following properties can be set:

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

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

Note: Booting up multiple SkyVault Activiti instances with Elasticsearch configured in embedded mode will not cluster. To enable Out-of-the-box clustering, set the elastic-search.discovery.type to the required type and configure it appropiately.

To connect to an external Elasticsearch cluster, set following property combined with the general settings described above.

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

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

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.

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

The event processor is architected to work 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, however leaving the default values as they are helps cater for typical scenarios.

Backing up the data stored in Elasticsearch is described in detail in the Elastic search documentation. When using the snapshot functionality of ElasticSearch, you must enable the HTTP interface and create firewall rules to prevent general public from accessing it.

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

Ocassionally, an Elasticsearch index can get corrupted and become unusable. All data that are sent to Elasticsearch is stored in the relational database (except if the property event.processing.processed.events.action has been set to delete, in which case the data is lost).

You might have to rebuild the indices when changing the core Elasticsearch settings (for example, number of shards).

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

Therefore, to rebuilding the Elasticsearch index, you must do the following:

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

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

Download the maven project

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

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:

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 addition, in the same folder, the example-activiti-ldap-for-ad.properties file contains an example configuration for an Active Directory system.

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

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

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

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

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

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

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

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

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

The first property enables Active Directory support and the second property is the domain of the user ID (i.e. userId@domain) to sign in using Active Directory.

If 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}))

The synchronization component will periodically query the IDM system and change the Activiti 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. The resource usage is heavier than the differential synchronization in this type of synchronization and therefore, it is usually only triggered on the very first sync when SkyVault Activiti starts up and is configured to use an external IDM. This is so that all users and groups are available in the database.

To enable full synchronization:

The frequency in which it runs is set using a cron expression:

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.

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:

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.

The SkyVault 2.0 (on premise) integration can be used to:

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

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:

Note: See the SkyVault Activiti Connector Guide for more information about integrating SkyVault Activiti with SkyVault 2.0. With the connector installed on your SkyVault 2.0 server you will be able to use the SkyVault Activiti’s Task application from SkyVault Share. If you are using SkyVault Activiti 1.3.2 with the Activiti Connector, you don’t need to have your users create the SkyVault accounts in Activiti (as mentioned above) because an SSO connection is established between the systems by default.

The SkyVault Cloud integration can be used to:

To integrate with SkyVault Cloud, you must have an account and be able to access to the API. To create an account, click here.

Set the following properties and copy app/rest/integration/alfresco-cloud/confirm-auth-request as-is:

Note: The redirectUri must match the host on which SkyVault Activiti is running.

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

The Google Drive integration can be used to:

To integrate Google Drive, you must have a valid development account to access the API. See this link for more information.

In addtion, you will need a secret key, x509 certificate url, and a client Id. These settings are provided by the Google Drive Dev Account.

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

The Box integration can be used to:

To integrate Box, you must have access to https://developers.box.com, the secret key, authentication urls, and client Id. These settings are provided by the Box Dev Account.

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

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

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

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

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

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

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

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

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

It is possible to run SkyVault Activiti in so-called "Multi-Schema Multi-Tenancy" mode ("MS-MT" in short). This is a multi-tenant setup, where every tenant has its own database schema. This means that the data of one tenant is completely separated from the data of other tenants.

This is an alternative to the "regular" multi-tenant mode, where the data of all tenants is stored in the same database schema and the data gets a "tenant tag" to identity which tenant the data belongs to. The following diagram shows this setup:

The main benefit of this setup is the ease of setup and configuration: there is no difference with setting up a single-tenant or multi-tenant. Each request can be handled by any node and the loadbalancer simply can route using simple routing algorithms.

The downside of this setup is clearly that the database can become the bottleneck if it has to hold all the data of all tenants and there is no "physical separation" of the tenant data.

The MS-MT setup looks as follows:

The most important benefit of this approach is that the data of each tenant is completely separated from the data of other tenants. Since only data of one tenant is stored in the database schema, queries will generally be more performant.

The downside of this approach is immediately visible in this diagram: each node needs to have a connection pool to the database schema of the tenant. With many tenants, this can mean quite a bit of "housekeeping" that will need to be performed compared to the previous approach (which can be negative for performance). Note that there is a "master database" or "primary database" in this diagram. This database stores the configurations of the tenant datasources and the mapping between user and tenant.

Alternatively, as shown in the following diagram, it is possible to configure the Suite nodes as such that they only manage a certain list of tenants (for example in the picture below the last node only manages tenant Z, and the first two manage tenant A and B, but not Z). Although this alleviates the downside of the previous setup, it does come with an extra cost: the loadbalancer now needs to be more intelligent and needs to route the incoming request to the appropriate node. This means that the request needs information to differentiate as to which tenant the request is coming from. This needs custom coding on the client side and is not by default available in the SkyVault Activiti web client.

Taking this to the extreme, it is possible to have one (or more nodes) for one tenant. However, in that case it is probably easier to run a single tenant SkyVault Activiti for each tenant. The remarks about the loadbalancer and enriching the request with tenant information as in the previous setup still apply.

Currently, following known limitations apply to the MS-MT feature:

This section describes how the MS-MT feature works and can be skipped if only interested in setting up an MS-MT SkyVault Activiti.

The MS-MT feature depends on this fundamental architecture:

The following diagram visualizes the above points: when a request comes in, the security classes for authentication (configured using Spring Security) will kick in before executing any logic. The request contains the userId. Using this userId, the primary datasource is consulted to find the tenantId that corresponds with it (note: this information is cached in a configurable way so the primary datasource is not hit on every request. But it does mean that user removals from a tenant can take a configurable amount of time to be visible on all nodes). This does mean that in MS-MT mode, there is a (very small) overhead on each request which isn’t there in the default mode.

The tenantId is now set on a threadlocal variable (mimicking how Spring Security and its SecurityContext works). If the value is ever needed, it can be retrieved through the com.activiti.security.SecurityUtils.getCurrentTenantId() method.

When the logic is now executed, it will typically start a new database transaction. In MS-MT mode, the default DataSource implementation is replaced by the com.activiti.database.TenantAwareDataSource class. This implementation returns the datasource corresponding with the tenantId value set on the threadlocal. The logic itself remains unchanged.

The MS-MT feature does have a technical impact on some other areas too:

To run SkyVault Activiti, you need to have installed a multi-tenant license. Switching to MS-MT mode is done setting the tenancy.model property to isolated.

When using MS-MT, there always needs to be a primary datasource. This datasource is configured exactly the same as when configuring the single datasource. For example when using a Mysql database:

Booting up SkyVault Activiti now will create the regular tables in the primary-activiti schema, plus some additional tables specific to the primary datasource (such tables are prefixed with 'MSMT_'). A default user with tenant manager capabilities is created (the login email and password can be controlled with the admin.email and admin.passwordHash properties) too.

One thing to remember is that there are no REST endpoints specific to MS-MT. All the existing tenant endpoints simply behave slightly different when running in MSMT mode. Using this tenant manager user (credentials in the basic auth header), it is now possible to add new tenants by calling the REST API:

with the following JSON body:

Note that in some databases such as postgres, you may need to set the database.schema or database.catalog for database who work with catalogs.

Note the \n in the body of the configuration property.

Also note that this configuration will be stored encrypted (using the security.encryption.secret secret).

This will:

When executing this request, in the logs you will see the tenant being created in MSMT mode:

Afterwards in the logs, you’ll see:

At the end, you’ll see the following message indicating all is ready:

You can now log in into the web UI using admin@alfresco.com/admin, change the password and add some users. These users can of course also be added via the REST API using the tenant admin credentials.

A new tenant can easily be added in a similar way:

with body

When the tenant admin for this tenant, admin@acme.com logs in, no data of the other one can be seen (as is usual in multi-tenancy). Also when checking the tenant-SkyVault and tenant_acme schema, you’ll see the data is contained to the tenant schema.

The tenant manager can get a list of all tenants:

To get specific information on a tenant, including the configuration:

which gives:

Assuming a multi-node setup: when creating new tenants, the REST call is executed on one particular node. After the tenant is successfully created, users can log in and use the application without any problem on any node (so the loadbalancer can simply randomly distribute for example). However, some functionality that depends on backgrounds threads (the Activiti job executor for example) will only start after a certain period of time since the creation of the tenant on another node.

This period of time is configured via the msmt.tenant-validity.cronExpression cron expression (by default every 10 minutes).

Similarly, when a tenant is deleted, the deletion will happen on one node. It will take a certain amount of time (also configured through the msmt.tenant-validity.cronExpression property) before the deletion has rippled through all the nodes in a multi-node setup.

Note that tenant datasource configuration are not automatically picked up and require a reboot of all nodes. However, changing the datasource of a tenant should happen very infrequently.

There are but a few configuration properties specific to MS-MT:

Following interfaces can be used to replace the default implementations of MS-MT related functionality:

The database for Activiti Administrator is configured exactly the same way as SkyVault Activiti. See the Database Configuration section.

For example (using MySQL):

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 in SkyVault Activiti, but to all enterprise Activiti process engines.

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 instances. The two can not be mixed within the same cluster though.

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

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.

SkyVault Activiti and Activiti Admin Application do not share user stores. The reason being:

The following pictures gives a high-level overview:

For SkyVault Activiti: The 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.

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.

SkyVault Activiti already contains this REST API, so you must add this additional REST app.

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 default user, change the settings in /WEB-INF/classes/META-INF/engine.properties. In the same file, you can also configure the following basic engine settings:

If these two property files are insufficient in configuring the process engine, you can override the complete process engine configuration in a Spring xml file located 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, you can configure this datasource and transaction manager.

The application uses Spring Security for authentication. By default, it will use the Activiti identityService to store and validate the user. To change it, 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 for multiple implementations).

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.