JBoss.orgCommunity Documentation

Chapter 17. Remote API

17.1. Remote Java API
17.1.1. Remote REST Java API Client Configuration
17.1.2. Remote JMS Java API Client Configuration
17.1.3. Remote CommandWebService Java API Client Configuration
17.1.4. Supported methods
17.2. REST
17.2.1. Runtime calls
17.2.2. Task calls
17.2.3. Deployment Calls
17.2.4. Deployment call details
17.2.5. Execute calls
17.2.6. REST summary
17.3. REST Query API
17.3.1. URL layout
17.3.2. Query Parameters
17.3.3. Parameter Table
17.3.4. Parameter examples
17.3.5. Query Output Format
17.4. JMS
17.4.1. JMS Queue setup
17.4.2. Using the remote Java API
17.4.3. Example JMS usage
17.5. Additional Information
17.5.1. REST Serialization: JAXB or JSON
17.5.2. Sending and receiving user class instances
17.5.3. Including the deployment id
17.5.4. REST Pagination
17.5.5. REST Map query parameters
17.5.6. REST Number query parameters
17.5.7. Runtime strategies

The workbench contains an execution server (for executing processes and tasks), which also allows you to invoke various process and task related operations through a remote API. As a result, you can setup your process engine "as a service" and integrate this into your applications easily by doing remote requests and/or sending the necessary triggers to the execution server whenever necessary (without the need to embed or manage this as part of your application).

Both a REST and JMS based service are available (which you can use directly), and a Java remote client allows you to invoke these operations using the existing KieSession and TaskService interfaces (you also use for local interaction), making remote integration as easy as if you were interacting with a local process engine.

17.1. Remote Java API

The Remote Java API provides KieSession, TaskService and AuditService interfaces to the JMS and REST APIs.

The interface implementations provided by the Remote Java API take care of the underlying logic needed to communicate with the JMS or REST APIs. In other words, these implementations will allow you to interact with a remote workbench instance (i.e. KIE workbench or the jBPM Console) via known interfaces such as the KieSession or TaskService interface, without having to deal with the underlying transport and serialization details.

The first step in interacting with the remote runtime is to use a RemoteRuntimeEngineFactory static newRestBuilder(), newJmsBuilder() or newCommandWebServiceClientBuilder() to create a builder instance. Use the new builder instance to configure and to create a RuntimeEngine instance to interact with the server.

Each of the REST, JMS or WebService RemoteClientBuilder instances exposes different methods that allow the configuration of properties like the base URL of the REST API, JMS queue locations or timeout while waiting for responses.

The Remote Java API provides clients, not "instances"

While the KieSession, TaskSerivce and AuditService instances provided by the Remote Java API may "look" and "feel" like local instances of the same interfaces, please make sure to remember that these instances are only wrappers around a REST or jMS client that interacts with a remote REST or JMS API.

 

This means that if a requested operation fails on the server, the Remote Java API client instance on the client side will throw a RuntimeException indicating that the REST call failed. This is different from the behaviour of a "real" (or local) instance of a KieSession, TaskSerivce and AuditService instance because the exception the local instances will throw will relate to how the operation failed. Operations on a Remote Java API client instance that would normally throw other exceptions (such as the TaskService.claim(taskId, userId) operation when called by a user who is not a potential owner), will now throw a RuntimeException instead when the requested operation fails on the server.

 

Also, while local instances require different handling (such as having to dispose of a KieSession), client instances provided by the Remote Java API hold no state and thus do not require any special handling.

 

Finally, the instances returned by the client KieSession and TaskService instances (for example, process instances or task summaries) are not the same (internal) objects as used by the core engines. Instead, these returned instances are simple data transfer objects (DTOs) that implement the same interfaces but are designed to only return the associated data. Modifying or casting these returned instances to an internal implementation class will not succeed.

The following is a simple example of creating a REST-based client. The appName variable in the code below will be either "business-central" or "kie-wb" dependending on whether you’re using product or community.

        String deploymentId = "com.burns.reactor:homer:1.0";
        String serverInstanceUrl = "http://localhost:8080/" + appName;

        RuntimeEngine engine = RemoteRuntimeEngineFactory.newRestBuilder()(1)
            .addDeploymentId(deploymentId)                 (2)
            .addUrl(new URL(serverInstanceUrl))
            .addUserName("homer")
            .addPassword("d0nut5R!!!")
            .build();                                      (3)

        KieSession kieSessionClient = engine.getKieSession();

1

Create the appropriate builder instance. The method .newJmsBuilder() is available to create JMS based builder instances

2

Call the appropriate methods and pass the appropriate parameters to configure the client

3

"Build" or instantiate the actual client RuntimeEngine instance which you can then use to interact with the server

Each builder has a number of different (required or optional) methods to configure a client RuntimeEngine instance.

Remote Rest Runtime Engine Builder methods

addDeploymentId(String deploymentId) when

Set the deployment id of the deployment

Required when:
doing an operation on a client instance that affects a process instance
addExtraJaxbClasses(Class…​ extraJaxbClasses ) when

Add extra classes to the classpath available to the serialization mechanisms

When passing instances of user-defined classes in a Remote Java API call, it’s important to use this method first to add the classes so that the class instances can be serialized correctly.

Required when:
passing custom class instances as arguments to an operation on a client instance
addPassword(String password) always
Set the password of the user connecting to the server
addProcessInstanceId(long process) when

Set the process instance id of the deployment

Required when:
interacting with a PER_PROCESS_INSTANCE deployment
addTimeout(int timeoutInSeconds)

Set the timeout for the REST call

The default is 5 seconds.

addUrl(URL serverInstanceUrl) always

Set the URL for the application instance

This should be a URL that roughly corresponds to http://server:port/business-central/ or http://server:port/kie-wb/ .

addUserName(String userName) always
Set the name of the user connecting to the server
clearJaxbClasses()
Clears the list of (user-defined) Classes that the client instance should know about

The following example illustrates how the Remote Java API can be used with the REST API.

public void startProcessAndHandleTaskViaRestRemoteJavaAPI(URL serverRestUrl, String deploymentId, String user, String password) {
        // the serverRestUrl should contain a URL similar to "http://localhost:8080/jbpm-console/"
        
        // Setup the factory class with the necessarry information to communicate with the REST services
        RuntimeEngine engine = RemoteRuntimeEngineFactory.newRestBuilder()
        .addUrl(serverRestUrl)
        .addTimeout(5)
        .addDeploymentId(deploymentId)
        .addUserName(user)
        .addPassword(password)
        // if you're sending custom class parameters, make sure that
        // the remote client instance knows about them!
        .addExtraJaxbClasses(MyType.class)
        .build();
        
        // Create KieSession and TaskService instances and use them
        KieSession ksession = engine.getKieSession();
        TaskService taskService = engine.getTaskService();
        
        // Each operation on a KieSession, TaskService or AuditLogService (client) instance
        // sends a request for the operation to the server side and waits for the response
        // If something goes wrong on the server side, the client will throw an exception.
        Map<String, Object> params = new HashMap<String, Object>();
        params.put("paramName", new MyType("name", 23));
        ProcessInstance processInstance
        = ksession.startProcess("com.burns.reactor.maintenance.cycle", params);
        long procId = processInstance.getId();
        
        String taskUserId = user;
        taskService = engine.getTaskService();
        List<TaskSummary> tasks = taskService.getTasksAssignedAsPotentialOwner(user, "en-UK");
        
        long taskId = -1;
        for (TaskSummary task : tasks) {
        if (task.getProcessInstanceId() == procId) {
        taskId = task.getId();
        }
        }
        
        if (taskId == -1) {
        throw new IllegalStateException("Unable to find task for " + user +
        " in process instance " + procId);
        }
        
        taskService.start(taskId, taskUserId);
        
        // resultData can also just be null
        Map<String, Object> resultData = new HashMap<String, Object>();
        taskService.complete(taskId, taskUserId, resultData);
        }

When configuring the remote JMS client, you must choose one of the following ways to configure the JMS connection:

  1. Pass the ConnectionFactory instance and the KieSession, TaskService and Response Queue instances when configuring the remote java client. To do that, please use the following methods:

  2. or pass a remote InitialContext instance that contains references to the necessary ConnectionFactory and Queue instances (see previous bullet).

  3. or pass a String with the hostname of the JBoss EAP server that KIE Workbench is running on

In addition, if you are doing an operation on a task via the remote JMS client (and are not using the disableTaskSecurity() method), then you must also configure SSL. The following methods (described in more detail below) are available for this:

The following example illustrates how to configure a Remote Java API JMS client using instances of the ConnectionFactory and Queue classes.

