1 Introduction

Please check out camunda.org to get started with camunda BPM. Read on here to get started with the camunda Grails plugin!

2 Get Started

2.1 Install the plugin

plugins {
    compile ":camunda:0.5.0"
}

You may want to refresh your dependencies now in order to make sure that Grails properly installs the plugin. Type on your command line

grails refresh-dependencies

2.2 Create a process definition

grails create-process [name]

As name choose a 'package and class' like name of your choice, e.g. "org.camunda.my.TestProcess". You should see the following two files generated by Grails:

| Created file grails-app/processes/org/camunda/my/TestProcess.bpmn
| Created file test/integration/org/camunda/my/TestProcessSpec.groovy

You may now want to look at the generated BPMN process definition by making use of camunda modeler. It's a minimal process, to get you started and build upon:

Furthermore you will find a 'spock' based integration spec executing and checking that process. It does have a bit more content than your typical almost empty Grails spec template...

[...]
given: "a new instance of TestProcess"
runtimeService.startProcessInstanceByKey("TestProcess")
when: "completing the user task"
def task = taskService.createTaskQuery().singleResult()
taskService.complete(task.id)
then: "the service method defined for the subsequent service task was called exactly once"
1 * sampleTestProcessService.serviceMethod(_ as Execution)
[...]

… again to get you started with typical process testing boilerplate readily adapted to your freshly created process definition and to build upon. You can directly execute that test:

2.3 Execute the integration test

Beware that this test will populate your test environment database with camunda related tables. By default, this will be a H2 in memory database preconfigured by Grails - so everything fine with that. For other databases, you will need to adapt the plugin configuration, too.

grails test-app integration: org.camunda.my.TestProcess

When executing the test you should see the following familiar output :-)

| Running 1 integration test… 1 of 1
| Completed 1 integration test, 0 failed in 0m 0s
| Tests PASSED - view reports in ./target/test-reports

Congrats! You are successfully using an embedded camunda BPM engine with the Grails framework! If you want to use camunda "behind the scenes" of your grails app that's all that is needed! But maybe you …

2.4 Wanna see camunda BPM in action?

./start-camunda.sh

Now, return to your your grails project command line, and create a 'war' file prepared to use the process engine managed by the camunda BPM tomcat container and shared with your grails app:

grails war

Move the war generated in your target folder into the camunda BPM tomcat 'webapp' folder. Open http://localhost:8080/camunda-welcome and navigate to the tasklist application. Log in with user 'demo', password 'demo' and start your new process via the (little bit hidden :-) "start process" button in the top right corner:

The sample form shows you different types of fields. You must at least select one of the values in the 'sampleRequiredSelectionField' in order to validate the start form and enable the "Start"-Button. Start the process and you should see the "Sample UserTask" of your process assigned to you as user "demo". You may want to check out the diagram pane of your process and then complete the task via the form. This will execute the subsequent service task (which logs the process variables provided by you into your tomcats logs/catalina.out file) and immediately after that finish your process instance.

3 A Word about Conventions

• your-project = top level project directory
• grails-app = standard grails layout directory
• processes = process definitions directory for *.bpmn resources

Within that folder you may choose to group your *.bpmn process definitions into packages. Every *.bpmn file inside that directory will go into your *.war when packaging it via Grails. (You may then choose to automatically redeploy those process definitions - or not - by explicitely configuring the 'deploymentResources' setting of your configuration.)

The create-process command uses another two naming conventions. The name you choose for your process will be suffixed with *Process.bpmn - in case you haven't provided that yourself as a part of the name. Therefore issueing e.g.

grails create-process org.camunda.my.Test

will result in the following two files being generated for you:

| Created file grails-app/processes/org/camunda/my/TestProcess.bpmn
| Created file test/integration/org/camunda/my/TestProcessSpec.groovy

Furthermore, every executable BPMN process must have an id defined inside its xml structure. The plugin takes care of generating this id for you - in the given example as "TestProcess", hence the name of the generated bpmn resource - but without package name and file extension:

<process id="TestProcess" name="TestProcess" isExecutable="true">
  …
</process>

When editing this freshly generated process definition with camunda modeler, you will see this id when opening the "properties" pane and clicking into the free area of the diagram:

Feel free to change the generated 'name' attribute to a better human readable version of the name!

This 'id' attribute is needed when using the camunda API services, like e.g. starting a process instance by 'key' (which is referring to this id attribute):

runtimeService.startProcessInstanceByKey("TestProcess")

