Mule Flow Diagrams [mulefd]

Table of Contents

Introduction
Features
Requirements
Installation
Usage
Known modules/connectors
- Registering custom modules
Copyright & License

Introduction

Mule application can contain multiple flows and sub-flows. All these can reference each other for processing messages. Data can also be exchanged synchronously or asynchronously using connectors.

A project can easily have multiple configuration files with flows/sub-flows that are spread across those files. When analyzing mule application, it could be difficult to see the complete data processing flow and their dependencies.

Have you ever wished to visualize your flow dependencies? How does message flows through your application?

If so, then try this mulefd application. It can read your configuration files and generate a diagrams that can easily tell you how your flows are connected.

$ mulefd
Missing required parameter: '<sourcePath>'
Usage: mulefd [-hV] [-gs] [-d=<diagramType>] [-fl=<flowName>]
						[-o=<outputFilename>] [-t=<targetPath>] <sourcePath>
Create Flow diagrams from mule configuration files.
	<sourcePath>        Source directory path containing mule configuration
							files
-d, --diagram=<diagramType>
						Type of diagram to generate. Valid values: GRAPH,
							SEQUENCE
							Default: GRAPH
-fl, --flowname=<flowName>
						Target flow name to generate diagram for. All
							flows/subflows not related to this flow will be
							excluded from the diagram.
-gs, --genSingles   Generate individual diagrams for each flow.
-h, --help              Show this help message and exit.
-o, --out=<outputFilename>
						Name of the output file
							Default: mule-diagram
-t, --target=<targetPath>
						Output directory path to generate diagram
-V, --version           Print version information and exit.

Copyright: 2020 Manik Magar, License: MIT
Website: https://github.com/manikmagar/mulefd

For an example mule configuration ./itests/test-hello-app.xml, run following command to generate a flow diagram -

$ mulefd ./itests/test-hello-app.xml -t ./itests/output

Features

Visualize mule flow dependencies and data flow.
Visualize mule flow dependencies for a single flow.
Identify unused mule flows and sub-flows.
Identify flow spaghetti situations.
Visualize synchronous and asynchronous data processing points.
Identify connector dependencies and usage.
Detect a possible recursive flow executions.

Requirements

At the minimum, Java 8 is required. The build pipeline also tests it against JDK 11+.

Tested and verified to use on OSX, Linux and Windows.

Installation

SDKMan [linux] [apple]

Recommended way to install both java and Mule flow diagrams is sdkman for Linux and OSX.

To install SDKMAN and Java -

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

sdk install java

Once Java is installed and ready, you install Mule Flow Diagrams -

sdk install mulefd

To test your installation run:

mulefd --help

This should print out usage information.

For upgrading existing installations via SDKMAN,run:

sdk upgrade mulefd

Homebrew [apple]

On OSX you can install 'java' and mulefd with Homebrew using custom taps.

To install Java 8:

brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk8

Once Java is installed you can use brew with manikmagar/tap to get mulefd:

brew install manikmagar/tap/mulefd

To upgrade to the latest version:

brew upgrade manikmagar/tap/mulefd

Test running mulefd --help in CLI.

Docker [docker]

If you don’t want to install mulefd, you can run it via docker.

docker run -v `pwd`:/app manikmagar/mulefd /app

This will generate diagrams in pwd or mounted directory.

Docker container resources are limited. Based on the size of your application, you may see outofmemory errors when executing with docker. You can allocate more memory with -m option to docker run command, Eg. -m 512m.

Scoop [windows]

On Windows, you can install mulefd using Scoop - A command-line installer for Windows.

Once you have Scoop installed and JDK configured, you can run following commands to get mulefd -

scoop bucket add manikmagar https://github.com/manikmagar/scoop-bucket
scoop install mulefd

To upgrade, you can run -

scoop update mulefd

Manual install [apple] [windows] [linux]

Unzip the latest binary release.
Add mulefd-<version>/bin folder in to your $PATH
Test running mulefd --help in CLI.

Build and Run

This project uses Gradle to compile and build. To create a zip distribution, run below command in project directory -

./gradlew distZip

To install the distribution -

Clone the project
Run ./gradlew installDist. This will explode the generated zip file to ./build/install directory.
You can verify binaries by executing -
1. [apple] [linux] : sh build/install/mulefd/bin/mulefd --help
2. [windows] : ./build/install/mulefd/bin/mulefd.bat --help

Usage

mulefd support various arguments for generating diagrams.

Example: mulefd ~/AnypointStudio/studio-workspace/mulefd-demo

