Allow Documentation and Example data sections for Connector templates

[m-myska]

Is your feature request related to a problem? Please describe.

Currently the are no Documentation and Example data sections in Connector templates as it's for generic element types.

Describe the solution you'd like

Documentation and Example data sections are visible on activity when Connector template is selected.

[crobbins215]

@sbuettner based on https://camunda.slack.com/archives/C06SBNKJHS6/p1715080678353749, are the team able to pick this up and get it done for the next alpha release after this one that's currently happening.

[yT0n1]

We should keep an eye on how the example data is handled in the Web Modeler's auto complete. E.g., if there is a result expression applied it should not propagate to the rest of the diagram (slack thread)

[yT0n1]

@crobbins215, do you have a timeframe when this will be implemented?

[crobbins215]

Its priority is set up as ready and now so should get picked up soon. FYI @sbuettner

[barmac]

The documentation part is already available. Regarding the example data, the question is whether it should be available for all connectors. Note that sometimes the template developer may provide the example data (in case of specialized templates), and in other cases it is the user's responsibility (generic REST connector).

Example:
I implement a MyService template. I know best what response MyService returns. To help my users use it, I add zeebe:property of format accepted by the example data extension as a hidden field so that my users don't need to paste anything on their own.

Also, I can already define such a field to be filled in by the user. So the template developer has full control (though it's undocumented).

[barmac]

The example data issue: bpmn-io/bpmn-js-element-templates#104

[barmac]

See also https://github.com/camunda/example-data-properties-provider/blob/main/test/fixtures/templates.json for how one could implement example output in the templates.

[marstamm]

X-Posting and summarizing the discussion from slack:

Core Problem:

Core use-case for the Play team is to mock output using example data. Modeler integration for this is not strictly necessary, but could improve modeling experience. However, this will require a custom variable provider that is connector specific.

Current State:

The Documentation Field is already available in Templated Tasks. For Example data, the template must support it and explicitly add it as a field. Cf. @barmac's comments above.

Suggested Solution (in this ticket)

Add Example data section to templated elements.

Adding the Example data field has some problems:

• bad integration with Element templates. In the current state, the data is not persisted across upgrades and there might be clashes when the template already defines example data. This is because we persist the data in a zeebe:property, that will be removed as it is not part of the template
• bad user experience: Example data provider expects the return data of the task. That means that the user needs to add the result of the result expression. Mapping is not done for us

The example data provider was not designed to work in this way, but as a MVP for simple use cases.

The variable system is pluggable. It would be easier to create an additional data provider that allows better code intelligence for this case and solve both problems we are facing.