Support Element documentation section within a templated activity

[bastiankoerber]

Problem you would like to solve

As a user, I can attach element documentation to each component, except connectors. This limitation is causing dissatisfaction among business users.

Consider this scenario: Business users are incorporating functional requirements into their BPMN files, using them both for developers to understand the requirements and as part of the documentation. This is achieved through element documentation. However, when a developer takes over and converts some of these empty or service elements into connectors, a problem arises. The business specifications attached to these elements are lost in the case of both custom and out-of-the-box connectors.

Proposed solution

Add the element documentation field to connectors as well.

Not in scope and just FYI
(Additional conversation started => Add element documentation to Web Modeler Design tab: https://camunda.slack.com/archives/C0693F1NFK5/p1702991078456759)

Alternatives considered

using comments => Not accepted at least by one customer => https://jira.camunda.com/browse/SUPPORT-19345.
They see comments as a conversation and not as a space for defined business requirements.

Additional context

Related to SUPPORT-19345
Related to SUPPORT-17421

Mentioned in user interview.

[bastiankoerber]

related FR: https://jira.camunda.com/browse/SUPPORT-19345
related interview notes: https://camunda.productboard.com/insights/notes/view/1018-notes-assigned-to-me/notes/37485044

[nikku]

To better understand your feature request: What exactly would you like to accomplish:

• As an element template author you can define if the Documentation field shall be shown or
• The documentation field always shows, regardless of your template definition?

[ingorichtsmeier]

My personal preference: Show the field always, with an option to disable it in JSON Config for certain templates/or in all templates of this organization.
And it would be good to have an option to configure the position. Sometimes the field should be at the top, sometimes at the bottom of the property panel, sometime in the middle.

[nikku]

We'll likely not be able to provide full customization options (regarding placing) @ingorichtsmeier.

Your suggestion regarding a sensible default (+ override it per template) makes sense to me.

[nikku]

Moving to backlog for the time being @bastiankoerber. If there is any particular urgency on this item, please bump it.

[bastiankoerber]

Moving to backlog for the time being @bastiankoerber. If there is any particular urgency on this item, please bump it.

it will be important for this epic: https://github.com/camunda/product-hub/issues/2027 to have the same UX for all elements
@crobbins215 FYI

[marstamm]

Displaying it always is an easy pick, while hiding it optionally requires some more work.

I propose to make progress now, we simply show the documentation always and handle configuration in a follow-up

[nikku]

@marstamm We already have entriesVisible as a way to define what is shown to the user.

In C7 you can use exactly that mechanism to show (or hide) the documentation section.

[marstamm]

entriesVisible is a boolean. How do we want to use this to hide a specific section?

https://github.com/camunda/element-templates-json-schema/blob/132ea180a19992852819398721684fe330781ca4/packages/element-templates-json-schema-shared/src/defs/base.json#L95-L98

[nikku]

Yea, my bad. It was a boolean or a string[] in properties-panel@0. If it is a string[] then it denotes the list of default entries to be shown with the template.

[marstamm]

With some research, you might be thinking of the entriesVisible like this:

"entriesVisible" : {
   "_all": true
}

This mechanism was only available in properties panel 0.x and has not been available for some time

[nikku]

Exactly. But customers ask for it now (again).

[nikku]

The point I'm making is: We solved this in the past, by giving element template authors control over what they want to show. It was powerful, and it will be powerful as a feature again, while being simple in implementation.

[marstamm]

As I understand this FR, the users don't want to configure anything, they just want a sensible default that allows for documentation on connectors. I think this makes sense as we also show the general and multi-instance sections without any configuration.

If we want to re-enable the old entriesVisible behavior and be consistent (default = hidden), we would have to update all connectors to achieve the behavior we want to achieve

[nikku]

As I understand this FR, the users don't want to configure anything

Got it, then let's make it so and await user feedback.

[barmac]

Some time ago we enabled the connector users to configure multiinstance characteristics as it is a feature specific to the diagram and not the element type. I believe the same applies to the documentation. Any BPMN element can be documented, and this should apply also to connectors. I don't see a reason why one should configure whether documentation is allowed for the same reason why connector template should not determine element's name.

[nikku]

Re-opening this as we want the same for Camunda 7, cf. SUPPORT-17421.

[nikku]

Additional fix for Camunda 7 element templates coming in via bpmn-io/bpmn-js-element-templates#67.