$ mulefd
Missing required parameter: '<sourcePath>'
Usage: mulefd [-hV] [-gs] [-d=<diagramType>] [-fl=<flowName>]
						[-o=<outputFilename>] [-t=<targetPath>] <sourcePath>
Create Flow diagrams from mule configuration files.
	<sourcePath>        Source directory path containing mule configuration
							files
-d, --diagram=<diagramType>
						Type of diagram to generate. Valid values: GRAPH,
							SEQUENCE
							Default: GRAPH
-fl, --flowname=<flowName>
						Target flow name to generate diagram for. All
							flows/subflows not related to this flow will be
							excluded from the diagram.
-gs, --genSingles   Generate individual diagrams for each flow.
-h, --help              Show this help message and exit.
-o, --out=<outputFilename>
						Name of the output file
							Default: mule-diagram
-t, --target=<targetPath>
						Output directory path to generate diagram
-V, --version           Print version information and exit.

Copyright: 2020 Manik Magar, License: MIT
Website: https://github.com/manikmagar/mulefd

Out of memory errors?

If your application is large and contains too many flows, process could fail with Exception in thread "main" java.lang.OutOfMemoryError: Java heap space error.

Try increasing the JVM allocated memory using -Xmx flag.

$ JAVA_OPTS='-Xmx1024m' mulefd ~/AnypointStudio/studio-workspace/mulefd-demo

For windows, you may need to set it at environment level -

set JAVA_OPTS=%JAVA_OPTS% -Xmx1024m
mulefd.bat ~/AnypointStudio/studio-workspace/mulefd-demo

Source directory

Source directory is a required argument. This argument specifies where mule xml configuration files be searched.

This argument value can be one of the following:

Path of the individual mule xml file. Eg. ~/Downloads/test-app-config.xml. In this case, diagram for just this file is generated.
Path to a standard mule 4 or mule 3 project root. Eg. ~/AnypointStudio/studio-workspace/mulefd-demo.
- Mule 3: All configurations from src/main/app/ are scanned to generate a diagram.
- Mule 4: All configurations from src/main/mule/ are scanned to generate a diagram.
Path to any non-mule project directory.

Generate Individual flow diagrams

When running against a large mule application, the generated mule-diagram.png can contain too many flows. To simplify understanding each flow, it can be helpful to generate diagrams per flow (not sub-flows).

You can specify -gs or --genSingles option to generate individual flow diagrams, in addition to the consolidated one.

These diagrams are generated at {targetPath}/single-flow-diagrams/{currentDateTime} directory. Each generated diagram has the same name as flow it represents.

📎	Some flow names, especially the APIKit generated flows can contain characters not valid for some OS. Names are thus sanitized. Any character not in `a-zA-Z0-9.-` is replaced with `_`.

Flowname

If you just want to generate diagram for a single flow then specify it with -fl or --flowname option. This will exclude all flows and subflows that are not related to this target flow.

Diagram Types

Current release supports generating Graph diagram only.

Output arguments

Target directory to output generated diagram can be specified with -t {directoryPath} option. This is an optional argument and defaults to the source directory (or parent directory if source is a file).

The file name for diagram defaults to mule-diagram.png. This can be changed by specifying -o {filename} argument.

Known modules/connectors

Mule has many connectors/modules that can be used for building flows and sub-flows, and list keeps growing. This tool maintains a list of known components with their supported operations for including in the generated diagram.

You can find this list in source code src/main/resources/default-mule-components.csv.

Each record in this file has following columns -

prefix,operation,sourceFlag,path,configName,async

prefix: Namespace of module/connector. Eg. vm, http etc.
operation: Name of an operation or input source in that namespace. Eg. listener, consume in vm etc. This supports wildcard entries (values defined as *) for non-source (sourceFlag=false) entries.
sourceFlag: true if operation is an input source withing that namespace. Eg. listener in vm.
path: Name of the attribute on operation which can help identify resource path. Eg. queueName for vm:listener or path for http:request. For sources, this is visible on source nodes in diagram.
configName: Name of the module configuration. Eg. config-ref attribute name for vm:listener. For sources, this is visible on source nodes in diagram. This can help identify source uniquely when multiple configuration exists.
async: true if this is an asynchronous operation. Defaults to false.

Registering custom modules

If any module is missing in the default list - either being a new module or a custom module, then it is possible for users to register their modules.

If mulefd-components.csv named CSV file exists in sourcePath, then all modules/connectors within that file are registered as known components. Structure of this file must be same as default components file explained above.

See example file at src/test/resources/mulefd-components.csv.

Copyright & License

Licensed under the MIT License, see the LICENSE file for details.

bondrk / mulefd Goto Github PK

mulefd's Introduction