Graphical Definition

Note that steps 1 and 2 can be done out of order. For those preferring to begin with the domain model, perform step 2 before the graphical definition of step 1. It is possible to create a Mapping model with no domain elements specified and run the diagram to test the graphical and tooling models.

Add a child ‘Node Mapping’ to the new ‘Top Node Reference’ and select our ‘Node Task’ as the ‘Diagram Node’

Add a child ‘Label Mapping’ to the ‘Node Mapping’ and select our ‘TaskName’ label as the ‘Diagram Label’

Right-click the Mapping element and select ‘Create generator model…’’

Name the model bpmn.gmfgen and opt to use IMapMode when prompted

Open the bpmn.gmfgen model and change the properties of the ‘Gen Editor Generator’ element:

Change ‘Diagram File Extension’ to ‘bpd’

Change ‘Package Name Prefix’ to ‘oopsla.bpmn’

Change ‘Model ID’ to ‘BPMN’

Save the model

Right-click the bpmn.gmfgen model and select ‘Generate diagram code’

A new ‘design.diagram’ project is created which we can run using ‘Run > Run…’

In the Run dialog, select ‘Eclipse Application’ and ‘New’

Change the ‘Name:’ field to ‘design.diagram’ and adjust ‘Location:’ to match

Run the runtime workbench, create a new project and diagram (under ‘Examples’ in New dialog) to test it works

Note that without a tool definition model, we will have no palette. Task elements can be added to the diagram regardless, using the popup menus that appear on the diagram under the mouse cursor.

You can continue to develop your graphical elements in this manner and test their look and feel in a ‘domain-free’ environment. The goal is to potentially reuse elements from these graphical definition models in other diagram definitions. Another option is to reuse those provided with GMF and any that may be developed and shared within the community. GMF provides basic, class, and state diagram galleries in its org.eclipse.gmf.graphdef plug-in, which can be loaded into your models using ‘Load Resource…’ and providing a URI of platform:/plugin/org.eclipse.gmf.graphdef/models/basic.gmfgraph (or classDiagram.gmfgraph, or stateDiagram.gmfgraph).

Developing the Domain Model

We will leverage one of GMF’s example diagrams to develop an ecore domain model for BPMN, using the specification Annex B. Optionally, you can copy the provided bpmn.ecore into your ‘model’ folder and create a diagram for it using the right-click ‘Initialize ecore_diagram diagram file’ option. If you do so, start with Step 4.

Using the wizard for a new Ecore Diagram, give it the name ‘bpmn’

In the properties view ‘Advanced’ tab, change the Name, Ns Prefix, and Ns URI to be ‘bpmn’ for the diagram

Expand the root of the genmodel in the editor and give the ‘Bpmn’ package a ‘Base package’ name of ‘oopsla’

Right-click on the root of the genmodel and select ‘Generate Model Code’ then ‘Generate Edit Code’ then ‘Generate Editor Code’ (optional)

Define the Tooling Model

As the Tooling Definition model is quite simplistic (only palette elements), we’ll use the provided wizard to create one from our domain model. Note that a similar wizard is available for creating a quick Graphical Definition model.

Name the model ‘bpmn.gmftool’ and create in our ‘model’ folder as usual

Select our ‘Diagram’ class for our ‘Diagram element’

Deselect all initially, then check the node column for:

Process

Pool

StartEvent

EndEvent

IntermediateEvent

Task

DataExclusiveGateway

ParallelGateway

DataObject

And for the following, select the Link column and Finish:

SequenceFlow

MessageFlow

Association

Give the Palette the title ‘BPMN Elements’

Rename the ‘bpmn’ group to ‘Nodes’

Create a new ‘Tool Group’ under our Palette and name it ‘Links’

Drag and drop our link creation tools to the ‘Links’ group

Note: you may want to select ‘true’ for the Collapsible property of the Tool Group items.

Define the Mapping Model

At this point, we are aware of how our domain will require us to construct diagrams using our graphical elements. Our basic Task node will be contained within a Process element, which itself is contained within a Pool element. There are many options to choose at this point, but for simplicity, we’ll begin by creating two simple dotted line rectangles to represent our Process and Pool elements. The specification seems a bit peculiar in that a Pool may have 0 or 1 Process items, but as the Process element is where all graphical elements are contained, it doesn’t seem like much of a diagram would exist without it ;-)

Note that if you opted to generate a ‘design.diagram’ plug-in earlier, you may delete that project and the associated bpmn.gmfmap and bpmn.genmodel models. To save a little time, you may keep the bpmn.gmfmap model and refactor as required given our new structure.

Open your bpmn.gmfgraph model once again

Create a new Rounded Rectangle element in the Figure Gallery named ‘DottedRectangleFigure’

Set ‘Line Kind’ to LINE_DOT

Set ‘Fill’ to ‘false’

Add a child ‘XY Layout’ element to the DottedRectangleFigure

Add a new Node to the Canvas named ‘Process’, selecting DottedRectangleFigure as its ‘Figure’

Add another Node named ‘Pool’ and also assign the DottedRectangleFigure as its ‘Figure’

Repeat until you’ve also added your bpmn.gmfgraph and bpmn.gmftool models

