View source for BPMN2-Modeler/DeveloperTutorials/ModelExtension

==Versions==
This Tutorial was developed with Eclipse 4.4 (Luna) and BPMN2-Plugin version 1.1.1.

== Model Extension: what is it, and why do I need it? ==
There are only two possible reasons for wanting to build a BPMN2 Modeler extension plugin that we can think of:

# We need a graphical tool that can build BPMN 2.0 compliant, executable process files for a particular BPM execution engine.
# We would like to use a graphical tool for documenting our business processes, but the BPMN 2.0 spec is insufficient for defining some particular piece of information that our business requires.

In both cases, you will likely need to extend the BPMN 2.0 language with your engine, or business-specific XML attributes and elements. In some cases you may even want to limit what is presented by the editor if you only need a small subset of BPMN 2.0, but this is a topic for another tutorial.

The BPMN2 Modeler extension API offers several different methods of extending the BPMN2 model, and each addresses a particular use-case as discussed next.

== The <modelExtension> extension point ==
The BPMN2 Modeler core exposes the ''org.eclipse.bpmn2.modeler.core.org.eclipse.bpmn2.modeler.runtime'' plugin extension point. One of these extension elements is called "modelExtension". Please see the [http://download.eclipse.org/bpmn2-modeler/doc/api/core.html Core Extension Point API] documentation for details.

This is used if you simply need to "decorate" a specific BPMN2 type with your own, business-specific attributes and elements, e.g. a '''UserTask''' or '''SequenceFlow'''. The [https://git.eclipse.org/c/bpmn2-modeler/org.eclipse.bpmn2-modeler.git/tree/plugins/org.eclipse.bpmn2.modeler.runtime.jboss.jbpm5 jBPM extension plugin] demonstrates a perfect example of when to use this extension:

<pre>
    <modelExtension
        id="org.eclipse.bpmn2.modeler.runtime.jboss.jbpm5.modelExtension.sequenceFlow"
        runtimeId="org.jboss.runtime.jbpm5"
        name="%modelExtension.name.0"
        type="SequenceFlow">
        <property name="priority" value="1"/>
        <property name="name" value=""/>
    </modelExtension>
</pre>

Here the ''type'' identifies a BPMN2 model type to which this extension applies, in this case a '''SequenceFlow'''. Note that we do not use the fully qualified "org.eclipse.bpmn2.SequenceFlow" class name because ''modelExtension'' is limited to only BPMN2 model objects and can not be used with external models.

This extension adds an attribute named ''priority'' to '''SequenceFlow'''; this attribute will be qualified with the "tns" prefix which corresponds to the targetNamespace "http://www.jboss.org/drools" defined by the jBPM plugin. The resulting XML looks like this:

<pre>
    <bpmn2:sequenceFlow id="SequenceFlow_3" tns:priority="2" sourceRef="ExclusiveGateway_1" targetRef="Task_3"/>
</pre>

As a bonus, this extension point is also used to override default initial values for existing BPMN2 attributes, and insert fully populated and initialized elements whenever a new BPMN2 object is created. Note that the ''name'' attribute in the example above is defined in the BPMN2 '''FlowElement'''. The default behavior of the editor is to automatically assign a generated name to all '''SequenceFlows''', but the ''modelExtension'' example above initializes the name to an empty string.

A more complex example of this initialization capability is demonstrated by the jBPM '''UserTask''' model extension (truncated here for simplicity):

<pre>
    <modelExtension
        id="org.eclipse.bpmn2.modeler.runtime.jboss.jbpm5.modelExtension.userTask"
        runtimeId="org.jboss.runtime.jbpm5"
        name="%modelExtension.name.12"
        type="UserTask">
        
        <property name="ioSpecification">
            <value>
                <property name="outputSets">
                    <value>
                        <property name="name" value="Output Set" type="EString"/>
                    </value>
                </property>
                <property name="dataInputs">
                    <value>
                        <property name="name" value="TaskName" type="EString"/>
                    </value>
                </property>
                <property name="dataInputs">
                    <value>
                        <property name="name" value="Priority" type="EInt"/>
                    </value>
                </property>
                
                ...

                <property name="inputSets">
                    <value>
                        <property name="dataInputRefs" ref="ioSpecification/dataInputs#0"/>
                        <property name="dataInputRefs" ref="ioSpecification/dataInputs#1"/>
                        
                        ...
                        
                    </value>
                </property>
            </value>
        </property>
        <property name="dataInputAssociations">
            <value>
                <property name="assignment">
                    <value>
                        <property name="from" type="FormalExpression">
                            <value>
                                <property name="body" value="Task Name"/>
                            </value>
                        </property>
                        <property name="to" type="FormalExpression">
                            <value>
                                <property name="body" ref="ioSpecification/dataInputs#0"/>
                            </value>
                        </property>
                    </value>
                </property>
                <property name="targetRef" ref="ioSpecification/dataInputs#0"/>
            </value>
        </property>
        <property name="dataInputAssociations">
            <value>
                <property name="assignment">
                    <value>
                        <property name="from" type="FormalExpression">
                            <value>
                                <property name="body" value="1"/>
                            </value>
                        </property>
                        <property name="to" type="FormalExpression">
                            <value>
                                <property name="body" ref="ioSpecification/dataInputs#1"/>
                            </value>
                        </property>
                    </value>
                </property>
                <property name="targetRef" ref="ioSpecification/dataInputs#1"/>
            </value>
        </property>
        
        ...
        
    </modelExtension>
</pre>

There's a lot of stuff going on here, let's go through each of these extension point elements:

# This ''modelExtension'' applies to the BPMN2 '''UserTask''' type.
# All BPMN2 '''Activity''' objects ('''Activity''' is a super class of '''UserTask''') have an optional '''ioSpecification''' container which defines inputs to, and outputs from the '''Activity'''. The line ''<property name="ioSpecification">'' will cause a new '''IoSpecification''' object to be created and attached to the '''UserTask'''.
# The lines that follow populate the '''IoSpecification''' object with '''OutputSet''', '''DataInputs''' and '''InputSet''' objects each of which are, in turn, constructed and initialized
# Within the '''inputSets''' definition, this line: ''<property name="dataInputRefs" ref="ioSpecification/dataInputs#0"/>'' initializes the '''dataInputRefs''' of the '''InputSet''' object with a reference to the newly created '''DataInput''' object that has already been created and inserted into the '''IoSpecification''' object's '''dataInputs''' list at index 0.
# Similarly, the next line creates a reference to the '''DataInupt''' object at '''IoSpecification''' '''dataInputs''' list index 1.
# The remaining bits of this example function similarly to initialize the '''DataInputAssociations''' of the '''IoSpecification'''.

== The <customTask> extension point ==
This extension is similar to ''modelExtension'' (i.e. it is used to extend and initialize a BPMN2 object) but is used only for objects that have a visual representation on the editing canvas. The name "customTask" is a misnomer because it can be used with not just '''Tasks''', but any BPMN2 type that has a visual associated with it, for example '''SequenceFlow''', '''EventDefinition''', '''Gateway''', etc.

The ''customTask'' definitions also appear in the tool palette as individual tool items in a tool drawer of your choosing. A Java class is required to manage the lifecycle of ''customTask'' objects. This class is involved in the Graphiti framework during creation, update and deletion so that every visual aspect of the element can be controlled.

For a detailed explanation of how to implement the Java code behind a ''customTask'', see the [[BPMN2-Modeler/DeveloperTutorials/CreateCustomTask|Create a Custom Task]] tutorial.

== BYOM! (bring your own model!) ==
Sometimes it becomes necessary to embed objects from an existing EMF model into a BPMN2 document. the BPMN 2.0 specification defines an extension mechanism using a special container element called (surprise!) "extensionElements". Feel free insert your application-specific model objects directly into this container, [http://www.merriam-webster.com/dictionary/willy-nilly willy-nilly], without fear of breaking BPMN 2.0 compliance!

The very detailed tutorial [[BPMN2-Modeler/DeveloperTutorials/ModelExtensionBYOM|Extending BPMN2 using an external EMF model]] shows you exactly how to do this, and provides some concrete examples.