Want to try out modeling in domain-specific, reusable building blocks? Check out our demo.

Element Templates

The tool that powers declarative, domain specific modeling at bpmn.io.

About

Element templates allow you to define re-usable, domain specific building blocks to supported bpmn.io toolkits. Through a set of utilities they deeply integrate into the modeling experience.

Features

Through a JSON document you define different aspects of a re-usable building block.

General Configuration

• Name and description
• Icon
• BPMN element type
• Category
• Documentation references
• Versioning + deprecation information

Property Configuration

• Type of control
• Technical binding
• Labels, description
• Validation
• Grouping
• Conditional activation criteria

Editor Integration

Through a set of utilities element templates get deeply integrated into our editor tooling.

Create/Append Anything

Provided through an extension.

• Palette and context pads have a ... entry to create / append any element
• Building blocks can be discovered via search
• Replace menu is enhanced to work using the same pattern

Configuration

Provided through the properties panel and a template chooser component.

• Allows to set an applicable template as well as unlinking and removing it
• Renders configured template controls
• Validates inputs according to defined validation rules
• Shows basic template meta-data

Upgrading/Migration/Replacement

Provided through the properties panel as well as an extension.

Templates come with two built-in ways of migration: Upgrading to a newer (compatible) version or deprecation (with the ability to display a custom message).

• Upgrading works alongside the built-in versioning feature
• Migration happens using the built-in replace feature
• Upgrade and replace will preserve defined properties on a best effort basis

The user can trigger the actual upgrade/migration/replacement operation in two ways:

• In the properties panel, using provided upgrade controls
• Through the extended replace menu by re-applying the template or switching to a different template

To learn more about element template evolution checkout the life-cycle documentation.

Basic Setup

The basic setup requires a BPMN modeler as well as properties panel and element template provider modules:

import BpmnModeler from 'bpmn-js/lib/Modeler';

import {
  BpmnPropertiesPanelModule,
  BpmnPropertiesProviderModule,
  ZeebePropertiesProviderModule,
  CloudElementTemplatesPropertiesProviderModule
} from 'bpmn-js-properties-panel';

It allows you to pass element templates to the modeler during instantiation via the elementTemplate configuration:

const elementTemplates = [ ... ];

const modeler = new BpmnModeler({
  container: '#canvas',
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule,
    ZeebePropertiesProviderModule,
    CloudElementTemplatesPropertiesProviderModule
  ],
  elementTemplates
});

Checkout API for advanced use-cases driven via additional APIs.

Supported Toolkits

Right now element templates are supported in bpmn-js.

Creating an Element Template Provider

Refer to the create a provider guide.

Related Utilities

• bpmn-js-element-templates - Provides the ElementTemplates core and ships with implementations for technical binding of Camunda 7 and 8 properties.
• element-template-icon-renderer - Renders embedded element template icons on the modeling canvas.
• element-template-chooser - A simple element template chooser that plugs into the properties panel
• element-template-json-schema - The schema definition for template descriptors
• bpmn-js-create-append-anything - A deep integration into the core modeling experience, featuring create + append anything and replacing with template tasks