Web services developer 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).

# Introduction

Web services are started automatically during WFE Server start up. Web services are located in wfe-service-4.X.X.jar.

Web services API in RunaWFE version 4 and Java API are the save but for several methods with signatures that contain complex structures and Maps (java.util.Map) because of web services limitations.

Replace 4.X.X to your version number in the whole document to form correct URLs.

# Determining WFE Server version

Service URLs include WFE Server version number. It can be acquired from http://host:port/wfe/version (no authentication is needed).

# Web services access URLs

# Jboss4

http://host:port/runawfe-wfe-service-4.X.X/WebServiceName?wsdl

# Jboss7 and WildFly

http://localhost:8080/wfe-service-4.X.X/WebServiceName/InterfaceName?wsdl

Service name and description	local WSDL	link to methods (and operations) description
AuthenticationServiceBean user authentication service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
AuthorizationServiceBean Operations authorization (permissions check) service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
BotServiceBean Botstations, bots and tasks management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
DefinitionServiceBean Process definitions management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ExecutionServiceBean Process instances and process control flow management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
TaskServiceBean Tasks management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ExecutorServiceBean Users and groups management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ProfileServiceBean User profiles management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
RelationServiceBean Relations management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
SystemServiceBean System management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ScriptingServiceBean Remote scripts execution service (on Server side)	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
SubstitutionServiceBean Substitution rules and criteria management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
BotInvokerServiceBean ^4.2.0+ Bot station management: start, stop, acquire status	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ReportServiceBean Reports management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
DataSourceServiceBean Datasources management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
ChatServiceBean Chat management service	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file
AuditServiceBean System and executions logs	WSDL for Jboss4 WSDL for WildFly и Jboss7	Open file

# Variables ^4.1.0+

Implementation of complex user types caused variables management to change (including simple variable types).

The following attributes are filled while getting variables:

Name	Value
name	variable name
scriptingName	variable name for scripts
format	variable type simple variable types are: (string, text, integer, double, bigdecimal, boolean, date, datetime, time, file) executor variable types are: (executor, user, group) complex types are: (list(?), map(?, ?)) with component types indicated instead of question marks. for executor types a descripton is formed based on attributes in JSON format
value	variable value in JSON format

For operations that send variables only name and value attributes must be filled. The rest of the attributes are acquired from the process definition.

Value of file type is represented as following with byte array in Base64 encoding:

{
 "fileName": "test.txt",
 "contentType": "text/plain",
 "data": "IyEvdXNyL2Jpbi9lbnYgcHl0aG9uCgo="
}

Executor types (executor, user, group) values are represented as following:

{
 "id": 44,
 "name": "kermit",
 "fullName": "Kermit Alex"
}

Only id or name must be filled to send variable.

# Examples

# Web service call in Java

wfe-webservice-client project is created to auto-generate client library on the basis of server services. You can find usage examples here or in project src/test/java folder.

Project can be build with the wfe-webservice-client command in project:.

mvn clean install -Dappserver=jboss7 -Dmaven.test.skip=true

Before building it's necessary to run Server (wsconsume utilite is used).

You can also generate web service client classes with the help of wsconsume.bat(sh) JBoss utilite. Also a already generated client classes with source (runawfe-ws-client.4.X.X.jar) are available here After that it's necessary to add classes to classpath and use thier API.

# Get user tasks

Пример:

   public static void main(String[] args) {
       try {
           AuthenticationAPI authenticationAPI = new AuthenticationWebService().getAuthenticationAPIPort();
           User user = authenticationAPI.authenticateByLoginPassword("Administrator", "wf");
           TaskAPI taskAPI = new TaskWebService().getTaskAPIPort();
           List<WfTask> tasks = taskAPI.getTasks(user, null);
           System.out.println("TASKS = " + tasks.size());
           for (WfTask task : tasks) {
               System.out.println(" Task " + task.getName() + " assigned to " + task.getOwner().getName());
           }
       } catch (Exception e) {
           e.printStackTrace();
       }
   }

# Commands for working with signals

Commands for working with signals were added to execution service in RunaWFE 4.4.1

boolean signalReceiverIsActiveWS(User user, Map<String, String> routingData) - can the signal be processed immediately (is there at least one active CatchEventNode receiver)

void sendSignalWS(User user, Map<String, String> routingData, Map<String, ?> payloadData, long ttlInSeconds) - sending signal to receivers (CatchEventNode)

Example of a business process with catch event node. Properties to route message - processDefinitionName=${currentDefinitionName}. File:Sample1655.par

Sample for testing

