Skip to content

Modeler API

The Modeler API module provides a framework for building visual modelers in Drupal. It decouples the concept of what is being modeled (Model Owners) from how it is modeled (Modelers), and supports rich contextual metadata through three YAML-based plugin systems (Contexts, Dependencies, Template Tokens).

Who is this for?

This documentation targets Drupal module developers who want to:

  • Integrate their configuration entities with a visual modeler (implement a Model Owner plugin).
  • Build a new visual editing experience (implement a Modeler plugin).
  • Provide contextual component lists, dependency rules, or template tokens for an existing model owner (define YAML plugins).

Key concepts

Concept Description
Model Owner A plugin that owns config entities which can be visually modeled. It defines available components, how they are stored, and how the model is saved. Examples: ECA, AI Agents.
Modeler A plugin that provides the visual editing UI. It knows how to render, parse, and serialize model data. Examples: BPMN.iO (XML/BPMN), Next-Gen Modeler (JSON/React Flow).
Context A YAML-based plugin that defines which components are available for a specific use case within a model owner.
Dependency A YAML-based plugin that constrains which components can follow other components.
Template Token A YAML-based plugin that provides token trees for use in model templates.
Component A value object representing a single element in a model (event, action, condition, gateway, etc.).

Architecture at a glance

Model Owner (e.g. ECA)          Modeler (e.g. BPMN.iO)
        |                              |
        |   <-- Modeler API -->        |
        |                              |
   Config Entity  <-->  Raw Data (XML/JSON)
        |
   Components / Successors / Colors / Swimlanes / Annotations

The Api service (modeler_api.service) acts as the central coordinator. It finds the right Model Owner for any config entity, manages the save cycle (parse raw data, reset components, add components, finalize), and exposes helpers for contexts, dependencies, export, and more.

Module requirements

  • Drupal ^11.2
  • PHP >=8.3
  • Optional: drupal/token for template token support.

Community