To the root ‘Mapping’ add a child ‘Canvas Mapping’

The Diagram Canvas maps to our ‘Canvas BPMN Diagram’

The Palette maps to our ‘Palette BPMN Elements’

The domain Element maps to our ‘EClass Diagram’

Also to the ‘Mapping’ root, add a child ‘Top Node Reference’

Set the ‘Containment Feature’ to ‘EReference pools’

Add a child ‘Node Mapping’ to the Top Node Reference

Set the Tool to ‘Creation Tool Pool’

Set the Diagram Node to ‘Node Pool’

Set the domain Element to ‘EClass Pool’

Add a ‘Child Reference’ to our Node Mapping

Set its Containment Feature to ‘EReference process’

Add a Node Mapping to this Child Reference

Set its Tool to ‘Creation Tool Process’

Set its Diagram Node to ‘Node Process’

Set its domain Element to ‘EClass Process’

Add another ‘Child Reference’ to this Node Mapping

Set its Containment Feature to ‘EReference graphicalElements’

Add another ‘Node Mapping’ to this Child Reference

Set its Tool to ‘Creation Tool Task’

Set its Diagram Node to ‘Node Task’

Set its domain Element to ‘EClass Task’

Add a Label mapping to our Task

Set the Diagram Label to ‘Diagram Label TaskName’

Set the Features property to ‘EAttribute name’

At this point, we’ve completed our mappings. Subsequent graphical elements will be added as children of our Process mapping, similar to the Task node. For now, we can create our generator model and run our diagram.

Right-click on the bpmn.gmfgen file and select ‘Generate diagram code’

In the Run > Run… dialog, create a new Eclipse Application configuration named ‘bpmn’ (adjust runtime workspace directory if desired)

Run the workspace, create a new basic project and new ‘Bpmn Diagram’ (under Examples in New dialog)

Adding More Elements

Rather than list the step-by-step instructions here for the creation of these graphical elements, it’s recommended that you open the provided bpmn.gmfgraph model provided in the solution to this step. Examine the elements in the model and copy/paste the solution to your workspace and work on the mapping definition.

The mapping model is rather straightforward and similar to the elements mapped so far. The connections are slightly different, and if required can be copied from the provided bpmn.gmfmap for this step.

After recreating the generator model, the Gen Child Node DataObjectEdit part needs a modification to provide a default size to match the figure. Right-click on the Inner Class Viewmap DataObjectFlowFigure and add a Default Size Attributes child. Specify 25 for the Height and 20 for the Width.

Feature Initialization

In our domain model, each Event element has type assigned using the EventType enum. Upon creating each even on the diagram, we are creating the proper type to be instantiated as a result of our mapping definition (bpmn.gmfmap). However, we still need to initialize the eventType attribute of the class. We can accomplish this using Feature Initializers and OCL.

Open your bpmn.gmfmap model and navigate to our Node Mapping for the EndEvent

Right-click and add a new child ‘Feature Seq Initializer’ to the NodeMapping

Then create a new child ‘Feature Value Spec’ to the initializer

Enter ‘EventType::END’ in the ‘Body’ property

Select ‘EAttribute eventType’ from the list for the ‘Feature’ property

Regenerate your bpmn.gmfgen model and code as before

Run your diagram and create a new End event, checking the initialization of its eventType attribute in the properties view

Tip : In GMF 2.1 a 'Feature Value Spec' doesn't have 'Body' and 'Language' attributes itself. Instead you have to add a 'Value Expression' child to the 'Feature Value Spec'. Then you can set the body expression in this 'Value Expression'.

OCL Constraints

Another use of OCL in GMF is for link constraints. In this step, we will add a constraint to prevent Association links from attaching to targets other than Artifacts.

Right-click on the Link Constraint and add a child ‘Target End Constraint’

In the ‘Body’ of the Constraint, add the text ‘self.oclIsKindOf(Artifact)’ [without the quotation marks]

Once again, regenerate your bpmn.gmfgen model and code

Run the diagram and attempt to create an Association link from an element to another non-Artifact element. You should receive feedback that the target is invalid.

Custom Figures

Polyline connections allow for source and target decorations. Unfortunately, there is no default support for ellipse decorations so we will have to provide our own custom figure to create the BPMN Message Flow link. As seen in the image, a Message Flow link has a hollow, closed arrow on the target with a small circle on the source of a dashed line connector. We will make use of an existing decorator in a graphical definition provided by GMF for the target decoration.
File:MessageFlow.png

Reopen your bpmn.gmfgraph model and add a new Polyline Connection to your Figure Gallery named ‘MessageFlowFigure’

Enter ‘platform:/plugin/org.eclipse.gmf.graphdef/models/classDiagram.gmfgraph’ in the dialog

Now, in the ‘Target Decoration’ property for our MessageFlowFigure will be a ‘Polyline Decoration ClosedArrow’ option

Select this decoration (Note, the only difference between this and the one we created for our NormalFlowFigure is the white fill color. The goal of this step is to demonstrate the ability to share/reuse Figure Gallery content between models)

Right-click on our MessageFlowFigure and create a new child ‘Custom Decoration’