How to Migrate Your Camunda Modeler Plugins to Work with Camunda Modeler 5.0

With the upcoming Camunda Modeler 5.0 release in April 2022, the entire user experience of the Modeler application will encounter significant updates. To find out more about how these updates will improve the user experience, review the blog post on introducing the new Camunda Modeler 5 features. 

While reading this blog post, learn how you, as a Camunda Modeler plugin maintainer, can update your plugin to benefit from the new features and make your plugin compatible with Camunda Modeler 5 and subsequent versions. Follow along with this guide for using the Camunda Modeler 5.0.0-alpha.0 release.

Migration Overview

When migrating your Camunda Modeler plugin, there are four steps you must take:

1. Update plugin helper version
2. Update plugin slot
3. Use overlay menus instead of modal menus
4. Update your plugin documentation and compatibility information

These steps are described below in detail. As a reference, we will use the Excel Import Plugin, the Autosave Plugin, and more specifically, the pull requests (Migrate Excel Import Plugin, Migrate Autosave Plugin) which were used to migrate these two plugins.

If you also extended the bpmn-js properties panel as part of your Camunda Modeler plugin, refer to this example repository, or review pull request example #172 and example #9. Both of these examples update an existing properties panel extension. These resources will help you understand how to use the new features, and how to be compatible with the updated properties-panel v1.0.0.

Update Plugin Helper version

The Camunda Modeler Plugin Helpers provide helper functions, which you might need to bundle your Camunda Modeler plugin. For example, they expose the Camunda Modeler user interface (UI) components, which you potentially might want to reuse to implement graphical interfaces as part of your plugin.

As a baseline for the plugin migration,  adjust the camunda-modeler-plugin-helpers dependency of your plugin to the latest version by using the code snippet below, for example:

npm install --save-dev camunda-modeler-plugin-helpers@^5.0.0-alpha.0

In our reference migration pull requests, view these updates Migrate plugin #68 and Migrate plugin #79.

Update Plugin Slot

Plugin slots can be used to display plugin UI controls in Camunda Modeler at different locations. These can then be used for user interaction.

Note that with Camunda Modeler 5.0 and beyond, there’ll no longer be a toolbar. You can now add UI controls in three different locations:

• In the status bar:
  • slot=”status-bar__file”
  • slot=”status-bar__app”
• In the tab actions:
  • slot=”tab-actions”

In addition to the slot attribute, you can also specify a group attribute, which allows you to ensure that plugins belonging to each other will appear next to each other (i.e., in the same group).

In our reference migration pull requests, find these updates in Migrate plugin #79 and Migrate plugin #68. The following screenshot shows results for all of the available options:

Use Overlay Menus Instead of Modal Menus

Starting with Camunda Modeler 5, we encourage you to use overlay menus instead of modal menus. Overlay menus provide the respective UI controls in a lightweight overlay, directly next to the respective icon that initiated the opening.

You can use overlays by importing the Overlay component (instead of the old Modal component). See an example in Migrate plugin #68. 

Within the ConfigOverlay, you can use the following to arrange the respective UI elements in an organized way:

• Section.Header
• Section.Body
• Section.Actions

In our reference migration pull requests, find these updates in Migrate plugin #68 and Migrate plugin #79.

Update Your Plugin Documentation and Compatibility Info

It’s important that your plugin users understand which version of Camunda Modeler your plugin is compatible with. To ensure this, we recommend adding a basic hint in the README.md file of your plugin repository. 

For example, this can be done by adding a basic badge like this:

In our reference migration pull requests, find these updates in Migrate plugin #79 and Migrate plugin #68.

Additional Resources

To learn more about extending Camunda Modeler, review the following resources:

• Camunda Modeler Plugin Starter Project 
• Camunda Modeler Plugin Examples
• Camunda Modeler Plugins Documentation
• Camunda Modeler 5.0.0-alpha.0 Download