private static final String CONNECTION_FACTORY_NAME = "jms/RemoteConnectionFactory"; 1
          private static final String KSESSION_QUEUE_NAME = "jms/queue/KIE.SESSION";
          private static final String TASK_QUEUE_NAME = "jms/queue/KIE.TASK";
          private static final String RESPONSE_QUEUE_NAME = "jms/queue/KIE.RESPONSE";
          
          public void startProcessViaJmsRemoteJavaAPI(String hostname, int jmsConnPort,
          String deploymentId, String user, String password,
          String processId) throws NamingException {
          
          InitialContext remoteInitialContext = getRemoteInitialContext();
          
          String queueName = KSESSION_QUEUE_NAME;
          Queue sessionQueue = (Queue) remoteInitialContext.lookup(queueName);
          queueName = TASK_QUEUE_NAME;
          Queue taskQueue = (Queue) remoteInitialContext.lookup(queueName);
          queueName = RESPONSE_QUEUE_NAME;
          Queue responseQueue = (Queue) remoteInitialContext.lookup(queueName);
          
          String connFactoryName = CONNECTION_FACTORY_NAME;
          ConnectionFactory connFact = (ConnectionFactory) remoteInitialContext.lookup(connFactoryName);
          
          RuntimeEngine engine = RemoteRuntimeEngineFactory.newJmsBuilder()
          .addDeploymentId(deploymentId)
          .addConnectionFactory(connFact) 2
          .addKieSessionQueue(sessionQueue)
          .addTaskServiceQueue(taskQueue)
          .addResponseQueue(responseQueue)
          .addUserName(user)
          .addPassword(password)
          .addHostName(hostname)
          .addJmsConnectorPort(jmsConnPort)
          .disableTaskSecurity() 3
          .build();
          
          // Create KieSession instances and use them
          KieSession ksession = engine.getKieSession();
          
          // Each operation on a KieSession, TaskService or AuditLogService (client) instance
          // sends a request for the operation to the server side and waits for the response
          // If something goes wrong on the server side, the client will throw an exception.
          ProcessInstance processInstance = ksession.startProcess(processId);
          long procId = processInstance.getId();
          }

1

The names of the ConnectionFactory and Queue instances may differ depending on your application server

2

Here we add the connection factory and queue instances.

3

If we are not using SSL, but are doing operations on tasks, then we have to explictly call the disableTaskSecurity() method. SSL is necessary for security reasons (plain-text password in message) when doing task operations via the remote Java API.

The following example illustrates how to configure a Remote Java API JMS client using a remote InitialContext instance. See your application server documentation for how to instantiate a remote instance of your application server’s InitialContext.

public void startProcessViaJmsRemoteJavaAPIInitialContext(String hostname, int jmsConnPort,
          String deploymentId, String user, String password,
          String processId) {
          
          // See your application server documentation for how to initialize
          // a remote InitialContext instance for your server instance
          InitialContext remoteInitialContext = getRemoteInitialContext();
          
          RuntimeEngine engine = RemoteRuntimeEngineFactory.newJmsBuilder()
          .addDeploymentId(deploymentId)
          .addRemoteInitialContext(remoteInitialContext)
          .addUserName(user)
          .addPassword(password)
          .build();
          
          // Create KieSession instances and use them
          KieSession ksession = engine.getKieSession();
          
          // Each operation on a KieSession, TaskService or AuditLogService (client) instance
          // sends a request for the operation to the server side and waits for the response
          // If something goes wrong on the server side, the client will throw an exception.
          ProcessInstance processInstance = ksession.startProcess(processId);
          long procId = processInstance.getId();
          }

The following example illustrates how to configure a Remote Java API JMS client using the hostname of the JBoss EAP server on which kie-wb or business-central is running.

public void startProcessViaJmsRemoteJavaAPI(String hostNameOrIpAdress,
          String deploymentId, String user, String password,
          String processId) {
          
          // this requires that you also have the following dependencies
          // - org.jboss.as:jboss-naming artifact appropriate to the EAP version you're using
          RuntimeEngine engine = RemoteRuntimeEngineFactory.newJmsBuilder()
          .addJbossServerHostName(hostNameOrIpAdress)
          .addDeploymentId(deploymentId)
          .addUserName(user)
          .addPassword(password)
          .build();
          }

Each builder has a number of different (required or optional) methods to configure a client RuntimeEngine instance.

Remote JMS Runtime Engine Builder methods

addConnectionFactory(ConnectionFactory connectionFactory) when

Add a ConnectionFactory used to create JMS session to send and receive messages

Required when:
configuring the JMS java client by passing ConnectionFactory and Queue instances
addDeploymentId(String deploymentId) when

Set the deployment id of the deployment

Required when:
doing an operation on a client instance that affects a process instance — this also includes completing or failing tasks created by process instances
addExtraJaxbClasses(Class…​ extraJaxbClasses ) when

Add extra classes to the client for when user-defined class instances are passed as parameters to client methods

When passing instances of user-defined classes in a Remote Java API call, it’s important to use this method first to add the classes so that the class instances can be serialized correctly.

Required when:
passing custom class instances as arguments to an operation on a client instance
addHostName(String hostname) when

Set the host name for the server that the client is making a JMS connection with

Required when:

configuring the JMS java client by setting ConnectionFactory and Queue instances

configuring the JMS java client to use SSL

addJbossServerHostName(String hostname)

Set the host name of the JBoss EAP server that the client is making a JMS connection with

After using this method, no other configuration is needed with regards to the server. However, additional server parameters (host name, port) may be needed when also configuring SSL.

Make sure that the EAP version-appropriate org.jboss.naming:jboss-naming dependency is available on the classpath when doing this

addJmsConnectorPort(int port) when

Set the port used for the JMS connection connection with the server

Required when:

configuring the JMS java client by passing ConnectionFactory and Queue instances

configuring the JMS java client to use SSL

addKeystoreLocation(String keystorePath) when

Set the location (path) of the keystore

Required when:
configuring the JMS java client to use SSL
addKeystorePassword(String keystorePassword) when

Set the password for the keystore

Required when:
configuring the JMS java client to use SSL
addKieSessionQueue(Queue ksessionQueue) when

Pass the javax.jms.Queue instance representing the KIE.SESSION queue used to receive process instance requests from the client

Required when:
configuring the JMS java client by setting ConnectionFactory and Queue instances
addPassword(String password) always
Set the password of the user connecting to the server
addProcessInstanceId(long process) when

Set the process instance id of the deployment

Required when:
interacting with a `PER_PROCESS_INSTANCE` deployment
addRemoteInitialContext(InitialContext remoteInitialContext)

Set the remote InitialContext instance from the remote application server, which is then used to retrieve the ConnectionFactory and Queue instances

After using this method, no other configuration is needed with regards to the server. However, additional server parameters (host name, port) may be needed when also configuring SSL.

addResponseQueue(Queue responseQueue) when

Pass the javax.jms.Queue instance representing the KIE.RESPONSE queue used to send responses to the client

Required when:
configuring the JMS java client by setting ConnectionFactory and Queue instances
addTaskServiceQueue(Queue taskServiceQueue) when

Pass the javax.jms.Queue instance representing the KIE.TASK queue used to receive task operation requests to the client

Required when:
configuring the JMS java client by setting ConnectionFactory and Queue instances
addTimeout(int timeoutInSeconds)
Set the timeout for the JMS message. The default is 5 seconds.
addTruststoreLocation(String truststorePath) when

Set the location (path) of the keystore

Required when:
configuring the JMS java client to use SSL
addTruststoreLocation(String truststorePassword) when

Set the password for the keystore

Required when:
configuring the JMS java client to use SSL
addUserName(String userName) always

Set the name of the user connecting to the server

This is also the user whose permissions will be used when doing any task operations

clearJaxbClasses()
Clears the list of (user-defined) Classes that the client instance should know about
disableTaskSecurity()
Enables configuration of a client that can send task-related operation requests without having to use SSL. If this option is not used and a task operation is called, the client will throw an exception.
useKeystoreAsTruststore()
Uses the same file (location) and password for the truststore configuration when configuring SSL.

Important

In order to instantiate a remote InitialContext via JNDI, the application-server-specific dependencies need to be included on the classpath.

For JBoss EAP 6, the artifact (jar) containing this class is the org.jboss:jboss-remote-naming artifact (jar), version 1.0.5.Final or higher. Depending on the version of AS 7 or EAP 6 that you use, this version may vary.

If you are using a different application server, please see your specific application server documentation for the parameters and artifacts necessary to create an InitialContextFactory instance or otherwise get a remote InitialContext instance (via JNDI) from the application server instance.

The following example illustrates how to configure a Remote Java API JMS client using a remote InitialContext instance along with SSL. In this case, the same file is being used as both the client’s keystore (the client’s identifying keys and certificates) and as the client’s truststore (the client’s list of trusted certificates from other parties, in this case, the server).

public void startProcessAndHandleTaskViaJmsRemoteJavaAPISsl(String hostNameOrIpAdress, int jmsSslConnectorPort,
        String deploymentId, String user, String password,
        String keyTrustStoreLocation, String keyTrustStorePassword,
        String processId) {
        
        InitialContext remoteInitialContext = getRemoteInitialContext();
        
        RuntimeEngine engine = RemoteRuntimeEngineFactory.newJmsBuilder()
        .addDeploymentId(deploymentId)
        .addRemoteInitialContext(remoteInitialContext)
        .addUserName(user)
        .addPassword(password)
        .addHostName(hostNameOrIpAdress)
        .addJmsConnectorPort(jmsSslConnectorPort)
        .useKeystoreAsTruststore()
        .addKeystoreLocation(keyTrustStoreLocation)
        .addKeystorePassword(keyTrustStorePassword)
        .build();
        
        // create JMS request
        KieSession ksession = engine.getKieSession();
        ProcessInstance processInstance = ksession.startProcess(processId);
        long procInstId = processInstance.getId();
        logger.debug("Started process instance: " + procInstId );
        
        TaskService taskService = engine.getTaskService();
        List<TaskSummary> taskSumList
        = taskService.getTasksAssignedAsPotentialOwner(user, "en-UK");
        TaskSummary taskSum = null;
        for( TaskSummary taskSumElem : taskSumList ) {
        if( taskSumElem.getProcessInstanceId().equals(procInstId) ) {
        taskSum = taskSumElem;
        }
        }
        long taskId = taskSum.getId();
        logger.debug("Found task " + taskId);
        
        // get other info from task if you want to
        Task task = taskService.getTaskById(taskId);
        logger.debug("Retrieved task " + taskId );
        
        taskService.start(taskId, user);
        
        Map<String, Object> resultData = new HashMap<String, Object>();
        // insert results for task in resultData
        taskService.complete(taskId, user, resultData);
        logger.debug("Completed task " + taskId );
        }

