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.

!image

Installation

> _Note:_ Installation instructions are coming soon.

Build and Run

``bash


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).

`javascript
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.

$3

| 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.

$3

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:

`javascript
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

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

$3

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

Examples

$3

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.

`javascript
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.

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

#### Provide the integration module to the process landscape constructor

`javascript
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.

$3

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:

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

$3

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:

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

// Somewhere in your UI:
Zoom In
Zoom Out
`

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:

`javascript
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:
Toggle Minimap;
``

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.