@processmaker/modeler

ProcessMaker BPMN modeler

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

• Project setup
• Testing
• Architecture
  • Global event bus
    • modeler-init
    • modeler-start
    • modeler-validate
    • modeler-change
  • Undo/redo store
  • Validation
    • Adding a new lint rule
    • Adding validation rules during runtime
• Examples
  • Adding a new component

Project setup

Clone the repository and cd into the modeler directory:

git clone [e-mail]:ProcessMaker/modeler.git
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 https://cli.vuejs.org/guide/cli-service.html#cli-service.

# 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

Docker Env

If you prefer to run Modeler using Docker

# Using Docker Compose
docker compose up

Testing

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 https://cli.vuejs.org/config/#cypress.

For more information on Jest, visit https://jestjs.io.

Extending the Modeler with modeler-init

The modeler-init event is the main entry point for plugins and extensions to customize the modeler at runtime. It provides several extension points, including:

• Registering custom nodes
• Registering BPMN extensions
• Registering inspector extensions
• Registering custom dropdown items for nodes

Unified Example

Below is a unified example that demonstrates how to use modeler-init to register a custom node and, after the process is loaded, inject a custom dropdown item for a Start Event node.

import MyCustomNodeConfig from './MyCustomNodeConfig';

// Listen for modeler-init to register nodes and extensions
window.ProcessMaker.EventBus.$on('modeler-init', ({ registerNode, registerCustomDropdownData }) => {
  // Register a custom node (if needed)
  registerNode(MyCustomNodeConfig);

  // Wait for the process to load before injecting dropdown items
  window.ProcessMaker.EventBus.$on('modeler-start', ({ modeler }) => {
    // Find the first Start Event node (or your custom node)
    const startEventNode = modeler.$store.getters.nodes.find(
      node => node.type === 'processmaker-modeler-start-event'
    );
    if (startEventNode) {
      // Inject a custom dropdown item
      modeler.registerCustomDropdownData(startEventNode, {
        label: 'Custom Start Option',
        id: 'custom-start-option',
        dataTest: 'switch-to-custom-start-option',
      });
    }
  });
});

• Use registerNode to add custom nodes.
• Use registerCustomDropdownData to add dropdown items, but only after the process and nodes are loaded (in modeler-start).
• You can also use other extension points provided in the modeler-init payload as needed.

Architecture

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.

modeler-init

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 */
  registerNode(intermediateMessageCatchEvent);

  /* 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',
    },
  });

});

modeler-start

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.

modeler-validate

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

modeler-change

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.

Validation

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 https://github.com/bpmn-io/bpmnlint.

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 reporter.report 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 node.id === 'string' && !node.id.startsWith('node_')) {
      reporter.report(node.id, '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 https://github.com/bpmn-io/bpmnlint/tree/master/rules.

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 node.id === 'string' && !node.id.startsWith('node_')) {
    reporter.report(node.id, 'Node ID must start with the string "node_"');
  }
});

Examples

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: https://github.com/bpmn-io/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: https://github.com/bpmn-io/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

<template>
  <div />
</template>

<script>
import Task from '@/components/nodes/task/task';

export default {
  extends: Task,
  mounted() {
    // Do things with this.shape
  },
};
</script>

Finally, register your custom component:

registerNode(CustomComponentConfig);