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.