Latest revision as of 06:36, 23 November 2020

Bot station user guide

RunaWFE Free Workflow System (BPMS) Version 4.5.0

© 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:

And click on the bot station name

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)

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".

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.

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.

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.

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.

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

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:

Then choose a TaskHandler.

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

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

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

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.

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"

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

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:

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.

“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.

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:

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:

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

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

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

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

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

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:

“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

choose the task handler class from the list:

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

Press “OK” to save task:

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:

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:

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:

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.

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.

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

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:

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

This swimlane will be initialized by bot.

Binding bot task to the node

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

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:

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"

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

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

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

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:

Select localbotstation and press “Finish”.

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

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

Input this task name - “GetFullName”

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

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

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

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”

Performing export:

Now UniversalBot has new task GetFullName

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

Use graph elements to create the following process graph:

We will use 2 swimlanes:

For the bot swimlane we will use the following initializer:

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)

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

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

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

Select GetFullName task from the list

Next we set correspondence between formal parameters and process variables:

The process is ready for export and running.

localbotstation is started as well as bots periodic invocation:

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

The GetFullName task of UniversalBot will provide julius full name.

# 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.

Type in the bot’s name - ReportBot

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.

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

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.

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.

Check if bot is successfully exported to the WFE Server:

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:

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.

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: