New Design Migration Guide

v3.14.0+

As of version 3.14.0, the Flowable product line comes with a new Design application, featuring a

• Redesigned User Interface, built upon a modern, performant and extensible technological foundation.
• Revised and updated REST API, using similar concepts and paradigms as found in other Flowable API's.

To facilitate differentiation between the previous version and the new one, we refer to the two versions as the "Angular-based Design" and the "React-based Design." These labels indicate the frontend technology on which each version is built. Going forward, all new development will be centered around the React-based Design application, as it offers the best features and performance. The Angular-based Design application is included in 3.14.0 to make the transition to the new Design application easier and to prevent any issues in the new Design application blocking any project timeline requirements.

Full backwards compatibility for apps and models was a crucial driver in the development of this new Design application, so the amount of migration needed should be non-existant when it comes to data and models.

The parts were migration potentially might be needed are technical in nature, related to advanced use cases and are described below.

No Migration Needed

Following sections reiterate the point made above: when it comes to existing apps and models, no migration is needed.

Database

In case you have an existing Design database containing models, then the new React Design application can be configured against this database exactly the same as before, and it will be upgraded automatically on first reboot.

As with any version upgrade, we advise to make a backup of the existing Design database before doing this.

The tenant concept was reworked in the new Flowable Design and enhanced with workspaces. More information can be found in the General Design Concepts. Due to the way tenants were used in the Angular-based Design, the default migration is going to create a workspace for all the unique tenant ids of all models and tenants in the database. All the workspaces will then belong to the default tenant, and all the users are going to be moved to the default tenant.

Starting from v3.16.3+ there is a property flowable.design.tenant-workspace-upgrade-strategy which when set to multi_tenant will create a new tenant for all the unique tenant ids of all models and users in the database. Every tenant will have one workspace with the key default, all the users are going to stay in their respective tenants, and admin users will no longer be able to view models between other tenants.

Apps

An app from the Angular-based Design application can be exported to and imported in the new React-based Design application.

Exporting an app from the new React-based Design application and importing it in the Angular-based Design application of the same product version is also supported (e.g. exporting an app in React-based Design 3.14.0 and import it in Angular-based Design 3.14).

Important to note here is that the new Design application has a single type of app when it comes to exporting. It's no longer necessary to make a distinction between the 'Design app' and the 'deployable app' like in the Angular-based Design.

Migration Needed

Following sections describe those changes where migration is needed.

Configuration Properties

Any properties with the prefix

flowable.modeler.app

need to be replaced with

flowable.design

For examples

flowable.modeler.app.deployment-api-url=http://my-server/flowable-work/app-api

now needs to be

flowable.design.deployment-api-url=http://my-server/flowable-work/app-api

info

There is one exception to this rule. The property flowable.modeler.app.security.type is now named application.design.security.type. This property is only available for the out-of-the-box Flowable images (e.g. war files or docker image). For a custom project build it is required to create an appropriate security configuration with OAuth 2.0.

Potential Migration Needed

Following sections describe advanced use cases that need migration, in case the particular feature or hookpoint was used. Review these carefully and ensure yourself whether or not you are using these.

Custom Palettes

Custom Design Palettes are supported in the new Design application in a similar way as before and as described in the custom palette documentation.

In general, XML palettes are still supported, but new features won't be added to them. It is advised to migrate these palettes to the JSON palette format.

When it comes to the JSON palette format, there are a few minor changes that need to be applied when used with the new Design application.

1. When using patchPalettes to enhance an existing palette, the IDs of those palettes have changed. The supported palettes that can now be patched out of the box depend on the type of product that the models are intended to be published to:

For BPMN models, which before had the flowable-process-palette ID, now one the following needs to be used:

• flowable-core-process-palette
• flowable-work-process-palette
• flowable-engage-process-palette

For CMMN models, which before had the flowable-case-palette ID, now one the following needs to be used:

• flowable-core-case-palette
• flowable-work-case-palette
• flowable-engage-case-palette

For Form models, which before had the flowable-form-palette ID, now one the following needs to be used:

• flowable-core-form-palette
• flowable-work-form-palette
• flowable-engage-form-palette

For Page models, which before had the flowable-page-palette ID, now one the following needs to be used:

• flowable-work-page-palette
• flowable-engage-page-palette