Both conventions - the *Process suffix as well as the artifact 'id' being unique across packages follow typical Grails conventions and therefore make sense for greenfield projects. However, the plugin will not strictly enforce these conventions. You may choose to place other *.bpmn files into your grails-app/processes folder and they will be accessible by integration tests, bundled into the war and deployed to the engine, too.

4 User Guide

4.1 Create a process definition

grails create-process [name]

As name choose a 'package and class' like name of your choice, e.g. "org.camunda.my.TestProcess". You should see the following two files generated by Grails:

| Created file grails-app/processes/org/camunda/my/TestProcess.bpmn
| Created file test/integration/org/camunda/my/TestProcessSpec.groovy

You may now want to look at the generated BPMN process definition by making use of camunda modeler. It's a minimal process, but enough to get you started with user tasks and services and to build upon:

Furthermore you will find a 'spock' based integration spec executing and checking that process. It does have a bit more content than your typical almost empty Grails spec template...

[...]
given: "a new instance of TestProcess"
runtimeService.startProcessInstanceByKey("TestProcess")
when: "completing the user task"
def task = taskService.createTaskQuery().singleResult()
taskService.complete(task.id)
then: "the service method defined for the subsequent service task was called exactly once"
1 * sampleTestProcessService.serviceMethod(_ as Execution)
[...]

… again to get you started with typical process testing boilerplate readily adapted to your freshly created process definition and to build upon. Please check out the chapter about conventions in order to fully appreciate the consequences of the process template being generated for you.

4.2 Inject camunda API Services

import org.camunda.bpm.engine.*
… 
AuthorizationService authorizationService
FormService formService
HistoryService historyService
IdentityService identityService
ManagementService managementService
RepositoryService repositoryService
RuntimeService runtimeService
TaskService taskService
CaseService caseService
FilterService filterService

Note that many of these bean 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 service names shown above and will expect to use these services via their established names. Therefore the plugin provides these services via those names shown above. 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.

In addition to the camunda API services, the ProcessEngine itself can be used as an injectable dependency, too:

import org.camunda.bpm.engine.*
… 
ProcessEngine processEngine

As an alternative to building your custom 'full fledged' grails application, you might want to use camunda tasklist to work yourself through your processes. In that case you will want to create some forms which can be presented to your camunda BPM tasklist user.

4.3 Develop a camunda BPM tasklist application

Using the camunda BPM tasklist with 'embedded' forms as described in this section, will just work with a 'shared' process engine deployment scenario.

With the help of the camunda Grails Plugin you can use grails gsp views to dynamically render 'embedded' forms and hook them to the camunda BPM tasklist. You just need two things: First, place your form into the views folder, like e.g. ...

/grails-app/views/test/sampleForm.gsp

… and second, associate your form to your process definition by attaching an attribute camunda:formKey to your 'userTask' xml element:

<userTask id="UserTask_1" name="Sample UserTask" camunda:formKey="embedded:app:camunda/test/sampleForm"/>

Or, for a start event, it would look very similar:

<startEvent id="StartEvent_1" name="Sample StartEvent" camunda:formKey="embedded:app:camunda/test/sampleForm"/>

Of course, you can also do this by making use of the camunda modeler properties pane:

But what happens now behind the scenes at run time? First, when you start a process or open a task with camunda BPM task list, it will realise that you want to use an 'embedded' form and that you want to provide it via your grails web 'app' (from camunda's tasklist perspective you provide it from the application, which deployed the process definition with that formKey). The tasklist will therefore request the form from the absolute path '/your-grails-app-context/camunda/test/sampleForm'. The string 'camunda/test/sampleForm' is the string you provided in the formKey. camunda Grails Plugin will then respond with the html body only of your 'test/sampleForm.gsp' and deliver it to the task list (by means of a plugin provided grails controller named 'camunda').

Make sure that the body of your gsp just contains a single form element and that the html follows the conventions for camunda embedded forms. Of course you are free to dynamically generate that html via gsp mechanisms. To learn more about camunda embedded forms, you may want to look at the raw html code of the sample form provided with camunda Grails Plugin or consult camunda's embedded-task-forms docs.

4.4 Redirect camunda BPM tasklist to your own grails application

camunda:formKey="embedded:app:forms/index"

or as an external form link clickable via the task list:

camunda:formKey="app:forms/index"

In both cases camunda's task list would now invoke your 'FormsController's 'index()' method (provided you use a standard grails UrlMappings layout). For embedded forms it would again expect to see just a HTML 'form' element. For external forms, you would render the full page yourself and would also need to take care of the subsequent form actions yourself. camunda BPM tasklist will provide you with a taskId url parameter to look up the task as well as with a callbackUrl parameter to redirect back to the task list.

5 Configuration Guide

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

• '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"
            }
        }
    }
}