Starting with this release, a simple webservice has been added to the remote API.

The following example illustrates how to configure a Remote Java API WebService client using the hostname of the JBoss EAP server on which kie-wb or business-central is running.

import java.net.URL;
        import java.util.List;
        import java.util.Map;
        
        import org.kie.api.command.Command;
        import org.kie.api.task.model.Task;
        import org.kie.remote.client.documentation.objects.MyType;
        import org.kie.remote.client.jaxb.JaxbCommandsRequest;
        import org.kie.remote.client.jaxb.JaxbCommandsResponse;
        import org.kie.remote.jaxb.gen.GetTaskCommand; 1
        import org.kie.remote.jaxb.gen.GetTaskContentCommand;
        import org.kie.remote.jaxb.gen.GetTasksByProcessInstanceIdCommand;
        import org.kie.remote.jaxb.gen.JaxbStringObjectPairArray;
        import org.kie.remote.jaxb.gen.StartProcessCommand;
        import org.kie.remote.jaxb.gen.util.JaxbStringObjectPair;
        import org.kie.remote.services.ws.command.generated.CommandWebService;
        import org.kie.remote.services.ws.command.generated.CommandWebServiceException;
        import org.kie.services.client.api.RemoteRuntimeEngineFactory;
        import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;
        import org.kie.services.client.serialization.jaxb.impl.JaxbLongListResponse;
        import org.kie.services.client.serialization.jaxb.impl.process.JaxbProcessInstanceResponse;
        import org.slf4j.Logger;
        import org.slf4j.LoggerFactory;
        
        public class WebserviceJavaApiExamples {
        
        private Logger logger = LoggerFactory.getLogger(WebserviceJavaApiExamples.class);
        
        /**
        * Create the webservice client
        * @param applicationUrl Something like "http://localhost:8080/kie-wb/"
        *                       or "http://localhost:8080/business-central/"
        * @param user The user doing the webservice requests
        * @param password The user's password
        * @param deploymentId The deployment id that the request will interact with
        * @return A {@link CommandWebService} client instance
        */
        private static CommandWebService createWebserviceClient(URL applicationUrl,
        String user, String password, String deploymentId) {
        CommandWebService client =
        RemoteRuntimeEngineFactory.newCommandWebServiceClientBuilder()
        .addServerUrl(applicationUrl)
        .addUserName(user)
        .addPassword(password)
        .addDeploymentId(deploymentId)
        .addExtraJaxbClasses(MyType.class) 2
        .buildBasicAuthClient();
        
        return client;
        }
        
        /**
        * Send a webservice request with a single command
        * @param service The webserivce client instance
        * @param cmd The command that we're sending (see the
        *            'org.kie.remote.jaxb.gen package' in kie-remote-client)
        * @param respClass The class that we expect as a response
        * @param deploymentId The id of the deployment that we will interact with
        * @return the response object
        * @throws CommandWebServiceException if the webservice operation fails
        */
        private static <T> T doWebserviceSingleCommandRequest(CommandWebService service,
        Command<?> cmd, Class<T> respClass, String deploymentId)
        throws CommandWebServiceException {
        // Get a response from the WebService
        JaxbCommandsRequest req = new JaxbCommandsRequest(deploymentId, cmd);
        JaxbCommandsResponse response = service.execute(req);
        
        // check response
        JaxbCommandResponse<?> cmdResp = response.getResponses().get(0);
        
        return (T) cmdResp;
        }
        
        /**
        * Start a simple process, and retrieve the task information and content
        * via the webservice
        *
        * @param applicationUrl Something like "http://localhost:8080/kie-wb/"
        *                       or "http://localhost:8080/business-central/"
        * @param user The user doing the webservice requests
        * @param password The user's password
        * @param deploymentId The deployment id that the request will interact with
        * @param processId The id of the process we want to start
        * @throws Exception if something goes wrong
        */
        public static void startSimpleProcess(URL applicationUrl,
        String user, String password, String deploymentId, String processId)
        throws Exception {
        
        CommandWebService commandWebService
        = createWebserviceClient(applicationUrl, user, password, deploymentId);
        
        // Create start process command
        StartProcessCommand spc = new StartProcessCommand();
        spc.setProcessId(processId);
        JaxbStringObjectPairArray map = new JaxbStringObjectPairArray();
        JaxbStringObjectPair keyValue = new JaxbStringObjectPair();
        keyValue.setKey("myobject");
        keyValue.setValue(new MyType("variable", 29));
        map.getItems().add(keyValue);
        spc.setParameter(map);
        
        // Do webService request
        JaxbProcessInstanceResponse jpir
        = doWebserviceSingleCommandRequest(commandWebService, spc,
        JaxbProcessInstanceResponse.class, deploymentId);
        long procInstId = ((JaxbProcessInstanceResponse) jpir).getId();
        
        // Create command
        GetTasksByProcessInstanceIdCommand gtbic = new GetTasksByProcessInstanceIdCommand();
        gtbic.setProcessInstanceId(procInstId);
        
        // Do webservice request
        JaxbLongListResponse jllr
        = doWebserviceSingleCommandRequest(commandWebService, gtbic,
        JaxbLongListResponse.class, deploymentId );
        List<Long> taskIds = jllr.getResult();
        long taskId = taskIds.get(0);
        
        // Commands for task and task content
        GetTaskCommand gtc = new GetTaskCommand();
        gtc.setTaskId(taskId);
        GetTaskContentCommand gtcc = new GetTaskContentCommand();
        gtcc.setTaskId(taskId);
        
        // Do webservice request (with both commands)
        JaxbCommandsRequest req = new JaxbCommandsRequest(deploymentId, gtc);
        req.getCommands().add(gtcc); 3
        JaxbCommandsResponse response = commandWebService.execute(req);
        
        // Get task and content response
        Task task = (Task) response.getResponses().get(0).getResult();
        Map<String, Object> contentMap
        = (Map<String, Object>) response.getResponses().get(1).getResult();
        }
        
        }

1

All commands that can be used with the webservice can be found in the org.kie.remote.jaxb.gen package in the kie-remote-client module. These commands contain the same data as the commands that they are based on (that have the same name) in the core jbpm and drools modules.

2

The addExtraJaxbClasses(Class…​) method must be used when using instances of user-defined classes in a command sent in a webservice request.

3

Similar to the REST /execute method, multiple commands can be sent in one webservice request

Remote Webservice Client Builder methods

addDeploymentId(String deploymentId) when

Set the deployment id of the deployment

Required when:
doing an operation on a client instance that affects a process instance — this also includes completing or failing tasks created by process instances
addExtraJaxbClasses(Class…​ extraJaxbClasses ) when

Add extra classes to the client for when user-defined class instances are passed as parameters to client methods

When passing instances of user-defined classes in a Remote Java API call, it’s important to use this method first to add the classes so that the class instances can be serialized correctly.

Required when:
passing custom class instances as arguments to an operation on a client instance
addServerUrl(URL applicationUrl) always
Set the URL for the application (kie-wb or business-central) that the webservice request will be sent to
addPassword(String password) always
Set the password of the user connecting to the server
addTimeout(int timeoutInSeconds)
Set the timeout for the Webservice response. The default is 5 seconds.
addUserName(String userName) always

Set the name of the user connecting to the server

This is also the user whose permissions will be used when doing any task operations

setWsdlLocationRelativePath()
OCRAM
useHttpRedirect()
OCRAM

As mentioned above, the Remote Java API provides client-like instances of the RuntimeEngine, KieSession, TaskService and AuditService interfaces.

This means that while many of the methods in those interfaces are available, some are not. The following tables lists the methods which are available. Methods not listed in the below, will throw an UnsupportedOperationException explaining that the called method is not available.

Table 17.1. Available process-related KieSession methods

Return typeMethod signatureDescription

void

abortProcessInstance( long processInstanceId)

Abort the process instance

ProcessInstance

getProcessInstance( long processInstanceId)

Return the process instance

ProcessInstance

getProcessInstance( long processInstanceId, boolean readOnly)

Return the process instance

List<ProcessInstance>

getProcessInstances()

Return all (active) process instances

void

signalEvent( String signal, Object event)

Signal all (active) process instances

void

signalEvent( String signal, Object event, long processInstanceId)

Signal the process instance

ProcessInstance

