@camunda/process-landscape

Process Landscape

Process Landscape is a visualization tool that provides a hierarchical view of interconnected processes, allowing users to explore the relationships and dependencies between multiple process levels. This tool automatically generates a landscape view of all BPMN diagrams within a project, offering insights without the need for manual maintenance or updates.

Installation

Note: Installation instructions are coming soon.

Build and Run

# get all required dependencies
npm install

# run our sandbox testing environment (either command)
npm start
npm run dev

# run our test suites
npm run test

# run the full CI in one command
npm run all

Usage

To get started, create a new ProcessLandscape instance to render a process landscape schema into the body of your page (or any other target root).

const processLandscape = new ProcessLandscape({
  root: document.body,
  data: exampleLandscapeData,
});

To experiment with configuration, see our sandbox environment.

Customization

The process landscape is highly customizable. These configurations are managed via services and configuration properties relating to those services.

Services may also entirely be re-implemented, but this requires a deep understanding of the codebase.

Some special integration services are not implemented within the library at all, and need to be defined by the implementing library following an expected interface.

If you are unsure how to work with services and service configuration, a section with examples is available at the end of the readme.

Integration services

Service	Role	Interface
linkHandler	Determines if the name of a process landscape node should be rendered as a link and defines the behavior when clicked.	{ hasLink(node), onClickLink(node) }

See SandboxNodeLinkHandler.js (and other integration examples for our sandbox) to better understand the interface of our services, and follow the detailed integration example to learn how to build your integration module.

Customization with RuleBuilder

The RuleBuilder is a flexible way to define dynamic styles, adorners, and behaviors for different parts of the process landscape.

With the RuleBuilder, you can declaratively apply styles and adorners to specific elements (e.g., nodes, links, or labels) based on customizable rules.

Example Rules

Here’s an example configuration of rules that demonstrate how to define styles and adorners for various node types:

import { RuleBuilder as Rule } from "@camunda/process-landscape";

const rules = [
  Rule.forLandscape().apply({
    horizontalNodeSpacing: 120,
    verticalNodeSpacing: 100,
  }),

  Rule.forLabels().apply({
    styles: {
      fill: "black",
      fontWeight: "bold",
    },
  }),

  Rule.forMarkers().apply({
    styles: {
      scale: 0.5,
    },
  }),

  Rule.forNodes().apply({
    styles: {
      strokeWidth: 1,
    },
    adorners: {
      definitions: [
        getAdornerInfo: () => ({
          content: "draft",
          position: "top-right",
          styles: {
            fontSize: "12px",
            fill: "gray",
          },
        }),
      ],
    },
  }),
];

const processLandscape = new ProcessLandscape({
  root: /* ... */,
  data: /* ... */,
  rules: rules
});

How It Works

• Rule Declaration: Use RuleBuilder.for methods to target specific components (landscape, nodes, links, labels, or markers).
• Apply Rules: Each rule defines visuals that should be applied to landscape element, e.g. styles and/or adorners.
• Prioritization: Rules are "merged" in order of definition. Ensure that you define more specific rules later, or they will never be applied.

Details for other modules

• features/adorners - Define additional visual indicators to landcape nodes

Examples

Integration module example

You can provide an integration module to group all the integration services you supply to the process landscape. Here's how you would set this up, with as example implementing only the linkHandler service.

Implement the service(s) as a class

Here we define a custom linkHandler according to its expected interface.

class ExampleLinkHandler {
  hasLink(node) {
    return node && node.businessObject.externalData?.link; // Example: check if the node has a "link" externalData property.
  }

  onClickLink(node) {
    console.log("Link clicked:", node.name); // Example: log the node name when the link is clicked.
  }
}

Bundle your service(s) in a module

What is important here is that the property name, linkHandler in this case, matches, as it is what the codebase will look for.

const IntegrationModule = {
  __init__: ["linkHandler"], // Initialize the linkHandler service.
  linkHandler: ["type", ExampleLinkHandler],
};

Provide the integration module to the process landscape constructor

const processLandscape = new ProcessLandscape({
  root: diagramContainerRef.current,
  data: landscapeData, // Your process landscape data.
  additionalModules: [IntegrationModule],
});

And there we go, you've successfully adapted the process landscape to work for your environment.

Module configuration example

Let's say we want to set the myProperty property of the myService. This may simply be achieved by supplying the property to the ProcessLandscape constructor as follows:

const processLandscape = new ProcessLandscape({
  root: document.body,
  data: exampleLandscapeData,
  myService: {
    myProperty: "myValue", // Custom value for myProperty.
  },
});

Landscape navigation helpers

The process landscape can easily be extended with several navigation helpers, such as:

• zoom level controls
• landscape minimap

Want to zoom in on details or zoom out for the bigger picture? The functionality is available out of the box, but you’ll need to add UI controls to unleash its magic. Here is a simple example on how to manage zoom level in your application:

const handleZoomIn = () => myDiagram.get("zoomScroll").stepZoom(1);
const handleZoomOut = () => myDiagram.get("zoomScroll").stepZoom(-1);

// Somewhere in your UI:
<button onClick={handleZoomIn}>Zoom In</button>
<button onClick={handleZoomOut}>Zoom Out</button>

Lost in a sea of elements? Integrate a minimap, so you always know where you are! 🏴‍☠️ Just initialize your landscape with minimapModule using this example:

import "diagram-js-minimap/assets/diagram-js-minimap.css";
import minimapModule from "diagram-js-minimap";

const processLandscape = new ProcessLandscape({
  root: diagramContainerRef.current,
  data: landscapeData,
  additionalModules: [minimapModule], // Add minimapModule here.
});

const toggleMinimap = () => processLandscape.get("minimap").toggle();

// Somewhere in your UI:
<button onClick={toggleMinimap}>Toggle Minimap</button>;

And all set, you've successfully integrated navigation helpers to your landscape to never get lost again.

Need more context? See DiagramSandbox component for integration details.