{"id":16119544,"url":"https://github.com/stephenott/camunda-formio-plugin","last_synced_at":"2025-03-16T08:32:50.049Z","repository":{"id":48884604,"uuid":"290046650","full_name":"StephenOTT/camunda-formio-plugin","owner":"StephenOTT","description":"Integration for Drag and Drop Formio Form Builder and Renderer with Camunda Tasklist App","archived":false,"fork":false,"pushed_at":"2021-08-26T21:16:17.000Z","size":3870,"stargazers_count":65,"open_issues_count":32,"forks_count":26,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-27T05:56:29.253Z","etag":null,"topics":["camunda","formio"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StephenOTT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-24T21:45:49.000Z","updated_at":"2024-10-19T15:18:52.000Z","dependencies_parsed_at":"2022-09-16T04:01:46.934Z","dependency_job_id":null,"html_url":"https://github.com/StephenOTT/camunda-formio-plugin","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephenOTT%2Fcamunda-formio-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephenOTT%2Fcamunda-formio-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephenOTT%2Fcamunda-formio-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephenOTT%2Fcamunda-formio-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StephenOTT","download_url":"https://codeload.github.com/StephenOTT/camunda-formio-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243807457,"owners_count":20350996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camunda","formio"],"created_at":"2024-10-09T20:54:25.273Z","updated_at":"2025-03-16T08:32:47.642Z","avatar_url":"https://github.com/StephenOTT.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Camunda Formio Plugin\n\nProvides client-side and server-side integration for using Camunda Embedded Forms with Formio Forms.\n\n![](./doc/FormBuild1.png)\n\n![](./doc/StartForm1.png)\n\n![](./doc/UT1.png)\n\n![](./doc/UT1.1.png)\n\n![](./doc/UT1.2.png)\n\n## What does it do?\n\nAllows you to configure *start-event* forms and *user-task* forms with a `formkey` that will load formio forms in Camunda Tasklist webapp.\n\n\n## How do I set it up?!\n\nConfiguring Formio for a Start Form:\n\n![Start Form](./doc/StartForm-Config.png)\n\n\nConfiguring Formio for User Tasks:\n\n![User Task Form](./doc/UserTask-Config.png)\n\nIf you want to add server side validation, you add a Validation Constraint with the name `formio`.  See the Server Validation \nsection for more details.\n\n\n## Installation\n\n### Camunda SpringBoot Deployment\n\nSee the `springboot` folder for a example of the deployment\n\n### Typical Camunda Deployment\n\nSee the `docker` folder for an example of the deployment using the Camunda Tomcat distribution\n\n\n## Building Forms:\n\nLocal Builder: Deploy Webapp and access a local builder at: `http://..../forms/builder.html`\n\nHosted Builder: [https://formio.github.io/formio.js/app/builder](https://formio.github.io/formio.js/app/builder)\n\n\n## Configure the BPMN\n\nExample of Configuring a Start Form:\n\n`embedded:/forms/formio.html?deployment=MyStartForm.json\u0026var=submission\u0026transient=true`\n\nIn this example, we use the `deployment` parameter to direct the use of the `MyStartForm.json` form schema which is found in the BPMN Deployment resources. \nWe use the `var` parameter to direct the name of the process variable that will be created to store the form submission. \nWe use the `transient` parameter to direct the process variable holding the form submission get created as a \n[transient variable](https://docs.camunda.org/manual/7.13/user-guide/process-engine/variables/#transient-variables) \n\n\n![start form configuration](./doc/StartForm-Config.png)\n\n```xml\n\u003cbpmn:startEvent id=\"Event_0emfvgy\"\n                 camunda:formKey=\"embedded:/forms/formio.html?deployment=MyStartForm.json\u0026#38;var=submission\u0026#38;transient=true\"\u003e\n    \u003cbpmn:outgoing\u003eFlow_1ax32ut\u003c/bpmn:outgoing\u003e\n\u003c/bpmn:startEvent\u003e\n```\n\n\nExample of Configuring a User Task:\n\n`embedded:/forms/formio.html?deployment=MyUT1.json\u0026var=subWithServerValidation\n\n![start form configuration](./doc/UserTask-Config.png)\n\n```xml\n\u003cbpmn:userTask id=\"Activity_1xq7c62\" name=\"Typical Form with Server Validation\"\n               camunda:formKey=\"embedded:/forms/formio.html?deployment=MyUT1.json\u0026#38;var=subWithServerValidation\"\u003e\n    \u003cbpmn:extensionElements\u003e\n        \u003ccamunda:formData\u003e\n            \u003ccamunda:formField id=\"FormField_0t7u03d\" type=\"string\"\u003e\n                \u003ccamunda:validation\u003e\n                    \u003ccamunda:constraint name=\"formio\"/\u003e\n                \u003c/camunda:validation\u003e\n            \u003c/camunda:formField\u003e\n        \u003c/camunda:formData\u003e\n    \u003c/bpmn:extensionElements\u003e\n    \u003cbpmn:incoming\u003eFlow_0069xxd\u003c/bpmn:incoming\u003e\n    \u003cbpmn:outgoing\u003eFlow_18xtnen\u003c/bpmn:outgoing\u003e\n\u003c/bpmn:userTask\u003e\n```\n\n\n### Configuration Options:\n\nThe following are the parameters that can be passed in the `formKey`:\n\n| Parameter | Required? | Default | Description |\n|---------------|-------------------|--------------|-----------------------|\n|deployment=    | Yes or use path= | - | The .json file name in the deployment created through the API. |\n|path=          | Yes or use deployment= | - | The file system path to the .json file. **Must start with a `/`** |\n|transient=     | No | false | If true, then variable will be submitted as Transient, and thus not saved to database.  Use a Script Task or listener in the transaction to post-process the submission into the desired variable. |\n|var=           | No | if start form then \"startForm_submission\", if user task then \"`[taskId]`_submission\"| Define a custom variable name for the form submission.  Will be submitted as a Process Variable.|\n\nExamples:\n\n1. `embedded:/forms/formio.html?deployment=MyUT1.json?transient=true\u0026var=myCustomSubmission`\n1. `embedded:/forms/formio.html?deployment=MyUT1.json?var=UT1-Submission`\n1. `embedded:/forms/formio.html?path=/forms/MyStartForm.json` (where the MyStartForm.json was placed in the `src/main/webapp/forms` folder.  **Make sure your path starts with a `/`**)\n\n\n### Configuration through Camunda Extension Properties\n\nIf you enable the `FormioParseListenerProcessEnginePlugin`, you can configure through Extension Properties rather than \nmanually creating the formKey:\n\n![extension props usage](/doc/formio_config_extension_props.png)\n\nThe same configuration options used in the formKey are used in the extension properties. \nEach extension property has a prefix of `formio_`.\n\nFor Server Validation you add a **name:** `formio_validation`, **value:** `true`.\n \n\n## Submission Storage\n\nWhen a successful submission occurs, a `json` variable will be created as a Process Instance Variable. \n\nUse [Camunda SPIN library](https://docs.camunda.org/manual/7.13/reference/spin/json/) to access the json variable properties.\n\nExample in a gateway expression: `${someSubmission.prop('data').prop('someFieldKey').value()}`\n\n\n### Resolving User Task `taskId` to more meaningful values\n\nVery often the taskID (which is typically a UUID) will not be very meaningful.  If you require more meaningful variable names \nconsider using the `var` parameter to set a custom variable name or use the Activity ID (the `id` property when you are in the Modeler on a user task activity).\n\n\n## Trigger 'BPMN Errors'\n\nSupport is provided to trigger interrupting BPMN Errors:\n\nTrigger a formio event with the name `bpmn-error` (typically with a button: set the button event to `bpmn-error`)\n\nThe default error code is `default`.  To set a custom error code, create a variable in the formio submission with the key \n`_errorCode`.  Typical use cases are to use a `text` component or a `hidden` component.\n\nNo error message is submitted by default.  To set a custom error message, create a variable in the formio submission with the key \n`_errorMessage`.  Typical use cases are to use a `text` component or a `hidden` component.\n\n**The submission variable created through the bpmn-error cannot be validated using the formio server validator: this is a limitation in Camunda**\n\n## Trigger 'BPMN Escalations'\n\nSupport is provided to trigger interrupting and non-interrupting BPMN Escalations.  Note that Camunda's form API does not \nmake a distinction between interrupting and non-interrupting escalation events and therefore some best practices are implemented:\n\nThe escalation code is `default`.  To set a custom escalation code, create a variable in the formio submission with the key \n`_escalationCode`.  Typical use cases are to use a `text` component or a `hidden` component.\n\n**The submission variable created through the bpmn-escalation cannot be validated using the formio server validator: this is a limitation in Camunda**\n\n### Interrupting BPMN Escalations\n\nTo trigger BPMN Escalation that is designed to be used with a interrupting BPMN Escalation boundary event:\n\nTrigger a formio event with the name `bpmn-escalation` (typically with a button: set the button event to `bpmn-escalaton`)\n\n### Non-Interrupting BPMN Escalations\n\nTo trigger BPMN Escalation that is designed to be used with a non-interrupting BPMN Escalation boundary event:\n\nTrigger a formio event with the name `bpmn-escalation-noninterrupt` (typically with a button: set the button event to `bpmn-escalaton-noninterrupt`)\n\nA non-interrupting escalation means the user task will remain in the task list, and the submission variable name will be given a suffix of `_escalation`. \nThe suffix is used to ensure if/when the user task is normally completed, the submission variable created through the \nuser task completion does not overwrite the submission variable created through escalation.\n\n\n## Deploying your Forms\n \n### REST API Form Deployment\n\nForms can be deployed through the REST API.  The form JSON must be part of the same deployment as the BPMN.\n \nIf changes need to be made to the form, you must deploy a new .json file along with the BPMN.\n \nAn example of using Postman to deploy:\n \n![Deployment in Postman](./doc/Deployment.png)\n\nWhen using REST API Form deployments, use the `deployment` parameter in the form key such as: \n`embedded:/forms/formio.html?deployment=MyUT1.json`\n\n### File System Forms Deployment (or other URLs)\n \nForms can be deployed on the file system and made available to the web application.  The common way to do this is \nthrough `src/main/webapp/forms` (or whatever folder you like within `webapp`).\n \nIf you want to make changes to the JSON, you can modify the JSON file without having to make a new BPMN deployment.\n \nIf you do not want to use the file system, you can deploy to another URL within the same domain as Camunda Webapps.  Then \nyou can set your `formKey` to something like: `embedded:/forms/formio.html?deployment=http://example.com/forms/MyUT1.json`\n \nThe benefit of having your form/JSON outside of the BPMN deployment is you are not required to redeploy the BPMN each \ntime you make changes to the form, but in many use cases you will want to tie your BPMN and forms together \nwithin the same deployment for versioning purposes.\n \n## Example Submission\n \n![Cockpit](./doc/Cockpit2.png)\n \n ```json\n{\n  \"data\": {\n    \"firstName\": \"SomeFirstName\",\n    \"lastName\": \"SomeLastName\",\n    \"email\": \"\",\n    \"phoneNumber\": {\n      \"value\": \"\",\n      \"maskName\": \"US\"\n    },\n    \"select\": [],\n    \"address\": {},\n    \"dueDate\": \"2020-08-18T12:00:00-04:00\",\n    \"birthdate\": \"00/00/0000\",\n    \"submit\": false\n  },\n  \"metadata\": {\n    \"timezone\": \"America/Montreal\",\n    \"offset\": -240,\n    \"origin\": \"http://localhost:8080\",\n    \"referrer\": \"http://localhost:8080/camunda/app/welcome/default/\",\n    \"browserName\": \"Netscape\",\n    \"userAgent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.2 Safari/605.1.15\",\n    \"pathName\": \"/camunda/app/tasklist/default/\",\n    \"onLine\": true\n  },\n  \"state\": \"submitted\"\n}\n```\n\n\n## Variable Fetching in Formio\n\nFormio will fetch variables based on configurations in the component configuration.\n\nUnder the API tab of a component create a custom property with the following format:\n\n**key:** `fetchVariable`  **value:** `variableName` (recommended not to use spaces in variable names)\n\nOnce you get your variable, use the Default Value Population feature to populate your field with the data returned from the variable fetch.\n\n\n## Default Value Population\n\nMake sure to fetch the variables using the `fetchVariable` configuration.\n\n### Simple Configuration\n\nThe simple configuration provides a rapid setup option allowing most common use case access to variables.\n\nIn the form component's API tab, set a custom property with key: `camVariableName` and the value being the dot notation path.\n\nExample:\n\n1. Given a simple camunda string variable named \"firstName\", the key-value configuration would be:\n   \n   `camVariableName: firstName`\n\n1. Given a previous formio form submission which is saved as a Camunda Json variable, the key-value configuration would be: \n\n   `camVariableName: somePreviousSubmission.data.firstName` \n\n\nIf the variable is type Json and you would like to print out the json into the form field, add a property in the API tab with the configuration:\n\nKey:`stringify`\n\nValue: `true` (If you are manipulating the raw json, this should be an equivalent of `\"true\"`)\n\n\n### Advanced Configuration\n\nThe advanced configuration provides javascript access to the variables, allowing complex configurations \nsuch as variable manipulation, merging, trim, etc.\n\nUse the Custom Default Value Javascript feature in Formio to parse the returned variables.\n\nVariables get stored in `$scope.camForm.formioVariables`\n\nIn the Custom Default Value configuration you can use the following to access the object of variables:\n\n```js\nlet variables = angular.element('#task-form-formio').scope().camForm.formioVariables\n```\n\nVariables names are the keys.\n\nIf the variable is type `Json` it is automatically available as a JS Object.\n\n### Example\n\nSet the default value of a Text field \"First Name\" with the `firstName` property that was submitted in the Start Form (a formio form submission)\n\nIn the First Name field's Custom Default Value configuration use the following: \n\n```js\nlet variables = angular.element('#task-form-formio').scope().camForm.formioVariables\n\nvalue = variables.postProcessed_submission.data.firstName\n```\n\nThe code `angular.element('#task-form-formio').scope()` is re-capturing the Camunda task form angular scope from the `\u003cform id=\"task-form-formio\u003e` element.\n\nFormio based submissions place the form submission data inside of the `data` object.\n\nCommon use case would be to set the First Name field as read-only if it is for display purposes.\n\n1. Configure the Component: \n\n   ![Build1](./doc/Form-Build-1.png)\n\n1. Go to the Data tab: \n\n   ![Build2](./doc/Form-Build-2.png)\n\n1. Scroll down to Custom Default Value: \n\n   ![Build3](./doc/Form-Build-3.png)\n\n1. Add your JS logic for selecting your default value: \n\n   ![Build4](./doc/Form-Build-4.png)\n\n1. Go to the API tab: \n\n   ![Build5](./doc/Form-Build-5.png)\n\n1. Create a Custom property with key `fetchVariable`, and the value of the variable you want to work within your JS in step 4.\n \n   ![Build6](./doc/Form-Build-6.png)\n   \n\n## Server Validation (Validating submissions against the schema on the server)\n\nFrom submissions can optionally be enabled with server-side validation by the Formio server-side validation.\n\nTo enable server-side validation of a *start-form* or *user-task*:\n\n1. add a \"validation constraint\" in the form fields configuration. \n\n1. Set any field type, and create a constraint with the key/name \"formio\":\n\n   ![server config](./doc/UserTask-Config.png)\n\n1. Deploy the [form-validation-server](https://github.com/StephenOTT/Form-Validation-Server)\n\n1. Configure the Plugin `FormioFormFieldValidationProcessEnginePlugin.class`.\nThe plugin has the following parameters:\n   1. `validationUrl` : The validation url to send submissions to.  Defaults to `localhost:8081/validate`.\n   1. `validationTimeout` : The milliseconds to wait before timeout of the Validation Url HTTP request.  Defaults to `10000` 10 seconds.\n   1. `validationHandler` : The bean instance that will execute the Formio Validation.  Defaults to an instance of `SimpleFormioValidationHandler.class`.  Override this configuration if you have special validation handling requirements.\n\n\n## Subforms / Nested Forms\n\nYou can nest forms using the `container` component.  The `container` component is used to gather form values into a nested \nJSON object.\n\n### Subform usage\n\n1. Add a container to your form\n1. In the api properties tab set a component property of:\n   1. Key: `subform` value: `deployment=mySubForm.json` or `path=/my/path/mySubForm.json`\n\nThe `subform` property value uses the same format as the formkey parameters.\n\nTypical use cases is to set the container to \"disabled\", then the nested form is read-only and you display the \nform of a previous submission.\n\n### Hide Subform buttons\n\nThe submit button will be hidden by default.  If you want to hide all buttons on your subform add a additional property \nto the container:\n\n - Key: `hideButtons`  value: `true` (this should be a string value)\n\n### Subform Pre-population\n\nIf you want to populate the subform with values from a variable, use the `camVariableName` property.  You can access previous \nform submissions with Key: `camVariableName`  value: `myPreviousSubmissionJsonVariable.data`. The data object, which is what \nFormio places all submission data into, will then be populated into the subform.\n\nIt is the responsibility of the parent form to provide variable resolution for any fields in the subform.  Subforms with \nform components that have `camVariableName` or `fetchVariable` properties will be ignored.  This may change in the future.\n\n## File Uploads\n\nUse the `file` component, and use the Base64 storage format.  The file will be uploaded as part of the JSON submission to camunda.\n\nYou can display you file upload in a formio form by returning the base64 value into a readonly/disabled form (such as using subforms).\n\nTypical use case would be to upload the file as JSON/base64 as part of the form submission, and then handle transitive modifications of the file \ninto other storage formats, and drop the base64 value from the submission / replace with other values pointing to a long term \nstorage format (such as a blob/file storage container) \n\n## Get-Form-Variables Command Security Plugin\n\nThe plugin `GetFormVariablesSecurityProcessEnginePlugin.class` provides variable security using Camunda Extension \nProperties on a User Task.\n\nPlugin full path: `com.github.stephenott.camunda.tasks.forms.command.GetFormVariablesSecurityProcessEnginePlugin`\n\nThe plugin provides two types of variable security:\n\n1. `allowed-variables` : a comma separated list of variable names that can be accessed using the endpoint `GET /task/{id}/form-variables` or the java api (getFormVariables).\n1. `restricted-variables` : a comma separated list of variable names that cannot be accessed using the endpoint `GET /task/{id}/form-variables` or the java api (getFormVariables).\n\n`allowed-variables` is used to control the exact list of variables that can be accessed.  Any variables that are not part of this list will be removed from the result.  No error will be thrown.\n\n`restricted-variables` is used to control which variables cannot be accessed.  Any variables that are part of this will be removed from the result.  No error will be thrown.\n\nExample:\n\n![allowed-variables](./doc/ut-allowed-variables.png)\n\n![restricted-variables](./doc/ut-restricted-variables.png)\n\n ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenott%2Fcamunda-formio-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephenott%2Fcamunda-formio-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenott%2Fcamunda-formio-plugin/lists"}