startProcess( String processId, CorrelationKey correlationKey, Map<String, Object> parameters)

Start a new process and return the process instance (if the process instance has not immediately completed)

ProcessInstance

startProcess(String processId, Map<String, Object> parameters)

Start a new process and return the process instance (if the process instance has not immediately completed)


Table 17.2. Available rules-related KieSession methods<

Return typeMethod signatureDescription

Long

getFactCount()

Return the total fact count

Object

getGlobal(String identifier)

Return a global fact

Integer

getId()

Return the id of the KieSession

void

setGlobal(String identifier, Object value)

Set a global fact

void

fireAllRules()

Fire all rules


Table 17.3. Available WorkItemManager methods

Return typeMethod signatureDescription

void

abortWorkItem(long workItemId)

Abort the work item

void

completeWorkItem(long workItemId, Map<String, Object> results)

Complete the work item

WorkItem

getWorkItem(long workItemId)

Return the work item


Table 17.4. Available task operation TaskService methods

Return typeMethod signatureDescription

Long

addTask(Task task, Map<String, Object> params)

Add a new task

void

activate(long taskId, String userId)

Activate a task

void

claim(long taskId, String userId)

Claim a task

void

claim(long taskId, String userId, List<String> groupIds)

Claim a task

void

claimNextAvailable(String userId, String language)

Claim the next available task for a user

void

claimNextAvailable(String userId, List<String> groupIds, String language)

Claim the next available task for a user

void

complete(long taskId, String userId, Map<String, Object> data)

Complete a task

void

delegate(long taskId, String userId, String targetUserId)

Delegate a task

void

exit(long taskId, String userId)

Exit a task

void

fail(long taskId, String userId, Map<String, Object> faultData)

Fail a task

void

forward(long taskId, String userId, String targetEntityId)

Forward a task

void

nominate(long taskId, String userId, List<OrganizationalEntity> potentialOwners)

Nominate a task

void

release(long taskId, String userId)

Release a task

void

remove(long taskId, String userId)

Remove a task

void

resume(long taskId, String userId)

Resume a task

void

skip(long taskId, String userId)

Skip a task

void

start(long taskId, String userId)

Start a task

void

stop(long taskId, String userId)

Stop a task

void

suspend(long taskId, String userId)

Suspend a task


Table 17.5. Available task retrieval and query TaskService methods

Return typeMethod signature

Task

getTaskByWorkItemId(long workItemId)

Task

getTaskById(long taskId)

List<TaskSummary>

getTasksAssignedAsBusinessAdministrator(String userId, String language)

List<TaskSummary>

getTasksAssignedAsPotentialOwner(String userId, String language)

List<TaskSummary>

getTasksAssignedAsPotentialOwnerByStatus(String userId, List<Status> status, String language)

List<TaskSummary>

getTasksOwned(String userId, String language)

List<TaskSummary>

getTasksOwnedByStatus(String userId, List<Status> status, String language)

List<TaskSummary>

getTasksByStatusByProcessInstanceId(long processInstanceId, List<Status> status, String language)

List<TaskSummary>

getTasksByProcessInstanceId(long processInstanceId)

`List<TaskSummary>

getTasksByVariousFields(List<Long> workItemIds, List<Long> taskIds, List<Long> procInstIds, List<String> busAdmins, List<String> potOwners, List<String> taskOwners, List<Status> status, boolean union)

List<TaskSummary>

getTasksByVariousFields(Map <String, List<?>> parameters, boolean union)

Content

getContentById(long contentId)

Attachment

getAttachmentById(long attachId)


Table 17.6. Available AuditService methods

Return typeMethod signature

List<ProcessInstanceLog>

findProcessInstances()

List<ProcessInstanceLog>

findProcessInstances(String processId)

List<ProcessInstanceLog>

findActiveProcessInstances(String processId)

ProcessInstanceLog

findProcessInstance(long processInstanceId)

List<ProcessInstanceLog>

findSubProcessInstances(long processInstanceId)

List<NodeInstanceLog>

findNodeInstances(long processInstanceId)

List<NodeInstanceLog>

findNodeInstances(long processInstanceId, String nodeId)

List<VariableInstanceLog>

findVariableInstances(long processInstanceId)

List<VariableInstanceLog>

findVariableInstances(long processInstanceId, String variableId)

List<VariableInstanceLog>

findVariableInstancesByName(String variableId, boolean onlyActiveProcesses)

List<VariableInstanceLog>

findVariableInstancesByNameAndValue(String variableId, String value, boolean onlyActiveProcesses)

void

clear()


17.2. REST

REST API calls to the execution server allow you to remotely manage processes and tasks and retrieve various dynamic information from the execution server. The majority of the calls are synchronous, which means that the call will only finish once the requested operation has completed on the server. The exceptions to this are the deployment POST calls, which will return the status of the request while the actual operation requested will asynchronously execute.

When using Java code to interface with the REST API, the classes used in POST operations or otherwise returned by various operations can be found in the (org.kie.remote:)kie-services-client JAR.

This section lists REST calls that interface process instances.

The deploymentId component of the REST calls below must conform to the following regular expression:

[\w\.-]+(:[\w\.-]+){2,2}(:[\w\.-]*){0,2}

For more information about the composition of the deployment id, see the Deployment Calls section.

[POST] /runtime/{deploymentId}/process/{processDefId}/start

[POST] rest/runtime/{deploymentId}/process/{processDefId}/startform

[GET] /runtime/{deploymentId}/process/instance/{procInstId}

[POST] /runtime/{deploymentId}/process/instance/{procInstId+}/abort

[POST] /runtime/{deploymentId}/process/instance/{procInstId}/signal

[GET] /runtime/{deploymentId}/process/instance/{procInstId}/variable/{varName}

[POST] /runtime/{deploymentId}/signal

[GET] /runtime/{deploymentId}/workitem/{workItemId}

[POST] /runtime/{deploymentId}/workitem/{workItemId}/complete

[POST] /runtime/{deploymentId}/workitem/{workItemId: [0-9-]+}/abort

[POST] /runtime/{deploymentId}/withvars/process/{processDefId}/start

[POST] /runtime/{deploymentId}/withvars/process/instance/{procInstId}

[POST] /runtime/{deploymentId}/withvars/process/instance/{procInstId}/signal

[POST] /history/clear

[GET] /history/instances

[GET] /history/instance/{procInstId}

[GET] /history/instance/{procInstId}/child

[GET] /history/instance/{procInstId}/node

[GET] /history/instance/{procInstId}/variable

[GET] /history/instance/{procInstId}/node/{nodeId}

[GET] /history/instance/{procInstId}/variable/{varId}

[GET] /history/process/{processDefId}

[GET] /history/variable/{varId}

[GET] /history/variable/{varId}/value/{value}

[GET] /history/variable/{varId}/instances

[GET] /history/variable/{varId}/value/{value}/instances

[GET] /runtime/{deploymentId}/history/variable/{varId}

[GET] /runtime/{deploymentId}/history/variable/{varId}/value/{value}

[GET] /runtime/{deploymentId}/history/variable/{varId}/instances

[GET] /runtime/{deploymentId}/history/variable/{varId}/value/{value}/instances

The following section describes the three different types of task calls: * Task REST operations that mirror the TaskService interface, allowing the user to interact with the remote TaskService instance * The Task query REST operation, that allows users to query for Task instances * Other Task REST operations that retrieve information

Task operation authorizations. Task REST operations use the user information (used to authorize and authenticate the HTTP call) to check whether or not the requested operations can happen. This also applies to REST calls that retrieve information, such as the task query operation. REST calls that request information will only return information about tasks that the user is allowed to see.

With regards to retrieving information, only users associated with a task may retrieve information about the task. However, the authorizations of progress and other modifications of task information are more complex. See the Task Permissions section in the Task Service documentation for more infomration.

Note

Given that many users have expressed the wish for a "super-task-user" that can execute task REST operations on all tasks, regardless of the users associated with the task, there are now plans to implement that feature. However, so far for the 6.x releases, this feature is not available.

All of the task operation calls described in this section use the user (id) used in the REST basic authorization as input for the user parameter in the specific call.

Some of the operations take an optional lanaguage query parameter. If this parameter is not given as a element of the URL itself, the default value of “en-UK” is used.

The taskId component of the REST calls below must conform to the following regex:

[0-9]+

[POST] /task/{taskId}/activate

[POST] /task/{taskId}/claim

[POST] /task/{taskId}/claimnextavailable

[POST] /task/{taskId}/complete - Completes a task - Returns a JaxbGenericResponse with the status of the operation - Parameters: Takes map query parameters, which are the "results" input for the complete operation

[POST] /task/{taskId}/delegate

[POST] /task/{taskId}/exit

[POST] /task/{taskId}/fail

[POST] /task/{taskId}/forward

[POST] /task/{taskId}/nominate

[POST] /task/{taskId}/release

[POST] /task/{taskId}/resume

[POST] /task/{taskId}/skip

[POST] /task/{taskId}/start

[POST] /task/{taskId}/stop - Stops a task - Returns a JaxbGenericResponse with the status of the operation

[POST] /task/{taskId}/suspend

[GET] /task/{taskId}/showTaskForm

[GET] /task/query

 

Example 17.1. Query usage

This call retrieves the task summaries of all tasks that have a work item id of 3, 4, or 5. If you specify the same parameter multiple times, the query will select tasks that match any of that parameter.

http://server:port/rest/task/query?workItemId=3&workItemId=4&workItemId=5

The next call will retrieve any task summaries for which the task id is 27 and for which the work item id is 11. Specifying different parameters will result in a set of tasks that match both (all) parameters.

`http://server:port/rest/task/query?workItemId=11&taskId=27`

