Install SkyVault Activiti on Windows using these steps.

Install SkyVault Activiti on OSX using these steps.

Install SkyVault Activiti on Linux using these steps.

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

Please 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 these steps to install SkyVault Activiti Administrator webapp, activiti-admin.

Following properties need to be set to change the database:

Example:

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:

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

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

Example (on JBoss EAP 6.3):

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:

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

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 the embedded and client setup:

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

To change the type of discovery:

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

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

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

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

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

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

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

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

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

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 the same folder, there is also a file 'example-activiti-ldap-for-ad.properties' which contains an example configruation for an Active Directory system.

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.

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.

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

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

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

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

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

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

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

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

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:

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

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

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.

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

The Google Drive integration can be used to:

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.

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

The Box integration can be used to:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

The following pictures gives a high-level overview:

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.

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:

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/

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

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

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

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:

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:

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.

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:

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

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

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:

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:

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:

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.

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.