For DMN DRD models, which before had the flowable-drd-palette ID, now one the following needs to be used:

• flowable-core-drd-palette
• flowable-work-drd-palette
• flowable-engage-drd-palette

2. Properties now need a category to be visible, for example:

{
  "id": "customSetting",
  "type": "SimpleTextExpression",
  "category": "commonDetails",
  "index": 0
},

3. The edoras category was replaced with the commonDetails category.

   These are the categories already defined in the core process palette:

   • commonDetails
   • assignment
   • otherSettings
   • formMapping
   • formValidation
   • caseView
   • expose
   • loop
   • variableAggregation
   • details
   • execution
   • common
   • mail
   • listeners
   • others
   • format

   These are the categories already defined in the core case palette:

   • commonDetails
   • assignment
   • otherSettings
   • commonMilestone
   • commonStage
   • formMapping
   • formOptions
   • caseView
   • details
   • control
   • execution
   • otherExecution
   • advanced
   • required
   • activation
   • activationStartForm
   • reactivation
   • itemreactivation
   • others
   • listeners
   • expose
   • format
   • mail

4. Every category needs its own definition. If a property doesn't appear in the side panel, make sure the used category is defined at the palette sectionCategories:

"sectionCategories": [
  {
    "id": "commonDetails",
    "index": 10
  },
  ...
]

5. Icons are now defined using a presentationId, which references a presentation on the root level (see example below).

6. Properties can now have an editCategory to group them together in the popup shown when the property is clicked.

7. If a custom palette contains removeStencils the removal will happen in the context of the palette definition it is placed in. Said differently: if a custom palette depends on a palette that has a removeStencils part, that custom palette cannot depend anymore on the removed stencil palette item. Before, this was possible, as removals were only applied at the end of palette resolving. Concretely this means that if building a form palette extension, you can't depend on base-text anymore (as it's part of the removeStencils), but need to use the cloud-text id, which has base-text as superId and effectively would lead to the same behavior as before.

v3.15.6+

8. The behaviour type values have changed. The values should be one of the supported runtime types. This can be used to render a component in Design in a certain way without the need to provide the custom component for it. If you want to provide a container like functionality you'll have to use one of the existing types. The available types are:

• Containers
  • accordion
  • buttonGroup
  • outcomeButtonGroup
  • panel
  • tabs
  • wizard
• Simple types
  • alert
  • attachment
  • boolean
  • dataTable
  • date
  • hline
  • htmlComponent
  • iFrame
  • image
  • label
  • link
  • list
  • number
  • password
  • pdfViewer
  • radio
  • richText
  • select
  • stringList
  • subform
  • switcher
  • text
  • textarea
  • upload
• Buttons
  • linkButton
  • restButton
  • scriptButton
  • outcomeButton
  • workAction
  • workInvokeService
  • createInstanceButton

note

When using behaviourType only the look and feel in Design will look the same, the properties are not automatically inherited.

Given the above, here's an example of a simple custom palette that enhances the default Work BPMN palette with a new service task in its own palette group that calls a custom backend service. It has one extra property and hides a few default ones, and removes the normal ServiceTask:

{
  "Palette-Id": "my-custom-bpmn-palette",
  "title": "Custom BPMN palette",
  "patchPalettes": ["flowable-work-process-palette"],
  "resourceBundles": [
    "com/flowable/config/custom/palette/i18n/custom-bpmn"
  ],
  "presentations": [
    {
      "id": "presentation.custom",
      "icon": "component-presentations/palette-icons/my-icon.png",
      "bigIcon": "component-presentations/palette-icons/my-icon.svg"
    }
  ],
  "stencils": [
    {
      "id": "my-custom-service-task",
      "name": "myCustomServiceTask",
      "presentationId": "presentation.custom",
      "superId": "ServiceTask",
      "groups": [
        "flowable-activities",
        "flowable-quick-draw",
        "custom-palette"
      ],
      "index": 0,
      "properties": [
        {
          "id": "expression",
          "value": "${myService.myMethod()}"
        },
        {
          "id": "customSetting",
          "type": "SimpleTextExpression",
          "category": "commonDetails",
          "editCategory": "myCustomProperties",
          "index": 0
        },
        {
          "id": "class",
          "visible": false
        },
        {
          "id": "delegateExpression",
          "visible": false
        }
      ]
    }
  ],
  "groups": {
    "custom-palette": {
      "index": 1,
      "basePaletteItemId": "my-custom-service-task",
      "visibleInViews": [
        "icon",
        "quick",
        "list"
      ]
    }
  },
  "removeStencils": ["ServiceTask"]
}

