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.

Core module configuration

The core module manages all which is extremely crucial for the functioning of the application, and we don't recommend to modify it beyond the properties we provide below.

landscapeRenderManager

Defines layout options for the process landscape.

{
  horizontalSpacing: 100, // Horizontal spacing between nodes.
  verticalSpacing: 120,   // Vertical spacing between nodes.
}

landscapeRenderer

Defines styles for individual nodes and their components.

{
  styles: {
    nodes: {
      // Styles for various node types, e.g., process, subprocess.
    },
    label: {
      // Styles for labels, differentiated by type (e.g., link or text).
    }
  }
}

textRenderer

{
  defaultStyle: {
    fontSize: 12,          // Default font size for text elements.
    fontFamily: "Arial, sans-serif", // Default font family for text.
    fontWeight: "normal",  // Font weight for text.
    lineHeight: 1.2,       // Line height ratio for text layout.
  },
  style: {
    // Custom styles to override the default text styles.
  },
}

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.metadata?.link; // Example: check if the node has a "link" metadata 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.
  },
});

For instance, if you wanted to customize the horizontalSpacing property of the landscapeRenderManager, you could do so like this:

const processLandscape = new ProcessLandscape({
  root: document.body,
  data: exampleLandscapeData,
  landscapeRenderManager: {
    horizontalSpacing: 150, // Custom horizontal spacing between nodes.
  },
});