Migrate from Bonita V6 to Bonita V7.8 or later using "redirect to URL" in web forms

[anthony.birembaut]

Forms to be used with Bonita 6.x for process instantiation and in human tasks that were designed externally, instead of using the embedded form editor in Bonita Studio, used a “redirect to URL” option. If you are using “redirect to URL” with externalized forms developed in another technology, it is still possible to migrate and then adapt your forms progressively.

Why is this action necessary?

In Bonita 7.0, the approach using _process contract_ and task contract was introduced. This decouples the UI from the process design model, and makes forms development smoother. The forms module used in versions 6.x of Bonita was still supported for many years, but it has now been fully removed from the platform in more recent versions.

As a result, if you still have Bonita processes running with 6.x forms, it is necessary to update those processes to define contracts and replace those forms in order to migrate to version 7.8 (or later) of Bonita.

An alternative to the “migrate all at once” approach is possible, though. You can migrate your processes, and then adapt your forms progressively to take advantage of the contracts feature in Bonita.

Here is one way to achieve that.

Implement and deploy a proxy

The first challenge you face in this situation is the need to redirect from Bonita to the external forms, and then back when the external form is submitted. The services and URLs that were used to do that are no longer available after Bonita v 7.7.5. So one way of making that work with Bonita 7.8 or later is to implement a kind of proxy that will redirect and start the process or execute the task for those requests.

You can find an example of proxy implementation that does this action in this Github repository.

This example works with 2 classes:

• The class URLRewritter is a servlet which, upon request, will look in the task (whose Id is provided in the request) for a variable named “externalFormURL” and redirect to the URL provided in this variable value.
• The class TaskSubmitterProxy is a servlet that will simulate the behavior of the Bonita 6.x forms submitURL endpoint, and execute the task using the task contract API. The values of the forms passed in the request are converted to contract inputs by this servlet.

Note 1: As this example is a proof of concept, only a few types of inputs are supported by this servlet (string, boolean, integer and long). Note 2: To support an external form for process instantiation, the same mechanism needs to be implemented with a process definition ID and a process contract.

These servlets should be built and packaged as a jar file and placed in bonita.war/WEB-INF/lib, and the web.xml file needs to be updated to declare them. For example:

<!-- V6 Forms Proxy to allow progressive migration -->

<servlet>

<servlet-name>v6FormUrlRewriterProxyServlet</servlet-name>

<servlet-class>com.bonitasoft.v6form.migration.experimental.filter.URLRewriter</servlet-class> </servlet>

<servlet-mapping>

<servlet-name>v6FormUrlRewriterProxyServlet</servlet-name>

<url-pattern>/forms/v6/proxy/*</url-pattern>

</servlet-mapping>

<servlet>

<servlet-name>v6FormTaskSubmitterProxyServlet</servlet-name>

<servlet-class>com.bonitasoft.v6form.migration.experimental.TaskSubmitterProxy</servlet-class> </servlet>

<servlet-mapping>

<servlet-name>v6FormTaskSubmitterProxyServlet</servlet-name>

<url-pattern>/forms/v6/proxySubmitter/*</url-pattern> </servlet-mapping>

<!-- (End) V6 Forms Proxy -->

Update the process to define the contracts

Next, update the process definitions to take, as contract, the fields that were sent back by external forms. This means updating the processes in a Bonita Studio version that matches the current version on which your production process is running. On each pool and human task that uses the “redirect to URL” option:

1. For each variable assignation defined in the section 6.x Application > Pageflow, as in

<variable_name>Takes value of field__<input passed_as_url_parameter="">, define a contract input of type TEXT named “_<input passed_as_url_parameter="">_Input” in the Execution > Contract section.</variable_name>

1. For human tasks in the Execution > Operation section, for each contract input, add a new operation such as <variable_name>Takes value of _<input passed_as_url_parameter="">_Input.</variable_name>

1. For the pool, update the initial value of each variable to set it with _<input passed_as_url_parameter="">_Input.

For example, with a configuration in Bonita 6.x Application > Pageflow like this:

• validAsText (data) Takes value of field_valid
• requestDescription Takes value of field_description

you need to define:

1. in Execution > Contract
   • validInput TEXT
   • descriptionInput TEXT

1. In Execution > Operations
   • validAsText Takes value of validInput
   • requestDescription Takes value of descriptionInput

1. Update the process to define the forms URLs

On each pool and human task that uses the “redirect to URL” option, change the form type to stop using Bonita 6.x forms technology:

1. In the section Execution > Form
   • select External URL
   • Set the URL to: /bonita/forms/v6/proxy (replace “bonita” with the name of the webapp (.war) if you renamed it)Whatever the URL you used to redirect, it will now point to the proxy.

1. In the section Data
   • For human tasks, declare a local variable, named externalFormURL of type Text, whose content is a groovy expression that returns the URL of the external form to display for the task.
   • For the pool, declare a pool variable, named externalFormURL of type Text, whose content is a groovy expression that returns the URL of the external form to display for the instantiation of the process.

At runtime, the parameters id (task id) and submitURL (URL used by your external form to submit the task) will be added by the proxy to those URLs. This replicates the behavior of the Bonita 6.x redirect URL feature.

2. Deploy the new version of the process

Now that the process has been updated successfully and no longer uses Bonita 6.x technology, it is ready to be deployed as a new version. To do that:

• In Bonita Studio
  • update the version of the process (on the pool)
  • build the process (.bar)
• In the production environment
  • deploy the process
  • disable the previous version of the process

If there are still running instances of the previous version of the process, you need to wait for them to be finished, or delete them if they don’t need to complete, or the migration tool will refuse to execute the migration steps to Bonita 7.8.0.

Now you are ready to update to one of the versions of Bonita from v7.8 or later.

What's next?

When you have migrated your processes to a new version of the Bonita platform, you will be able to take advantage of all its advanced capabilities, and for Bonita Enterprise users, also access support for the currently supported Bonita versions. But another key advantage of this migration is that you can now progressively update your forms, or redesign them with Bonita UI Designer, to fully leverage the contract API and eventually get rid of these proxy servlets.