Version: 8.8 (unreleased)

Defining templates

An element template is defined in a template descriptor files as a JSON object. The element template object is divided into required and optional key-value pairs:

Required keys

$schema : String: URI pointing towards the JSON schema which defines the structure of the element template .json file. Element template schemas are maintained in the element templates JSON schema repository.
id : String: Identifier of the template.
name : String: Name of the template. Shown in the element template selection modal and in the properties panel on the right side of the screen (after applying an element template).
appliesTo : Array<String>: List of BPMN element types the template can be applied to.
properties : Array<Object>: List of properties that the template applies to the BPMN element. Each property object defines the type of input and how its value is bound to a BPMN or Camunda extension property.

Optional keys

version : Integer: Property to support template versioning and upgrading. If you add a version to a template, it is considered unique based on its ID and version.
description : String: Description of the template. Shown in the element template selection modal and in the properties panel (after applying an element template).
keywords : Array<String>: List of keywords. Helps users find the template through search. Keywords are used for search and filtering but are not displayed in the UI.
category : Object: Category for the template. The template appears under the category name in the element template selection modal.
documentationRef : String: URL pointing to the template's documentation. Shown in the properties panel (after applying an element template).
icon : Object: Sets the template's icon. The icon is shown in the element template selection modal and in the properties panel (after applying an element template).
engines : Object: Dictionary of environments compatible with the template. The environment version is specified using a semantic version range.
elementType : Object: Sets the type of the element. The element is replaced with the specified type when a user applies the template.
groups : Object: Defines groups of property input fields. Groups are sections in the properties panel. Properties can be assigned a group.

Some keys and values require other keys to be set. If your editor supports the JSON schema, it will flag missing keys as errors. The Web Modeler's editor will also show these errors in the template editor problems panel.

Below you find a simple example of an element template with the most commonly used keys:

{
  "$schema": "https://unpkg.com/@camunda/zeebe-element-templates-json-schema/resources/schema.json",
  "name": "Template 1",
  "id": "sometemplate",
  "description": "some description",
  "keywords": ["search alias", "create action"],
  "version": 1,
  "engines": {
    "camunda": "^8.6"
  },
  "appliesTo": ["bpmn:Task"],
  "elementType": {
    "value": "bpmn:ServiceTask"
  },
  "properties": [
    {
      "label": "Input Variable",
      "type": "String",
      "value": "someProcessVariable",
      "binding": {
        "type": "zeebe:input",
        "name": "anInputVariable"
      }
    }
  ]
}

Creating multiple templates in one file

You can define multiple templates in one JSON file by wrapping them in an array.

warning

This is a Desktop Modeler-specific feature. Web Modeler requires each template to be in a separate file.

[
  {
    ...
    "name": "Template 1",
    "id": "some-template-id",
    "description": "some description",
    ...
  },
  {
    ...
    "name": "Template 2",
    "id": "another-template-id",
    "description": "another description",
    ...
  }
]

Creating and editing templates

You can create and edit element templates in the text editor of your choice. Connector templates are a specific type of element template, so the same applies to them. If your editor supports the JSON schema, it will recognize the structure of the template and provide additional editing support, such as formatting, code completion, and error highlighting.

The Web Modeler offers a built-in template editor with validation and error highlighting, as well as a live preview of the properties panel with the applied template.

Required keys​

Optional keys​

Creating multiple templates in one file​

Creating and editing templates​

Further reading​

Required keys

Optional keys

Creating multiple templates in one file

Creating and editing templates

Further reading