Skip to content

Home

Jump to bottom
Aaron Louie edited this page Feb 14, 2020 · 4 revisions

CR Connect Workflow Configurator

Workflow Configuration

User Experience (UX) and Usability Guidelines

Break down big, complicated User Tasks into smaller Sub-Processes.

  • People are easily overwhelmed when presented with too much complexity at once. If a User Task has too many form fields and hide/show logic in it, that's a sign you need to break it out into multiple User Tasks, encapsulated by a Sub-Process.
  • By using Sub-Processes to encapsulate complexity, we can present users with only the information they need to see to accomplish one small thing at a time.
  • With Sub-Processes, your diagrams will also be easier to read and share with others!

Limit the number of form fields on each form.

  • Humans are very bad at holding more than 7 things in their heads at once, so limit any single form in a single User Task to 5 (7 max) fields.
  • If a task requires capturing more than 7 fields, break up that task into either a linear or parallel set of User Tasks (see next point below).

Provide a mapping between the real world and process flows.

  • If User Tasks really can be done at the same time, use Parallel Gateways to allow users to jump between tasks. Limit the number of parallel User Tasks to 3 (5 max).
  • If some User Tasks MUST be done in order, represent those tasks as a linear sequence of tasks. Limit the number of sequential User Tasks to 3 (5 max).

Form Field Types in Camunda Modeler

By default, Camunda Modeler supports a very limited set of form field types:

  • string: Single line of text
  • boolean: Yes/No
  • long: Number
  • date: Date & Time
  • enum: Dropdown Box

To provide more complete support on the front end, we use the form field Property attributes.

You will need to add the following custom types (select custom type in the Type dropdown):

  • textarea: Multiple lines of text
  • file: Single file
  • files: Multiple files
  • tel: Phone number
  • email: Email address
  • url: Website address

Then to display each of the following types of form fields, set the type and, in some cases, add a custom property with the listed value.

Display Type Property > Id Property > Value
Text input box (single line) string n/a n/a
Number input box long n/a n/a
"Yes/No" radio buttons boolean n/a n/a
Date picker date n/a n/a
Dropdown box enum n/a n/a
Checkboxes enum enum_type checkbox
Radio buttons enum enum_type radio
Textarea (multi-line text) textarea (Custom Type) n/a n/a
Single File file (Custom Type) n/a n/a
Multiple Files files (Custom Type) n/a n/a
Telephone number tel (Custom Type) n/a n/a
Email address email (Custom Type) n/a n/a
Web address url (Custom Type) n/a n/a

Form Field Configuration

Hiding fields

Fields can be hidden and shown conditionally with a Javascript expression, which will be parsed on the front end by Formly. You can reference any other fields in the form using the prefix model in front of its Form Field ID. For example, if you have a boolean field with ID of hasUploadedFile, you can access its value with model.hasUploadedFile in the Formly expression.

Property > Id Property > Value (example)
hide_expression !(model.someBooleanFieldName && (model.enumFieldName === 'Other'))

Required fields

To make a field required by default, add the following Validation Constraint:

Constraint > Name Constraint > Config
required true

If a field needs to be filled out based on the value of some other field(s) in the form, you can use a Formly Javascript expression (see above).

Property > Id Property > Value (example)
required_expression !(model.someBooleanFieldName && (model.enumFieldName === 'Other'))

Help text

There are three places where help text will be displayed on the front end when the form is rendered:

  • Placeholder text: appears within the field if it is empty
  • Description text: appears below the field
  • Help dialog text: appears in a pop-up when the ? button next to the field is clicked. Markdown formatting code is supported for this field, but you will need to replace all line breaks with \n (for now).

To display each type of help text, add a custom property:

Type of help text Property > Id Property > Value (example)
Placeholder text placeholder Enter your email address here
Description text description Upload a digitally-signed PDF file that is no more than 1GB in size.
Placeholder text help # This is a large heading\n\nParagraph of text goes here.\n\nThe next paragraph goes here. You can even insert [links](https://sartography.com)!\n\nThis is a list:\n- Apples\n- Oranges\n- Bananas

Dynamic labels

If the text label of a field needs to change based on the value of some other field(s) in the form, you can use a Formly Javascript expression (see above). The example below uses a ternary (if/then) operator to display a different label if the field dogName is filled out.

Property > Id Property > Value (example)
label_expression !!model.dogName ? 'How old is ' + model.dogName + '?' : 'How old is your dog?'
Clone this wiki locally