Support for numeric and boolean input types

[markfarkas-camunda]

Problem you would like to solve

It is impossible to define boolean or numeric input type in the element template.

This issue was first raised here: camunda/camunda#12142

This issue was also raised in the forum: https://forum.camunda.io/t/checkbox-in-a-camunda-8-connector-template/44610

Consider the following case: I would like to create a Stripe connector based on the rest prototype connector. For creating a charge, specifying the amount is mandatory. This has to be in integer format. See here

For this it would make sense to have an input type Number in the element template json file.

Format would look like this:

    {
      "label": "Amount",
      "group": "parameters",
      "type": "Number",
      "feel": "optional",
      "binding": {
        "type": "zeebe:input",
        "name": "amount"
      }
    }

Supporting numeric inputs would also give the following advantages:

• Validation on the frontend (before deploying the process definition)
• More straightforward input for the user (number type input html tag)
• Eliminating the need of always converting a value in connector code

Also, adding a boolean type would have similar benefits. In the element template I could imagine something like this if we want to make it possible to get the right value for e.g.: the capture boolean property:

    {
      "label": "Capture",
      "group": "parameters",
      "type": "Boolean",
      "feel": "optional",
      "binding": {
        "type": "zeebe:input",
        "name": "capture"
      }
    }

Supporting boolean inputs would also give the following advantages:

• Validation on the frontend (before deploying the process definition)
• More straightforward input for the user (checkbox)
• Eliminating the need of always converting a value in connector code

Having Boolean and Number type format would allow us to construct a body property in the element template which consist of different types of values. For example:

{
  "propertyName1": "value",
  "numericPropertyName": 3,
  "booleanPropertyName": true
}

In this particular Stripe demo case:

{
  "currency": "usd",
  "amount": 200,
  "capture": true,
  ...
}

Constructing the body in element template looks something like this below. Converting inputs to the proper format makes it even harder to read this long value. That's one reason supporting different format would be really helpful:

    {
      "group": "input",
      "type": "Hidden",
      "value": "={\"currency\": if currency= null then null else currency, \"amount\":if amount= null then null else amount,\"capture\":if capture= null then null else capture}",
      "binding": {
        "type": "zeebe:input",
        "name": "body"
      },
      "optional": false
    }

Proposed solution

Make it possible to define an input field with "type": "Number" and "type":"Boolean" instead of "type": "String".

Alternatives considered

An alternative solution can be to convert the value from string to number with the number() function first, and then use this instead, but this approach is very inconvenient and cumbersome.

Additional context

Related to #740
Related to #472
Related to #2739
Related to #1933
Related to bpmn-io/bpmn-js-element-templates#39

[barmac]

Thanks for suggestion. Is this a blocker for the team?

[markfarkas-camunda]

Not right now but we are creating connectors frequently, and we have to use workarounds if we face this. Therefore the sooner it is implemented the better from our and also from the customers' perspective.

[barmac]

Thanks for insights. We will discuss it in the next iteration planning.

[nikku]

FYI @christian-konrad. This is a medium sized issue and we did not prioritize it.

[sbuettner]

@nikku Hey Nico, in the context of element template generation we would like to make use of boolean types and therefore need support in the properties panel.

[nikku]

We'll discuss this topic with the team again.

[nikku]

An earlier investigation already revealed that building boolean bindings properly is likely not straight forward, cf. bpmn-io/bpmn-js-element-templates#39 and following.

I added prior user feedback to this issue, asking for similar functionality. It is definitely unexpected that we don't support Boolean as a type.

[bastiankoerber]

An earlier investigation already revealed that building boolean bindings properly is likely not straight forward, cf. bpmn-io/bpmn-js-element-templates#39 and following.

I added prior user feedback to this issue, asking for similar functionality. It is definitely unexpected that we don't support Boolean as a type.

is there a way to prioritize it?

[nikku]

This is in ready to be prioritized in our next planning round (ref).

[marstamm]

I investigated what needs to be done to support this use-case today. Here is my evaluation on what challenges we need to overcome for it.

From the UI perspective, we already have the required components to allow templating with optional FEEL bindings. These are the same as form-js uses:

However, when it comes to bindings, we face issues:

Boolean

1. An unchecked checkbox will have no value (not false)
2. When used in a field that requires a feel expression (e.g. input mappings), zeebe accepts true as a value, but interprets it as the string "true".

Solution proposal

1
Provide options to define the value that should be set, for checked and unchecked state:

{
  "label": "Capture",
  "type": "Boolean",
  "feel": "optional",
  "checkedValue": "true", // optional, default: true
  "uncheckedValue": "false", // optional, default: undefined
  "binding": {
    "type": "zeebe:input",
    "name": "capture"
  }
}

This also allows checkboxes for other use-cases, where the property itself is not a boolean number, such as "Enable retries" setting "retries" to 3 with "checkedValue": "3"

2
See Below

