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

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:

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.

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

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.

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.

This is a very basic example of a custom form field type that simply displays a static image.

Create a new form stencil in the Kickstart App and click the Add new item link.

The Form runtime template (the html used when the form is rendered at runtime) and the Form editor template (the html used in the form builder) is the same here:

Create another new item for the form stencil. This time, we’ll create a configurable image. So unlike the static image of the previous example, here the user building the form will be able to select the image that will be displayed.

The Form runtime template needs to show the image that the form builder has selected. We’ll assume we have set a property url (see later on). Note how we’re using ng-src here (see AngularJs docs on ng-src) to have a dynamic image:

Note the syntax field.params.customProperties to get access to the non-default properties of the the form field.

The Form editor template simply needs to be a generic depiction of an image or even simpler like here, just a bit of text

Don’t forget to add a property url to this stencil item with the name url and type text.

This example is more advanced then the previous two: here, we’ll have a simple list of number fields with a button at the bottom to add a new line item, while generating a pie chart on the right.

We’ll use the 'Epoch' library as an example here. Download the following files from its Github site:

Create a new form stencil item and name it "Chart". Scroll down towards the Script library imports section, and upload these two libraries. At runtime, these third party libraries will be included when the form is rendered.

Note: the order in which the third party libraries are defined is important. Since the Epoch library depends on d3, d3 needs to be first in the table and epoch second (as that is the order in which they are loaded at runtime).

The Form editor template is the easy part. We could just use an image of a pie chart here.

Let’s first define the controller for this form field type. The controller is an AngularJs controller, that will do mainly three things:

The Form runtime template needs to reference this controller, use the model and link the callback for the button:

At runtime, the following will be rendered:

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:

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.

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.

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.

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.

The simplest option is to create a class that implements the org.activiti.engine.delegate.JavaDelegate interface, like this:

Build a jar with this class, and add it to the classpath. In the Service task configuration, set the 'class' property to using the fully qualified classname (in this case my.company.MyJavaDelegate).

Another option is to use a Spring bean. It is possible to use a delegateExpression on a service task that resolves at runtime to an instance of org.activiti.engine.delegate.JavaDelegate. Alternatively, and probably more useful, is to use a general Spring bean. The application automatically scans all beans in the com.activiti.extension.bean package. For example:

Build a jar with this class, and add it to the classpath. To use this bean in a service task, set the expression property to ${helloWorldBean.sayHello(execution)}.

It is possible to define custom configuration classes (using the Spring Java Config approach) if this is needed (for example when sharing dependencies between delegate beans, complex bean setup, etc.). The application automatically scans for configuration classes in the package com.activiti.extension.conf; package. For example:

Which can be injected in the bean that will be called in a service task:

To get the current user, it is possible to use the com.activiti.common.security.SecurityUtils helper class.

The following beans are available out of the box in the Activiti BPM Suite:

A hook point is a place where custom logic can be added. Typically this is done by implementing a certain interface and putting the class implementing the interface on the classpath where it can be found by the classpath component scanning (package com.activiti.extension.bean for example)..

It’s possible to add custom REST endpoints to the BPM Suite, both in the regular REST API (used by the BPM Suite html/javascript UI) and the public API (using basic authentication instead of cookies).

The REST API in the SkyVault Activiti BPM Suite is built using Spring MVC. Please check the Spring MVC documentation on how to create new Java beans to implement REST endpoints.

To build against the REST logic of the SkyVault Activiti BPM Suite and its specific dependencies, add following dependency to your Maven pom.xml file:

The bean needs to be in the com.activiti.extension.rest package to be found!

A very simple example is shown below. Here, the Activiti TaskService is injected and a custom response is fabricated. Of course, this logic can be anything.

Create a jar containing this class, and add it to the SkyVault Activiti BPM Suite classpath.

A class like this in the com.activiti.extension.rest package will be added to the rest endpoints for the application (e.g. for use in the UI), which use the cookie approach to determine the user. The url will be mapped under /app. So, if logged in into the UI of the BPM Suite, one could go to http://localhost:8080/activiti-app/app/rest/my-rest-endpoint and see the result of the custom rest endpoint:

To add a custom REST endpoint to the public REST API, protected by basic authentication, a similar class should be placed in the com.activiti.extension.api package:

Which can be accessed like the regular API:

Note: due to classloading, it is currently not possible to put jars with these custom rest endpoints in the global or common classpath (for example tomcat/lib for Tomcat). They should be put in the web application classpath (for example WEB-INF/lib).

The REST API uses Basic Authentication for user authentication. This means that every request needs to have the Authorization header appropriately set.

The Activiti open source REST API is bundled with the SkyVault Activiti BPM Suite. This means that all operations described in the Activiti User Guide are available as documented there, except for REST endpoints that don’t make sense within the Suite product (e.g. forms, as they are implemented differently).

This REST API is available on <your-server-and-context-root>/api/

For example: fetching process definitions is described in the Activiti User Guide as an HTTP GET on repository/process-definitions. This maps to <your-server-and-context-root>/api/repository/process-definitions.

Important: requests on this REST API can only be done using a user that is a tenant admin (responsible for one tenant) or a tenant manager (responsble for many tenants). This matches the Actviti Engine (Java) Api, which is agnostic of user permissions. This means that when calling any of the operations, the tenant identifier must always be provided in the url, even if the system does not have multi tenancy (there will always be one tenant in that case).

This REST API exposes data and operations which are specific to the SkyVault Activiti BPM Suite. Contrary to the Activiti Open Source REST API it can be called using any user. The following sections describe the various REST API endpoints.

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

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 applicatio 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/