Support Zeebe user task

[barmac]

What should we do?

<bpmn:userTask id="Activity_1kl1v6a">
  <bpmn:extensionElements>
    <zeebe:formDefinition externalReference="customFormKey" />
    <zeebe:userTask />
  </bpmn:extensionElements>
</bpmn:userTask>

zeebe-bpmn-moddle

• [x] Add extension: <zeebe:userTask> (in User Task)
• [x] Add externalReference to <zeebe:formDefinition>

properties panel

• [x] I can set implementation of a user task as either "job worker" or "Zeebe user task"
  • [x] "Zeebe user task" is displayed if element contains <zeebe:userTask> extension element
  • [x] "Job worker" is displayed otherwise
• [x] When I change the implementation to "Job worker", the <zeebe:userTask> extension is removed
• [x] When "Zeebe user task" is selected, only “Camunda form (linked)” and “Custom form key” for form linking are allowed. Embedded forms are disallowed.
• [x] In "Zeebe user task", set custom form key value to attribute “externalReference” instead of “formKey” (https://github.com/camunda/zeebe/issues/16006)

linting

• [x] Error is displayed if <zeebe:userTask> is used prior to Camunda 8.5
• [x] Error if external reference or form ID is missing in Zeebe user task

Why should we do it?

Part of efforts: User Task lifecycle & listeners in Zeebe

Epic: https://github.com/camunda/product-hub/issues/1823

[barmac]

I clarified the task listeners, and we are not implementing this feature yet (cf. https://github.com/camunda/product-hub/issues/1823#issuecomment-1918589148).

[tmetzke]

@barmac, we'll call the corresponding property of user task records in Zeebe externalFormReference to have enough context in a user task, looking at the attribute. Should we align this here and also go for that name in modeling or do you think it's fine to have a slight difference here since the externalReference is part of the form definition in the model already?

[nikku]

@tmetzke As far as I know we treated a form key not starting with camunda-form as an external reference in the past. How/why did we decide to change course?

Does this mean we'll now have 4 options for our users to choose?

@barmac Let's take a focused amount of time to think about the UX rather soon.

[tmetzke]

Hey @nikku, thanks for asking, we missed to publicly clarify this anywhere, I guess. As described in the (internal) technical proposal, there will be 2 options in the Zeebe user tasks: linked Camunda forms (via formId) or custom forms (via externalReference). As job-based user tasks are meant to be deprecated in the future, those will be the two options moving forward. For job-based user tasks (the current default), nothing changes in that regard.

Why the change? There has been quite some confusion around the formKey in Camunda 8 in the past:

1. We more or less took this over from how it's done in Camunda 7. However, since Zeebe uses a key-based terminology instead of Camunda 7's id-based one for unique identification of entities (e.g. processInstanceKey instead of processInstanceId), this led to name clashes and misunderstandings. For example, all key-based attributes in a job record can be used as Long value-based references to other entities, while the formKey can't. This is merely a String value, describing how to find the related form.
2. The value of the formKey attribute is quite cumbersome for users to decode. The specific way the form is linked can only be obtained through dedicated String parsing and pattern matching, analyzing potential prefixes in the value to exist. @christian-konrad also expressed his preference of a clear separation of linked forms and custom forms in modeling (internally) over here.

As a result, we (internally) decided to go for formId and externalReference for user task forms, moving forward. We intend to highlight this in the public documentation as well.

Since we're still in development here and in alpha-status, I'm absolutely open to discussing this if you see any hard requirements to do this differently. Sorry for not involving the modeling team more in this move. With @christian-konrad also pushing for this, I figured this was an obvious move to make (technically from the Zeebe end but also product-wise).

[tmetzke]

I also added this reasoning to the public issue in Zeebe.

[barmac]

Does this mean we'll now have 4 options for our users to choose?

Technically it's 5 different options spread among 2 groups:

• Job worker:
  • Embedded form
  • Linked form (formId)
  • External form (formKey)
• Zeebe user task
  • Linked form (formId)
  • External form (externalReference)

[nikku]

Thanks @tmetzke. This rationale makes absolute sense as we have the opportunity to re-think things.

[barmac]

Since each of the features in the upstream libraries are merged, this is now fixed upstream.

[barmac]

This will complete the story: https://github.com/bpmn-io/bpmn-js-properties-panel/issues/1032