I brought up this question during February’s question corner with @nikku . The BPMN spec (section 8.2.2) allows for specifying multiple documentation elements on BaseElements, distinguishing them by an id. In its current state, the Modeler does not allow defining multiple elements graphically. Nico’s response to the question was - understandably - that not everything is supported or even makes sense and that any additional elements entered in the XML would be preserved by the Modeler. Unfortunately, the latter is not the case - the attached model contains a secondary Documentation element for the task, which is preserved when loading the diagram, but wiped out when making any change to the element’s primary documentation. documentation-test.bpmn (2.2 KB)
@nikku was interested in the use case for having multiple, so here it is
Documentation can serve multiple audiences. First and foremost, the Documentation element is often used to provide general documentation about elements or instructions to users performing user tasks. In the user task case, an important feature is that the documentation also enjoys substitution of expressions in the documentation on task creation. But what if, besides this documentation, you also need to document parts of the process for other audiences (for instance, business departments such as auditors), which should not be shown by default to users? You could use a custom extension to capture the documentation, and that would most likely be correctly preserved by the Modeler. However, substitution would not work and since the specification already provides for this, support for it in the Modeler would be even nicer.
I realise there might be complications implementing this, since there is no “primary” element, but I wanted to post the case first before considering implementation details.
Working with the engine’s api, the documentation field has not received much love over the years.
+1 on having an array of documentation elements.
As a simple workaround you could use a delimiter and parse your docs:
such as:
/n
---------------------
/n
Even if you add an array of Element Documentation fields, we still end up with Modeler issues such as the Text field’s visual size, limits on width of the props panel, and you would likely be adding some sort of heading / categorization to each documentation element to know what audience the documentation applies to.
In previous projects, given the limitations of the modeler’s BPMN dev experience, it was much more appropriate to use file references in the documentation field. This way you can manage your documentation independently of the BPMN file and work with a much more clean UI experience.
Additionally when you deploy to the engine, the docs would be carried into the engine (or at least uploaded to the engine as you may strip them out upon deployment), but you are still uploading a larger and larger file that is full of non-execution relevant data.
Hi @StephenOTT , thanks for the vote of support! Indeed, we considered a delimiter as well, even though it is a bit messy and rather dependent on convention and error-prone.
You’re right that even with an array, you’d need something like a classifier and you’d probably also need to rely on some convention to give that a good chance of working reliably if you’re doing anything else than just displaying all the entries.
I also considered creating a Modeler plugin, that simply allows to edit a custom property, perhaps even with a special pop-up that provides you with more space to type some content (e.g. in AsciiDoc). And your suggestion to use a reference was also on the table.
Do you think the extra information in the model is problematic? I’d say that in this case, being able to document the model IN the model outweighs the disadvantage of a slightly larger model. Any reasonably complex model already has some much “bloat” in there just for the DI, that it might not even affect document size that much
Depends on what they are documenting. Docs can add up in size if you start adding docs about service calls, scripts, request response examples of API calls, etc.
Adding form schema data into the Bpmn contributed to a 10x to 50x size increase.
Regardless I agree it should be possible to add add multiple docs directly into the Bpmn.
Hi @tiesebarrell, thanks for remembering and raising this issue here. Thanks @StephenOTT for sharing your feedback, too. I was able to look into it after taking a short easter holiday break.
We actually have a long standing bug report that is open regarding this. Unfortunately I had in the back of my head that we fixed it already. Apparently, that is not the case, as of today .
In the spirit of “playing nicely with others” the editor should do the following:
Only ever edit documentation that is marked as plain text (or does not have a textFormat property set
Keep other existing documentation tags.
As you mention, documentation is a great extension point for any kind of data. As a tool we should not mandate and or limit users in what they do with it.
.