https://github.com/stephenott/camunda-formio-plugin
Integration for Drag and Drop Formio Form Builder and Renderer with Camunda Tasklist App
https://github.com/stephenott/camunda-formio-plugin
camunda formio
Last synced: over 1 year ago
JSON representation
Integration for Drag and Drop Formio Form Builder and Renderer with Camunda Tasklist App
- Host: GitHub
- URL: https://github.com/stephenott/camunda-formio-plugin
- Owner: StephenOTT
- License: mit
- Created: 2020-08-24T21:45:49.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-08-26T21:16:17.000Z (almost 5 years ago)
- Last Synced: 2025-02-27T05:56:29.253Z (over 1 year ago)
- Topics: camunda, formio
- Language: Kotlin
- Homepage:
- Size: 3.69 MB
- Stars: 65
- Watchers: 10
- Forks: 26
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Camunda Formio Plugin
Provides client-side and server-side integration for using Camunda Embedded Forms with Formio Forms.
## What does it do?
Allows you to configure *start-event* forms and *user-task* forms with a `formkey` that will load formio forms in Camunda Tasklist webapp.
## How do I set it up?!
Configuring Formio for a Start Form:
Configuring Formio for User Tasks:
If you want to add server side validation, you add a Validation Constraint with the name `formio`. See the Server Validation
section for more details.
## Installation
### Camunda SpringBoot Deployment
See the `springboot` folder for a example of the deployment
### Typical Camunda Deployment
See the `docker` folder for an example of the deployment using the Camunda Tomcat distribution
## Building Forms:
Local Builder: Deploy Webapp and access a local builder at: `http://..../forms/builder.html`
Hosted Builder: [https://formio.github.io/formio.js/app/builder](https://formio.github.io/formio.js/app/builder)
## Configure the BPMN
Example of Configuring a Start Form:
`embedded:/forms/formio.html?deployment=MyStartForm.json&var=submission&transient=true`
In 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.
We use the `var` parameter to direct the name of the process variable that will be created to store the form submission.
We use the `transient` parameter to direct the process variable holding the form submission get created as a
[transient variable](https://docs.camunda.org/manual/7.13/user-guide/process-engine/variables/#transient-variables)
```xml
Flow_1ax32ut
```
Example of Configuring a User Task:
`embedded:/forms/formio.html?deployment=MyUT1.json&var=subWithServerValidation
```xml
Flow_0069xxd
Flow_18xtnen
```
### Configuration Options:
The following are the parameters that can be passed in the `formKey`:
| Parameter | Required? | Default | Description |
|---------------|-------------------|--------------|-----------------------|
|deployment= | Yes or use path= | - | The .json file name in the deployment created through the API. |
|path= | Yes or use deployment= | - | The file system path to the .json file. **Must start with a `/`** |
|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. |
|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.|
Examples:
1. `embedded:/forms/formio.html?deployment=MyUT1.json?transient=true&var=myCustomSubmission`
1. `embedded:/forms/formio.html?deployment=MyUT1.json?var=UT1-Submission`
1. `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 `/`**)
### Configuration through Camunda Extension Properties
If you enable the `FormioParseListenerProcessEnginePlugin`, you can configure through Extension Properties rather than
manually creating the formKey:
The same configuration options used in the formKey are used in the extension properties.
Each extension property has a prefix of `formio_`.
For Server Validation you add a **name:** `formio_validation`, **value:** `true`.
## Submission Storage
When a successful submission occurs, a `json` variable will be created as a Process Instance Variable.
Use [Camunda SPIN library](https://docs.camunda.org/manual/7.13/reference/spin/json/) to access the json variable properties.
Example in a gateway expression: `${someSubmission.prop('data').prop('someFieldKey').value()}`
### Resolving User Task `taskId` to more meaningful values
Very often the taskID (which is typically a UUID) will not be very meaningful. If you require more meaningful variable names
consider 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).
## Trigger 'BPMN Errors'
Support is provided to trigger interrupting BPMN Errors:
Trigger a formio event with the name `bpmn-error` (typically with a button: set the button event to `bpmn-error`)
The default error code is `default`. To set a custom error code, create a variable in the formio submission with the key
`_errorCode`. Typical use cases are to use a `text` component or a `hidden` component.
No error message is submitted by default. To set a custom error message, create a variable in the formio submission with the key
`_errorMessage`. Typical use cases are to use a `text` component or a `hidden` component.
**The submission variable created through the bpmn-error cannot be validated using the formio server validator: this is a limitation in Camunda**
## Trigger 'BPMN Escalations'
Support is provided to trigger interrupting and non-interrupting BPMN Escalations. Note that Camunda's form API does not
make a distinction between interrupting and non-interrupting escalation events and therefore some best practices are implemented:
The escalation code is `default`. To set a custom escalation code, create a variable in the formio submission with the key
`_escalationCode`. Typical use cases are to use a `text` component or a `hidden` component.
**The submission variable created through the bpmn-escalation cannot be validated using the formio server validator: this is a limitation in Camunda**
### Interrupting BPMN Escalations
To trigger BPMN Escalation that is designed to be used with a interrupting BPMN Escalation boundary event:
Trigger a formio event with the name `bpmn-escalation` (typically with a button: set the button event to `bpmn-escalaton`)
### Non-Interrupting BPMN Escalations
To trigger BPMN Escalation that is designed to be used with a non-interrupting BPMN Escalation boundary event:
Trigger a formio event with the name `bpmn-escalation-noninterrupt` (typically with a button: set the button event to `bpmn-escalaton-noninterrupt`)
A 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`.
The suffix is used to ensure if/when the user task is normally completed, the submission variable created through the
user task completion does not overwrite the submission variable created through escalation.
## Deploying your Forms
### REST API Form Deployment
Forms can be deployed through the REST API. The form JSON must be part of the same deployment as the BPMN.
If changes need to be made to the form, you must deploy a new .json file along with the BPMN.
An example of using Postman to deploy:
When using REST API Form deployments, use the `deployment` parameter in the form key such as:
`embedded:/forms/formio.html?deployment=MyUT1.json`
### File System Forms Deployment (or other URLs)
Forms can be deployed on the file system and made available to the web application. The common way to do this is
through `src/main/webapp/forms` (or whatever folder you like within `webapp`).
If you want to make changes to the JSON, you can modify the JSON file without having to make a new BPMN deployment.
If you do not want to use the file system, you can deploy to another URL within the same domain as Camunda Webapps. Then
you can set your `formKey` to something like: `embedded:/forms/formio.html?deployment=http://example.com/forms/MyUT1.json`
The benefit of having your form/JSON outside of the BPMN deployment is you are not required to redeploy the BPMN each
time you make changes to the form, but in many use cases you will want to tie your BPMN and forms together
within the same deployment for versioning purposes.
## Example Submission
```json
{
"data": {
"firstName": "SomeFirstName",
"lastName": "SomeLastName",
"email": "",
"phoneNumber": {
"value": "",
"maskName": "US"
},
"select": [],
"address": {},
"dueDate": "2020-08-18T12:00:00-04:00",
"birthdate": "00/00/0000",
"submit": false
},
"metadata": {
"timezone": "America/Montreal",
"offset": -240,
"origin": "http://localhost:8080",
"referrer": "http://localhost:8080/camunda/app/welcome/default/",
"browserName": "Netscape",
"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",
"pathName": "/camunda/app/tasklist/default/",
"onLine": true
},
"state": "submitted"
}
```
## Variable Fetching in Formio
Formio will fetch variables based on configurations in the component configuration.
Under the API tab of a component create a custom property with the following format:
**key:** `fetchVariable` **value:** `variableName` (recommended not to use spaces in variable names)
Once you get your variable, use the Default Value Population feature to populate your field with the data returned from the variable fetch.
## Default Value Population
Make sure to fetch the variables using the `fetchVariable` configuration.
### Simple Configuration
The simple configuration provides a rapid setup option allowing most common use case access to variables.
In the form component's API tab, set a custom property with key: `camVariableName` and the value being the dot notation path.
Example:
1. Given a simple camunda string variable named "firstName", the key-value configuration would be:
`camVariableName: firstName`
1. Given a previous formio form submission which is saved as a Camunda Json variable, the key-value configuration would be:
`camVariableName: somePreviousSubmission.data.firstName`
If 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:
Key:`stringify`
Value: `true` (If you are manipulating the raw json, this should be an equivalent of `"true"`)
### Advanced Configuration
The advanced configuration provides javascript access to the variables, allowing complex configurations
such as variable manipulation, merging, trim, etc.
Use the Custom Default Value Javascript feature in Formio to parse the returned variables.
Variables get stored in `$scope.camForm.formioVariables`
In the Custom Default Value configuration you can use the following to access the object of variables:
```js
let variables = angular.element('#task-form-formio').scope().camForm.formioVariables
```
Variables names are the keys.
If the variable is type `Json` it is automatically available as a JS Object.
### Example
Set the default value of a Text field "First Name" with the `firstName` property that was submitted in the Start Form (a formio form submission)
In the First Name field's Custom Default Value configuration use the following:
```js
let variables = angular.element('#task-form-formio').scope().camForm.formioVariables
value = variables.postProcessed_submission.data.firstName
```
The code `angular.element('#task-form-formio').scope()` is re-capturing the Camunda task form angular scope from the `