null

5.2 Configure an 'embedded' process engine

5.2.1 Configure your process engine

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

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

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

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

1. the 'org.camunda.bpm:camunda-engine' dependencies are provided by the container
2. 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

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

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

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

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

6 Deployment Guide

6.1 Consider your deployment scenario

Do you either want to use the engine just behind the scenes of your own custom grails application with your own forms, controllers, services etc? Then go for the embedded engine. Or do you want to use the camunda BPM platform 'tasklist' with embedded forms and implement a grails based process application for it? Then go for the shared engine. In that case you will still want to use an embedded engine for testing your application.

Now, configure your deployment scenario accordingly! Then move on with deploying your application according to your scenario.

6.2 Scenario 'shared' process engine

(2) Make sure you declared the shared engine for those grails environments with which you prepare your container deployment war, e.g. 'production':

environments {
    production {
        camunda.deployment.scenario = "shared"
    }
}

(3) camunda BPM comes bundled with a dependency to the 'org.codehaus.groovy:groovy-all' library, which causes failure when deploying groovy/grails based applications bundled with their own version of that library. Therefore the plugin prevents the bundling of the 'org.codehaus.groovy:groovy-all' library bundled with grails and instead assumes that this library is already provided by the container. When preparing the camunda BPM container for a production environment, you should check that the 'org.codehaus.groovy:groovy-all' library version bundled in the container matches the version you need for your grails application and eventually replace it with the version you need.

You might want to check how to configure and finetune the dependencies provided by a camunda BPM container for a shared engine in greater detail.

Finally, build your 'war' file ...

grails war

...and deploy it to your camunda BPM containers 'webapp' folder. Open http://localhost:8080/camunda-welcome and browse to camunda cockpit or tasklist application.

6.3 Scenario 'embedded' process engine

environments {
    production {
        camunda {
            deployment.scenario = 'embedded'
            engine {
                configuration {
                    databaseSchemaUpdate = true
                    deploymentResources = ['classpath:/**/*.bpmn']
                    jobExecutorActivate = true
                }
            }
        }
    }
}

Finally, build your 'war' file ...

grails war

...and deploy it to your servlet container, e.g. by placing it into tomcats 'webapp' folder.

Optionally, you might want to download camunda BPM standalone webapp, deploy it alongside your grails' webapp and point it to the database of your embedded engine. You can then use camunda BPM cockpit to monitor and manage your processes. You can also use tasklist and work with 'generated' and/or 'external' forms, 'embedded' forms however will just work in the 'shared' process engine scenario.

7 Testing Guide

Beware: you can explicitely turn on/off the job executor in your environment by configuration. In this case the plugin will not interfere with your explicit choice!

In essence this behaviour makes sure that you can perform your tests

• in a single-threaded manner, fully controlled by your test code, and without having the job executor interfering from background threads.
• with the possibility to mock your service calls from within the process

7.1 Drive the process instances

<serviceTask id="myServiceTask" … camunda:async="true">
…
</serviceTask>

In such a case you must now mimic the work of the background job executor and explicitely tell the process to "move on" with execution, e.g. by writing:

def job = managementService.createJobQuery().processInstanceId(pid).singleResult()
managementService.executeJob(job.id)

7.2 Mock the service calls

<serviceTask id="myServiceTask" camunda:expression="#{sampleTestProcessService.serviceMethod(execution)}" … >
…
</serviceTask>

For your tests, instead of calling your actual service 'sampleTestProcessService' you can call a mock, like e.g.

def sampleTestProcessService = Mock(SampleService)
org.camunda.bpm.engine.test.mock.Mocks.register("sampleService", sampleTestProcessService)

This will make sure that the juel identifier 'sampleService' will be resolved to the mock instance, provided you use the MockExpressionManager for resolving your JUEL expression identifiers - which is what the plugin will make sure for Grails' integration test phase.

7.3 Auto reload and redeploy your bpmn process definitions

Also check the possibility to turn this feature on/off explicitely by configuration.

8 Further Resources

8.1 camunda Grails plugin

• grails.org Website
• Documentation
• GitHub Repository
• Issue Tracking
• Roadmap
• Changelog

8.2 camunda BPM

• User Guide
• Installation Guide
• BPMN 2.0 Implementation Reference
• Java API
• GitHub Repositories
• Issue Tracking

8.3 camunda Modeler

• BPMN 2.0 Modeler
• BPMN 2.0 Modeling Reference