BPMN2 Modeler Runtime Specialization




This extension point is used to customize and extend the BPMN2 Modeler UI as well as the BPMN2 model itself. The following aspects of the editor can be customized; note that some extension points may affect more than one of these aspects:

All of these extension elements may also be defined within a Workspace Project instead of, or in addition to, an extension plug-in. When the editor starts up, all XML files contained in the project folder named ".bpmn2config" are loaded. These configuration files override default behavior provided by the editor core or other contributing plug-ins defining the Target Runtime for which the Project is configured. As an example, suppose that you have installed the BPMN2 Modeler from eclipse.org along with a third-party vendor supplied extension plug-in for the "Foo Target Runtime" with the ID org.foo.runtime. Also, the "Foo Target Runtime" defines the target namespace "http://org.foo" for BPMN2 extensions. After configuring your Workspace Project to use the "Foo Target Runtime" (see the discussion about setting Project Preferences in the User's Guide), it is possible to customize the editor behavior using the following configuration file placed in the Project's ".bpmn2config" folder:

<?xml version="1.0" encoding="UTF-8"?>
 <runtime id="org.foo.runtime">
   name="My Webservice EndPoint Extension"
   <property name="serviceAddress" type="ServiceAddress">
     <property name="port" type="EString" />
     <property name="binding" type="BindingType:EEnum" value="SOAP HTTP" />
This will decorate the BPMN2 EndPoint model element with an extension element named "serviceAddress"; that element will have two attributes named "port" and "binding". The resulting EndPoint definition XML might look like this in a bpmn2 file:

  <bpmn2:endPoint id="EndPoint_1">
      <extensions:serviceAddress extensions:port="RequestPortType" extensions:binding="HTTP"/>
There are a couple of issues to consider, however, when using configuration files to extend model elemnts: A final note: these configuration files are intended to be used primarily by plug-in developers to test out various BPMN2 Modeler extension points, rather than in a production environment where process file integrity is crucial.

Configuration Markup:

<!ELEMENT extension (runtime | model | propertyTab* | customTask* | modelExtension* | modelEnablement* | propertyExtension* | featureContainer* | style* | toolPalette* | dataType* | typeLanguage* | expressionLanguage* | serviceImplementation)+>

<!ATTLIST extension




<!ELEMENT runtime EMPTY>

<!ATTLIST runtime

name        CDATA #REQUIRED

versions    CDATA #IMPLIED

id          CDATA #REQUIRED

description CDATA #IMPLIED

class       CDATA #REQUIRED>

This element defines a namespace for a specific execution engine, referred to as a "Target Runtime" in this documentation.


<!ATTLIST model

runtimeId       CDATA #IMPLIED

uri             CDATA #REQUIRED

resourceFactory CDATA #IMPLIED>

This element specifies an extension model URI that will be used by the Target Runtime plug-in. The model extension may refer to an actual Java implementation, generated the traditional way from an EMF ecore file, or it may just define a namespace URI which will be used to create dynamic classes and features from modelExtension and customClass definitions.

<!ELEMENT propertyTab EMPTY>

<!ATTLIST propertyTab

id         CDATA #REQUIRED


label      CDATA #IMPLIED

category   CDATA #IMPLIED


indented   (true | false)

image      CDATA #IMPLIED


class      CDATA #REQUIRED

features   CDATA #IMPLIED

type       CDATA #IMPLIED

popup      (true | false) >

Defines contributions to the Tabbed Property Sheet Page for a selected BPMN2 element.

<!ELEMENT modelExtension (property)+>

<!ATTLIST modelExtension

id          CDATA #REQUIRED

runtimeId   CDATA #IMPLIED

name        CDATA #IMPLIED

description CDATA #IMPLIED

type        CDATA #REQUIRED

decorator   CDATA #IMPLIED

uri         CDATA #IMPLIED>

Defines extension attributes and elements to the BPMN2 model. Any BPMN2 class that derives from "BaseElement" may be extended. The extension features and classes are defined by property elements contained in this modelExtension.

<!ELEMENT customTask (property)*>

<!ATTLIST customTask

id               CDATA #REQUIRED

runtimeId        CDATA #IMPLIED

name             CDATA #REQUIRED

description      CDATA #IMPLIED

type             CDATA #REQUIRED

featureContainer CDATA #REQUIRED

category         CDATA #IMPLIED

propertyTabs     CDATA #IMPLIED

icon             CDATA #IMPLIED

uri              CDATA #IMPLIED>

Defines extension attributes and elements for BPMN2 objects. The difference between this and the modelExtension extension element is that that customTask extensions will appear in the Tool Palette.

<!ELEMENT property (value)*>

<!ATTLIST property

name        CDATA #REQUIRED

value       CDATA #IMPLIED

label       CDATA #IMPLIED

description CDATA #IMPLIED

ref         CDATA #IMPLIED

type        CDATA #IMPLIED>

Describes an extension to a BPMN2 model feature. If the feature already exists in an EMF model, then this property element can be used to initialize the feature's value when a new instance of the object is created. If the feature does not exist, it is created using dynamic EMF and extends the existing type, but in a different namespace.

<!ELEMENT value (property)*>

<!ATTLIST value


If a property represents a complex element instead of a simple attribute, then a value may be used to define and populate the contents of the property. For example:

  <property name="device" type="Device" label="Device Definition">
    <property name="type" type="DeviceType:EEnum" value="Phone Tablet Computer Banana" label="Device Type"/>
    <property name="deviceID" type="DeviceIdentifier" label="Device Details">
      <property name="carrier" type="EString" value="" label="Carrier or Service Provider"/>
      <property name="identifier" type="EInt" value="0" label="Device Identifier"/>
This is interpreted as follows:
  1. create a dynamic EClass structure called "Device"
  2. create a dynamic EEnum called "DeviceType"
  3. create the EEnum literal values "Phone", "Tablet", "Computer" and "Banana". These will be the only valid values for the DeviceType EEnum
  4. create a DeviceType feature in the Device class called "type"
  5. create a dynamic EClass structure called "DeviceIdentifier"
  6. create two features in DeviceIdentifier called "carrier" (a string) and "identifier" (an integer) and initialize them with an empty string and 0, respectively
  7. create a DeviceIdentifier feature in the Device class called "deviceID"
Note the use of the special notation"DeviceType:EEnum" to create the "DeviceType" enumeration class.

<!ELEMENT modelEnablement (enable* | disable*)>

<!ATTLIST modelEnablement

id          CDATA #REQUIRED

runtimeId   CDATA #IMPLIED

profile     CDATA #REQUIRED

ref         CDATA #IMPLIED

description CDATA #IMPLIED>

This element is used to select which model classes and features are visible in the editor Tool Palette and Property Sheets. This allows the editor to be tailored to a subset of BPMN2 language elements supported by a particular BPMN2 execution engine.


<!ATTLIST enable



Enables visibility of a specific BPMN2 model class and feature.

<!ELEMENT disable EMPTY>

<!ATTLIST disable



Disables visibility of a specific BPMN2 model class and feature.

<!ELEMENT propertyExtension EMPTY>

<!ATTLIST propertyExtension




type      CDATA #REQUIRED>

Defines a provider class for model object and feature properties. The provider class allows extension plug-ins to define specialized behaviors and properties for BPMN2 model objects. Property Extensions are typically used to define custom labels for objects and features, convert values to and from different types, manage related objects, etc.

<!ELEMENT featureContainer EMPTY>

<!ATTLIST featureContainer



type      CDATA #REQUIRED>

Defines custom behavior for graphical components managed by the editor. FeatureContainers are the providers of lifecycle behavior for all graphical components, including creation of a component, adding a component to a diagram, updating the visual presentation of a component, resizing and moving the component, etc.


<!ATTLIST style

object          CDATA #REQUIRED

shapeForeground CDATA #IMPLIED

shapeBackground CDATA #IMPLIED

labelFont       CDATA #IMPLIED

labelForeground CDATA #IMPLIED

labelBackground CDATA #IMPLIED

runtimeId       CDATA #IMPLIED

labelPosition   CDATA #IMPLIED

routingStyle    CDATA #IMPLIED

useDefaultSize  (true | false)

defaultHeight   CDATA #IMPLIED

defaultWidth    CDATA #IMPLIED>

Defines the visual properties of a BPMN2 element, including colors and text fonts.

<!ELEMENT toolPalette (category*)>

<!ATTLIST toolPalette



profile   CDATA #REQUIRED>

Defines a custom Tool Palette for the BPMN2 editor. Tool Palettes are associated with a diagram type and a tool profile name combination. An extension plug-in may define any number of tool profiles and hence, Tool Palettes.

<!ELEMENT category (tool*)>

<!ATTLIST category

id          CDATA #REQUIRED

name        CDATA #IMPLIED

description CDATA #IMPLIED

icon        CDATA #IMPLIED

before      CDATA #IMPLIED

after       CDATA #IMPLIED

fromPalette CDATA #IMPLIED>

Defines a "category" or Tool Palette Drawer. A toolPalette may have any number of category elements.

<!ELEMENT tool (object*)>

<!ATTLIST tool

id          CDATA #IMPLIED

name        CDATA #REQUIRED

description CDATA #IMPLIED

icon        CDATA #IMPLIED

object      CDATA #IMPLIED

fromPalette CDATA #IMPLIED>

Defines a Tool Palette "tool" which may be used to construct arbitrarily complex sequences of BPMN2 elements. A tool definition may define just a simple object:

 <tool name="Create a Task" object="Task[$name='My Simple Task']"/>
or it may contain compound object definitions:

 <tool name="Two Tasks" description="Two Tasks connected by a SequenceFlow">
  <object type="Task" id="task1"/>
  <object type="Task" id="task2"/>
  <object type="SequenceFlow[source='task1',target='task2']"/>
See the object extension element for more information.


<!ATTLIST object



optional (true | false) >

Used to create compound objects and templates.


<!ATTLIST dataType



Defines a Data Type Conversion delegate. This is used to convert a Target Runtime-specific data type to and from String representations.

<!ELEMENT typeLanguage (type*)>

<!ATTLIST typeLanguage


name      CDATA #IMPLIED

uri       CDATA #IMPLIED

prefix    CDATA #IMPLIED>

This extension element identifies a data type system supported by the Target Runtime. A Target Runtime may define any number of these type systems. The definition element that appears first is used as the default. The Default Target Runtime provides support for XSD Schema and Java types only.

<!ELEMENT expressionLanguage EMPTY>

<!ATTLIST expressionLanguage


name      CDATA #IMPLIED

uri       CDATA #IMPLIED>

This extension element identifies an expression language supported by the Target Runtime. A Target Runtime may define any number of these expression languages. The definition element that appears first is used as the default. The Default Target Runtime provides support for XPath and Java only.

<!ELEMENT serviceImplementation EMPTY>

<!ATTLIST serviceImplementation


name      CDATA #IMPLIED

uri       CDATA #IMPLIED>

This extension element identifies a Service Task implementation supported by the Target Runtime. A Target Runtime may define any number of these implementations. The definition element that appears first is used as the default. The Default Target Runtime provides support for ##WebService and ##Unspecified only.


<!ATTLIST type



Specification of a data type supported by the type system.

This example illustrates some of the features of this extension point:

 <extension point="org.eclipse.bpmn2.modeler.runtime">
  <!-- the runtime definition -->
  <runtime name="Sample Business Process Engine" versions="1.0"
   id="org.eclipse.bpmn2.modeler.examples.dynamic" class="org.eclipse.bpmn2.modeler.examples.dynamic.SampleRuntimeExtension"
   description="BPMN2 Modeler customizations for a sample runtime engine">

  <!-- In this example, there is no extension model per-se. This model definition 
   only provides a default namespace URI for extension attributes and elements 
   that are defined in the <modelExtension> and <customTask> elements below. 
   We could have provided a namespace URI in each of those elements, but it's 
   more convenient to do so here.
  <model runtimeId="org.eclipse.bpmn2.modeler.examples.dynamic"

  <!-- This <customTask> item extends the BPMN2 TextAnnotation element by adding 
   "name", "evaluate" and "cost" attributes. In addition, the "text" attribute 
   which is a feature of TextAnnotation, will be initialized to "Risk Task" 
   whenever a new instance of this item is created. This item will appear as 
   a tool entry in a tool palette drawer named "Risk & Mitigation".
   description="This task represents a risk that can occur in the connected Elements."
   id="org.eclipse.bpmn2.modeler.examples.dynamic.risk" name="Risk Task"
   category="Risk &amp; Mitigation" icon="risk.png"
   runtimeId="org.eclipse.bpmn2.modeler.examples.dynamic" type="TextAnnotation">
   <property name="name" value="Risk Task" type="EString" />
   <property name="text" value="Risk Task" type="EString" />
   <property name="evaluate" value="true" type="EBoolean" />
   <property name="cost" value="0" type="EInt" />

  <!-- This <modelExtension> extends BPMN2 Activity elements and all subclasses 
   (Task, UserTask, etc.) Besides the boolean "isDevice", the extension adds 
   a new type called "Device" which contains a "type" attribute (an enum) and 
   a "DeviceIdentifier" type which itself contains two attributes, a String 
   and an Integer. Note that a specialized <propertyTab> is needed to display/edit 
   these extensions (see below).
  <modelExtension id="org.eclipse.bpmn2.modeler.examples.dynamic.activity"
   uri="http://org.eclipse.bpmn2/default" name="Activity Extension"
   <property name="isDevice" type="EBoolean" value="true"
    label="Is Device" />
   <property name="device" type="Device" label="Device Definition">
     <property name="type" type="DeviceType:EEnum" value="Phone Tablet Computer Banana"
      label="Device Type" />
     <property name="deviceID" type="DeviceIdentifier" label="Device Details">
       <property name="carrier" type="EString" value=""
        label="Carrier or Service Provider" />
       <property name="identifier" type="EInt" value="0"
        label="Device Identifier" />

  <!-- This <propertyTab> will add a new tab to the Property Sheet called "Activity 
   Extensions". The tab will be visible for all BPMN2 Activity objects and their 
   subclasses (type="org.eclipse.bpmn2.Activity") In this case, the Default 
   property sheet page (class="default") is sufficient to display the attributes 
   and elements, although we could have supplied our own Java class to handle 
   these extensions.
  <propertyTab id="org.eclipse.bpmn2.modeler.examples.dynamic.activity.tab"
   afterTab="org.eclipse.bpmn2.modeler.description.tab" class="default"
   features="isDevice device carrier identifier" type="org.eclipse.bpmn2.Activity"
   label="Activity Extensions">