View source

__NOTOC__
 NOTE: JRapid and Activiti BPM integration is in Beta stage.

[http://en.wikipedia.org/wiki/Business_process_management BPM] solves the problem of modeling and orchestrating business processes. 
[http://www.activiti.org Activiti] is a light-weight workflow and BPM Platform. It can be integrated with a [http://www.jrapid.com JRapid] project to provide a complete solution for BPM. JRapid allows you to easily create the necessary forms to support user tasks present in processes.

==Installation==
===1. Create and update JRapid project===
Create a new project on a [[Server#Dedicated_Servers|dedicated server]], as you will need to be able to upload files and add custom Java code to your classes.
 '''Note''': You will not be able to follow this tutorial on the cloud environment if your project is hosted
 on a [[Server|Shared Development Server]], as these do not allow developers to upload custom code and new files.
 You may test your project by [[Run Project In Eclipse|running the application in a local development environment]].


[[Update Project Version|Update you JRapid project's version]] and make sure it is at least 1.0nb97.

Use JRapid's [[Eclipse Plugin|Eclipse Plug-in]] to synchronize the project with your local Eclipse workspace.

===2. Download required installation files===
Download the installation bundle containing all the required files from [http://img.jrapid.net/files/jrapid-activti-setup.zip here]. Unpack to a known location in your hard disk.

===3. Import the required Java libraries to your project===
Find the required Java libraries in the libs/ folder included in the installation bundle. Copy the library files to your project’s ''/WebContent/WEB-INF/lib'' folder and make sure they are added to the classpath.

JRapid and Activiti integration required libs:

<table>
<tr><td>
* jrapid-bpm.jar
* activation-1.1.jar
* activiti-engine-5.6.jar
* activiti-pvm-5.0.beta2.jar
* antlr-2.7.4.jar
* commons-email-1.2.jar
* groovy-all-1.7.2.jar
* hibernate-jpa-2.0-api-1.0.0.Final.jar
</td>
<td>
* javassist-3.12.0.GA.jar
* jaxb-api-2.1.jar
* jaxb-impl-2.1.7.jar
* jaxb-xjc-2.1.7.jar
* juel-impl-2.2.1.jar
* livetribe-jsr223-2.0.6.jar
* log4j-1.2.9.jar
</td>
<td>
* mail-1.4.1.jar
* mybatis-3.0.1.jar
* slf4j-api-1.6.1.jar
* spring.jar
* spring-security-core-2.0.4.jar
* stax-api-1.0-2.jar
* wsdl4j-1.6.2.jar
</td>
</tr>
</table>

===4. Import User Management Template===
Use the ''Add-ons'' menu option in the JRapid Designer to import the ''User Management'' template from the [http://community.jrapid.com/ JRapid Community] and add the necessary Privileges, Roles and Users.

[[File:bpm9.jpg]]


Make sure you add the ''LOGGED'' value to the Privileges enumset.


[[File:bpm9b.jpg]]

Source AML definition:
<pre class="brush:xml;">
    <enumset name="Privileges" privileges="privileges">
        <enum value="LOGGED">LOGGED</enum>
        <enum value="HELPDESK">HELPDESK</enum>
        <enum value="APPROVER">APPROVER</enum>
        <enum value="ANONYMOUS">ANONYMOUS</enum>
    </enumset>
</pre>

===5.  Import Activiti Process Template===
Import the ''BPM Process'' template from the [http://community.jrapid.com/ JRapid Community].

Create the required Activiti database tables using the contents of the scripts in the db folder provided with the downloaded bundle by connecting through a SQL client. You may use MySQL Query Browser and the [[Database|database connection info]] for your project.

Read [[Database#Development_Database_Schema|this]] for more information on how to connect to your project's database schema.

===6. Import BPM Processes View===
Import the ''Activiti BPM Processes'' View from the [http://community.jrapid.com/ JRapid Community].

===7. Import BPM Inbox View===
Import the ''Activiti BPM Inbox'' View from the [http://community.jrapid.com/ JRapid Community].


===8. Configure the Users and Roles DAO and email===
Add the following lines to your ''jrapid.properties'' file, replacing %BASE_PACKAGE% with your project's base package name:

<pre class="brush:plain">
default.bpm.userdao=%BASE_PACKAGE%.dao.hibernate.HibernateUserDAO
default.bpm.roledao=%BASE_PACKAGE%.dao.hibernate.HibernateRoleDAO
default.bpm.processdefinitiondao=%BASE_PACKAGE%.dao.hibernate.HibernateProcessDefinitionDAO
default.bpm.locator=%BASE_PACKAGE%.dao.MainDAOLocator
</pre>

If you're planning to create tasks that send emails add the following properties to ''jrapid.properties'' file, replacing the corresponding values for your outgoing email service:

<pre class="brush:plain">
default.mail.smtp.host=smtp.gmail.com
default.mail.smtp.port=587
default.mail.smtp.username=
default.mail.smtp.password=
</pre>

===9. Add modified MailActivityBehavior class===
Copy the ''org'' folder included in the installation package files to your project's ''JavaSource/'' folder.

[[File:bpm9d.jpg]]

===10. Add TaskServices methods===
Use the ''TaskServicesMethods.txt'' included in the installation bundle or the code snippet below to add the code to the TaskServices class. These overridden methods provide the business logic necessary for listing tasks in the Inbox.


<pre class="brush:java;">
	@Override
	public Collection<Task> findSubsetUnassigned(Map<String, String> params) {
		List<Task> tasks = new ArrayList<Task>();
		ProcessEngine processEngine = Engine.getEngine();
		
		for (org.activiti.engine.task.Task t:processEngine.getTaskService().createTaskQuery().taskCandidateUser(Session.getMySession().getUsername()).list()) {
			tasks.add(new TaskWrapper(t, el));
		}
		
		return new Page<Task>(tasks, 1, 1, tasks.size());
			
	}
	@Override
	public Collection<Task> findSubsetAssignedToMe(Map<String, String> params) {
		List<Task> tasks = new ArrayList<Task>();
		ProcessEngine processEngine = Engine.getEngine();
		
		for (org.activiti.engine.task.Task t:processEngine.getTaskService().createTaskQuery().taskAssignee(Session.getMySession().getUsername()).list()) {
			tasks.add(new TaskWrapper(t, el));
		}
		
		return new Page<Task>(tasks, 1, 1, tasks.size());
			
	}
	
	static class TaskWrapper extends Task {

		

		public TaskWrapper(org.activiti.engine.task.Task t, EL el) {
			ProcessDefinition def = ProcessDefinition.DAO().findOneBy("processDefinitionId", t.getProcessDefinitionId());
			if (def != null) {
				Map<String, Object> vars = Engine.getEngine().getRuntimeService().getVariables(t.getExecutionId());
				this.setDescription(el.evaluate(def.getLabel(), String.class, vars));
				this.setIcon("../upload/" + def.getIcon());
			}
			this.setName(t.getName());
			this.setTaskId(t.getId());
			GregorianCalendar date = new GregorianCalendar();
			date.setTime(t.getCreateTime());
			this.setCreateTime(date);
			this.setFormKey(Engine.getEngine().getFormService().getTaskFormData(t.getId()).getFormKey());
		}

		
	}
</pre>

===11. Add ProcessDefinitionFileServices methods===
Use the ''ProcessDefinitionFileServicesMethods.txt''  or the code snippet below to add the code to the ProcessDefinitionFileServices class.

<pre class="brush:java;">
@Override
    public Collection<ProcessDefinitionFile> findPage(Map<String, String> params) {
        
        ArrayList<ProcessDefinitionFile> files = new ArrayList<ProcessDefinitionFile>();
        
        File dir = new File(Session.getMySession().getRequest().getRealPath("WEB-INF/bpm"));
        System.out.println(dir.getAbsolutePath());
        if (dir.exists()) {
            for (String file : dir.list()) {
                System.out.println(file);
                if (file.endsWith(".bpmn20.xml")) {
                    ProcessDefinitionFile pdf = new ProcessDefinitionFile();
                    pdf.setFile(file);
                    pdf.setId(file);
                    files.add(pdf);
                }
            }            
        }        
        
        return new Page<ProcessDefinitionFile>(files, 1, 1, files.size());
    }
</pre>

===12. Add BPM console===
Add the ''bpm'' folder included in the installation bundle to your ''WebContent/'' folder.
Replace ''bi.tld'' in ''/WebContent/WEB-INF'' folder with the new version provided in the installation package.

==Modeling your process==

===1. Model your BPM process===
Switch to the JRapid Designer BPM view by clicking on the BPM link at the top right corner.


[[File:bpm2_1.jpg]]


Use the Signavio Activiti Modeler embedded in the JRapid Designer to model your process and save the definition.
You may read more about getting the modeler to run on you computer following [http://www.activiti.org/userguide/index.html#demo.setup.one.minute.version this].


Click the Create button in the BPM Options pane to launch the modeler.


[[File:bpm2_2.jpg]]


You'll be asked to enter a name for the new process.


[[File:bpm2_3.jpg]]


Once you click OK the Signavio Activiti Modeler will be opened.


[[File:bpm2_4.jpg]]


Model your process, making sure you set the corresponding Task Type to each entity in the Properties dialog.
Currently, the only supported task types are User, Service and Script.


[[File:bpm2_8.jpg]]


Save the model.

[[File:bpm2_5.jpg]]

===2. Create JRapid forms===
Create forms for each user task by clicking on the ''Create Forms'' button.

[[File:bpm2_6.jpg]]

This will open a dialog that lists all the existing User tasks in your process. Check the ones you would like a form to be created for. Note that the start event can create a form too.

[[File:bpm3.jpg]]

===3. Add properties to forms===
Once the entities for the forms are created you must edit each user task entity and add the necessary properties, mapping them to the corresponding process engine variables.

Click on the Link Forms button to open the BPM process diagram.


[[File:bpm2_7.jpg]]


Click on a user task on the BPM process diagram and a dialog is opened.


[[File:bpm4.jpg]]


Use the ''Edit form'' link to open the edit entity dialog and add the necessary properties.


[[File:bpm4a.jpg]]


Click OK to save the changes an go back to the ''Edit user task'' dialog. Use the ''Asignee'', ''Candidate users'' or ''Candidate groups'' fields to specify the user or users this task will be assigned to or available to claim. '''The values for the ''Candidate groups'' field must match existing system Roles.'''

Now map the entity properties to the process engine variables as shown in the next picture.


[[File:bpm5.jpg]]


Repeat the procedure described above for each user task.

When you click on services tasks, used in this case for sending email notifications, the dialog shown is the following.
The ''type'' is set to ''mail'', but services tasks may also define class or expression services. Remember that you must [[email (value of stereotype)|configure how emails are to be sent]].

[[File:bpm6.jpg]]

===6. Override find method of User Task entities===
Edit the Services class for every entity that implements a User Task in your process and override the ''find()'' method to include the following code:

<pre class="brush:java">
return super.doFind(id, super.find(id));
</pre>

For example, the RegisterTravelExpense user task that maps to the JRapid entity with the same name generates the RegisterTravelExpenseServices class where the ''find()'' method must be overridden as follows:


<pre class="brush:java">
public class RegisterTravelExpenseServices extends RegisterTravelExpenseServicesAbstract {
	
	@Override
	public RegisterTravelExpense find(String id) {
		return super.doFind(id, super.find(id));
	}

}
</pre>

===7. Deploy process definition to your project===
Import your process definition to the [http://www.jrapid.com JRapid] application through the ProcessDefinition entity form. Enter a name and select the file corresponding to your BPM process definition. Mark as active. The installation bundle includes an ''icons'' folder with example images you may use.

[[File:bpm_p_def.jpg|BPM Process definition]]

===8. Create new process instance===
Login to your application with a valid user and go to you Inbox panel. You must create valid users first and assign them the corresponding user roles. Remember you must create the LOGGED role, grant it the LOGGED privilege and assign it to every user as the Inbox Panel included in the BPM template assumes users are granted this role.

[[File:bpm8.jpg]]

Start your process from the Process Definitions listing by clicking on the corresponding ''Start'' button. This will create a new process instance. Refresh your Tasks listing and the instance should be listed there if you are the assignee or a member of the candidate role for the first user task.

==See Also==

* [http://www.activiti.org Activiti BPM Platform]
* [http://www.jrapid.com JRapid Website]

* [http://www.jrapid.com/starting-guide-web-designer.html Getting Started with JRapid web-based Designer]
* [http://www.jrapid.com/starting-guide-eclipse-plugin.html Getting Started with JRapid Eclipse Plugin]

* [[Run Project In Eclipse]]

* [[Eclipse Plugin|JRapid Eclipse Plugin]]

[[Category:Concept]]
[[Category:Article]]