Note that for custom groups, as shown above, list needs to be added such that it is visible in the palette.

Project Dependencies

To be able to support two Design applications, the Angular-based Design application uses a new group id com.flowable.design.angular and all Maven or Gradle dependencies need to be updated to use this group id if you plan to keep using the Angular-based Design application.

In addition to the group id the artifact ids for the flowable-platform-palette and flowable-engage-palette use new artifact ids flowable-platform-palette-angular and flowable-engage-palette-angular respectively.

The new React-based Design application uses the com.flowable.design package.

PublishReleaseAppHandler

The com.flowable.design.service.editor.PublishReleaseAppHandler interfaces has been removed. It needs to be replaced with a Flowable event listener Spring bean listening to the APP_PUBLISHED event, for example:

public class CustomAppPublishListener extends AbstractFlowableEventListener {

    @Override
    public boolean isFailOnException() {
        return false;
    }
    
    @Override
    public Collection<? extends FlowableEventType> getTypes() {
        return Collections.singleton(DesignEventType.APP_PUBLISHED);
    }
    
    @Override
    public void onEvent(FlowableEvent event) {
        if (event instanceof AppPublishedEvent) {
            appPublished((AppPublishedEvent) event);
        }
    }
    
    protected void appPublished(AppPublishedEvent event) {
        // Write your custom logic with the event here
    }
}

REST APIs

Old Method	Old	New Method	New
GET	/api/editor/models	GET	/design-api/workspaces/{workspaceKey}/models
GET	/api/editor/models/{modelId}	GET	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}
GET	/api/editor/models/{modelId}/thumbnail	GET	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}/thumbnail
PUT	/api/editor/models/{modelId}	PUT	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}
DELETE	/api/editor/models/{modelId}	DELETE	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}
GET	/api/editor/models/{modelId}/editor/json	GET	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}?includeContent=true
POST	/api/editor/models/{modelId}/editor/json	PUT	/design-api/workspaces/{workspaceKey}/models/{modelType}/{modelKey}/content
GET	/api/editor/app-models/key/{appKey}/export	GET	/design-api/workspaces/{workspaceKey}/apps/{appKey}/export
POST	/api/editor/import-process-model	POST	/design-api/workspaces/{workspaceKey}/import-bpmn
POST	/api/editor/models	POST	/design-api/workspaces/{workspaceKey}/models

In all places workspaceKey is used, the value default can be used to be identical to the behavior of the Angular-based Design application.

We do advise to access models through their app instead of via the model key in the workspace, i.e. using /design-api/workspaces/{workspaceKey}/apps/{appKey}/models/{modelType}/{modelKey} (the /apps/{appKey} is not included in the table above).

See the Swagger documentation for more details.

Remote IDM Configuration

The properties for remote communication with Flowable Work / Engage / Orchestrate (e.g. to retrieve user or group information) have been changed:

Old property	New property
flowable.common.app.idm-url	flowable.design.remote.idm-url
flowable.common.app.idm-api-context-path	flowable.design.remote.idm-api-context-path
flowable.common.app.idm-admin.user	flowable.design.remote.authentication.user
flowable.common.app.idm-admin.password	flowable.design.remote.authentication.password
flowable.common.app.idm-admin.authentication-type	flowable.design.remote.authentication.type

DeploymentTenantProvider

The DeploymentTenantProvider interface has been moved to the com.flowable.design.engine.api.runtime package.

The interface has changed to provide access to the full model details being deployed and the configured tenant in the deployment servers.

HttpClientProvider

The com.flowable.design.service.http.HttpClientProvider interface has been removed.

There are alternative ways to customize the remote calls that should be done to Flowable Work:

• Provide custom RemoteHttpClientHttpRequestCustomizer that can modify the request, e.g. by adding a custom header.
• Provide a custom DesignRemoteHttpClientWebClientCustomizer that would customize the Spring WebClient used by Flowable.
• Provider a custom org.flowable.http.common.api.client.FlowableHttpClient Spring bean with your own implementation.