active catch event with the following routing properties "processDefinitionName"="sample1655-unknown" and "processDefinitionName"="sample1655".
sending signal to CatchEventNode receiver in "sample1655"

   public static void main(String[] args) {
       try {
           AuthenticationAPI authenticationAPI = new AuthenticationWebService().getAuthenticationAPIPort();
           User user = authenticationAPI.authenticateByLoginPassword("Administrator", "wf");
           ExecutionAPI executionAPI = new ExecutionWebService().getExecutionAPIPort();
           {
               List<StringKeyValue> routingData = new ArrayList<>();
               routingData.add(create("processDefinitionName", "sample1655-unknown"));
               System.out.println(executionAPI.signalReceiverIsActiveWS(user, routingData));
           }
           {
               List<StringKeyValue> routingData = new ArrayList<>();
               routingData.add(create("processDefinitionName", "sample1655"));
               System.out.println(executionAPI.signalReceiverIsActiveWS(user, routingData));
           }
           {
               List<StringKeyValue> routingData = new ArrayList<>();
               routingData.add(create("processDefinitionName", "sample1655"));
               List<StringKeyValue> payloadData = new ArrayList<>();
               payloadData.add(create("stringValue", "sample"));
               payloadData.add(create("datetimeValue", "17.02.2020 15:17:44"));
               executionAPI.sendSignalWS(user, routingData, payloadData, 1);
           }
       } catch (Exception e) {
           e.printStackTrace();
       }
   }
   private static StringKeyValue create(String key, String value) {
       StringKeyValue kv = new StringKeyValue();
       kv.setKey(key);
       kv.setValue(value);
       return kv;
   }

# Example of Python web service call

You can use suds library to interact with the Server via web services.

File:Demo variables test.par

Note. In the following scripts it's necessary to change version for your actual server version

Process start

import suds
authentication = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/AuthenticationServiceBean?wsdl")
user = authentication.service.authenticateByLoginPassword("Administrator", "wf");
execution = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/ExecutionServiceBean?wsdl")
variable1 = execution.factory.create('{http://impl.service.wfe.runa.ru/}variable')
variable1.name="string"
variable1.value="Test"
variable2 = execution.factory.create('{http://impl.service.wfe.runa.ru/}variable')
variable2.name="date"
variable2.value="2012-01-01"
variable3 = execution.factory.create('{http://impl.service.wfe.runa.ru/}variable')
variable3.name="number"
variable3.value=2012
variable4 = execution.factory.create('{http://impl.service.wfe.runa.ru/}variable')
variable4.name="executor"
variable4.value="{\"id\":1}"
print execution.service.startProcessWS(user, "demo variables test", [variable1, variable2, variable3, variable4])

Receiving form by definition id and node id

import suds
import base64
authentication = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/AuthenticationServiceBean?wsdl")
user = authentication.service.authenticateByLoginPassword("Administrator", "wf");
definition = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/DefinitionServiceBean?wsdl") 
execution = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/ExecutionServiceBean?wsdl") 
processDefinition = definition.service.getLatestProcessDefinition(user, "demo variables test")
interaction = definition.service.getTaskNodeInteraction(user, processDefinition.id, "ID1")
print base64.b64decode(interaction.formData).decode("utf-8")

Receiving variables definition list in process definition

import suds
import base64
authentication = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/AuthenticationServiceBean?wsdl")
user = authentication.service.authenticateByLoginPassword("Administrator", "wf");
definition = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/DefinitionServiceBean?wsdl") 
processDefinition = definition.service.getLatestProcessDefinition(user, "demo variables test")
variables = definition.service.getVariableDefinitionsWS(user, processDefinition.id)
print variables

Receiving process instance variables list

import suds
import base64
authentication = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/AuthenticationServiceBean?wsdl")
user = authentication.service.authenticateByLoginPassword("Administrator", "wf");
execution = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/ExecutionServiceBean?wsdl")
print execution.service.getVariablesWS(user, 46)

Refreshing process instance variables

import suds
import base64
authentication = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/AuthenticationServiceBean?wsdl")
user = authentication.service.authenticateByLoginPassword("Administrator", "wf");
execution = suds.client.Client("http://localhost:8080/runawfe-wfe-service-4.X.X/ExecutionServiceBean?wsdl")
variable = execution.factory.create('{http://impl.service.wfe.runa.ru/}variable')
variable.name = "editors"
variable.value = "[\"Scaners\", \"Ports\", \"Enumerators\"]"
print execution.service.updateVariablesWS(user, 46, variable)

WebServicesDeveloperGuide

Contents

# Introduction

# Determining WFE Server version

# Web services access URLs

# Jboss4

# Jboss7 and WildFly

# Variables ^4.1.0+

# Examples

# Web service call in Java

# Get user tasks

# Commands for working with signals

# Example of Python web service call

Process start

Receiving form by definition id and node id

Receiving variables definition list in process definition

Receiving process instance variables list

Refreshing process instance variables

Navigation menu

Search

WebServicesDeveloperGuide

# Introduction

# Determining WFE Server version

# Web services access URLs

# Jboss4

# Jboss7 and WildFly

# Variables 4.1.0+

# Examples

# Web service call in Java

# Get user tasks

# Commands for working with signals

# Example of Python web service call

Process start

Receiving form by definition id and node id

Receiving variables definition list in process definition

Receiving process instance variables list

Refreshing process instance variables

Navigation menu

Search

# Variables ^4.1.0+