It is not necessary to add configuration in order to get started. However, you will need some configuration to deploy to other environments than development and test. The plugin provides the possibility to adapt to your specific requirements by adding a new section 'camunda' to your Config.groovy (either top-level or beneath a specific environment):

camunda {
  …
}

You will need such a configuration section to deploy to other environments than development and test. Find out more in the following two chapters.

5.1 Set the deployment scenario

You can set the deployment scenario for your process engine. The plugin currently supports the deployment scenarios

'embedded' the process engine is embedded into your grails application and started and stopped with your grails application lifecycle
'shared': the process engine is shared, so preconfigured within and managed by your container
'none': the process engine configuration and startup is turned off

camunda {
  deployment.scenario = "embedded" // (or "shared", "none")
}

As long as you do not set this value explicitely, the plugin assumes for grails' environments dev and test the value 'embedded' to be the default scenario, *for all other environment the value 'shared'* (except if you have provided explicit camunda.engine.configuration values for an embedded engine in which case 'embedded' remains default for other environments, too). The moment you set this value explicitely, the plugin of course won't interfere anymore!

The moment you set the value explicitely, the plugin won't interfere with your decision. However,

Typically, you will want to use the 'shared' engine only for those grails environments which you use to prepare your container deployment war, e.g. 'production':
environments {
    production {
        camunda {
            deployment {
                scenario = "shared"
            }
        }
    }
}

Currently the plugin only supports tomcat as a container to look up a shared process engine. Download camunda BPM Tomcat distribution.

null

5.2 Configure an 'embedded' process engine

5.2.1 Configure your process engine

You can fully control your embedded camunda process engine configuration via Config.groovy:

camunda {
  engine {
    configuration {
      …
    }
  }
}

Find a full specification of the values possible in the camunda docs for the spring process engine configuration.

Note that in case you do not configure a value the plugin relies on the default values coming with the camunda engine in use - with the following three exceptions for the default grails environments development and test:

your database is populated with camunda tables the first time the database is accessed
any .bpmn (and for legacy reasons .bpmn20.xml) process definitions found in the classpath will be deployed to the database
the job executor is turned on

This choice was made in order to make it as easy as possible to get started while relying on explicit configuration choices when deploying to other (and potentially production) databases.

That means if you want to have that same behaviour for any other environment, you need to explicitely configure that in Config.groovy:

camunda {
  engine {
    configuration {
      databaseSchemaUpdate = true
      deploymentResources = ['classpath:/**/*.bpmn', 'classpath:/**/*.bpmn20.xml']
      jobExecutorActivate = true
    }
  }
}

Obviously you can also change the configuration for the environments development and test, for the sake of the example e.g. to the current camunda defaults used for the grails environment production:

camunda {
  engine {
    configuration {
      databaseSchemaUpdate = false
      deploymentResources = []
      jobExecutorActivate = false
    }
  }
}

Please be aware that during integration test phase of any environment, two camunda configuration values are set by the plugin: the camunda job executor is turned off and service mocking is made available. Find more information about that in section testing.

5.2.2 Use primitive types, beans or any other object

For configuration, you can of course use primitive typed configuration values such as Strings and booleans, like e.g.

camunda {
  engine {
    configuration {
      processEngineName = "myCustomName"
      databaseSchemaUpdate = false
    }
  }
}

but also any object available in Config.groovy or directly constructed within it, like e.g.

List<BpmnParseListener> parseHandlers = new ArrayList<BpmnParseListener>();
parseHandlers.add(new CustomParseHandler());camunda {
    engine {
        configuration {
            preParseListeners = parseHandlers
        }
    }
}

or even spring beans configured e.g. via 'grails-app/conf/spring/resources.groovy' or e.g. via 'grails-app/conf/DataSource.groovy', simply referencing them via their bean name:

camunda {
    engine {
        configuration {
            dataSource = "dataSource_camunda"
        }
    }
}

5.2.3 Use an alternative database

