Use cases for custom elements/namespaces

Developers
1

So, we saw this example go out on custom namespaces, which seems to fit nicely to some of the customization we’re aiming to do to BPMN files: https://github.com/bpmn-io/bpmn-js-examples/tree/master/custom-meta-model

My question though - are there specific use cases that should be avoided when building extensions this way? For example, I have to do some major customization to forms and was planning to build that as an XML structure within my BPMN files, allowing them to be edited in a customization over bpmn.js. Is that normal, or should that customization live outside of the file?

2

Let me try to give you my view on that topic.

Use Cases

You would generally use custom elements/namespaces to attach meta data to a BPMN diagram that is closely related to the diagram elements itself and that has a similar life cycle (in terms of data editing, timeliness). Some examples:

  • Additional requirements for certain activities
  • Editing notes
  • Technical details, related to actual process execution
  • One-Time analytics / planning such as target KPIs

Form customizations may be a good candidate for embedding, too, if the form definition is tied closely to the defined process.

Non Use Cases

You would use mash-ups instead if the meta-data has a totally different life cycle and/or has to be taken from external data sources anyway. Example: Runtime data, i.e. running instances in a certain activity at a specific point in time.

You would not embed the data, if it needs to be easily accessible from outside the BPMN context, too.

Implementation Approaches

If you decide on enriching BPMN diagrams with custom meta-data, you have got a few options:

Hijack documentation tag

You may abuse the <bpmn:documentation> tag to hold your extension data in a format of your choice.

This approach is shown in the commenting example / bpmn-js-embedded-comments.

Executive summary: It reads and writes user comments in BPMN 2.0 diagrams in the following format

<bpmn:documentation textFormat="text/x-comments">
author:comment;
;other-author:other comment
canbe multiline, too
</bpmn:documentation>

The text can be anything though, including JSON or another <![CDATA[]> escaped XML document.

Create a meta-model extension

You would want to do this if

  • you want schema validation
  • you want default values for properties
  • you need to instantiate your extension elements in a well defined manner
  • you would like to access your extension elements in a well defined manner
  • you need to have the information as a BPMN 2.0 compliant vendor extension anyway
  • you love XML

Creating a meta-model extension is a bunch of work.

Create extensions on the fly

bpmn-js pulls through unknown custom elements and even allows you to create them during modeling.

So just in case you feel uncomfortable with the work involved in building a custom extension this may be an option for you, too.

1 Like