The Form Generation Tool generates the web forms needed for the execution of processes (workflows).

Tool Installation

Please download Form Generation Tool zip file available at https://www.ibm.com/support/pages/node/7151078. The zip file contains three binary files of the same tool for multiple operating systems. Please choose the binary file according your operating system and extract it into desired destination. Then please make sure the binary file is executable.

Make sure the binary file is executable - linux example
chmod a+x form-generation-cli-linux

Form Generation

You can generate forms using the Form Generation Tool for any Workflow that requires input data. However, for this documentation, we will use existing Apache Kie jbpm-compact-architecture-example project available at https://www.ibm.com/support/pages/node/7151078. You will find more example projects in this zip file, however jbpm-compact-architecture-example requires the minimal effort to see forms in the action. Or you can use your own project.

Browsing the linked examples, you may notice the projects use Maven. So when Maven builds an Apache Kie project, Kie generates JSON schemas to represent the data models for both Workflows and User Tasks. The Form Generation Tool then locates those JSON Schemas in the project and, taking advantage of the Uniforms APIs, processes them and generates static forms as a resource in the project src/main/resources/forms folder.

Generation Prerequisities

  • Make sure your Apache Kie project has been compiled, otherwise the CLI won’t be able to find all the form schemas.

Once the Form Generation Tool binary file is extracted and executable you can start the Form Generation Tool from your command line.

Start the binary file - linux example
./form-generation-cli-linux

This will start a wizard to help you generate the forms:

First, set the path to your Apache Kie project. We will use jbpm-compact-architecture-example.

Kogito Form Generation CLI
===========================

This tool will help you generate forms for the Processes and User Tasks in your Kogito Projects.
The tool will search for the User Tasks JSON schemas generated in your project, so make sure the project is build.
The generated forms will be stored as resources in your project (in src/main/resources/forms folder).

? Type your Kogito Project path:---> /path/to/my/projects/jbpm-compact-architecture-example <---

Select one of the available Form types (Patternfly or Bootstrap 4). We will use Bootstrap 4. Use the arrow keys to change the selection.

? Select the Form type:
  patternfly
❯ bootstrap

Confirm Selection, type Y, to start the Form Generation process.

Current selection:
Project path: /path/to/my/projects/jbpm-compact-architecture-example
Form type: bootstrap

? Do you want to continue? (Y/n) Y
Note

Currently there is an issue for the Array type. You will probably spot similar warning between log messages. This is a known and reported issue.

Unsupported field type: Array

Once the generation is done, browse to /path/to/my/projects/jbpm-compact-architecture-example/src/main/resources/forms folder.

ls /path/to/my/projects/jbpm-compact-architecture-example/src/main/resources/forms/

hiring.config
hiring.html
hiring_HRInterview.config
hiring_HRInterview.html
hiring_ITInterview.config
hiring_ITInterview.html

Form Type

Form Generation Tool supports two form types:

  • patternfly: This type generates .tsx files using the patternfly library for styling the forms.

  • bootstrap: This type generates .html files using the bootstrap library for styling the forms.

Furthermore, according to the file name extension, we can say that .tsx files are React forms and .html files are plain html forms.

Form Config

Each generated form, both patternfly and bootstrap, has a corresponding .config file. Such config files contain schema information about the object that the form is generated for. Furthermore, the goal of this .config file is to load additional scripts and styles.

For the patternfly forms, by default, no additional scripts or styles are loaded.

For the bootstrap forms, by default, we load bootstrap@4.0.0 styles and jquery@3.2.1 scripts.

Form DevUI

For Quarkus-based Apache Kie projects, you can use and test them by using the jBPM Quarkus DevUI extension.

To do so, just add the following dependency in your project pom.xml:

<dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-quarkus-devui</artifactId>
    <version>9.1.0-ibm-0001</version>
</dependency>
Note
 This is already done for jbpm-compact-architecture-example.

And start the project in Dev mode with the command:

mvn clean -Pdevelopment quarkus:dev

Then, in your browser, navigate to:

http://localhost:8080/q/dev-ui/extensions
Note

Currently jbpm-compact-architecture-example contains one wrong dependency that needs to be removed. Please remove org.jbpm:jbpm-quarkus-devui-bom from the project pom.xml. For more information, see Known limitations.

On the displayed page, find this card and click Forms.

jBPM Quarkus Dev UI Card
Figure 1. jBPM Quarkus Dev UI Card

Now we should see a list of all available forms that we listed via the command line earlier in this documentation.

Forms list
Figure 2. Forms list

Then, if we choose any form, we will have an option to adjust it. We will continue with the hiring form. Please click on it to open it. Now we see two tabs: Source and Connections.

Source

The Source tab displays the form source code on the left side, while on the right side there is the form UI.

Hiring form
Figure 3. Hiring form

Let’s remove this piece of the source code

<div class="alert alert-warning" role="alert">
  <h4 class="alert-heading">Unsupported field type: Array</h4>
  <p>Cannot find form control for property <code>candidateData.skills</code> with type <code>Array</code>.</p>
  <hr />
  <p class="mb-0">
    Some complex property types, such as <code>Array</code> aren't yet supported, however, you can still write your own component into
    the form and manually bind it.
  </p>
</div>

and click the Execute form button. We will immediately see the result.

Updated hiring form
Figure 4. Updated hiring form

The same functionality is available for the React forms.

Connections

The Connections tab displays loaded scripts and styles.

Important
 This tab is for loading external resources only.

We can try to load newer bootstrap@5.1.3 version.

To do it, we need to update the hiring.config from:

{
  "scripts": {
    "jquery.js": "https://code.jquery.com/jquery-3.2.1.slim.min.js",
    "bootstrap.bundle.min.js": "https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.bundle.min.js"
  },
  "styles": {
    "bootstrap.min.css": "https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
  }
}

to:

{
  "scripts": {
    "jquery.js": "https://code.jquery.com/jquery-3.2.1.slim.min.js",
    "bootstrap.bundle.min.js": "https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"
  },
  "styles": {
    "bootstrap.min.css": "https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css"
  }
}

After updating hiring.config to use bootstrap@5.1.3 instead of bootstrap@4.0.0, the form UI should be more compact, using smaller visual gaps between elements.