camunda's ORM mapping is provided by the mybatis mapping framework. Therefore the plugin can - and does by default - reuse your Grails 'dataSource' and 'transactionManager' beans, however it needs to be informed about a databaseType different from Grails default 'h2':

camunda {
  engine {
    configuration {
      databaseType = "postgres" // one of (as of writing): [h2, mysql, oracle, postgres, mssql, db2]
    }
  }
}

Find here a list of camunda's enviroments supported by the version bundled with the plugin and the corresponding configuration values for different database types.

You can also point the process engine to a different database than the one you use for your grails domain objects. First configure it in your 'grails-app/conf/DataSource.groovy'...

dataSource {
  dbCreate = "create-drop" // one of 'create', 'create-drop', 'update', 'validate', ''
  url = "jdbc:h2:mem:devDb;MVCC=TRUE;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE"
}
…
dataSource_camunda {
  dbCreate = "create-drop" // one of 'create', 'create-drop', 'update', 'validate', ''
  url = "jdbc:h2:mem:devDbCamunda;MVCC=TRUE;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE"
}

… then reference this alternative dataSource bean in 'grails-app/conf/Config.groovy':

camunda {
  engine {
    configuration {
      dataSource = "dataSource_camunda"
    }
  }
}

5.3 Configure a 'shared' process engine

5.3.1 Provide a custom processes.xml file

When deploying to a 'shared' process engine container, camunda Grails Plugin will automatically add an empty META-INF/processes.xml to your war file, in case you do not provide your own.

Please read about camunda's processes.xml to learn more about its configuration possibilities.

If you want to provide your custom processes.xml, just place it into your grails-app/processes folder like

/grails-app/processes/META-INF/processes.xml

This will be bundled with your war like any other resource file and the plugin won't interfere anymore with an empty processes.xml when building your war.

5.3.2 Provide a custom process application class

camunda Grails Plugin will automatically take care of registering a default process application class of type org.camunda.bpm.engine.spring.application.SpringServletProcessApplication for you. So normally you don't need to do anything.

However, for some reason, you may want to provide a custom process application class. Place this class inside your grails application's /src/groovy or src/java folder and register it like

environments {
    production {
        camunda {
            deployment {
                scenario = "shared"
                application = my.project.pkg.MyCustomSpringServletProcessApplication 
            }
        }
    }
}

The plugin will then use this class for either registering your custom spring process application (in case this class extends org.camunda.bpm.engine.spring.application.SpringServletProcessApplication) or for all other types the plugin will register nothing and assume that you want your container to detect and use that class. In that latter case don't forget to annotate it with org.camunda.bpm.application.ProcessApplication.

5.3.3 Configure and finetune dependencies provided by a camunda BPM container

When needing to prepare a war for a 'shared' process engine scenario, one needs to be aware that

the 'org.camunda.bpm:camunda-engine' dependencies are provided by the container
the 'org.codehaus.groovy:groovy-all' library is provided by the container

One therefore will need to configure the project dependencies in BuildConfig.groovy in a way which makes sure that those dependencies are not included in such a war (scope: 'provided'). At the same time, one might face the issue, that one needs those dependencies included in another war which is meant to work with an embedded engine (e.g. when excuting 'grails run-war'). As of Grails 2.3.x, environments can be safely used in BuildConfig.groovy. One can therefore configure something along the following lines:

environments {
  production {
    provided ("org.camunda.bpm:camunda-engine:$camundaVersion") {
      excludes 'spring-beans'
    }
  }
}

However, in order to provide an improved 'out of the box' experience for new camunda Grails Plugin users as well as provide some finetuning possibilities for advanced users, the plugin provides two configuration options with which the 'WEB-INF/lib' folder of a war prepared for a 'shared' engine scenario (and only for those scenarios) can be manipulated after having been filled with all the configured jars. Those properties are set to defaults which make sure that you can directly deploy to shared engine containers just as easy as you deploy for embedded engine scenarios. In Config.groovy you can use

camunda.deployment.shared.war.excludes = ['camunda-*.jar', 'groovy-all-*.jar']
camunda.deployment.shared.war.includes = ['camunda-engine-spring-*.jar']

