BotStationConfigurationGuide

Bot station configuration 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).

# Botstation configuration

Bot station configuration is located in botstation.properties

There must be a RunaWFE user that corresponds to bot station (botstation.system.username property must contain this user name). Using this user name bot station connects to WFE Server to read bot station parameters. This user login and password are placed in botstation.properties.

There must be a RunaWFE user for each bot. Using this user name bot executes tasks in the WFE Server. Bot configuration must contain login and password for this user. Bot's password must match the one of the bot user.

Permissions to work with bot station are set in "Permission owners" page. Click on the link "Permission owners" to get there:

Bot station user must have rights to read bot station:

Note: By default in botstation.properties Administrator is authorized bot station user.

# Creating TaskHandler configurations

DatabaseTaskHandler

DatabaseTaskHandler configuration is an xml file. The scheme to it can be found in the RunaWFE sourceforge repository in the bots project (resources/bot/database-tasks.xsd). Here's an example of the configuration used to insert a record into database and to call a stored procedure.

<?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:/wfebotds">
   <queries>
     <query sql="insert into OVERTIMES(INSTANCE_ID, EMPLOYEE_CODE, FROM_DATE, TO_DATE, REASON, COMMENT, CHIEF_COMMENT) values(?, ?, ?, ?, ?, ?, ?)">
       <param  var="instanceId" />
       <swimlane-param  var="employee" field="code" />
       <param  var="date_since" />
       <param  var="date_till" />
       <param  var="reason" />
       <param  var="comments" />
       <param  var="chief comments" />
     </query>
     <query sql="{CALL sp_insertShift(?, ?, ?, ?, ?)}">
       <param  var="instanceId" />
       <swimlane-param  var="employee" field="code" />        
       <swimlane-param  var="requester" field="code" /> 
       <param  var="lunch_hour" />
       <param  var="count_holidays" />
       <result var="commit" />
     </query>
   </queries>
 </task>
</database-tasks>

EmailTaskHandler

Configuration has the same syntax as appropriate handler.

StartProcessTaskHandler

StartProcessTaskHandler configuration is set in xml file. The scheme to it can be found at in the RunaWFE sourceforge repository in the bots project (resources/bot/process-start.xsd).

Example:

<?xml version="1.0" encoding="UTF-8"?>
<process-start xmlns="http://runa.ru/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://runa.ru/xml process-start.xsd">
 <process name="NewSubProcess">
   <variable from="X" to="XX"/>
   <variable from="Y" to="YY"/>
   <variable from="r" to="rr"/>
   <started-process-id variable-name="process1"/>
 </process>  
 <process name="NewSubProcess">
   <variable from="X" to="XX"/>
   <variable from="Y" to="YY"/>
   <variable from="r" to="rr"/>
   <started-process-id variable-name="process2"/>
 </process>  
</process-start>

StopProcessHandler

StopProcessHandler configuration is in xml file.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<config>
  <input>
    <param name="processId" variable="VAR" />
  </input>
</config>

Note. Mind that Bot for this handler must have stop permission for the process it is used in.

TextReportTaskHandler

TextReportTaskHandler configuration is set in xml file. The scheme to it can be found in the RunaWFE sourceforge repository in the bots project (resources/bot/textreport.xsd).

Example:

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://runa.ru/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://runa.ru/xml textreport.xsd">
 <template fileName="/bot/TextFileTemplate_demo.txt" fileEncoding="UTF8" />
 
 <report fileName="textFile.txt" fileEncoding="UTF8" variableName="resultTextFile" contentType="plain/text" />
 
 <replacements xmlFormat="true" applyToRegexp="false" />
 
</config>

In this case report template must be placed in UTF8 in file $JBOSS_HOME/server/default/conf/bot/TextFileTemplate_demo.txt.

As it is stated in the following configuration string:

<template fileName="/bot/TextFileTemplate_demo.txt" fileEncoding="UTF8" />

An example of template from the TextFileCreation demo process:

Report title: ${header}.
 number: ${number}       
 date:   ${date}
       Text: 
 ${mainText}

In the resultant file there is the business process variable value in the place of ${business_process_variable_name} from template.

The resultant file is in UTF8, is named textFile.txt and is stored in "resultTextFile" process variable.

<report fileName="textFile.txt" fileEncoding="UTF8" variableName="resultTextFile" contentType="plain/text" />

Separately in configuration the formatter and format pattern are indicated for a given variable. In this example variable "date" will be formatted with the help of ru.runa.wf.web.forms.format.DateFormat and its output will correspond day-month-year pattern with 2 digits for each item.

