Getting Started

Flo-Lang is a DSL built with Jetbrains MPS that was designed to model orchestration workflows and generate various software components that can be used in a Java application. Currently, these are:

  • Akka Event-Sourced Domain model + Finite State Machine

  • Graphiz graphs for visualising the flow

  • Test-FW complaint BDD Test scenarios for the possible permutations through the flow

  • Embeddable documentation from the model, in the form of Asciidoc

MPS itself is traditionally IDE driven, so we have built a set of modules and configurations that allow transparent integration into downstream projects uses, providing that the downstream project is Maven based, and adheres to a set of conventions.

Note that whilst the MPS IDE (Or Intellij with MPS Plugins) is needed to create and modify solutions, it is not needed to compile existing solutions via the Maven build. The Maven build process actually downloads an MPS binary and compiles the solution in a headless mode.

Users have several options on workflow with regard to obtaining MPS.

1. Installing MPS

Current working MPS version for command line builds and IDE is 2022.3.1.

The most common way to install MPS is via Jetbrains ToolBox as this manages installation of different versions.

getting started 1

Downloading MPS as described above is all that is needed to get started. The additional ICON-specific dependencies and plugins will get loaded into MPS as part of the project.

The below section describes the headless version of MPS that is used as part of the project build process, you should not need to care about this unless you have a specific reason or interest.

Bundled MPS

When building an IPF project that includes a flo-lang subproject, there are pre-configured Maven plugins that download a version of MPS and use it headlessly to generate the resulting java source code.

This is separate and independent of any MPS installation that has been manually downloaded to a user’s machine, it enables CI servers and removes the dependency of MPS from the host machine.

You may ask be asking "Can I just use this distribution" rather than needing to download a separate version. The answer is "yes, but not without a bit of effort, and its unsupported".

It is much simpler and advised to have your dedicated OS-specific application installed.

The issue is that the version that used headlessly is a generic distribution, to make it "runnable" you have to add some Operating System specific changes to the scripts.

Linux and Windows seem to work okay without issue for now, but for Apple Silicon MacOS machines the following changes are needed.

For MacOS ARM Models

Within the mps.sh file:

Replace the following property

-Djna.boot.library.path="${IDE_HOME}/lib/jna"

with the following value

-Djna.boot.library.path="${IDE_HOME}/lib/jna/aarch64"

Also add the following JVM security exports to the final command arguments

--add-opens=java.desktop/sun.lwawt.macosx=ALL-UNNAMED

--add-exports=java.desktop/sun.font=ALL-UNNAMED

--add-exports=java.desktop/com.apple.eawt=ALL-UNNAMED

--add-exports=java.desktop/com.apple.laf=ALL-UNNAMED

--add-exports=java.desktop/com.apple.eawt.event=ALL-UNNAMED

The headless mps version can be found in the following default location

<your_project_root>/<your_domain_root>/mps/target/mps

Project Setup

It is always advised that to create a new project setup you use the IPF archetype. This provides a simple mechanism to bootstrap a new project and gives you the ideal launch pad to create your payment flows.

Once your new project has been set up using the archetype, we can simply open the project in MPS by selecting File/Open and then navigating to <generated_archetype_root>/domain-root/mps.