Handlers

Using handlers

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

GroovyActionHandler

This action handler is used to recount the values of business process variables. You must provide valid groovy code (See details) in the configuration for this handler. Groovy language is based on Java.

Configuration examples:

My_date = new java.util.Date();
My_rnd = new java.util.Random(1000).nextInt();
My_time = java.lang.System.currentTimeMillis();

int n = Integer.parseInt(multNumber);
String[] array = new String[n];
for (int i=0; i < n; i++) {
    array[i] = "book "+i;
};
multArray = array;

The variables that change their values in the configuration script change them in the business process instance. Note that only those variables that defined in the business process are changed. Variables declared only in the namespace of the script are not saved in business process.

ExecuteFormulaActionHandler

ExecuteFormula is a universal ActionHandler that can change variable value. ExecuteFormulaDemo demo process was developed to illustrate this action handler usage. Action handlers are placed in transitions between nodes. If you point cursor to the action handler icon on the process you can see the formula that is used in configuration. In order to edit the formula click on button near the "Configuration" property on the "Properties" tab:

In the configuration dialog type in an expression: 'variable name' = expression

You can use the following operators in formula: +, -, *, /, <, <=, ==, !=, >, >=, &, |, ^.

Multiplication and division have the highest priority (4). Addition and subtraction have priority of 3. Comparison has priority of 2. Boolean operators «&» (and), «|» (or) и «^» (xor) have the lowest priority.

If there are spaces in the variable name then enclose it into single quotation marks.

Besides variables you can use values of types Long, Double, Boolean, String, Date and function.

For example there are date(date), time(date) and hours_round_up(number) functions

• date(date) discards time and leaves only date.
• time(date) discards date and leaves only time.
• hours_round_up(number) rounds up time in minutes to hours upwards.
• round(number) or round(number, number of digits after decimal point) rounds up the number leaving the fixed number of digits after decimal point.
• round_up(number) or round_up(number, number of digits after decimal point) rounds up number upwards.
• round_down(number) или round_down(number, number of digits after decimal point) rounds up number downwards.
• get_process_id() - returns the id of current process instance
• random() - random number from 0 to 1

Examples:

variable1 = 2

variable2 = 3.1415926535

variable3 = true

variable4 = "string"

variable5 = " \" " (if you want to use quotation mark put back slash '\' before it)

variable6 = 01.09.2008

variable7 = '01.09.08 18:00' (enclose date with single quotation marks)

variable8 =round_up(2.564367, 3) (variable8 = 2.565)

'current date' = current_date()

'time' = current_time()

'date and time' = current_date_time()

There are also functions that are specific for the Russian language. (See the Russian version of this document).

# SQLActionHandler

SQLActionHandler is used to perform sql operation on data base data. You can read data from db into business process variables or write values of business process variables into db. You can perform several queries in one SQLActionHandler

Creating SQLActionHandler:

• Check "show handlers" option to be active in upper properties menu.
• Choose "action handler" from the palette menu. Place a new action handler on a chosen transition. Select created action handler circle in the graph.
• Choose SQLActionHandler as handler class in the properties tab below the graph.
• Create configuration for the handler: open the configuration dialog by pressing a right hand side button in the properties tab below the handler class line.

The configuration window:

DataSource (JDNI name) is the name of datasource registrated on the application server where the business process will be instantiated. The usual prefix for jboss appserver is java:/

Press Add SQL query link to add new sql query:

SQL query contains a parametrized SQL query line, mapping of SQL parameters to business process variables and mapping of the SQL result to the business process variables. Mind that the quantity of the query parameters (marked with ?) in the query line must exactly match the number of variables you add in "SQL parameters". And the number of enumerated table columns in the query line must match the number of SQL result variables.

Query can be taken from variable. Write ${query1} in configurator query line, where query1 is a string variable with sql query formed in business process as its value..

AssignSwimlaneActionHandler

It is used to assign and reassign swimlane in any moment in the process according to a given configuration. The configuration is the same as for swimlane edit.

SendEmailActionHandler

It is used for email message sending. A task ftl-form can be placed into the message body if the ActionHandler is placed on process node and not on transition. Another way of sending email message is to use SendEmailTaskHandler. The configuration format for SendEmailTaskHandler is the same as for the SendEmailActionHandler.

There is a specialized configurator that can be used to create a SendEmailActionHandler configuration. In order to open it first create an ActionHandler and choose SendEmailActionHandler from the available handlers list, then begin configuration edit. The xml text of the configuration can be view on the XML tab of the configurator. The JavaMail is used to send the email, the tables with additional parameters can be found in the packages using the link above.

Configurator static fields

"Common" tab

Do not continue the process execution if error while sending the message occurs.

• true: on error the process rolls back to the previous state.

• false: on error the process proceeds to the next state, the error is logged.

- (path to the file) path to the file with basic email sending configuration relative to the RunaWFE server configuration folder (jboss/server/default/conf). This file contains the same configurations that are available on the "Server Connection" and "Message Attributes" configurator tabs in the same format. This helps to configure several email handlers that share the same configuration values. Parameter values set in the file can be overridden by the parameters set in configurator.

"Server Connection" tab

(in this tab it is possible to use variables in the form fields e.g. ${variableName})

- Mail protocol: email server protocol name

- Host: IP address and name of email server host

- Port: Email server port

- Use authentication: Outgoing email server demands authentication check

- Debug: if it is on all the information about communication with email server is logged

- Additional connection parameters: any valid javamail parameters can be added.

"Message Attributes" tab

(in this tab it is possible to use variables in the form fields e.g. ${variableName})

- Subject: the subject of the message

- To: recipient email address

- Cc: "send copy to" email address

- Additional message parameters: any valid javamail parameters can be added.

"Content" tab

- Use body from form: the check box is available only if the SendEmailActionHandler is placed on the node, there's a form for this node, and this form is of ftl (freemarker) type.

- Insert Variable: This link helps to insert variable value to the message content body. Freemarker syntax can be used in the form text, it can be copied from the ftl-form. Also images inline insertion is available in the content body.

- Attachments: allows to add attachments to the mail (FileFormat).

"XML" tab

Here the configuration file content in xml format can be viewed.

Buttons:

- Send test message: sending a test message with the set parameters right from the Developer Studio. If file with configurations is indicated then the test message will not be sent.

- Copy: copy configuration into buffer (same as with Ctrl-C)

- Finish: save configuration

- Cancel: cancel edit

# ActorNameActionHandler (depricated since v4.0.0, use GetExecutorInfoHandler instead)

Note. It is deprecate since version 4.0.0. Use GetExecutorInfoHandler instead.

Allows to add employee login or full name to the process instance variables by code or login. To set action handler parameters use configurator in Developer Studio.

In configurator form choose the variable with the employee code or login as input values for the action handler. Then choose the result data format:

• name - for employee login

• full name - for employee full name

Also choose the name of the variable to which the result value is saved.

BotInvokerActionHandler

Invokes botstation.

Configuration contains address of the botstation. Empty configuration means local botstation.

EscalationActionHandler

Expands task swimlane executors using dynamic group.

Additional executors are determined by orgfunction from handler configuration.

AddObjectToListActionHandler

Adds variable to list.

RemoveObjectFromListActionHandler

Removes variable to list.

CreateOptionActionHandler

Creates new variable of type ru.runa.wf.web.Option (it can be used in MultiSelectTag).

# Excel/Word Action handlers

Excel and Word action handlers are used for work with .xlsx and .docx files. Those handlers are based on Apache POI library.

Apache POI is a java library for reading and writing Excel, PowerPoint and Word documents.

To read data from .xlsx office.excel.handler.ExcelReadHandler is used. To write data to .xls files office.excel.handler.ExcelSaveHandler is used. For .docx doc.DocxHandler is used.

excel.handler.ExcelReadHandler

Allows to read data from xlsx files. The following form is used to configure the handler:

In “Input file” a path to file or file variable is indicated.

Example:

“Add cell” - adds the following parameters to read data from the given cell:

1). “Variable” – a variable to which the data from the cell will be saved;

2). “Page” – name or number of the page with the given cell;

3). “Column/Row” – the cell address (numbers from 1 to 999999999);

“Add horizontal”/ “Add vertical” – adds parameters to read arrays of corresponding data horizontally or vertically:

1). “Variable” – array variable of "List" type to which the data from the cells array will be saved;

2). “Page” – sets name or number (start with 1) of the page with the given array;

3). “First Column”/“Row”, “Column/First Row” – the address of the cell starting from which the array will be read (a row horizontally, a column vertically), numbers start with 1;

Example:

The handler will read file “input.xls” from \\SRV\nfsshared\ folder

The contents of cell from second column of row 1 from page "Sheet5" will be saved into variable "Cell1".

The contents of 3rd row starting from column 1 from page number 1 will be saved into "list1" variable.

The contents of column 7 starting from row 4 from Sheet1 page will be saved into "list2".

Handler configuration can be also set in xml, for example:

excel.handler.ExcelSaveHandler

This handler is used to write data into .xlsx files and has the following form for parameters configuration:

Parameters:

“Input file” is a template that is used to prepare the output file. It can be set via file variable or via absolute path to the file.

Example. The template is the following:

The output file is the following:

“Output file” – the result file to which the data is saved. Here the file name and path are set separately, but the file variable can also be used. Example:

“Add cell”, “Add horizontal”, “Add vertical” – adds parameters to write variable to a cell, array to horizontal cell range, array to vertical call range respectively. Parameters and number ranges are the same as for configuration of excel.handlers.ReadHandler

Example:

Input file (template) c:/in/sample.xls is used to create c:/out/Result.xls, with Sheet1 formed as follows:

• variable “Cell1” value will be placed in column 1: row 1 cell.

• array “list1” (column 2: first row 1):

• array “list2” (first column 3: row 1)

doc.DocxHandler

This handler is used for work with docx files on the template basis. Docx template handler description

The handler configuration can be made in the following:

"Input file" is a file with a template that is used for the output docx file creation. It can be specified as file variable or absolute path to the file. It is also possible to create/import a file with template right into a business process.

"Output file" is a file name and folder where output docx file will be created. A file variable can also be used here.

If "Throw an error if template isn't a match" is checked the input file check for correspondence to configuration will be carried out and if some variables are missing or named differently there will be an error thrown during handler execution and the output file will not be formed.

# Create date variable

Class name: ru.runa.wfe.extension.handler.var.CreateCalendarHandler

Modifies or creates date variable using multiple "add" and "set" operations with calendar fields. You can inject integer variable value using placeholder ${variable}. For "add" operation business calendar time is supported.

# Add read process permissions

Class name: ru.runa.wfe.extension.handler.process.AddReadProcessPermissionsHandler

Adds READ permission to current process instance for given executors (actors or groups).

Parameters

name	type	description
Executors	One or more executors (organized as list) expected	In case of null variable value nothing happens. In case of executor already has read permission nothing happens.