With the 'includes' setting you can make an exception to the 'excludes' setting. The example given shows the defaults used by the plugin. In case you configure all the camunda dependencies for all your environments yourself in a more proper way with 'provided' scopes as shown above, you should override the defaults of those two values and set them to null. Then the plugin won't interfere with your 'shared' engine war generation any longer.

5.4 Consider 'java.util.logging' settings

camunda uses java.util.logging. Therefore you need to make a conscious choice about whether to turn on/off the 'grails.logging.jul.usebridge' setting in your Config.groovy. See the information about the performance impact on http://www.slf4j.org.

In case the bridge is not turned off explicitely by you, the plugin will turn it on for all Grails test phases. However, your explicit choice won't be overridden.

This decision in particular makes sure that the bridge is turned on for tests executed in the default Grails environment 'test', for which no explicit setting is made in the default grails application. As soon as you make an explicit decision for any of your default or custom environments, the plugin won't interfere anymore.

5.5 Use an alternative version of camunda

Currently the plugin comes bundled with a dependency to the release 7.3.0 of camunda BPM. However you may want to choose another version. You then have to explicitely override the needed dependencies in your BuildConfig.groovy:

dependencies {
  compile ("org.camunda.bpm:camunda-engine:$camundaVersion") {
    excludes 'spring-beans'
  }
  runtime ("org.camunda.bpm:camunda-engine-spring:$camundaVersion") {
    excludes 'spring-context', 'spring-jdbc', 'spring-orm'
  }
}

Replace '$camundaVersion' with the version of camunda of your choice. It is recommended to explicitely exclude any spring dependencies coming with camunda and make sure to properly test your application with the spring framework version provided by the Grails version you use.

Note that for camunda versions prior to 7.1.0-Final, you must also configure camunda's custom maven repository:

repositories {
  mavenRepo "https://app.camunda.com/nexus/content/groups/public"
}

5.6 Provide alternative bean names

Many of camunda's API service names are quite generic (like 'taskService', 'managementService' etc) and could easily clash with names you want to use in your application for other purposes - even more so when having in mind the Grails naming convention to use *Service as a name pattern for Grails services. On the other hand typical camunda users are used to the established service names and will expect to use these services via their established names. Therefore the plugin provides these services via the established names. However, in order to avoid potential name conflicts with grails services pre-existing in your project, the plugin also allows to change these default bean names via configuration:

camunda {
  beans.runtimeService = 'myCamundaRuntimeService'
}

Internally the plugin realises this with Spring's bean aliasing mechanism. Instead of the default alias 'runtimeService' the custom alias 'myCamundaRuntimeService' is used. You can then inject your 'org.camunda.bpm.engine.RuntimeService'-typed bean as

def myCamundaRuntimeService

5.7 Override plugin configuration with custom beans

Of course, it is also possible to override some or all of the camunda spring beans defined by the plugin via the standard Grails way: by editing 'grails-app/conf/spring/resources.groovy'. In order to do that properly it is useful to know that the plugin registers all beans following the name convention camunda[DefaultAlias]Bean, e.g. the 'processEngine' is registered as bean 'camundaProcessEngineBean', then given either its default alias 'processEngine' (or its custom alias defined by the user).

This decision was made partly in order to allow the configuration of alternative bean names, partly because some historic 2.3 versions of Grails display issues with custom spring beans named in potential "conflict" with the *Service name convention for Grails services.

5.8 Configure auto reloading of bpmn process definitions

You can automatically reload and redeploy '.bpmn' process definitions placed beneath 'grails-app/processes'. When changing the process definition while you are running your application with 'run-app', it will be redeployed to the process engine.

You can turn this feature on/off explicitely:

camunda {
  deployment.autoreload = true // (or false)
}

The autoreload feature is by default enabled for grails 'dev' and 'test' environments. For all other environments it is by default disabled.

<< 4User Guide

6Deployment Guide >>

5 Configuration Guide - Reference Documentation

Table of Contents

5 Configuration Guide