How to use script connector with Bonita BPM 6
This tutorial explains how to use a script connector with Bonita BPM 6. You need to have a working Bonita BPM 6 Studio installed on your desktop. For this example we run it on a Linux distribution (Ubuntu 12.04 LTS) .
Simple example
Create a diagram and select the task where you want to put the connector. In this example we will add a connector on a human task.
Add data
First, we will add 2 transient data to store the script exit code and output.
- outout type is text (but you may use other type)
- exitCode type is integer
Add connector
At the bottom of the screen, in "General" tab, select "Connectors". Click on the "Add" button.
From "Script", choose "System script" and click on "Next".
Define a name for this connector and select when you want the connector to be executed:
- enter: at the start of the task
- finish: when the task ends
In this example we will execute the connector on "enter" in order to directly use the output of the script in the human task.
Then choose your Script interpreter, for example "/bin/bash". Define the execution parameter:
- -c for Unix if you use bash as interpreter
- /c for Windows if you use cmd as interpreter
This means that the connector will make the following call in our example "/bin/bash -c /bin/mycommand" For more details please refer to the help of the interpreter:
bash - GNU Bourne-Again SHell<br />
<br />
SYNOPSIS<br />
bash [options] [file]<br />
<br />
COPYRIGHT<br />
Bash is Copyright (C) 1989-2011 by the Free Software Foundation, Inc.<br />
<br />
DESCRIPTION<br />
Bash is an sh-compatible command language interpreter that executes commands read from the standard input or from a file. Bash also incor‐<br />
porates useful features from the Korn and C shells (ksh and csh).<br />
<br />
Bash is intended to be a conformant implementation of the Shell and Utilities portion of the IEEE POSIX specification (IEEE Standard 1003.1). Bash can be configured to be POSIX-conformant by default.<br />
<br />
OPTIONS<br />
<br />
All of the single-character shell options documented in the description of the set builtin command can be used as options when the shell is invoked. In addition, bash interprets the following options when it is invoked:<br />
-c string If the -c option is present, then commands are read from string. If there are arguments after the string, they are assigned to the positional parameters, starting with $0.<br />
[..]
Start a new CMD shell and (optionally) run a command/executable program.<br />
<br />
Syntax<br />
<br />
Syntax<br />
<br />
CMD [charset] [options]<br />
<br />
CMD [charset] [options] [/c Command] <br />
<br />
CMD [charset] [options] [/k Command] <br />
<br />
Options<br />
/C Run Command and then terminate<br />
[...]
Write your script, for example call "/bin/mycommand".
Retrieve data
To get the script output and exit code, select on the left column the data defined and map the "output" with "result" and "exitCode" with "exitStatus".
To avoid warnings you should change data types by cliking on the Edit icon 
on the right. Into the "Edit expression" window choose "Script" and change the "Return type" field. Select "java.langString" for "result" and "java.lang.Integer" for "exitStatus".
Test
Click on "Run" to start the case.
Start the "Step1"
You should see no output and the exit code 127.
The exit code 127 is a common error meaning "command not found" (see also: http://tldp.org/LDP/abs/html/exitcodes.html). It's an error that you may encounter if you use a wrong path or, in this example, a non existing command.
Parametrized script
Now we will see how to use data to parametrize a script.
Add data
Add 2 more data at the pool level:
- path: choose Text type and set the default value to "/bin"
- param1: choose Text type and set the default value to "/home"
Go to "Application" tab, and choose "Skip" to skip the start case form. Edit the script connector and replace "/bin/mycommand" by "${path}/df -h ${param1}" Note: you can type "ctrl+space" into the field in order to select data available
Test
Click on "Run" to start the case. It should show the space used on /home.
In this case the exit code is 0 as the "df" command worked well (but I need to clean out my partition ;)).
Now try treating the different exitStatus in your diagram according to your own real life usage.