Number

Same as 2️⃣ for Boolean values, setting a number 123 in an input mapping without a feel expression, will result in the engine interpreting it as the string "123"

Solution Proposal

2.1
Do not support (optional-) FEEL expressions for these custom elements. If we know which fields require a feel expression, we can then adjust the value by pre-fixing the value with = as a feel expression. However, this would limit the usability of these fields. In my opinion, allowing custom FEEL expressions allows us to build much more powerful connectors.

2.2
Similar to the first option, we could automatically prefix the = when we know the field requires it. However, because we use the content of the property exclusively to know if the property is a feel expression, we would need some additional logic. Both left and right side are the same value in the XML:

If we check if the value after = is atomic, we would show the checkbox/number input when reloading the properties panel. Even if the user previously used the editor to change the value. Only when an expression or variable name is used in the field would we show the feel editor.

---

As we need to know about the places which require feel in both cases, I would propose to go for 2.2, as it allows us more flexibility in building templates.

[nikku]

Both left and right side are the same value in the XML:

Unfortunately this is not true. In core (engine) all fields without = prefix are interpreted as strings, so passing someNumber="15" as an input mapping would yield the string 15. Only = 15 will yield the actual number.

In other places interpretation of the value is completely user defined (zeebe:properties, zeebe:taskHeader).

In form-js things are easier, as we know which fields are numbers, and we interpret them as such. Element templates in contrast can bind to arbitrary properties. This is why it is particularily tricky to bind to everything that is not a string.

Eliminating the need of always converting a value in connector code

@markfarkas-camunda This is an interesting expectation. I presume you mean you don't want to convert when using an input mapping? Or do you refer to other things as well, i.e. zebee:property with automatic type cohersion (which is impossible).

[marstamm]

Unfortunately this is not true.

I am aware of that, as described in the problem section. This is in context of the solution proposal of 2.2, where we would automagically add the = sign. With this solution, both inputs would result in the same XML for input/output mappings

[nikku]

Similar to the first option, we could automatically prefix the = when we know the field requires it.

We may know for input mappings. But what about other things such as additional configuration (zeebe:property, zeebe:taskHeader)? We don't know how these properties are interpreted, and hence don't know if = 10 should be serialized or 10.

One example is webhook inbound (start) connector where there exists no input mappings, but tons of FEEL expressions (that may be fed by Number fields):

---

My suggestion is: Let us not do magic, but find a robust solution to handle that. This is reflected on an earlier comment of mine (bpmn-io/bpmn-js-element-templates#39 (comment)).

[marstamm]

I see, let's not do any magic then and rely on user input to decide how we handle the input.

However, is our existing feel property powerful enough for it? As it currently only handles the display of the property to the user, there is one scenario missing: Binding to a FEEL field but not showing a FEEL editor.
I feel like there should be a third option besides optional and required that means "this is a feel field, but do not allow a feel editor to be displayed". feel: restricted maybe?

[nikku]

I feel like there should be a third option besides optional and required that means "this is a feel field, but do not allow a feel editor to be displayed". feel: restricted maybe?

I feel the same 🙂. Maybe it is going to be a different property as well. My proposal is: Let's prototype something and see how it works.

[marstamm]

Let's prototype something and see how it works

👍

Maybe it is going to be a different property as well

I thought about this as well, but we cover 90% of the use-cases with the existing FEEL property already: if a feel expression is optional, we will not break it if we commit =15 even when 15 would work as well. It would be redundant to introduce another property that describes feel.

[nikku]

Released with https://github.com/camunda/camunda-bpmn-js/blob/main/CHANGELOG.md#410

[nikku]

@barmac identified in #4154 a bunch of issues that we want to assess and potentially follow-up on. Moving this back to ready.

CC @marstamm

[marstamm]

I investigated the reported problems and evaluated them. I also tried to assign priorities to the issues to figure out what needs to be fixed before the release:

Description	Evaluation	Priority
Template requires string as value for numbers	Ease of Use, Not a regression, needs to be added to schema. We discussed this in the kickoff and we recommend using FEEL as a value when required	low
Condition with number is never fulfilled	Ease of Use, has workaround with String value	low
type: Boolean, value: true, feel: required breaks	Breaking bug, need to cast value to string before passing to Editor	high
type: Number inconsistent increase behavior	Can only reproduce in camunda-bpmn-js and downstream libs, works fine in element template repo. This is also broken for non-feel Number fields	needs more investigation, medium
type: Boolean, feel: optional does not trigger FEEL editor	can't reproduce	can't reproduce

[nikku]

@marstamm We agreed that we'd officially release this with the next release? If so, please milestone accordingly (M75). Otherwise let's close + assess which linked issues we can close in the process.

[marstamm]

Only major thing missing for an official release is https://github.com/bpmn-io/internal-docs/issues/919 documentation

[nikku]

Closing as discussed. Will follow-up with documentation soon.