Installation and usage

Installation

BPMNator is made with NodeJS and is written in TypeScript so you need to have both of them installed before you start.

There are two ways to install BPMNator. Via npm repository or cloning git repository e compiling the code.

Way 1: install via npm

If you want to use BPMNator as a library:

# (optionally) init a new NodeJS project:
npm init
# just install bpmnator locally:
npm i bpmnator

Or if you want to use BPMNator both as a library and as command-line program:

# install bpmnator globally
npm i --global bpmnator

Way 2: install from git repository

# clone repository:
git clone https://github.com/ossacolsale/bpmnator.git
# go to bpmnator directory:
cd bpmnator
# compile typescript code:
tsc
# you'll find compiled code inside "dist" folder

Usage

Once installed, you need to create one YAML-BPMNator file. For example:

name: Example process
activities:
    My first task:
        type: human
        goto: My second task
    My second task:
        type: manual
# and so on...

See the YAML syntax section of this wiki to learn every detail really soon.

Then you can use BPMNator to parse and transform your YAML in a standard BPMN 2.0 file by two main ways described as follows.

First method: the NodeJS or JavaScript or TypeScript library (class BPMNator)

You can call BPMNator from inside your JavaScript or TypeScript code:

import { BPMNator } from 'bpmnator';

const bpmnator = new BPMNator();

If you use TypeScript, you can benefit the autocompletion and all the features of .dt definitions.

Every method of the class BPMNator produces an output error in case of failure.

The methods provided by the class BPMNator must be used as follows (see also commented rows to understand every possibile alternative):

const URI = '/home/username/myProcess.yaml';
const BPMN_OUTPUT = '/home/username/myProcess.bpmn';

// first you must load YAML file, by URI or by content:
if (bpmnator.LoadYAMLbyURI(URI)) {
// if (bpmnator.LoadYAMLbyContent(content)) { //use this if you want to load directly the content of yaml file

//then you must call BuildProcess() that leads the process to an intermediate stadium between YAML and BPMN
    if (bpmnator.BuildProcess()) {   

//finally you can produce BPMN in 4 different ways:
            bpmnator.ProduceBPMN().then((bpmn_output) => doSomethingWithThe(bpmn_output)); //it's async, produce bpmn output and let you do whatever you want with it
//            bpmnator.SaveBPMN(BPMN_OUTPUT); //use this if you want to save bpmn in a specific file
//            let bpmn_output = bpmnator.ProduceBPMNWithoutDiagram(); //use this if you want to produce bpmn output without the diagram
//            bpmnator.SaveBPMNWithoutDiagram(BPMN_OUTPUT); //use this if you want to save bpmn without the diagram in a specific file

        }
    } 
}

Second method: CLI

You can also use BPMNator, with some limitations, via command line.

• If you used npm global installation just type bpmnator in your shell console.

• Else, if you used npm local installation, just make the following steps:

# go inside "bpmnator" folder in one of two possible ways:
cd node_modules/bpmnator
# execute main file:
node dist/bin/bmpnator

• If you used cloned git repository compilation

# go inside "bpmnator" folder in one of two possible ways:
cd bpmnator
# execute main file:
node dist/bin/bmpnator

The CLI provides two modes.

BPMN to stdout

bpmnator  yaml_file_uri

With only one parameter (the complete uri of yaml file), BPMNator prints the BPMN content directly to standard output.

BPMN to file

bpmnator  yaml_file_uri  bpmn_file_uri

With two parameters (the complete uri of yaml input file and the complete uri of bpmn file to write), BPMNator saves BPMN content into the file you indicate.