Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "BPMN2-Modeler/DeveloperTutorials/ModelExtension"
m (save point) |
m |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
==Versions== | ==Versions== | ||
This Tutorial was developed with Eclipse 4.4 (Luna) and BPMN2-Plugin version 1.1.1. | 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? == | == Model Extension: what is it, and why do I need it? == | ||
| Line 17: | Line 12: | ||
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 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. | 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 | + | 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> | <pre> | ||
| Line 35: | Line 30: | ||
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. | 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> | <pre> | ||
| Line 132: | Line 127: | ||
# 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'''. | # 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 | # 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: | + | # 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. |
| − | + | ||
| − | + | ||
| − | + | ||
| − | 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. | # 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 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. |
Latest revision as of 10:30, 12 March 2015
Contents
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 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 jBPM extension plugin demonstrates a perfect example of when to use this extension:
<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>
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:
<bpmn2:sequenceFlow id="SequenceFlow_3" tns:priority="2" sourceRef="ExclusiveGateway_1" targetRef="Task_3"/>
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):
<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>
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 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, willy-nilly, without fear of breaking BPMN 2.0 compliance!
The very detailed tutorial Extending BPMN2 using an external EMF model shows you exactly how to do this, and provides some concrete examples.