How to extend Relationship tag


Hi everyone,

I’m following the “Property panel extension” example (Magic) to create a modeler that allows me to add BPSim tags to the xml file. I don’t know how to add these tags to the bpmn tag called “relationship” because there are no graphic elements with this tag. Is there a way to create the “relationship” tag in the xml via modeler?

I would like to write a xml file like the following one:




Is <semantic:relationship> supposed to be a custom element instead of a custom property? The resulting diagram will not be valid BPMN 2.0. What are you trying to model that can not be achieved with the existing BPMN elements?


semantic is the namespace of bpmn specification

I have to add a set of tags (that refers to bpsim simulation) under “extensionElements” which is under “relationship” as in the previous photo. I don’t know how to bind these new tags to the bpmn relationship tag.
I know that I can add a custom tag (as in the magic example) to a drawable element in the modeler but the relationship element is not drawable so I don’t know what to do.


Forget about my question, I just learned that there is a relationship element in the BPMN specification. You can use BpmnFactory to create BPMN elements:

const rootElement = canvas.getRootElement();
const definitions = rootElement.businessObject.$parent;

const relationship = bpmnFactory.create('bpmn:Relationship');
relationship.$parent = definitions;
relationship.type = 'BPSimData';

// and so on...

definitions.relationships = [ relationship ];

That’s how you work with the BPMN model. We do this a lot in the properties panel.


To clarify: most of the examples we saw allow you to modify properties that are bound to the model counterpart of the selected element.
Which means that if you select a task you can change properties that are “within” in the corresponding task element in the model (which can be an extended BPMN model so you can add your own properties and elements within a task).
Using bpmn:relationship to store simulation-related properties for some of the elements (that is what BPSim that we are adopting does) we found ourselves in the weird situation in which we want to use a properties panel that, when selecting a task, lets you change elements that are in a different part of the model (the BPSimData) and are not nested in the BPMN model fragment for that task.
Is there any example showing a clean way to achieve that? Thanks.


Okay, so you want to edit properties of the bpmn:Definitions object which is not selectable. The topmost element that is selectable is the bpmn:Process or the bpmn:Collaboration. You can either extend the properties panel to display properties of the bpmn:Definitions object in an existing tab or be able to select the bpmn:Defintions object somehow. Technically possible.


I do not doubt it is technically possible, it’s just how intricate this would turn out to be.
Also notice that I do not want to select bpmn:Defintions somehow, I still want to select an existing displayable element, like a task. To exemplify: using BPSim I can say that the duration of a task for simulation purposes should be obtained with a random sample from a normal distribution with average 3min and variance 0.2.
These values should end up in the BPSimData part of the model even if they refer a task whose main properties are, of course, in the BPMN part of the model.


Okay, so you want to select any element but still want to display properties of the bpmn:Definitions object. You can use the properties-panel-extension example as a starting point and simply add another tab to the properties panel that displays bpmn:Definition properties. Similar to the magic tab in the example:

// Create the custom relationships tab
function createRelationshipsTabGroups(canvas) {

  // Create a group called "Relationships".
  var relationshipsGroup = {
    id: 'relationships',
    label: 'Relationships',
    entries: []

  const definitions = canvas.getRootElement().businessObject.$parent;

  // Add the relationships props to the relationships group.
  relationshipsProps(relationshipsGroup, definitions);

  return [


No, we want to select any element, show its BPSim properties in the properties panel (we have to add this tab), edit these properties and generate the xml file where the BPSim properties of every element end up in the bpmn:relationship, like in the follow image:


Then it’s a matter of adding the respective tab and fetching the respective model elements for a selected element.


I guess this is where we are having difficulties.
Let’s refer to the properties-panel-extension example: at one point you have to bind the elements in the panel with the elements in the model. This is described in the “Create a Moddle Extension” section but this is not what we need. In the example the spell property is an attribute for a new BewitchedStartEvent elements that extends bpmn:StartEvent. That is spell in the model is still “under” the element that is selected whereas in our case this should refer to a different element in the model which makes it less straightforward.


Have you created the model extension already? If not, it would look similar to this:

  "name": "BPMSim",
  "uri": "http://some-company/schema/bpmn/bpmnsim",
  "prefix": "bpmsim",
  "xml": {
    "tagAlias": "lowerCase"
  "types": [
      "name": "BPMSimData",
      "properties": [
          "name": "scenario",
          "isMany": false, // set to true if BPMSimData can have more than one Scenario element
          "type": "Scenario"
      "name": "Scenario",
      "properties": [
          "name": "author",
          "isAttr": true,
          "type": "String"
          "name": "created",
          "isAttr": true,
          "type": "String"
          "name": "id",
          "isAttr": true,
          "type": "String"
  "emumerations": [],
  "associations": []

How would you identify the corresponding relationship element for an element?


We have to extend bpmn:Relationship in the model extension. In addition, we can’t “bind” any graphical element with this tag. How could we do that?


Thanks @philippfromme, we already did create the model extension (sort of, we are using a super-simplified version at the moment). BPSimData properties link to BPMN elements simply by referring their id with the elementRef attribute (just like BPMN DI elements do using the bpmnElement attribute).
In this example we would like to be able to edit parameters like max, min, mean and standardDeviation in a “BPSim panel” when the element with id _10-42 is selected in the BPMN diagram.

      <bpsim:ElementParameters elementRef="_10-42">
            <bpsim:TruncatedNormalDistribution max="1000" mean="1" min="0" standardDeviation="0.5"/>