The next call will retrieve any task summaries for which the task id is 27 or the work item id is 11. While these are different parameters, the union parameter is being used here so that the union of the two queries (the work item id query and the task id query) is returned.

http://server:port/rest/task/query?workItemId=11&taskId=27&union=true`

The next call will retrieve any task summaries for which the status is Created and the potential owner of the task is Bob. Note that the letter case for the status parameter value is case-'in’sensitve.

http://server:port/rest/task/query?status=creAted&potentialOwner=Bob`

The next call will return any task summaries for which the status is Created and the potential owner of the task is bob. Note that the potential owner parameter is case-'sensitive'. bob is not the same user id as Bob!

http://server:port/rest/task/query?status=created&potentialOwner=bob`

The next call will return the intersection of the set of task summaries for which the process instance is 201, the potential owner is bob and for which the status is Created or Ready.

http://server:port/rest/task/query?status=created&status=ready&potentialOwner=bob&processInstanceId=201

That means that the task summaries that have the following characteristics would be included:

  • process instance id 201, potential owner bob, status Ready
  • process instance id 201, potential owner bob, status Created

And that following task summaries will not be included:

  • process instance id 183, potential owner bob, status Created
  • process instance id 201, potential owner '`mary`, status Ready
  • process instance id 201, potential owner bob, status `Complete`

[GET] /task/{taskId}/content

[GET] /task/content/{contentId}

The calls described in this section allow users to manage deployments. Deployments are in fact KieModule JARs which can be deployed or undeployed, either via the UI or via the REST calls described below. Configuration options, such as the runtime strategy, should be specified when deploying the deployment: the configuration of a deployment can not be changed after it has already been deployed.

The above deploymentId regular expression describes an expression that contains the following elements, separated from eachother by a : character:

In a more formal sense, the deploymentId component of the REST calls below must conform to the following regex:

`[\w\.-]+(:[\w\.-]+){2,2}(:[\w\.-]*){0,2}`

This regular expression is explained as follows:

Table 17.7. [\w\.-] character sets

[A-Z]

[0-9]

.

[a-z]

_

-


This [\w\.-] element occurs at least 3 times and at most 5 times, separated by a : character each time.

Example 17.2. Accepted deploymentId's

  • com.wonka:choco-maker:67.190

  • These example `deploymentId’s contain the optional kbase and ksession id groups.

    • com.wonka:choco-maker:67.190:oompaBase
    • com.wonka:choco-maker:67.190:oompaLoompaBase:gloopSession

There are 2 operations that can be used to modify the status of a deployment:

These POST deployment calls are both asynchronous, which means that the information returned by the POST request does not reflect the eventual final status of the operation itself.

Important

As noted above, both the /deploy and /undeploy operations are asynchronous REST operations. Successfull requests to these URLs will return the status 202 upon the request completion. RFC 2616 defines the 202 status as meaning the following:

 

RFC 2616: "the request has been accepted for processing, but the processing has not been completed."

 

This means the following:

  1. While the request may have been accepted "successfully", the operation itself (deploying or undeploying the deployment unit) may actually fail.
  2. Furthermore, information about deployments, such as that retrieved by calling the GET operations described below, are snapshots and the information (including the status of the deployment unit) may have changed by the time the user client receives the answer to the GET request.

[GET] /deployment/

[GET] /deployment/ {deploymentId}

[POST] /deployment/{deploymentId}/deploy

[POST] /deployment/{deploymentId}/undeploy

While there is a /runtime/{id}/execute and a task/execute method, both will take all types of commands. This is possible because execute takes a JaxbCommandsRequest object, which contains a list of (org.kie.api.command.)Command objects. The JaxbCommandsRequest has fields to store the proper deploymentId and processInstanceId information.

Of course, if you send a request with a command that needs this information (deploymentId, for example) and don’t fill the deploymentId in, the request will fail.

[POST] /execute

Table 17.8. Runtime commands

AbortWorkItemCommand

GetProcessInstancesCommand

GetIdCommand

CompleteWorkItemCommand

SetProcessInstanceVariablesCommand

SetGlobalCommand

GetWorkItemCommand

SignalEventCommand

 
 

StartCorrelatedProcessCommand

DeleteCommand

AbortProcessInstanceCommand

StartProcessCommand

FireAllRulesCommand

GetProcessIdsCommand

GetVariableCommand

InsertObjectCommand

GetProcessInstanceByCorrelationKeyCommand

GetFactCountCommand

UpdateCommand


Table 17.9. Task commands

ActivateTaskCommand

FailTaskCommand

GetTasksOwnedCommand

AddTaskCommand

ForwardTaskCommand

NominateTaskCommand

CancelDeadlineCommand

GetAttachmentCommand

ProcessSubTaskCommand

ClaimNextAvailableTaskCommand

GetContentCommand

ReleaseTaskCommand

ClaimTaskCommand

GetTaskAssignedAsBusinessAdminCommand

ResumeTaskCommand

CompleteTaskCommand

GetTaskAssignedAsPotentialOwnerCommand

SkipTaskCommand

CompositeCommand

GetTaskByWorkItemIdCommand

StartTaskCommand

DelegateTaskCommand

GetTaskCommand

StopTaskCommand

ExecuteTaskRulesCommand

GetTasksByProcessInstanceIdCommand

SuspendTaskCommand


Table 17.10. History/Audit commands

ClearHistoryLogsCommand

FindProcessInstanceCommand

FindSubProcessInstancesCommand

FindActiveProcessInstancesCommand

FindProcessInstancesCommand

FindVariableInstancesByNameCommand

FindNodeInstancesCommand

FindSubProcessInstancesCommand

FindVariableInstancesCommand


The following /rest/execute call can be used to start a process (with process id ‘evaluation’ in the project with deployment id ‘org.jbpm:Evaluation:1.0’) and two parameters (parameter employee equal to ‘krisv’ and reason equal to ‘Yearly performance evaluation’).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-request>
  <deployment-id>org.jbpm:Evaluation:1.0</deployment-id>
  <ver>6.2.0.1</ver>
  <user>krisv</user>
  <start-process processId="evaluation">
    <parameter>
      <item key="reason">
        <value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Yearly performance evaluation</value>
      </item>
      <item key="employee">
        <value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">krisv</value>
      </item>
    </parameter>
  </start-process>
</command-request>

Note that the request should also contain the following HTTP headers:

  • A Content-Type header with the value of application/xml
  • A Authorization header with basic authentication information, as specificed by RFC2616 (see link).

The response will contain information about the process instance that was just started:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <command-response>
    <deployment-id>org.jbpm:Evaluation:1.0</deployment-id>
    <ver>6.2.0.1</ver>
    <process-instance index="0">
    <process-id>evaluation</process-id>
    <id>15</id>
    <state>1</state>
    <parentProcessInstanceId>0</parentProcessInstanceId>
    <command-name>StartProcessCommand</command-name>
  </process-instance>
</command-response>

The /execute operation also supports sending user-defined class instances as parameters in the command. This relies on JAXB for serialization and deserialization. To be able to deserialize the custom class on the server side, a "Kie-Deployment-Id" header must also be set to the deployment id of the project.

For example, when starting a process or completing a task, a user typically passes additional parameters (process variable values or the result data for the completed task). These values are then either primitives (Strings, ints, etc.) or user-defined classes that were created using the data modeler in the workbench, added directly to the deployed project or part of a dependency to the deployment (project).

The following request starts a process which contains a custom TestObject class (with two fields) as a parameter.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-request>
  <deployment-id>demo:testproject:1.0</deployment-id>
  <ver>6.2.0.1</ver>
  <user>krisv</user>
  <start-process processId="testproject.testprocess">
    <parameter>
      <item key="testobject">
        <value xsi:type="testObject" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <field1>1</field1>
          <field2>2</field2>
        </value>
      </item>
    </parameter>
  </start-process>
</command-request>

Just as in the basic example above, both a Content-Type and Authorization header should be set in the request.

The 3 headers that therefore need to be set in the requst are the following:

  • A Content-Type header with the value of application/xml
  • A Authorization header with basic authentication information, as specificed by RFC2616 (see link).
  • A Kie-Deployment-Id header with the value of the deployment id containing the class definitions of any parameters sent with the command .

The URL templates in the table below are relative to the one of the following URLs:

[POST] /runtime/{deploymentId}/process/{procDefID}/start
[POST] /runtime/{deploymentId}/process/{procDefID}/startform
[GET] /runtime/{deploymentId}/process/instance/{procInstanceID}
[POST] /runtime/{deploymentId}/process/instance/{procInstanceID}/abort
[POST] /runtime/{deploymentId}/process/instance/{procInstanceID}/signal
[GET] /runtime/{deploymentId}/process/instance/{procInstanceID}/variable/{varId}
[POST] /runtime/{deploymentId}/signal/{signalCode}
[POST] /runtime/{deploymentId}/workitem/{workItemID}/complete
[POST] /runtime/{deploymentId}/workitem/{workItemID}/abort
[POST] /runtime/{deploymentId}/withvars/process/{procDefinitionID}/start
[GET] /runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/
[POST] /runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/signal
[GET] /task/query
[GET] /task/content/{contentID}
[GET] /task/{taskID}
[POST] /task/{taskID}/activate
[POST] /task/{taskID}/claim
[POST] /task/{taskID}/claimnextavailable
[POST] /task/{taskID}/complete
[POST] /task/{taskID}/delegate
[POST] /task/{taskID}/exit
[POST] /task/{taskID}/fail
[POST] /task/{taskID}/forward
[POST] /task/{taskID}/nominate
[POST] /task/{taskID}/release
[POST] /task/{taskID}/resume
[POST] /task/{taskID}/skip
[POST] /task/{taskID}/start
[POST] /task/{taskID}/stop
[POST] /task/{taskID}/suspend
[GET] /task/{taskID}/content
[GET] /task/{taskID}/showTaskForm
[POST] /history/clear/
[GET] /history/instances
[GET] /history/instance/{procInstId}
[GET] /history/instance/{procInstId}/child
[GET] /history/instance/{procInstId}/node
[GET] /history/instance/{procInstId}/node/{nodeId}
[GET] /history/instance/{procInstId}/variable
[GET] /history/instance/{procInstId}/variable/{variableId}
[GET] /history/process/{procDefId}
[GET] /history/variable/{varId}
[GET] /history/variable/{varId}/instances
[GET] /history/variable/{varId}/value/{value}
[GET] /history/variable/{varId}/value/{value}/instances
[GET] /deployments
[GET] /deployment/{deploymentId}
[POST] /deployment/{deploymentId}/deploy
[POST] /deployment/{deploymentId}/undeploy

17.3. REST Query API

The REST Query API allows users of the jBPM console and the KIE workbench (as well as products based on these applications) to "richly" query tasks, variables and process instances.

The rich query operations can be reached via the following URLs:

http://server.address:port/{application-id}/rest/query/
  runtime
    task                     * [GET] rich query for task summaries and process variables
    process                  * [GET] rich query for process instances and process variables

Both url’s take a number of different query parameters. See the next section for a description of these.

In the documentation below,

When you submit a REST call to the query operation, your URL will look something like this:

http://localhost:8080/business-central/rest/query/runtime/process/processId=org.process.frombulator&piid=29

A query containing multiple different query parameters will search for the intersection of the given parameters.

However, many of the query parameters described below can be entered multiple times: when multiple values are given for the same query parameter, the query will then search for any results that match one or more of the values entered.

Example 17.4. Repeated query parameters

The following process instance query:

processId=org.example.process&processInstanceId=27&processInstanceId=29

will return a result that

  • only contains information about process instances with the "org.example.process" process definition
  • only contains information about process instances that have an id of 27 or 29

Some query criteria can be given in ranges while for others, a simple regular expression language can be used to describe the value.

Query parameters that

In order to pass the lower end or start of a range, add _min to end of the parameter name. In order to pass the upper end or end of a range, add _max to end of the parameter name.

Range ends are inclusive.

Only passing one end of the range (the lower or upper end), results in querying on an open ended range.

Example 17.5. Range parameters

The following task query:

processId=org.example.process&taskId_min=50&taskId_max=53

will return a result that

  • only contains information about tasks associated with the "org.example.process" process definition
  • only contains information about tasks that have a task id between 50 and 53, inclusive.

While the following task query:

processId=org.example.process&taskId_min=52

will return a result that

  • only contains information about tasks associated with the "org.example.process" process definition
  • only contains information about tasks that have a task id that is larger than or equal to 52

In order to apply regular expressions to a query parameter, add “_re” to the end of the parameter name.

The regular expression language contains 2 special characters:

The slash character (\) is not interpreted.

Example 17.6. Regular expression parameters

The following process instance query

processId_re=org.example.*&processVersion=2.0

will return a result that

  • only contains information about process instances associated with a process definition whose name matches the regular expression "org.example.*". This includes:

    • org.example.process
    • org.example.process.definition.example.long.name
    • orgXexampleX
  • only contains information about process instances that have a process (definition) version of 2.0

The "task or process" column describes whether or not a query parameter can be used with the task and/or the process instance query operations.

Table 17.11. Query parameters

parametershort formdescriptionregexmin / maxtask or process

processinstanceid

piid

Process instance id

 

X

T,P

processid

pid

Process id

X

 

T,P

workitemid

wid

Work item id

  

T,P

deploymentid

did

Deployment id

X

 

T,P

taskid

tid

Task id

 

X

T

initiator

init

Task initiator/creator

X

 

T

stakeholder

stho

Task stakeholder

X

 

T

potentialowner

po

Task potential owner

X

 

T

taskowner

to

Task owner

X

 

T

businessadmin

ba

Task business admin

X

 

T

taskstatus

tst

Task status

  

T

`processinstancestatus

