Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

ProcessMaker BPMN modeler


@processmaker/modeler is a Vue.js based BPMN modeler scaffolded using Vue CLI 3.

Project setup

Clone the repository and cd into the modeler directory:

git clone
cd modeler

You can now run any of the below commands. Most commands make calls vue-cli-service. You can read more about those commands at

# Compile the app and start a local development server
npm run serve

# Create a production build of the app to be distributed as an npm package
npm run build-bundle

# Report and fix ESLint errors
npm run lint


Unit tests are set up using jest and end-to-end tests are set up using Cypress. Unit and end-to-end tests can be run separately or together. Code coverage is collected for both types of tests and combined into a single coverage report for the entire project.

Tests can be run locally with the following commands:

# Run the Jest unit test suite
npm run test-unit

# Open Cypress to run the end-to-end (e2e) test suite
npm run open-cypress

# Run the Cypress end-to-end (e2e) test suite in headless mode
npm run test-ci

# Run the Jest unit test tests and then the Cypress tests in headless mode
npm test

Tests are run automatically on CircleCI when new branches are created and updated. The CI uses the npm test command to run both the unit and e2e test suites and to collect code coverage.

For more information on Cypress, visit

For more information on Jest, visit


The entry point for the application is src/main.js; this is the "starting point" which is used when running npm run serve or npm run build.

Global event bus

window.ProcessMaker.EventBus points to an independent Vue instance which acts as the application's global event bus. The modeler currently emits two events on the event bus which can be listened to in application code to hook into, customize, and extend the modeler's behaviour: modeler-init, and modeler-start.


This event is fired before the modeler and BpmnModdle are set up and mounted. Listeners to this event are passed an object with three methods: registerInspectorExtension, registerBpmnExtension, and registerNode.

import bpmnExtension from '@processmaker/processmaker-bpmn-moddle/resources/processmaker.json';
import { intermediateMessageCatchEvent } from '@/components/nodes';

window.ProcessMaker.EventBus.$on('modeler-init', ({ registerBpmnExtension, registerNode, registerInspectorExtension }) => {

  /* Add a BPMN extension */
  registerBpmnExtension('pm', bpmnExtension);

  /* Register a component to be used in the modeler */

  /* Add custom properties to inspector */
  registerInspectorExtension(intermediateMessageCatchEvent, {
    id: 'pm-condition',
    component: 'FormInput',
    config: {
      label: 'Condition',
      helper: 'Expression to be evaluated on webhook to activate event. Leave blank to accept always.',
      name: 'pm:condition',



This event is fired after the modeler has been set up and mounted. Listeners to this event are passed an object with a single method, loadXML.

window.ProcessMaker.EventBus.$on('modeler-start', ({ loadXML }) => {

  loadXML('<?xml version="1.0" encoding="UTF-8"?> ... </bpmn:definitions>');


For the modeler to function correctly, loadXML must be called when the application loads.


This event is fired during validation, and can be used to add custom validation rules. See Adding validation rules during runtime.


This event is fired anytime a change is made to the modeler that causes the underlying XML to change. This event is fired immediately after new state is pushed to the undo/redo stack.

window.ProcessMaker.EventBus.$on('modeler-change', () => {
  console.log('The diagram has changed');

Undo/redo store

The undo/redo feature is implemented using Vuex, with the undo/redo Vuex store initialized in src/undoRedoStore.js. The undo/redo store keeps track of every change in the underlying BPMN XML, recording a copy of the XML string in a stack. Traversing the undo/redo stack simply uses the loadXML function to load the XML string from the current position in the stack.


Adding a new lint rule

By default, the modeler automatically validates your diagram as you create it. This validation can be toggled on and off using the switch in the status bar. Validation is handled using

To add a new validation rule, create a new file in processmaker-plugin/rules named after your rule, for example, node-id.js. This file should export a function that returns an object with a check method. The check method will receive two arguments—node and reporter—and must return undefined if validation passes, or to raise an error. For exmaple:

// processmaker-plugin/rules/node-id.js

 * Rule that checks node IDs start with "node_"
module.exports = function() {
  function check(node, reporter) {
    if (typeof === 'string' && !'node_')) {, 'Node ID must start with the string "node_"');

  return { check };

When you are done writing the rule, add it to processmaker-plugin/index.js:

module.exports = {
  configs: {
    all: {
      rules: {
        'processmaker/custom-validation': 'error',
        'processmaker/gateway-direction': 'error',
        'processmaker/node-id': 'error',

For more examples, see the list of default rules at

Adding validation rules during runtime

To add custom validation when the linter runs, use the global event bus:

window.ProcessMaker.EventBus.$on('modeler-validate', (node, reporter) => {
  if (typeof === 'string' && !'node_')) {, 'Node ID must start with the string "node_"');


Adding a new component

Creating a new modeler component requires creating a Vue component, a component config, and calling the registerNode method to register your component.

First, create your component config, and save it in a .js file:

// CustomComponentConfig.js

export default {
  // A unique ID that will be used to identify your component
  id: 'unique-custom-component-id',

  // A reference to the Vue component representing your component
  component: CustomComponent,

  // The bpmn type for your component, which will be used to save the component under in XML
  // It has the form prefix:name
  bpmnType: 'custom-namespace:CustomComponent',

  // A toggle to show/hide the component in the controls panel
  control: true,

  // The category to place the component under in the controls panel
  category: 'BPMN',

  // The icon representing the component in the controls panel
  icon: require('@/assets/toolpanel/scriptTask.svg'),

  // The label for the component in the controls panel
  label: 'Script Task',

  // The function used to create the BPMN definition object for the component in the XML
  // moddle is a reference to an instance of bpmn-moddle:
  definition(moddle) {
    return moddle.create('bpmn:ScriptTask', {
      name: 'Script Task',

  // The function used to create the BPMN diagram object for the component in the XML
  // moddle is a reference to an instance of bpmn-moddle:
  diagram(moddle) {
    return moddle.create('bpmndi:BPMNShape', {
      bounds: moddle.create('dc:Bounds', {
        height: taskHeight,
        width: 116,

  // The configuration for the inspector panel
  inspectorConfig: [
      name: 'CustomComponent',
      items: [
        // Each item corresponds to a form element. 
          // Component can be a custom Vue component or a reference to a form component from @processmaker/vue-form-elements
          component: 'FormText',
          config: {
            label: 'Custom Component Label',
            fontSize: '2em',
        // ...
    // ...

Then, create a Vue component for your custom element:

// CustomComponent.vue

  <div />

import Task from '@/components/nodes/task/task';

export default {
  extends: Task,
  mounted() {
    // Do things with this.shape

Finally, register your custom component: