Creating a BPMN Viewer and Editor: A Visual Guide

    Thursday, July 4, 20248 min read229 views
    Creating a BPMN Viewer and Editor: A Visual Guide

    Background of BPMN (Business Process Model and Notation)

    Effective communication is crucial for organizations undertaking business process improvement initiatives. Complex workflows often involve diverse teams, technical developers, business users, and business analysts. The intricate nature of these processes and the underlying technology can make it challenging to visualize the flow of work.

    This standardized graphical representation provides a clear and concise way to represent even the most intricate business processes. BPMN diagram's visual nature fosters collaboration between departments, leveraging the human brain's well-documented ability to process visuals significantly faster than text.

    Benefits of BPMN Implementation

    Implementing BPMN offers a multitude of benefits for your organization:

    • Shared Understanding

    Visual process models created with BPMN foster clear communication across teams. Regardless of background or expertise, individuals can easily grasp the process flow, facilitating discussions and knowledge retention.

    • Bridging the Business-IT Divide

    BPMN acts as a common language, allowing business stakeholders and IT teams to collaborate effectively. By visualizing process needs before diving into technical implementation, teams can ensure alignment and deliver solutions that truly meet business objectives.

    • Enhanced Visibility and Collaboration

    Modern BPMN tools empower teams to work on and share process models remotely, fostering team collaboration even in distributed workforces. This asynchronous collaboration fosters creativity and boosts productivity.

    • Streamlined Development

    Executable BPMN models enable the complete process design before any coding begins. This eliminates wasted development effort on code that may need revision later. By aligning upfront on scope and solutions, teams can deliver projects more efficiently.

    After going through all the introduction and benefits of BPMN, we will now delve deeper guiding you through the creation of a basic BPMN viewer and editor using pre-built tools. We'll explore the detailed steps, and integration processes, and even touch upon customization options.

    BPMN Diagrams: A Visual Guide to Business Processes

    BPMN uses diagrams with special symbols to represent business processes. These visual maps make it easy for anyone, regardless of technical expertise, to understand the flow of work. Whether it's a simple or complex process, BPMN diagrams provide a clear picture.

    Building Blocks of a BPMN Diagram

    The BPMN standard groups these symbols into categories for easy recognition. Let's explore these building blocks:

    • Swim lanes: Imagine lanes on a swimming pool but representing different participants in the process. These can be entire departments (pools) or specific teams within a department (lanes).

    • Flow Elements: These are the heart of the BPMN diagram, connecting to show the process flow. They come in three main types:

      • Events: Triggers that start, interrupt, or end the process.

      • Activities: Specific actions performed within the process.

      • Gateways: Decision points where the process flow can branch based on certain conditions.

    • Connecting Objects: Just like connecting lines on a flowchart, these arrows show how the flow elements link together. There are four different types:

      • Sequence Flows: The typical flow from one step to the next.

      • Message Flows: Used for communication between participants outside the main process.

      • Associations: Connect objects to provide additional information, but don't show a direct flow.

      • Data Associations: Show how data is used or produced during specific activities.

    • Data: Information that's needed or created throughout the process. This can be things like documents, numbers, or customer details.

    By understanding these building blocks, you can effectively interpret and even create complex BPMN diagrams and presentations, to visualize your business workflows.

    Example of BPMN Diagram for a Pizza Ordering

    Example of BPMN Diagram for a Pizza Ordering

    How to Create a BPMN Viewer and Editor

    Creating a custom BPMN viewer and editor from scratch can be a complex task. Here are two approaches to consider:

    1. Build on top of existing libraries

    This is the recommended approach for most cases. free open-source Libraries like bpmn-js provide a solid foundation for building custom BPMN tools. Here's how you can achieve this with bpmn-js:

    • Learn bpmn-js: Explore the bpmn-js documentation and tutorials to understand its core concepts, functionalities, and APIs.

    • Customize the viewer: You can extend the basic viewer features by leveraging bpmn-js functionalities. This could involve hiding certain elements, adding custom shapes, or modifying the visual style.

    1. Build from scratch (not recommended)

    This approach requires a deep understanding of BPMN specifications, diagramming concepts, and user interface development. It's a significant undertaking and might not be the most efficient solution unless you have very specific requirements not met by existing libraries.

    Here are some additional resources that might be helpful:

    • This online bpmn tool provides a comprehensive overview of bpmn-js and related libraries, along with helpful resources for getting started.

    • JavaScript diagramming libraries: If you're building from scratch, exploring general-purpose diagramming libraries like GoJS can be a starting point for the visual representation of the BPMN elements.

    We will explore building a bpmn viewer on top of the existing library step by step in detail.

    Picking the Right Library

    The best library for your project depends on your specific needs and skillset. Here's a quick guide to help you decide:

    • For Beginners: If you're new to BPMN and web development, consider Camunda Modeler. Its user-friendly interface simplifies the process of creating basic diagrams.

    • For Customization: If you need more control over the viewer and editor's functionalities, opt for bpmn-js. It offers greater flexibility for tailoring the tool to your specific requirements.

    • For Quick Collaboration: is a great choice for quick process visualization and collaboration within teams. However, its editing capabilities might be limited compared to dedicated desktop applications.

    Using the Library

    There are two ways to use bpmn-js in your project

    1. Quick and Easy: This option uses a pre-built version of bpmn-js. It's like a ready-made kit that lets you add BPMN features to your website with just a few lines of code. This is perfect if you just need basic BPMN functionality.

    2. More Control, More Work: This option involves installing bpmn-js piece by piece. It's like building your own toolbox with different BPMN components. This gives you more flexibility to customize the features, but it takes a little more effort to set up.

    Ready to streamline your business processes and boost team collaboration? Partner with Angular Minds, with a team of BPMN experts. We'll help you implement BPMN effectively, fostering clear communication, enhanced visibility, and ultimately, improved process efficiency.

    Embed pre-packaged Assets

    Download or simply include the relevant dependencies files into your website:


    <!-- required viewer styles -->
    <link rel="stylesheet" href="" />
    <script src=""></script> 


    <!-- required modeler styles -->
    <link rel="stylesheet" href="" />
    <link rel="stylesheet" href="" />
    <link rel="stylesheet" href="" />
    <script src=""></script>

    you can check the starter template below for reference:

    <!DOCTYPE html>
        <meta charset="UTF-8" />
        <title>Hello World</title>
        <!-- viewer distro (without pan and zoom) -->
        <script src=""></script>
        <!-- required viewer styles -->
        <link rel="stylesheet" href="">
        <!-- viewer distro (with pan and zoom) -->
        <script src=""></script>
        <!-- needed for this example only -->
        <script src=""></script>
        <!-- example styles -->
          html, body, #canvas {
            height: 100%;
            padding: 0;
            margin: 0;
          .diagram-note {
            background-color: rgba(66, 180, 21, 0.7);
            color: White;
            border-radius: 5px;
            font-family: Arial;
            font-size: 12px;
            padding: 5px;
            min-height: 16px;
            width: 50px;
            text-align: center;
          .needs-discussion:not(.djs-connection) .djs-visual > :nth-child(1) {
            stroke: rgba(66, 180, 21, 0.7) !important; /* color elements as red */
        <div id="canvas"></div>
          var diagramUrl = '';
          // viewer instance
          var bpmnViewer = new BpmnJS({
            container: '#canvas'
           * Open diagram in our viewer instance.
           * @param {String} bpmnXML diagram to display
          async function openDiagram(bpmnXML) {
            // import diagram
            try {
              await bpmnViewer.importXML(bpmnXML);
              // access viewer components
              var canvas = bpmnViewer.get('canvas');
              var overlays = bpmnViewer.get('overlays');
              // zoom to fit full viewport
              // attach an overlay to a node
              overlays.add('SCAN_OK', 'note', {
                position: {
                  bottom: 0,
                  right: 0
                html: '<div class="diagram-note">Mixed up the labels?</div>'
              // add marker
              canvas.addMarker('SCAN_OK', 'needs-discussion');
            } catch (err) {
              console.error('could not import BPMN 2.0 diagram', err);
          // load external diagram file via AJAX and open it
          $.get(diagramUrl, openDiagram, 'text');

    Roll Your Own Modeler

    If you want to add your features to the bpmn-js library, you can install it using npm. This lets you pick and choose which parts of the library you want to use in your project. It also gives you more control over what gets included in your final viewer or view modeler application.

    Step 1: install bpmn-js via npm

    npm install bpmn-js

    Step 2: access the BPMN modeler via an ES import

    import Modeler from 'bpmn-js/lib/Modeler';
    // create a modeler
    const modeler = new Modeler({ container: '#canvas' });
    // import diagram
    try {
      await modeler.importXML(bpmnXML);
      // ...
    } catch (err) {
      // err...

    Step 3: Add Stylesheets

    <link rel="stylesheet" href="bpmn-js/dist/assets/diagram-js.css" />
    <link rel="stylesheet" href="bp

    Step 4: Hook into Life-Cycle Events

    you can track what's happening in the modeler, like when elements change or when you interact with the diagram. This lets you make templates to react to these events and do things like keeping track of changes.

    modeler.on('commandStack.changed', () => {
      // user modeled something or
      // performed an undo/redo operation
    modeler.on('element.changed', (event) => {
      const element = event.element;
      // the element was changed by the user

    You can find the more info on official documentation of

    Hire Expert Developers
    Hire Expert Developers
    With a customer-centric approach and clean code, the team of developers at Angular Minds is the perfect fit for your next project.
    Hire now

    Related articles

    This website uses cookies to analyze website traffic and optimize your website experience. By continuing, you agree to our use of cookies as described in our Privacy Policy.