Join our largest event of the year | CamundaCon 2022 October 5-6

Icon Close

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.

Labelled UI controls in Camunda Modeler

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:

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.

modal and overlay menus

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 file of your plugin repository. 

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

Camunda Modeler 5.0+ badge

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:

  • Feel Example Flow in Camunda 8

    FEEL more confident transforming data

    FEEL (Friendly Enough Expression Language) was created by the Object Management Group (OMG) “as part of the DMN standard”. Its goal is to be easy to understand, and at the same time, be full-featured enough to handle decision tables and literal expressions. When business and IT often work together on complex projects, writing expressions in a (relatively) accessible way reduces miscommunications and helps align teams. Camunda uses FEEL to map and transform business process data dynamically. For example, a loan application process pulls a credit score from an API call into a decision table. The decision table automates the next step of the process depending on the rules in the table. The data from the decision automation can then be...

    Read more
  • Workflow diagram and pattern examples using BPMN...

    There are multiple angles to look at workflows one of which is patterns. The Workflow Patterns initiative differentiates between control, data, and resource perspectives. They are not just focusing on the modeling language as such but have workflow systems in mind too. It’s valuable to have a closer look at those patterns and discuss which parts of it can be shown and even automated in BPMN, and which parts are taken care of in the technical implementation. I have seen BPMN diagrams that try to include every aspect in the diagram itself. This often leads to overloaded BPMN models with a lack of clear transparency of the business flow. Therefore, it is important to focus on all aspects of workflow...

    Read more
  • Title slide that reads "Camunda Automation Platform 7.18.0-alpha5 Released"

    Camunda Automation Platform 7.18.0-alpha5 Released

    We are pleased to announce the next alpha release of Camunda Platform Runtime 7.18. This release features the following improvements: Logging: Engine name parameter in mapped diagnostic context Exception Error Codes now available in the External Task Clients IBM WebSphere Application Server Liberty support New Supported Environments 7 Bug Fixes You can download Camunda for free or run it with Docker. For a complete list of all improvements, take a look at the release notes. Please also see the list of known issues. If you want to dig in deeper, you can find the source code on GitHub. Logging: Engine Name Parameter in Mapped Diagnostic Context As an addition to the already present list of parameters for the logging context,...

    Read more

Ready to get started?

Still have questions?