Adding JSF Forms to your Process Application

A working example can be found in the .

The BPMN process used for this example is shown in the image below:

In this process model we added so called form keys to

  • the Start Event “invoice received”. This is the form the user has to complete to start a new process instance.
  • the User Tasks. These are the forms the user has to complete when completing user tasks that are assigned to him.
    This is how the forms are referenced in the BPMN 2.0 XML with the attribute:

Creating Simple User Task Forms

Create a JSF page in src/main/webapp/WEB-INF representing a form used for User Tasks. A very simple task form is shown below:

  1. <!DOCTYPE HTML>
  2. <html lang="en" xmlns="http://www.w3.org/1999/xhtml"
  3.   xmlns:ui="http://java.sun.com/jsf/facelets"
  4.   xmlns:h="http://java.sun.com/jsf/html"
  5.   xmlns:f="http://java.sun.com/jsf/core">
  7. <f:view>
  8.   <h:head>
  9.     <f:metadata>
  10.       <f:event type="preRenderView" listener="#{camundaTaskForm.startTaskForm()}" />
  11.     </f:metadata>
  12.     <title>Task Form: #{task.name}</title>
  13.   </h:head>
  14.   <h:body>
  15.     <h1>#{task.name}</h1>
  16.     <h:form id="someForm">
  17.       <p>
  18.         Here you would see the actual form to work on the task in a design
  19.         normally either matching your task list or your business application
  20.         (or both in the best case).
  21.       </p>
  23.       <h:commandButton id="complete" value="Task Completed"
  24.           action="#{camundaTaskForm.completeTask()}" />
  25.     </h:form>
  26.   </h:body>
  27. </f:view>
  28. </html>

Note that you need camunda-engine-cdi in order to have the camundaTaskForm bean available.

How does this work?

If the user clicks on “Start to work on task”

  • starts a conversation,
  • remembers the callback URL
  • starts the User Task in the process engine, meaning the bean sets the start date and assigns the task to the CDI business process scope (see CDI Integration for details).
    For that, you just need to add this code block to the beginning of your JSF view:
  1. <f:metadata>
  2.   <f:event type="preRenderView" listener="#{camundaTaskForm.startTaskForm()}" />
  3. </f:metadata>

Submit the form by calling the camundaTaskForm bean again, which:

  • Completes the task in the process engine, causing the current token to advance in the process
  • Ends the conversation
  • Triggers a redirect to the callback URL of the tasklist

Note that the command button doesn’t have to be on the same form, you might have a whole wizard containing multiple forms in a row before having the completeTask button. This will work because of the conversation running in the background.

Access Process Variables

In the forms you can access your own CDI beans as usual and also access the Camunda CDI beans. This makes it easy to access process variables, e.g., via the processVariables CDI bean:

  1.   <p>Here you would see the actual form to work on the task in some design normally either matching you task list or your business application (or both in the best case).</p>
  3.     <tr>
  4.       <td>
  5.         Process variable <strong>x</strong> (given in in the start form):
  6.       </td>
  7.       <td>
  8.         <h:outputText value="#{processVariables['x']}" />
  9.       </td>
  10.     </tr>
  11.     <tr>
  12.       <td>
  13.         Process variable <strong>y</strong> (added in this task form):
  14.       </td>
  15.       <td>
  16.         <h:inputText value="#{processVariables['y']}" />
  17.       </td>
  18.     </tr>
  19.     <tr>
  20.       <td></td>
  21.       <td>
  22.         <h:commandButton id="complete" value="Task Completed"
  23.             action="#{camundaTaskForm.completeTask()}" />
  24.       </td>
  25.     </tr>
  26.   </table>
  27. </h:form>

This is rendered to a simple form:

JSF Task Forms - 图1

The same mechanism can be used to start a new process instance:

  1. <!DOCTYPE HTML>
  2. <html lang="en" xmlns="http://www.w3.org/1999/xhtml"
  3.   xmlns:ui="http://java.sun.com/jsf/facelets"
  4.   xmlns:h="http://java.sun.com/jsf/html"
  5.   xmlns:f="http://java.sun.com/jsf/core">
  7. <f:view>
  8.   <f:metadata>
  9.     <f:event type="preRenderView" listener="#{camundaTaskForm.startProcessInstanceByKeyForm()}" />
  10.   </f:metadata>
  11.   <h:head>
  12.     <title>Start Process: #{camundaTaskForm.processDefinition.name}</title>
  13.   </h:head>
  14.   <h:body>
  15.     <h1>#{camundaTaskForm.processDefinition.name}</h1>
  17.       <p>
  18.         Here you see the actual form to start a new process instance, normally
  19.         this would be in some design  either matching you task list or your business
  20.         application (or both in the best case).
  21.       </p>
  23.       <table>
  24.         <tr>
  25.           <td>
  26.             Process variable <strong>x</strong>:
  27.           </td>
  28.           <td>
  29.             <h:inputText value="#{processVariables['x']}" />
  30.           </td>
  31.         </tr>
  32.         <tr>
  33.           <td></td>
  34.           <td>
  35.             <h:commandButton id="start" value="Start Process Instance"
  36.                 action="#{camundaTaskForm.completeProcessInstanceForm()}" />
  37.           </td>
  38.         </tr>
  39.       </table>
  40.     </h:form>
  41.   </h:body>
  42. </f:view>
  43. </html>

JSF Task Forms - 图2
in the tasklist and chooses the process your start form is assigned to, he will follow a link to this form, including the processDefinitionKey and the callback URL (the URL to access the central tasklist) as GET-Parameters. Accessing this form will trigger the special CDI bean camundaTaskForm which:

  • Starts a conversation
  • Remembers the callback URL to the centralized tasklist
    You need to add this code block to the beginning of your JSF view:

Submitting the start form now:

  • Starts the process instance in the process engine
  • Ends the conversation
  • Triggers a redirect to the callback URL of the tasklist
    1. <h:commandButton id="start" value="Start Process Instance" action="#{camundaTaskForm.completeProcessInstanceForm()}" />

Note that the command button doesn’t have to be on the same form, you might have a whole wizard containing multiple forms in a row before having the completeProcessInstanceForm button. This will work because of the conversation running in the background.

Styling your Task Forms

We use in our tasklist - so best add this to your Process Application as well and you can easily polish your UI:

To include CSS and Javascript libraries in your project you can add them to your maven project as dependencies.

  1. <dependencies>
  3.   <!-- ... -->
  5.   <dependency>
  6.     <groupId>org.webjars</groupId>
  7.     <artifactId>bootstrap</artifactId>
  8.     <version>3.1.1</version>
  9.   </dependency>

To use them, add tags like the following ones to your JSF page. If you have several forms, it may be helpful to create a template that you can refer to from your forms to avoid redundancies..