BotStationUserGuide

From RunaWFE
Jump to navigation Jump to search

Bot station user guide

RunaWFE Free Workflow System (BPMS) Version 4.5.0

© 2003 - 2015, Consulting Group Runa

© 2015 - 2024, "Process Technologies" Ltd, this document is available under GNU FDL license. RunaWFE Free is an open source system distributed under a LGPL license (http://www.gnu.org/licenses/lgpl.html).


What is Bot and Bot station

In RunaWFE system the tasks can be carried out by specific applications named bots as well as by humans. Bot is a short name from robot. Every bot must have a corresponding RunaWFE user account. Every bot is registered in a bot station that periodically invokes all registered bots. Bot receives a task assigned to the corresponding user and delegates the task execution to the TaskHandler assigned for this task. After the task is completed bot reports it to the WF system and returns the values for business process variables.


Bot station is an environment for bots' work. Bots from bot station periodically check if there are tasks for them to perform. If current business process instances' states have some tasks for bots, bots perform them and return results to the WFE Server.


Bots might help to integrate heterogeneous enterprise applications into one enterprise information system. In various business processes' nodes bots interact with various enterprise information systems and return results to the process variables. This way different enterprise information systems might use business process variables in order to exchange information.


Bot station configuration

A default WFE Server configuration has one bot station in it (localbotstation) and two bots that are used in demo processes.

Bot stations and bots are configured on Bot stations page of RunaWFE web-interface. "Bot stations" option of main menu is visible for any user who has permissions to read bot stations. In order to change settings user has to have permissions to update bot station configurations.

Bot station's status can be set to on or off. That means that periodical bots invocation is on or off respectively.

Note. A bot can be called implicitly even if periodical bot invocation is not started. If BotInvokerActionHandler is added to activity node and is executed on task start then all bots are called.

How to view bostations list

Open “bot station” menu:

Ima en1 1.png


And click on the bot station name

Ima4 1.png


After clicking on bot's name in order to edit its tasks list parameters

Changing bot's details

In order to change bot's detail click on that bot name in the bots list of the bot station. Change the bot details in “Bot Details” section and click “Apply”. The changes will be applied immediately and will be used during next bot activation. System restart is NOT necessary.


Bot's details are:

  • bot's name (corresponds to user login)
  • bot's password (must match user password)
  • bot's tasks list (Task list consists of task name, a name of task handler and task handler configuration)

Ima5 1.png

How to create a bot

After bots were added to Developer Studio it became possible to export bot in botName.bot file. If this file is imported to WFE Server the bot with all its tasks is added to botstation. If there's no user with bots name while import is carried out then the bot user is added automatically. The user with bots name is automatically bound to bot. After bot import you might want to change its user and the bot passwords. They must match.

In order to import bot go to page of the botstation you want to import the bot into. (Bot stations -> botstationName) In "Deploy bot" section click browse and select .bot file exported from Developer Studio. If this bot already exists in botstation and you want to update existing tasks configurations check "Replace tasks".

Pic8 1 en.png

It's also possible to create bots in old way.

At first it's necessary to create a user that will correspond to the new bot and set a password and permissions to log in to the system for this user.

If a user has permissions to create bots, then on the bot station page this user will see an option to “Add Bot” and on the bot's page there will be “Add task” option.

To create a bot click on “Add Bot” option on the bot station page.


Pic6 en.jpg


On bot addition page it's necessary to choose the user whose tasks the bot will perform (this is the user we created for this bot earlier) and to type this user's password.


Pic7 en.png

Removing bots

In order to remove bots from bot station navigate to the bot station page, check the check boxes for the bots that you want to remove and click “Remove” button. Selected bots will be removed with their respective tasks.


Starting and stopping bots periodical invocation

Navigate to the botstations page and choose a bot station from the list. On the chosen bot station page in the “Bot station Status” section you can see if bot station itself is on (that is if bot station is found by the address that is indicated in bot station properties) and if bot station periodical invocation is on or off.

In order to start/stop periodical invocation click on the button below bot invocation status.

Pic8 en.png

Note. A bot can be called implicitly even if periodical bot invocation is not started. If BotInvokerActionHandler is added to activity node and is executed on task start then all bots are called.

Changing TaskHandler configurations

Navigate to the bot's page and find the task you want to change configuration for in the bot's tasks list. There are two ways to change configuration for this task:

  • by uploading a file with configuration with the help of “Browse” button
  • by using “edit” link that will open the current configuration in edit mode. In order of it to work correctly web-browser must support javascript

If you want to delete task, uncheck the checkbox in front of task name and click “Apply” button at the bottom of the “Tasks” section. The deleted task will disappear from the bot's task list.

See more details in Task handler configuration.

How to add a new task for bot

After bots were added to Developer Studio it's became possible to export from Developer Studio not only bot but also its individual tasks to botName.taskName.bot file.

In order to import bot task to WFE Server go to botstation which contains bot you want to add task to. (Bot stations -> botstationName). In the "Deploy bot" section choose .bot file exported from Developer Studio. If this task already exists in the system, then check "Replace tasks". Press "Deploy bot". The new task is added to the bot or previously existing task is updated.

Pic8 1 en.png

There's another way of adding a new task used for old Developer Studio/WFE Server versions.

Click on “Add” link. A new emply task will be added to bot's task list. Type in the new task name, select TaskHandler class and upload a configuration file if necessary. Then press “Apply” button at the bottom of the “Tasks” section. Changes will be activated immediately and will be used during next bot invocation.

This is described below in details:

Click on “Add” link in “Tasks” section


Pic9 en.png

Every task has a name, TaskHandler class and configuration. Task name must coincide with this task name in the process definition. TaskHandler class must implement TaskHandler interface and can be chosen from a drop-down list of all such classes. Those classes are being looked for in wfe-bots.jar and also in jar-files that are indicated in botstation.properties in taskhandler.jar.names parameter. Configuration is a text file that contains setting for task. For example for the SQL bot for tasks with DatabaseTaskHandler a configuration file contains sql query(ies) and a list of variable names from which bot takes values and to puts them into query parameters.


In the new task empty name field type the task name:

Pic10 en.png

Then choose a TaskHandler.

Pic11 en.png

And browse a configuration file for upload. Then click “Apply”.

After configuration file is uploaded it can be viewed and edited from web-interface.


Pic13 en.png

To start bots when control flow reaches activity node add "Invoke bot station" action handler on it when designing process.

Ima14 1.png

What are the TaskHandler classes

Every bot can perform a set of tasks. Every task must be linked to a TaskHandler class. TaskHandler is a java class that contains code to perform the task. Any number of bot tasks can be linked to the same TaskHandler class.

Bot's TaskHandler class must implement ru.runa.wf.logic.TaskHandler interface. It contains the following methods:

  • handle(Subject subject, TaskStub taskStub) – task handling
  • configure(String configurationName) – read configuration data from a file named configurationName
  • configure(byte[] configuration) — read configuration from database and passing it to the bot as a byte array.


There are several TaskHandlers that come along with RunaWFE system. Some of them are:

  • ru.runa.wf.logic.bot.DatabaseTaskHandler – operations on database tables
  • ru.runa.wf.logic.bot.CancelProcessTaskHandler – business process cancellation and updating any relevant data that is not in RunaWFE core system.
  • ru.runa.wf.logic.bot.DoNothingTaskHandler – simplest example of a TaskHandler
  • ru.runa.wf.logic.bot.EmailTaskHandler – sends a text via email server
  • ru.runa.wf.logic.bot.MSWordReportTaskHandler – generates MS Word file
  • ru.runa.wf.logic.bot.WebServiceTaskHandler – provides data to a third party web service.
  • ru.runa.wf.logic.bot.StartProcessTaskHandler – starts a process instance.

For DatabaseTaskHandler a configuration file must comply to database-task.xsd scheme. Driver and url attributes of “task” element must define the name of the jdbc class driver and url for connecting to the database.

Note. Url must be written in a format suitable for the named driver. Url must contain a database user name and a password for this user.


Configurations for bots that send email messages are set in .properties files in utf8 encoding. Use smtp.server property to specify SMTP server that is used to send messages. The rest of the properties correspond to email message header fields (from, to, reply.to, cc, bcc and subject).


MSWordReportTaskHandler is developed for Word bot. This task handler configuration file structure is defined by msword-report-task.xsd


For WebServiceTaskHandler all configurations must be placed into .xml files that comply to webServiceTaskHandlerConfig.xsd scheme. Main parameters are

  • url – webservice url;
  • request-method – HTTP request method (POST, GET, PUT, etc);
  • interaction (of request type)– xml that is send as a request to webservice. In this request you may use special tags in order to get information from wfe: <runawfe:variable name="variable_name"/> - returns variable value, <runawfe:processId/> - returns current process instance (id).

Working with bots and bot stations in Developer Studio

Developer Studio

Since RunaWFE 3.6 Graphic Process Designer has grown into Developer Studio. The main new feature of the Developer Studio is environment for bots and bot stations development.

Adding Bot Station

All work with bot stations, bots and their tasks is done under "Bots" tab.

En bots st pic1.png

There are two ways to add a new bot station and they are to create a new bot station or to import an existing one. You can import bot station from file or right from the RunaWFE server.

To create a new bot station right click to see the popup menu and choose "New bot station"

En bots st pic2.png

Type in the new bot station parameters such as name, RMI-address and location.

En bots st pic3.png

After pressing "Finish" button the created bot station will appear in the bot station list of the "Bots" tab.

To import a preexisting bot station use "Import bot station" menu item of the popup menu:

En bots st pic4.png

If bot station is imported from file use “Import from file”, then press "Choose", select the bot station file (with .botstation extension) and press "Open".

To import bot station from server use “Import from WFE Server”. After automatic synchronization with server you will see the list of bot stations available for import.

En bots st pic5.png

“Connection settings” is a link to dialog with WFE Server connection settings “Synchronization” will perform synchronization with WFE Server and refresh the list of available bot stations.

After pressing "Finish" button the imported bot station will appear in the bot station list of the "Bots" tab.

En bots st pic6.png

Bot station parameters can be edited. Select bot station from the list, right click on it and choose "Edit". In the dialog you will see the bot station current parameters that can be edited:

En bots st pic7.png

En bots st pic8.png

You can also delete and export bot station. Use the corresponding popup menu items or icons on the top controls panel under the main menu to do so:

En bots st pic9.png

Exporting bot station is similar to its importing. You can export bot station into file or directly to WFE Server.

En bots st pic10.png

Not only bot station but all its bots and their tasks will be exported during bot station export.

Adding bots

To add a new bot do the following:

  • select bot station,
  • right click on it,
  • choose “New bot” item

En bots st pic11.png

In the dialog type in the name of the bot and choose bot station for it:

En bots st pic12.png

After pressing “Finish” the created bot will be on the bots list of the selected bot station:

En bots st pic13.png

You can add bot to a bot station by importing it from file or WFE Server using the correspondent item from the popup menu.

En bots st pic14.png

You can do the following with existing bot:

  • rename it;
  • delete it;
  • export it (along with all its tasks).

# Bot task

Since 3.6 there are the following types of task handlers, configurations and tasks:

  • Simple task handler is a class that implements TaskHandler
  • Parametrized task handler is a class that implements ParamBasedTaskHandler.
  • Simple configuration is a configuration without any format restrictions
  • Parametrized task handler configuration is a configuration in a definite XML format
  • Extended configuration is a child configuration of simple configuration for a simple task handler. But it differs from simple configuration because it encompasses parameters.
  • Simple bot task is a task with simple bot and simple configuration;
  • Parametrized bot task is task with parametrized handler and configuration. It has fixed set of parameters and configuration format is predefined;
  • Extended bot task is a task with simple task handler and extended configuration;

It's possible to create a new task or to import preexisting one from file or WFE Server. Use popup menu or icons on the controls panel under the main menu:

En bots st pic15.png

  • “New task” is used to create a new simple bot task and parametrized tasks;
  • “New task with formal param” is used to create tasks with formal parameters (extended tasks)

Simple task

Use "New task" menu option. In case of simple task type the task name

En bots st pic16.png

choose the task handler class from the list:

En bots st pic17.png

set the task configuration by pressing "Change". Type the configuration in the opened dialog:

En bots st pic18.png

Press “OK” to save task:

En bots st pic19.png


Extended task

The creation of extended task is slightly different. Use "New task with formal param" menu option.

  • select task handler class;
  • create formal parameters for configuration;
  • create configuration;

After typing the bot task name the following editor will open:

En bots st pic20.png

As you can see along with task handler class and configuration it is necessary to add formal input and output parameters.

Press "Add" button and type the parameter name in the dialog, select the attribute (its type) from the list:

En bots st pic21.png

There're 2 checkbox options:

  • "Map this parameter to value" - if not checked then parameter is a constant value.
  • "This parameter is required" - if not checked then in parameter-variable mapping you can skip variable selection and leave it empty.


After adding all necessary input and output task handler parameters create the configuration. For example for ru.runa.wf.office.doc.DocxHandler the configuration editor form will look like this:

En bots st pic22.png

Added formal parameters are available for usage in the configuration. In this example below you can see that fileIn formal input parameter is used to set input file.

En bots st pic23.png

Parametrized task

To create parametrized task use "new task" menu item.

Type in task name.

Then choose parametrized handler from the list. For example "Add object to list", "Upload file", etc.


Bots st pic23 1.png

An unchangeable (in Developer Studio set of input and output parameters is added for the task automatically.

Bots st pic23 2.png

If you want to add new parametrized handler to Developer Studio you should provide configuration file along with handler registration. The configuration file format is fixed. More about it see adding parametrized task handler

Using bots in processes

Since 3.6 the bots usage in process has changed and it is being selected depending on the task type of the bot.

Initializing swimlane with bot

In order to use bot task in process that you develop you should create swimlane and initialize it with bot. Select the swimlane and press "Change" to do so:

En bots st pic24.png

In the dialog go to the "Bot" tab and select bot name from the "Executor by name" list. Press "Ok".

En bots st pic25.png

This swimlane will be initialized by bot.

En bots st pic26.png

Binding bot task to the node

Select the graph node and set its swimlane property to the swimlane initialized by bot.

En bots st pic27.png

Next step depends on the task type for this node (if it's simple, extended or parametrized.)

If the task is of simple type the old way of binding (that was used in earlier Developer Studio versions) works. This means the name of the task must completely coincide with the node name. In the node popup menu the "Bot task" item will lead to the task configuration:

En bots st pic28.png

If the task is of parametrized type it is not necessary for the node name to coincide with the task name. To bind task to the node right click on the node and choose "Bind"

En bots st pic29.png

You will see a dialog with the list of available tasks (extended or parametrized):

En bots st pic30.png

After the task is set it is necessary to set the correspondence between formal parameters of the task and process variables:

En bots st pic31.png

This concludes task and node binding. You can edit parameters, unbind task and go to the task configuration from the node popup menu.

En bots st pic32.png

An example of extended bot task development on the basis of SQLTaskHandler and its usage in process

A short description:

We will add a new task with formal parameters (based on SQLTaskHandler) to UniversalBot from localbotstation. We use a simple SQL query in configuration with user login as parameter and user full name as result. Then we create a process with the bot task we created earlier. To connect process task with bot task we set task formal parameters and process variables correspondence. Next we export and run the process.

Let’s import localbotstation from WFE Server: open botstation import menu, choose “Import from WFE Server”. Synchronization will be performed automatically and localbotstation will be available in the botstations list:

En bots st pic33.png

Select localbotstation and press “Finish”.

On the “Bots” tab localbotstation with all its bots and tasks will appear:

En bots st pic34.png

Let’s add a new extended task to UniversalBot. In this bot context menu choose “New bot task with formal param”

En bots st pic35.png

Input this task name - “GetFullName”

En bots st pic36.png

Select ru.runa.wf.logic.bot.SQLTaskHandler as task handler

En bots st pic37.png

Next we create formal parameters and task handler configuration. There’s one input parameter. Press “Add” and type parameter name and attribute:

En bots st pic38.png

There’s one output parameter. Let’s add it too:

En bots st pic39.png

For both parameters their attribute (type) is String

Next let’s set the handler configuration:

<?xml version="1.0" encoding="UTF-8"?>
<database-tasks xmlns="http://runa.ru/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://runa.ru/xml database-tasks.xsd"> 
 <task datasource="java:/DefaultDS"> 
   <queries> 
     <query sql="SELECT FULL_NAME FROM EXECUTORS WHERE NAME=?"> 
       <param var="ParamName"/> 
       <result var="Result"/> 
     </query> 
   </queries> 
 </task> 
</database-tasks>

In the configuration above:

  • datasourse is a jndi name of data source that is registered on server (for boss prefix java:/ is used);
  • query sql is a sql query to DB which performs select of user full name by user login. Question mark is used in place of query input parameter;
  • param var is the name of input formal parameter;
  • result var is the output formal parameter which will contain the result of the query (full user name);

Let’s save the developed task. Next we will export it to the WFE Server. Select it in the list, right click for the context menu, choose “Export bot task”

En bots st pic40.png

Performing export:

En bots st pic41.png

Now UniversalBot has new task GetFullName

En bots st pic42.png

Let’s develop the process. Create new process named SqlProcTask

En bots st pic43 1.png

Use graph elements to create the following process graph:

En bots st pic44.png

We will use 2 swimlanes:

En bots st pic45.png

For the bot swimlane we will use the following initializer:

En bots st pic46.png

In the “Start” element and in OutputFullName node select swimlane1. It will be initialized by the process starter. In the “Task” node choose bot swimlane. Create process variables: name (String), full (String)

En bots st pic47 1.png

In the start node create a form with user login input. Use the FTL “InputVariable” and variable “name”:

En bots st pic48 1.png

In “Output FullName” node create a form for user full name output. Use the “DisplayVariable” tag, and output “name” and “full” variables:

En bots st pic49 1.png

Now consider bot task. Select node “Task” and right click for context menu, select “Bot task > Bind”

En bots st pic50.png

Select GetFullName task from the list

En bots st pic51.png

Next we set correspondence between formal parameters and process variables:

En bots st pic52.png

The process is ready for export and running.

localbotstation is started as well as bots periodic invocation:

En bots st pic53.png

Start SqlProcTask process. Input user name "julius" and press start.

En bots st pic54.png

The GetFullName task of UniversalBot will provide julius full name.

En bots st pic55.png

En bots st pic56.png

# An example of extended bot task development on the basis of MSWordReportTaskHandler

A short description:

We will create a new bot on localbotstation, add a task with formal parameters based on ru.runa.wf.logic.bot.MSWordReportTaskHandler. Then we will develop a new process utilizing this bot task.

A short scenario of process execution:

User types in data (a text message and sum), then action handler determines current date and time. Next bot task is executed with report.doc file as a result. The file will contain user data and report creation date. Next node will provide user access to the file download link.

Let’s create ReportBot in the localbotstation , open the “Bots” tab and select localbotstation (see how to import localbotstation in the previous example with SQLTaskHandler), right click for the context menu and select “New bot” option.

En bots st pic57.png

Type in the bot’s name - ReportBot

En bots st pic58.png

Let’s add a bot task. Select bot, then select “New bot task with formal params” from the context menu. Type in GenerateReport in the task name field.

En bots st pic59.png

Now select task handler class – MSWordReportTaskHandler, and add formal input and output parameters

En bots st pic60.png

Add input parameters:

  • ParamMsgString (String type);
  • ParamSumDouble (Double type);
  • ParamCreaDate (Date type)

Add output parameters FileOut (File type), and edit task handler configuration in configurator.

En bots st pic61.png

Here type in the path to the result word document template (template creation is described later on), the name of report file and output formal parameter FileOut.

Now add the correspondence between formal parameters and template bookmarks from report-template.doc:

ParamMsgString – Msg
ParamSumDouble – SumDouble
ParamCreaDate – CreaDate

Save the created task and export it along with the bot to WFE Server: select ReportBot in the list and then select “Export bot” from the context menu.

En bots st pic62.png

Check if bot is successfully exported to the WFE Server:

En bots st pic63.png

Now lets prepare report-template.doc template and save it in (runa installation dir)/server/standalone/wfe.custom/bot ,

For example, In case you use Simulator the path will be:

C:\Program Files\RunaWFE\Simulation\standalone\wfe.custom\bot

Create doc file report-template.doc with the following contents:

En bots st pic64.png

Create bookmarks in the template. In order to do it in MS Word, for example, select one by one Msg, SumDouble and CreaDate followed by selecting “Insert”/”Bookmark” each time from the menu, in the bookmarks dialog type in the bookmark name ( Msg, SumDouble, CreateDate). Bookmarks names must coincide with what is indicated in the GenerateReport task configuration.

En bots st pic65.png

MSWordReportTaskHandler will create report.doc file from the template we created, and bookmarks will be substituted by variables values from the process where the task is used.

Let’s create WordReportProc process:

En bots st pic66 1.png

Add swimlanes:

En bots st pic67.png

Use initializer for the bot:

En bots st pic68.png

Select swimlane1 for swimlane in “Start” node and in “Read Report” node and bot in “Task” node.

Create variables necessary for the report:

En bots st pic69 1.png

Use form created for “Start” element to input message and Sum variables:

En bots st pic70 1.png

On the transition to “Task” node add ExecuteFormulaActionHandler action handler with the following configuration:

En bots st pic71.png

Thus in CreationDate variable the current date and time will be stored

Bind bot task to “Task” node by selecting “Task” node on the graph then “Bot task > Bind” from the context menu.

En bots st pic72 1.png

Select GenerateReport task:

En bots st pic73.png

Set formal parameters and variables correspondence:

En bots st pic74.png

In “Read Report” node create form with ftl tag “Download file”

En bots st pic75.png

The process is ready for export to WFE Server and execution:

Run WordReportProc and input data, then press “Start”

En bots st pic76.png

When control flow comes to the GenerateReport task it is performed by ReportBot and report.doc is created.

En bots st pic77.png