Integrate DMN evaluation into form logic

[sergei-maertens]

Decision Model and Notation (DMN) is a worldwide-standard for modelling decisions. DMN can be executed by DMN engines, such as Camunda.

Massively simplified, it allows you to define rules in an almost-Excel-like interface, that given a particular set of inputs produces a set of outputs. You could compare it with a pure function def decision(input1, input2, ...): ... that operates as a black box.

We want to enable form builders to call decision models as part of our logic evaluation process.

Functional UX

The functional user experience, as a person who creates and maintains forms.

As an example case, consider "applying for a some sort of financial benefits". The conditions for such a hypothetical application are not straightforward, and those are (can be) modeled in a DMN table with name "application conditions":

• if you are younger than 20 and are employed, you may not apply
• if you are younger than 25 and have a yearly income of 40K+, you may not apply
• if you are 25 or older and live by yourself with an income of 45K or less, you may apply
• if you are 65+ with an income of 35K or less, you may apply

It has the following input parameter names: age, income, hasAJob, numHouseholdMembers and ouput parameter names: conditionsFulfilled, reason

1. Set up a form with the fields:
   • employment status (yes/no)
   • age (number)
   • household size (number of people, integer, >= 1)
   • yearly income (currency)
   • content ("You are not allowed to apply because you don't meet the criteria", initially hidden)
2. Define user defined variable isAllowedToApply, default value true
3. Navigate to logic tab
4. Add complex logic rule
   • trigger: true (always evaluate, optionally optimize to only evaluate once employment status, age and household size are all non-empty)
   • action: "call decision model"
   • click button "configure" (similar to service fetch)
5. Modal opens to configure the DMN call action
   • From a dropdown, select the applicable decision model ("application conditions")
   • (optionally) select the version of the decision model
   • map the input parameters:
     • age: age
     • income: yearly income
     • hasAJob: employment status
     • numHouseholdMembers: household size
   • map the output parameters:
     • conditionsFulfilled -> isAllowedToApply
   • Click the "save" button
6. Add a second logic rule
   • trigger: {"!=": "isAllowedToApply"}
   • action 1: prevent form submissions
   • action 2: change content from hidden to visible

Technical tasks

Must have

• [x] Implement the modal/form to configure a DMN call action

  • must be added to storybook
  • dropdown field to select the decision definition (API endpoints exist)
  • dropdown/text input field to specify the version of the selected definition (check how the Camunda process definition form works)
  • section for input variable mapping: textfield for DMN input parameter as key, value is our form variables from a dropdown
  • section for output variable mapping: textfield for DMN output parameter as key, value is our form variables from a dropdown

• [x] Implement the UI for an additional logic action type, evaluate-dmn

  • must be added to storybook
  • similar to fetch-from-service action type - present "configure" button
  • different from service fetch: all configuration aspects are saved on the action itself

• [x] Implement the backend the evaluate-dmn logic action. This is probably a bit of a combination of service fetch and variable action types.

  • the action execution must call the openforms.dmn.service.evaluate_dmn function
  • the DMN call itself with input parameters + values & output parameters + values must be logged
  • apply the input/output parameter mapping (form variables -> input -> DMN -> output -> assign to form variables)

• [x] Must support Camunda 7.x (7.16 is what we used for BPMN)

• [x] Documentation updates

  • Configuration requirements for DMN/Camunda (supported/tested versions, required permissions...)
  • Example form using a DMN table

Should have

• ~Support Camunda 8.x (seems to be at 8.3 at the time of writing)~ (Camunda 8 has a different license and will not be used for now).

Nice to haves (moved to #3855)

• Extract the available input/output parameters from the DMN XML definition
• "Try it out" tab where you can provide values for the input parameters, make the call & show the output parameters
• Result caching for given input parameters (pure function should be memoizable), though there is a risk the table is updated during multiple execution calls
• [x] Support multiple plugins abstraction. Currently, Camunda is just a single plugin for the DMN feature, multiple engines may be supported in the future (perhaps we'll roll our own if Camunda is not available?)
• In the configuration modal, automatically select the plugin if there is only one option available.

Resources

• DMN
• Camunda DMN

[sergei-maertens]

still WIP

[SilviaAmAm]

Discuss the PRIO of the other checkboxes