pist

Process instance status

  

T,P

processversion

pv

Process version

X

 

T,P

startdate

stdt

Process instance start date1

 

X

T,P

enddate

edt

Process instance end date1

 

X

T,P

varid

vid

Variable id

X

 

T,P

varvalue

vv

Variable value

X

 

T,P

var

var

Variable id and value 2

  

T,P

varregex

vr

Variable id and value 3

X

 

T,P

all

all

Which variable history logs 4

  

T,P


[1] The date operations take strings with a specific date format as their values: yy-MM-dd_HH:mm:ss. However, users can also submit only part of the date:

  • Submitting only the date (yy-MM-dd) means that a time of 00:00:00 is used (the beginning of the day).
  • Submitting only the time (HH:mm:ss) means that the current date is used.

Table 17.12. Example date strings

Date str ingActual meaning

15-05-29_13:40:12

May 29th, 2015, 13:40:12 (1:40:12 PM)

14-11-20

November 20th, 2014, 00:00:00

9:30:00

Today, 9:30:00 (AM)


For the format used, see the SimpleDateFormat documentation.

[2] The var query parameter is used differently than other parameters. If you want to specify both the variable id and value of a variable (as opposed to just the variable id), then you can do it by using the var query parameter. The syntax is var_<variable-id>=<variable-value>

Example 17.7.  var_X=Y example

The query parameter and parameter pair var_myVar=value3 queries for process instances with variables4 that are called myVar and that have the value value3


[3] The varreggex (or shortened version vr) parameter works similarly to the var query parameter. However, the value part of the query parameter can be a regular expression.

[4] By default, only the information from most recent (last) variable instance logs is retrieved. However, users can also retrieve all variable instance logs (that match the given criteria) by using this parameter.

Table 17.13. Query parameters examples

parametershort formexample

processinstanceid

piid

piid=23

processid

pid

processid=com.acme.example

workitemid

wid

wid_max=11

deploymentid

did

did_re=com.willy.loompa.*

taskid

tid

taskid=4

initiator

init

init_re=Davi*

stakeholder

stho

stho=theBoss&stho=theBossesAssistant

potentialowner

po

potentialowner=sara

taskowner

to

taskowner_re=*anderson

businessadmin

ba

ba=admin

taskstatus

tst

tst=Reserved

processinstancestatus

pist

pist=3&pist=4

processversion

pv

processVersion_re=4.2*

startdate

stdt

stdt_min=00:00:00

enddate

edt

edt_max=15-01-01

varid

vid

varid=numCars

varvalue

vv

vv=abracadabra

var

var

var_numCars=10

varregex

vr

vr_nameCar=chitty*

all

all

all


The process instance query returns a JaxbQueryProcessInstanceResult instance.

The task query returns a JaxbQueryTaskResult instance.

Results are structured as follows:

A JaxbQueryProcessInstanceInfo object contains:

  • a process instance object
  • a list of 0 or more variable objects

A JaxbQueryTaskInfo info object contains:

  • the process instance id
  • a list of 0 or more task summary obejcts
  • a list of 0 or more variable objects

17.4. JMS

The Java Message Service (JMS) is an API that allows Java Enterprise components to communicate with each other asynchronously and reliably.

Operations on the runtime engine and tasks can be done via the JMS API exposed by the jBPM console and KIE workbench. However, it’s not possible to manage deployments or the knowledge base via this JMS API.

Unlike the REST API, it is possible to send a batch of commands to the JMS API that will all be processed in one request after which the responses to the commands will be collected and return in one response message.

When the Workbench is deployed on the JBoss AS or EAP server, it automatically creates 3 queues:

The KIE.SESSION and KIE.TASK queues should be used to send request messages to the JMS API. Command response messages will be then placed on the KIE.RESPONSE queues. Command request messages that involve starting and managing business processes should be sent to the KIE.SESSION and command request messages that involve managing human tasks, should be sent to the KIE.TASK queue.

Although there are 2 different input queues, KIE.SESSION and KIE.TASK, this is only in order to provide multiple input queues so as to optimize processing: command request messages will be processed in the same manner regardless of which queue they’re sent to. However, in some cases, users may send many more requests involving human tasks than requests involving business processes, but then not want the processing of business process-related request messages to be delayed by the human task messages. By sending the appropriate command request messages to the appropriate queues, this problem can be avoided.

