# Introduction

The Eclipse BPMN2 Modeler is an open-source, graphical tool for authoring and editing files that are compliant with the OMG BPMN 2.0 standard. It is assumed that the reader is familiar with BPMN 2.0 and its applications; discussions about the details of the BPMN 2.0 specification (a.k.a. “the spec”) are beyond the scope of this document, but there are many resources online [1] and in print [2], [3] that cover this topic.

The foundation of the BPMN2 Modeler is the Eclipse BPMN2 Metamodel [4] (a.k.a. “the model”), which was developed by contributing members of the OMG BPMN 2.0 working group and is fully compliant with the spec. However, the BPMN2 Modeler UI surfaces only the most commonly used elements, simply because the model is incredibly complex and all-inclusive. In the real world, most BPMN execution engines only support a subset of the spec, and the BPMN2 Modeler can be easily customized to target any spec-compliant runtime with User Preference settings and/or specialized extension plug-ins.

This document covers version 1.0.1 of BPMN2 Modeler, published November 15, 2013.

## Background

Development of the BPMN2 Modeler project is sponsored by Red Hat/JBoss and was intended to replace the Eclipse-based BPMN Designer, developed in-house for jBPM. As the jBPM engine evolved to support more and more features of the spec, it became increasingly difficult to extend the Designer to support those features.

Being the leader of open source, Red Hat understands the benefits of developing software in the community, and it was decided at the beginning that the replacement for the BPMN Designer should not be limited to only supporting the jBPM suite, but should be broader in scope and fully spec compliant. Not only is this a good thing for the community, but it also leaves the path open for the jBPM suite to evolve as new features are requested by customers.

This User Guide covers both the generic editor as well as the jBPM Target Runtime plug-in extensions.

## Eclipse Platform Compatibility

The BPMN2 Modeler uses Graphiti, a project that is (as of this writing) still in the incubation phase at Eclipse. Because there are several released versions of the Graphiti API that are incompatible with each other, there are also different versions of the BPMN2 Modeler for each version of Graphiti. The table below summarizes these versions and their Eclipse platform releases.

Table 1: Eclipse Platform Compatibility

Graphiti versions | Eclipse Platform versions | BPMN2 Modeler update site
0.8.2 | 3.6.2 (Helios) | http://download.eclipse.org/bpmn2-modeler/updates/helios
0.9.2 | 3.7 - 4.2.1 (Indigo - Juno) | http://download.eclipse.org/bpmn2-modeler/updates/juno
0.10.0 | 4.3 (Kepler) | http://download.eclipse.org/bpmn2-modeler/updates/kepler

Note that while the Graphiti project’s policy is to maintain backward-compatibility with at least one prior version of Eclipse, there may be problems installing two different versions of its API in the same Workbench. Thus, while both versions 0.9.2 and 0.10.0 of Graphiti are supported in Eclipse Juno and Indigo, it may not be possible to install both versions because of dependency conflicts.

## Document Conventions

Menu actions, mouse click commands or any other UI labels or callouts are in bold:

Delete – deletes the selected element.

Sequences of actions that involve cascading menus are separated with an arrow:

From the main menu, click Help -> Install New Software

Sometimes it is necessary to distinguish between references to specific BPMN2 model elements and the concepts they represent. For example BPMN2 defines a Process element, but we may also refer to a process in a broader sense outside the context of the BPMN2 model. Whenever a BPMN2 model element is discussed, it will be highlighted in a different color and font:

A Sequence Flow is used to show the order in which Activities will be performed.

Usage Tips and hints are highlighted with a border:

The Description text can be hidden by changing the Editor Behavior preferences.

Actions that may cause unexpected results are highlighted with a border:

If any of the above attributes are changed as a result of these settings, those changes will be reflected in the file when it is saved.

Hyperlinks to other sections of the document are highlighted and underlined:

See the Context Button Pad section for more information.

Source code and console commands are highlighted with a border:

package org.jboss.jbpm5.runtime;

public class Configuration {

public static class Parameter {

String name;

String value;

}

}

## Installation

The BPMN2 Modeler is installed the same way as any other Eclipse plug-in. From the Eclipse Workbench main menu, select Help -> Install New Software. Next, select the update site URL for your version of eclipse, as defined in Table 1 and enter this in the Work with text box of the Install Software wizard as shown below:

Figure 1: Install Software Wizard Dialog

Select the features you wish to install then finish the wizard by clicking the “Next” and “Finish” buttons. Once the software has been installed, you will need to restart the workbench.

## Project Resources

Please visit the BPMN2 Modeler project website for new release announcements and other news concerning the project, here:

http://eclipse.org/bpmn2-modeler/

A community forum for posting questions and exchanging ideas is also available here:

http://www.eclipse.org/forums/

A Bugzilla bug tracking system is available for reporting new bugs, or checking the status of existing bugs, here:

https://bugs.eclipse.org/bugs/buglist.cgi?product=BPMN2Modeler

The source code for the editor as well as several sample extension plug-ins can be found at the Eclipse Git repository. To clone a local repository, simply use the following Git command:

$ git clone http://git.eclipse.org/gitroot/bpmn2-modeler/org.eclipse.bpmn2-modeler.git

The repository is also mirrored at github.com and can be cloned like this:

$ git clone git://github.com/eclipse/bpmn2-modeler.git