WebServicesDeveloperGuide

From RunaWFE
Jump to navigation Jump to search

Web services developer guide

RunaWFE Free Workflow System (BPMS) Version 4.4.2

© 2015-2021, "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)