<report fileName="textFile.txt" fileEncoding="UTF8" variableName="resultTextFile" contentType="plain/text" />

MSWordReportTaskHandler

MSWordReportTaskHandler configuration is set in xml file. The scheme to it can be found in the RunaWFE sourceforge repository in the bots project (resources/bot/msword-report-task.xsd).

Example:

<<?xml version="1.0" encoding="UTF-8"?>
<msword-report-task xmlns="http://runa.ru/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://runa.ru/xml msword-report-task.xsd">

 <report template-path="C:\Workflow\Templates\Word\sample-template.doc" output-variable="report" output-variable-file-name="report.doc">
   <mapping bookmark="vacationDateFrom" variable="dateFrom" format-class="ru.runa.wf.web.forms.format.DateFormat" />
   <mapping bookmark="employeeFullName" variable="fullName" />
 </report>
</msword-report-task>

Bookmarks in sample-template.doc will be replaced by formated values of process variables. Sample-templated will be saved as report.doc and assigned to process variable report according to this configuration line:

<report template-path="C:\Workflow\Templates\Word\sample-template.doc" output-variable="report" output-variable-file-name="report.doc">

The report template in this case must be in C:\Workflow\Templates\Word\sample-template.doc. The bookmarks in this file are created and named as it is usually done via Word editor main menu.

To form text that replaces a bookmark variable type set in Developer Studio is used.

WebServiceTaskHandler

The WebServiceTaskHandler is designed for performing SOAP requests to web-services and for processing their responses. All task handler configurations are set in an xml file.

The root element config contains:

Elements	Description	Required
url	Sets the URL for the SOAP request	Required. Only once
SOAPAction	Sets the SOAPAction attribute value in the SOAP request	Optional. Only once
basic-authentication	Sets the Authentication attribute value in the SOAP request.	Optional. Only once
request-method	Sets the request type (POST, GET, etc.)	Optional. Only once
errorAction	Sets the behavior in case of an error. It can be overridden in the interaction element.	Optional. Only once
log	If the value is true, then the log level for the web-service request and response is debug	Optional. Only once
interaction	Describes one interaction with the web-service.	Required. Once or more

Elements of interaction element:

Elements	Description	Required
request	Sets the SOAP request that will be sent to a web-service.	Required. Only once
response	Sets the XSLT transformation that will be applied to the web-service response. Element attributes (optional) maxLength: the maximum length of the web-service response. If this length exceeded the task handler throws an exception. variable: the name of the business process variable in which the response is being stored.	Required.
errorAction	Sets up the behavior in case of an error. Can be set to one of the following values: BREAK (default value) – If an error occurs task handler stops performing the task and throws an exception. In a certain amount of time the bot's task handler code will be invoked again and all the requests will be queued for the execution again. IGNORE – If an error occurs task handler will ignore it and will pass the execution on to the next business process element. RETRY – If an error occurs the task execution is delayed. In a certain amount of time the bot's task handler will be invoked again and the sequence of requests will be queued again, but in this case only starting from the request that initiated the exception during last execution. All the variable values that were saved in task handler will be saved in business process variables.	Optional

During task handling bot executes the sequence of requests from the xml configuration file (set in interaction element). The response is saved into the variable which name is set in “variable” attribute of the response element. (If the variable name is not set then result is not saved). If the request is successfully performed, then XSLT from response element configuration is applied to the response. If request returned an error, then the error message is saved into variable that is set in “variable” attribute (If the variable name is not set then error message is not saved). After it the action from errorAction is carried out.

In XML request and in XSLT for response one can use specialized tags in order to access business process data:

• getProcessInstanceId – Returns current process id.
• getVariable(String name) – Returns a value of the variable with a given name for the current process .
• getProcessInstanceGraph(String processInstanceIdVariable)
• setNewVariable(String name, String value) – Set the value of the variable with the given name. It is used in XSLT, that is applied to the web-service response.

# Starting remote bot station

• Place jndi.properties file into classpath and edit it

# JbossAS4
# java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
# java.naming.provider.url=jnp://rtwf.rtr.ru:10099
# java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces

# JbossAS7
java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447
jboss.naming.client.ejb.context=true

• Set ejb.type property to "remote" (in wfe.delegate.properties)
• Start it

By default localbotstation is configured on WFE Server. To start a remote bot station:

• While installing remote bot station set server name and port of the main WFE Server.
• On main WFE Server create a new user with bot station name. Any new name can be used.
• On main WFE Server bot station page click on "Add bot station" and select the user with bot station name from the list. Set url to access remote bot station. Example: jnp://remotebotstationhostname:10099