The term "command request message" used above refers to a JMS text message that contains a serialized JaxbCommandsRequest object. At the moment, only XML serialization (as opposed to, JSON or protobuf, for example) is supported.

While it is possible to interact with a BPMS or KIE workbench server instance by sending and processing JMS messages that you create yourself, it will always be easier to use the remote Java API that’s supplied by the kie-services-client jar.

For more information about how to use the remote Java API to interact with the JMS API of a server instance, see the <link linkend='remote.java.api.jms'>Remote Java API</link> section.

The JMS API accepts TextMessage instances that contain serialized JaxbCommandsRequest objects. These JaxbCommandsRequest instances can be filled with multiple command objects. In this way, it’s possible to send a batch of commands for processing to the JMS API.

When users wish to include their own classes with requests, there a number of requirements that must be met for the user-defined classes. For more information about these requirements, see the Sending and receiving user class instances section in the remote API additional documentation section.

The following is a rather long example that shows how to use the JMS API. The numbers ("callouts") along the side of the example refer to notes below that explain particular parts of the example. It’s supplied for those advanced users that do not wish to use the jBPM Remote Java API.

The jBPM Remote Java API, described here, will otherwise take care of all of the logic shown below.

package org.kie.remote.client.documentation.jms;
      
      import static org.kie.services.client.serialization.SerializationConstants.DEPLOYMENT_ID_PROPERTY_NAME;
      import static org.kie.services.client.serialization.SerializationConstants.SERIALIZATION_TYPE_PROPERTY_NAME;
      import static org.kie.services.shared.ServicesVersion.VERSION;
      
      import java.util.Collections;
      import java.util.List;
      import java.util.Set;
      import java.util.UUID;
      
      import javax.jms.Connection;
      import javax.jms.ConnectionFactory;
      import javax.jms.JMSException;
      import javax.jms.Message;
      import javax.jms.MessageConsumer;
      import javax.jms.MessageProducer;
      import javax.jms.Queue;
      import javax.jms.Session;
      import javax.jms.TextMessage;
      import javax.naming.InitialContext;
      import javax.naming.NamingException;
      
      import org.kie.api.command.Command;  1
      import org.kie.api.runtime.process.ProcessInstance;
      import org.kie.api.task.model.TaskSummary;
      import org.kie.remote.client.api.RemoteRuntimeEngineFactory;  2
      import org.kie.remote.client.api.exception.MissingRequiredInfoException;
      import org.kie.remote.client.api.exception.RemoteApiException;
      import org.kie.remote.client.api.exception.RemoteCommunicationException;
      import org.kie.remote.client.jaxb.ClientJaxbSerializationProvider;
      import org.kie.remote.client.jaxb.JaxbCommandsRequest;
      import org.kie.remote.client.jaxb.JaxbCommandsResponse;
      import org.kie.remote.jaxb.gen.AuditCommand; 3
      import org.kie.remote.jaxb.gen.GetTaskAssignedAsPotentialOwnerCommand;
      import org.kie.remote.jaxb.gen.StartProcessCommand;
      import org.kie.remote.jaxb.gen.TaskCommand;
      import org.kie.services.client.serialization.JaxbSerializationProvider;
      import org.kie.services.client.serialization.SerializationException;
      import org.kie.services.client.serialization.SerializationProvider;
      import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;
      import org.kie.services.client.serialization.jaxb.rest.JaxbExceptionResponse;
      import org.slf4j.Logger;
      import org.slf4j.LoggerFactory;
      
      public class SendJmsExample {
      
      protected static final Logger logger = LoggerFactory.getLogger(SendJmsExample.class);
      
      public void sendCommandsViaJms( String user, String password, String connectionUser, String connectionPassword,
      String deploymentId, String processId, String hostName ) {
      
      /**
      * JMS setup
      */
      // Get JNDI context from server
      InitialContext context = RemoteRuntimeEngineFactory.getRemoteJbossInitialContext(hostName, connectionUser, connectionPassword);
      
      // Create JMS connection
      ConnectionFactory connectionFactory;
      try {
      connectionFactory = (ConnectionFactory) context.lookup("jms/RemoteConnectionFactory");
      } catch( NamingException ne ) {
      throw new RuntimeException("Unable to lookup JMS connection factory.", ne);
      }
      
      // Setup queues
      Queue sessionQueue, taskQueue, sendQueue, responseQueue;
      try {
      sendQueue = sessionQueue = (Queue) context.lookup("jms/queue/KIE.SESSION");
      taskQueue = (Queue) context.lookup("jms/queue/KIE.TASK");
      responseQueue = (Queue) context.lookup("jms/queue/KIE.RESPONSE");
      } catch( NamingException ne ) {
      throw new RuntimeException("Unable to lookup send or response queue", ne);
      }
      
      /**
      * Command preparation
      */
      StartProcessCommand startProcCmd = new StartProcessCommand();
      startProcCmd.setProcessId(processId);
      
      /**
      * Send command via JMS and receive response
      */
      SerializationProvider serializationProvider = ClientJaxbSerializationProvider.newInstance();
      ProcessInstance procInst = (ProcessInstance) sendJmsCommand(startProcCmd,
      connectionUser, connectionPassword,
      user, password, deploymentId, null,
      connectionFactory, sendQueue, responseQueue,
      serializationProvider, Collections.EMPTY_SET, JaxbSerializationProvider.JMS_SERIALIZATION_TYPE,
      5 * 1000);
      
      /**
      * Command preparation
      */
      GetTaskAssignedAsPotentialOwnerCommand gtaapoCmd = new GetTaskAssignedAsPotentialOwnerCommand();
      gtaapoCmd.setUserId(user);
      
      // Send command request
      Long processInstanceId = null; // needed if you're doing an operation on a PER_PROCESS_INSTANCE deployment
      
      /**
      * Send command via JMS and receive response
      */
      @SuppressWarnings("unchecked")
      List<TaskSummary> taskSumList = (List<TaskSummary>) sendJmsCommand(gtaapoCmd,
      connectionUser, connectionPassword,
      user, password, deploymentId, processInstanceId,
      connectionFactory, sendQueue, responseQueue,
      serializationProvider, Collections.EMPTY_SET, JaxbSerializationProvider.JMS_SERIALIZATION_TYPE,
      5 * 1000);
      
      long taskId = taskSumList.get(0).getId();
      }
      
      // @formatter:off
      public static Object sendJmsCommand( Command command,
      String connUser, String connPassword,
      String userName, String password, String deploymentId, Long processInstanceId,
      ConnectionFactory factory, Queue sendQueue, Queue responseQueue,
      SerializationProvider serializationProvider, Set<Class<?>> extraJaxbClasses, int serializationType,
      long timeoutInMillisecs ) {
      // @formatter:on
      
      if( deploymentId == null && !(command instanceof TaskCommand || command instanceof AuditCommand) ) {
      throw new MissingRequiredInfoException("A deployment id is required when sending commands involving the KieSession.");
      }
      JaxbCommandsRequest req; 4
      if( command instanceof AuditCommand ) {
      req = new JaxbCommandsRequest(command);
      } else {
      req = new JaxbCommandsRequest(deploymentId, command);
      }
      
      req.setProcessInstanceId(processInstanceId);
      req.setUser(userName);
      req.setVersion(VERSION);
      
      Connection connection = null;
      Session session = null;
      JaxbCommandsResponse cmdResponse = null;
      String corrId = UUID.randomUUID().toString();
      String selector = "JMSCorrelationID = '" + corrId + "'";
      try {
      
      // setup
      MessageProducer producer;
      MessageConsumer consumer;
      try {
      if( password != null ) {
      connection = factory.createConnection(connUser, connPassword);
      } else {
      connection = factory.createConnection();
      }
      session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
      
      producer = session.createProducer(sendQueue);
      consumer = session.createConsumer(responseQueue, selector);
      
      connection.start();
      } catch( JMSException jmse ) {
      throw new RemoteCommunicationException("Unable to setup a JMS connection.", jmse);
      }
      
      // Create msg
      TextMessage textMsg; 5
      try {
      
      // serialize request
      String xmlStr = serializationProvider.serialize(req); 6
      textMsg = session.createTextMessage(xmlStr);
      
      // set properties
      // 1. corr id
      textMsg.setJMSCorrelationID(corrId);
      // 2. serialization info
      textMsg.setIntProperty(SERIALIZATION_TYPE_PROPERTY_NAME, serializationType);
      if( extraJaxbClasses != null && !extraJaxbClasses.isEmpty() ) {
      if( deploymentId == null ) {
      throw new MissingRequiredInfoException(
      "Deserialization of parameter classes requires a deployment id, which has not been configured.");
      }
      textMsg.setStringProperty(DEPLOYMENT_ID_PROPERTY_NAME, deploymentId);
      }
      // 3. user/pass for task operations
      boolean isTaskCommand = (command instanceof TaskCommand);
      if( isTaskCommand ) {
      if( userName == null ) {
      throw new RemoteCommunicationException(
      "A user name is required when sending task operation requests via JMS");
      }
      if( password == null ) {
      throw new RemoteCommunicationException(
      "A password is required when sending task operation requests via JMS");
      }
      textMsg.setStringProperty("username", userName);
      textMsg.setStringProperty("password", password);
      }
      // 4. process instance id
      } catch( JMSException jmse ) {
      throw new RemoteCommunicationException("Unable to create and fill a JMS message.", jmse);
      } catch( SerializationException se ) {
      throw new RemoteCommunicationException("Unable to deserialze JMS message.", se.getCause());
      }
      
      // send
      try {
      producer.send(textMsg);
      } catch( JMSException jmse ) {
      throw new RemoteCommunicationException("Unable to send a JMS message.", jmse);
      }
      
      // receive
      Message response;
      try {
      response = consumer.receive(timeoutInMillisecs);
      } catch( JMSException jmse ) {
      throw new RemoteCommunicationException("Unable to receive or retrieve the JMS response.", jmse);
      }
      
      if( response == null ) {
      logger.warn("Response is empty");
      return null;
      }
      // extract response
      assert response != null: "Response is empty.";
      try {
      String xmlStr = ((TextMessage) response).getText();
      cmdResponse = (JaxbCommandsResponse) serializationProvider.deserialize(xmlStr); 7
      } catch( JMSException jmse ) {
      throw new RemoteCommunicationException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()
      + " instance from JMS response.", jmse);
      } catch( SerializationException se ) {
      throw new RemoteCommunicationException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()
      + " instance from JMS response.", se.getCause());
      }
      assert cmdResponse != null: "Jaxb Cmd Response was null!";
      } finally {
      if( connection != null ) {
      try {
      connection.close();
      if( session != null ) {
      session.close();
      }
      } catch( JMSException jmse ) {
      logger.warn("Unable to close connection or session!", jmse);
      }
      }
      }
      
      String version = cmdResponse.getVersion();
      if( version == null ) {
      version = "pre-6.0.3";
      }
      if( !version.equals(VERSION) ) {
      logger.info("Response received from server version [{}] while client is version [{}]! This may cause problems.",
      version, VERSION);
      }
      
      List<JaxbCommandResponse<?>> responses = cmdResponse.getResponses();
      if( responses.size() > 0 ) {
      JaxbCommandResponse<?> response = responses.get(0);
      if( response instanceof JaxbExceptionResponse ) {
      JaxbExceptionResponse exceptionResponse = (JaxbExceptionResponse) response;
      throw new RemoteApiException(exceptionResponse.getMessage());
      } else {
      return response.getResult();
      }
      } else {
      assert responses.size() == 0: "There should only be 1 response, not " + responses.size() + ", returned by a command!";
      return null;
      }
      }
      }

