Can we reasonably build a Philly benefit screener with Camunda Forms + DMN?

[prestoncabe]

I'll experiment and document my findings here.

This is for #28

[prestoncabe]

I looked more deeply into this last night and today:

What I learned/did

• Camunda Forms is easy to get started with using Camunda Modeler (free download).
• Forms can also be created using the playground at bpmn.io or a standalone editor that you can embed in another website
• I created a simple form to collect two "facts" (dateOfBirth and livesInPhiladelphiaPa). Here is a portable HTML file that implements this simple form and logs the form output to the JS console when you change the form or hit the submit button.
• The example form outputs data in the same format that can be sent to our DMN services! :smiley:
• The example form has a "BPMN.IO" watermark that can't be removed without breaking the open source license :frowning_face:
• There was an effort in the KIE/Kogito world to build something similar a couple of years ago, but it has yet to get past an experimental phase (demo).

Things to explore further

• Can I restyle the form with additional CSS?
• Can I create a VS Code plugin for working with (editing) Camunda Forms? (Someone already made plugins for working with Camunda's BPMN and DMN editors, so this should be fairly straightforward?).
• Can I build a custom renderer for Camunda Forms (so we can do custom styling and get rid of the watermark)?
• There are other similar technologies that maybe we should give a look to:
  • JSON Forms
  • integration with Camunda Forms?
  • various community-built editor projects
  • Form.io
  • JotForm
  • TypeForm
  • JSON Editor

@sierscse FYI

[prestoncabe]

This page has really interesting ideas for how to customize Camunda Forms:

• Add images to forms
• Add images conditionally (e.g. different colors to indicate eligibility/ineligibility)
• Show real-time calculations (e.g. net income displayed after entering gross income and other relevant data?)
• Templated text views (e.g. "scripting" with dynamic data calculated in real time)
• Custom form components (e.g. "widgets" to help with collect complex data like income info?)

[prestoncabe]

Some other food for thought for using Camunda Forms effectively: https://camunda.com/blog/2023/05/draft-to-perfection-effective-forms-human-workflows/

[prestoncabe]

Another idea: using custom properties of form components to customize those components. For example, you could reference an external API (like a DMN decision service) to populate some reference on a form (like the current income limit or something like that).

Is this also how we could use the response from DMN to hide/show form elements based on whether the household is still eligible for a particular benefit? For example, the changed/submitted callbacks could update properties that are used to hide/show questions for a benefit.

https://github.com/bpmn-io/form-js-examples/blob/master/custom-properties/README.md

[prestoncabe]

I was able to rig up a development environment for using Camunda forms interacting with our DMN API. Using Project IDX (or Cloud Shell) makes this a bit more convoluted as compared to using a local dev environment, but it can be worked around.

Here are the steps:

1. Create the .form file using Camunda Modeler (local desktop application).
   • I hope eventually to rig up a way to do this in VS Code itself (by rigging up an extension for the web version of the Modeler app), but this is out of scope for now.
2. Copy/paste the form into a special script tag (<script type="application/form-schema">) in an html file.
3. Use Camunda Forms "viewer" API to write code that loads the form and defines listeners for changed/submitted events.
   • the listeners are what POST to the DMN API and do something with the results.
4. Use Project IDX's "Generate Access Token" command to create an authorization token to put in the request headers where you POST to the DMN. (something similar is available in Cloud Shell... I think?)
5. Serve the html file by naming it index.html, putting it in the root directory of the project, and running npx live-server. (can put it somewhere else if you run the server from the other directory).
6. Steps 4 and 5 are only needed if not running locally. (if the DMN API is running locally, you should just be able to open the html file directly on the same machine with no issues).

With the above steps, I am able to develop and test forms, see results back from the DMN!! It's fairly clunky to setup, but I expect that we'll streamline this over time.

Example gist: https://gist.github.com/prestoncabe/f44800973357ce5f191c0a4a6152040f

For now, I think I'll take a break on this front and fix some issues in the DMN revealed by testing the form (it doesn't handle blank/null data like I think we'll want).

@sierscse FYI

[prestoncabe]

Things to do a proof of concept for (that we will need for the philly tax benefit screener):

• A way to indicate "might be eligible , but need more info"
  • red/yellow/green... yellow when any of the elig. checks are null.
• "benefit status" - readout of the meaningful numbers/math to give feedback to the user as they fill out the form.
• "scripting" - "you might be eligible..." (next steps; call to action)
• ~reset button~ DONE
• remove BPMN.io watermark (if I can find a way that complies with licensing)?
• fix DMN server issues to not error when input info is null
• (for text benefit screener: will need concept of "benefit amount" figured out)

[prestoncabe]

I'm still swimming around in uncertainty, but I've learned some more things in the past couple of days:

Use FEEL to hide/show "scripting" text based on the state of the form.

• I'm able to demonstrate varying text based on the answers to questions (for example, show a message that instructs the user to answer more questions, or show some feedback/calculation). This uses a combination of FEEL and the Camunda Forms templating features (specifically the #if control).
• In Camunda Modeler, I'm also able to demonstrate varying text based on some arbitrary other data (for example, the eligibility result), but despite several hours of effort, I've yet to discover how to make this work when the form is actually connected to the DMN API. I'm still confused about how I can update state (and therefore trigger the scripting change) after a successful call to the API... I'll keep working on this.

Use the "Previews" feature of Project IDX

You can configure IDX to automatically launch a web server and preview it within the IDX window. Makes it easy to sit down and automatically troubleshoot forms. Not sure how/if this will be useful long term for a hypothetical DMN Benefits Toolbox developer, but it seems like it will have a place in helping to simplify the experience.

[prestoncabe]

Well, I think I've proved the concept of a simple screener using Camunda Forms + DMN. There's a lot more to figure out to build a real screener (need a production deployment plan, figure out how to handle multiple benefits in one screening, deal with the look and feel - including what to do about the BPMN.io watermark, etc.)... but I think the enough pieces are there to start planning what a MVP solution for Philly real estate tax benefits would look like.

@sierscse - we can start talking about that tomorrow!

[prestoncabe]

Screencast from 2024-10-07 22-29-08.webm

demo! @sierscse