Drupal Modeler API ready for testing

The Modeler API is a new module that has been created by the Drupal community to address the requirement of existing modules and ecosystems with complex configurations, providing modern and easy-to-use UIs for non-technical users so they can independently create, modify, and maintain their own sites. Examples of such ecosystems are ECA (Events, Conditions, Actions - Drupal's modern rules engine), AI Agents, and Migrations.

Current status

There are 4 modules involved that are ready for testing right now:

• Modeler API 1.0.0-alpha4
• ECA 3.0.0-alpha4
• BPMN.iO 3.0.0-alpha4
• AI Agents 1.1.x-dev

This combination of modules requires Drupal core 11.2 or later, so you should get started with the latest beta version, or maybe even a release candidate which may be available already by the time you're giving this a try.

Those modules are close to beta, but minor things still missing, which may slightly enhance some of the existing interfaces. However, we're planning to publish stable releases in the next couple of weeks. That's why we're asking you to give it a try and report back what you find.

How to test the Modeler API

Please install a Drupal 11.2 site with the modules mentioned above in the mentioned versions (or later).

Don't test with existing ECA models or AI Agents at this time. Just create new ones, we still need to provide the migration script to convert existing models to the enhanced structure. It's nothing major, but some things have been improved and will make future maintenance so much easier.

When you find issues, please report them in the issue queues of the respective module. If you're uncertain which one is causing the issue, simply go to the Modeler API, and we'll be triaging them afterwards. Of course, the more detail you can provide, the better. Stack traces, exported models (config entities), or even short video clips are extremely helpful at this stage.

What this means for the Modeler API

The Modeler API is the orchestration between model owners (ECA, Agents, Migration) and modelers (BPMN.iO, etc.). Model owners and modelers have no direct connection any longer, it all goes through the API. And that comes with its own settings page at /admin/config/workflow/modeler_api

There you'll find a field set for each combination of model owners and modelers, that lets you define how each of those combinations behave. Currently, there are 3 settings for each combination:

• Theme: this only comes with a default setting right now, but it prepares the system for customizations in the look and feel for the UI on each model owner
• Drupal Form API: yes, BPMN.iO now uses the Drupal Form API by default, which improves the user experience noticeably, and it allows us to build a lot more fancy features in the future
• Storage: the models are controlled by the model owner modules, but there is also the raw data from the modeler that goes with each of the models. The storage of that raw data is governed by the Modeler API, the model owner doesn't have to bother with that. And here you can choose whether the raw data shouldn't be stored at all, or as third-party settings in the model, or as a separate config entity.

For the testing exercise that we're currently interested in, especially the storage setting is important. Please try them all out. Here are a few notes about that:

• If raw data isn't stored, only the layout of the diagram will be lost, but that's technically not required. It may, however, matter to the user.
• If raw data is stored in a separate config entity, then the third-party setting of the model will contain an MD5 hash of that raw data so that the Modeler API can verify that the model data and the raw modeler data still match when the model gets re-opened for editing. If it doesn't, the raw data will be discarded and the layout re-build from scratch.
• If the raw data is stored with the model, then you'll find that in third-party settings. This will increase the storage size, but no other side effect is expected.

What this means for ECA

Actually, ECA isn't really affected much by this change. Only the ECA UI submodule got changed, and everything else is untouched. So, the processing of models hasn't changed at all. It's only about the interaction between ECA and the BPMN.iO modeler. However, don't forget to enable the ECA UI submodule, as this is required to interact with the Modeler API as the UI for ECA.

That said, we've removed a ton of code which wasn't related to the ECA processing. And that is fantastic news moving forward with ECA. But of course, all these statements need to be verified, and that's why testing them now is so important.

There is one new feature, among others, that's important in the context of AI Agents: There is a new "Tools" event. This lets you define a model that starts with such an event and gets exposed as a tool to AI Agents. That way, you can provide extra capabilities to agents without having to write PHP code at all. Using such tools requires you to also configure the input data that the agents needs to provide when utilizing such tools. That's currently done in a textarea by manually typing YAML format. We're planning to provide an easier to use widget for that soon, though. The documentation for that input data definition will be published separately in the next few days.

What this means for BPMN.iO

A lot, is the short answer. This modeler has been changed almost entirely. Not only have we removed the third-party property panel on the right, and replaced it with the Drupal Form API, we also re-arranged all the other things and prepared this UI for future improvements at a much higher pace than ever before.

For example, action items: the buttons have been reduced to what is essentially submitting stuff to the Drupal site, e.g. saving the model or exporting it as an archive or a recipe. All other action items got moved into the canvas, where they are small buttons in the bottom-left corner. Yes, they don't look pretty yet, and here we're calling for help: we need somebody to help us to get them right with icons and proper styling.

New action items are:

• Copy and Paste: not only can you copy and paste selected items in the canvas, this now also works between browser tabs so that you can copy components over to other models. This works by utilizing local storage of the browser.
• Information: this opens a configuration form to edit metadata of the current model, including the name, ID, version, documentation, tags, and changelogs.
• Layout: this item automatically lays out the current diagram beautifully.
• Mini-map: this opens a small panel that lets you navigate around the canvas, which is useful when you've zoomed into the canvas (can be done with ctrl-mouse-wheel). We should probably add action buttons for that as well!

In the tools' palette (top-left corner of the canvas) you find a new element which is called "Participant", also known as swim lanes. They allow you to group things together. That's only for visual purposes. And there is currently a limitation with that: those swim lanes are only stored in raw data, which means that they will be lost when not saving the raw data (see settings for the Modeler API above).

You'll find other new things as well, e.g. colour selection for elements, or sub-processes for AI Agents. But we probably let you discover some stuff yourself.

What this means for AI Agents

This framework fully replaces the complex setup form for agents. Using the circle as a starting element for an agent provides the config form for the agent's metadata. Followed by the rectangle elements, called actions in ECA, are tools being made available to that agent. And each tool can be selected and configured separately.

But there are also sub-agents: those are AI Agents themselves, but they can be made available, and even configured, as part of any other agent that should be allowed to use any other agent as a sub-agent. In BPMN.iO there is the sub-process element which represents a sub-agent. So you have your main agent starting with a circle and followed by tools. And then you can have any number of sub-agents, each of which also having a circle with the agent's metadata, and any number of tools attached to it.

When saving the diagram, Modeler API will save each of the sub-agents as separate agent config entities.

Don't forget to enable the "AI Agents Modeler API" submodule to get access to this functionality. When you then go to /admin/structure/ai-agent and click on edit for any of the existing agents, or create a new agent for that matter, you will find yourself in the BPMN.iO canvas that you know from ECA, but now to edit your own agent.

What's missing at this point is to embed an existing agent as a sub-agent. But you can create new agents as sub-agents.

What's next

There will certainly bugs be found, and we'll fix them all quickly. We then also want to go beta, which will be possible when the following API changing features are finalized:

• Storing swim lanes and colour outside the raw data so that those won't be lost when raw data is not available.
• Adding support for annotations, which will help to make diagrams even more self-explaining.
• Adding support for extra modes like edit (already available), view, log view, and replay. As a first step, there will only be the modes, not all of their functionality.

Sounds like a lot, but should only be a matter of days. So, by the end of June 2025, we're aiming for at least RC releases, followed by stable releases soon afterwards. That's just for your own planning. And that's to explain why testing now matters. Please help us to get this done.