1 2 3

These classes can all be found in the kie-api, kie-services-client and kie-services-jaxb JARs. For this example, the only dependency needed is org.kie.remote:kie-remote-client, which transitively depends on both the org.kie:kie-api and org.kie.remote:kie-remote-jaxb artifacts.

4

The JaxbCommandsRequest instance is the "holder" object in which you can place all of the commands you want to execute in a particular request. By using the JaxbCommandsRequest.getCommands() method, you can retrieve the list of commands in order to add more commands to the request. A deployment id is required for command request messages that deal with business processes. Command request messages that only contain human task-related commands do not require a deployment id.

5

Note that the JMS message sent to the remote JMS API must be constructed as follows:

  • It must be a JMS text message (javax.jms.TextMessage).
  • It must contain a serialized instance of a JaxbCommandsRequest, added to the message as a UTF string
  • It must have a filled JMS Correlation ID property.
  • It must have an int property with the name of "serialization" set to an acceptable value (only 0 at the moment).

6 7

The same serialization mechanism used to serialize the request message will be used to serialize the response message.

17.5. Additional Information

Except for the Execute calls, all other REST calls described below can use either JAXB or JSON.

All REST calls, unless otherwise specified, use JAXB serialization.

When using JSON, make sure to add the JSON media type ("application/json") to the ACCEPT header of your REST call.

Sometimes, users may wish to pass instances of their own classes as parameters to commands sent in a REST or Webservice request or JMS message. In order to do this, there are a number of requirements.

Retrieving process variables

While submitting an instance of a user-defined class is possible via both the JMS and REST API, retrieving an instance of the process variable is only possible via the REST API.

When interacting with the Remote API, users may want to pass instances of their own classes as parameters to certain operations. As mThis will only be possible if the KJar for a deployment includes these classes.

REST calls that involve the TaskService (e.g. that start with /task..), often do not contain any information about the associated deployment. In that case, an extra query parameter will have to be added to the REST call so that the server can find the appropriate deployment with the class (definition) and correctly deserialize the information passed with the call.

For these REST calls which do not contain the deployment id, you’ll need to add the following parameter:

Table 17.14. Deployment id query parameter

Parameter nameDescription

deploymentId

Value (must match the regex [a-zA-Z0-9-:\.]+) specifies the deployment which contains the user-defined class(es) needed to correctly deserialze information passed in the call


Some of the REST calls below return lists of information. The results of these operations can be paginated, which means that the lists can be split up and returned according to the parameters sent by the user.

For example, if the REST call parameters indicate that page 2 with page size 10 should be returned for the results, then results 10 to (and including) 19 will be returned.

The first page is always page 1 (as opposed to page "0").

Table 17.15. Pagination query parameter syntax

Parameter nameDescription

page

The page number requested. The default value is 1.

p

Synonym for the above page parameter.

pageSize

The number of elements per page to return. The default value is 10.

s

Synonym for the above pageSize parameter.


If both a "long" pagination parameter and its synonym are used, then only the value from the "long" variant is used. For example, if the page is given with a value of 11 and the p parameter is given with a value of 37, then the value of the page parameter, 11 , will be used and the p parameter will be ignored.

For the following operations, pagination is always used. See above for the default values used.

Table 17.16. REST operations using pagination

REST call URLShort Description

/history/instance

Returns a list of ProcessInstanceLog instances

/history/instance/{procInstid}

Returns a list of ProcessInstanceLog instances

/history/instance/{procInstId}/child

Returns a list of ProcessInstanceLog instances

/history/instance/{procInstId}/node

Returns a list of NodeInstanceLog instances

/history/instance/{procInstId}/node/{nodeId}

Returns a list of NodeInstanceLog instances

/history/instance/{procInstId}/variable

Returns a list of VariableInstanceLog instances

/history/instance/{procInstId}/variable/{varId}

Returns a list of VariableInstanceLog instances

/history/variable/{variableId}

Returns a list of VariableInstanceLog instances

/history/variable/{variableId}/instances

Returns a list of ProcessInstance instances

/history/variable/{variableId}/value/{value}

Returns a list of ProcessInstance instances

/history/variable/{variableId}/value/{value}/instances

Returns a list of ProcessInstance instances

/history/process/{procDefId}

Returns a list of ProcessInstanceLog instances

/task/query

Returns a list of TaskSummaryImpl instances

/query/runtime/task

Returns a JaxbQueryTaskResult instance

/query/runtime/process

Returns a JaxbQueryProcessInstanceResult instance


If you’re triggering an operation with a REST API call that would normally (e.g. when interacting the same operation on a local KieSession or TaskService instance) take an instance of a java.util.Map as one of its parameters, you can submit key-value pairs to the operation to simulate this behaviour by passing a query parameter whose name starts with map_.

Example 17.8. Query parameter examples

If you pass the query parameter map_kEy=vAlue in a REST call, then the Map that’s passed to the actual underlying KieSession or TaskService operation will contain this (String, String) key value pair: "kEy" ⇒ "vAlue". You could pass this parameter like so:

http://localhost:8080/kie-wb/rest/runtime/myproject/process/wonka.factory.loompa.hire/start?map_kEy=vAlue

Map query parameters also use the object query parameter syntax described below, so the following query parameter, map_total=5000 will be translated into a key-value pair in a map where the key is the String "total" and the value is a Long with the value of 5000. For example:

http://localhost:8080/kie-wb/rest/runtime/myproject/process/wonka.factory.oompa.chocolate/start?map_total=5000`

The following operations take query map parameters:

  • /runtime/{deploymentId}/process/{processDefId}/start
  • /runtime/{deploymentId}/workitem/{processItemId}/complete
  • /runtime/{deploymentId}/withvars/process/{processDefId}/start
  • /task/{taskId}/complete
  • /task/{taskId}/fail

While REST calls obviously only take strings as query parameters, using the following notation for query parameters will mean that the string is translated into a different type of object when the value of the string is used in the actual operation:

Table 17.17. Number query parameter syntax

Regex syntaxType

\d+

Long

\d+i

Integer

\d+l

Long


The remote API calls allow access to the underlying deployments, regardless of whether these deployments use the Singleton, Per-Process-Instance or Per-Request strategies.

While there’s enough information in the URL in order to access deployments that use the Singleton , or Per-Request strategies, that’s not always the case with the Per-Process-Instance runtimes because the remote API operation will need the process instance id in order to identify the deployment.

Therefore, for REST calls for which the URL does not contain the process instance id, you’ll need to add the following parameter:

Table 17.18. Per-Process-Instance runtime query parameter

Parameter nameDescription

runtimeProcInstId

Value (must match the regex [0-9]+) specifies the process instance id that identifies the underlying Per-Process-Instance deployment Will have no effect if the underlying deployment uses the Singleton or Per-Request strategy