Chapter 21. Remote API

REST API calls to the Knowledge Store REST API allow you to manage the organization units, repositories, and projects.

All POST and DELETE calls return details about the request as well as a job ID that can be used to request the job status and verify whether the job finished successfully. The GET calls return information about repositories, projects, and organizational units.

Parameters and results of these calls are provided in the form of JSON entities. Java classes for different entities are available in the org.guvnor.rest.client package and are referenced in the following text.

The KIE module JAR files can be deployed or undeployed using the Business Central UI or the REST API calls.

Deployment units are represented by a unique deployment ID consisting of the following elements separated by colons:

Red Hat JBoss BPM Suite allows you to get a diagram of your process in Business Central through the remote REST API. To get the diagram, you need to generate the image based on the SVG source first, which is done automatically by the process designer when you save a process definition.

To ensure that the process is saved in the process designer as SVG and is added to the kJAR, set <storesvgonsave enabled="true"/> in the /org.kie.workbench.KIEWebapp/profiles/jbpm.xml file in business-central.war. SVGImageProcessor adds further annotations based on the audit log data. You can extend SVGImageProcessor further for more advanced visualizations.

The following process image REST operations are provided by Business Central:

Runtime REST API provided by Business Central allows you to work with its underlying execution server, including process engine, task service, and business rule engine, and manipulate runtime data.

With the exception of execute operations (see Section 21.1.6, “Execute Operations”), all the other REST calls can use JAXB or JSON. The calls are synchronous and return the requested data as JAXB objects by default. When using JSON, the JSON media type (application/json) should be added to the ACCEPT header of the REST call.

map_age=5000

{ "age" => Long.parseLong("5000") }

curl -v -H 'Accept: application/json' -u eko 'localhost:8080/business-central/rest/tasks/'

/history/instances?page=3&pageSize=20
/history/instances?p=3&s=20

/rest/runtime/business-central/process/org.jbpm.test/start?map_var1=1234i

The REST Query API allows developers to query tasks, process instances, and their variables. The operations results are grouped by the process instance they belong to.

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

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

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

processId=org.example.process&taskId_min=52

processId_re=org.example.*&processVersion=2.0

For remote communication, it is recommended to use the Remote Java API. See Section 21.5, “Remote Java API”.

For performing runtime operations that involves passing a custom Java object used in the process (such as starting a process instance with process variables, or completing a task with task variables), you can use the approach mentioned in Section 21.5.2.3, “Custom Model Objects and Remote API”.

If it is not possible to use the Remote Java API or if your requirement is to use the REST API directly, you may consider using the execute operations. While the REST API accepts only string or integer values as parameters, the execute operation allows you to send complex Java objects to perform Red Hat JBoss BPM Suite runtime operations.

The execute operations are created to support the Remote Java API. Use the operations only in exceptional circumstances, such as:

Additionally, you can consider using the execute operations in cases when you are running any other client besides Java.

In the following example, a complex object org.MyPOJO is passed as a parameter to start a process:

package com.redhat.gss.jbpm;

import java.io.StringReader;
import java.io.StringWriter;
import java.net.URL;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.core.MediaType;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;

import org.MyPOJO;
import org.apache.commons.codec.binary.Base64;
import org.jboss.resteasy.client.ClientRequest;
import org.jboss.resteasy.client.ClientRequestFactory;
import org.jboss.resteasy.client.ClientResponse;
import org.kie.api.command.Command;
import org.kie.remote.client.jaxb.JaxbCommandsRequest;
import org.kie.remote.client.jaxb.JaxbCommandsResponse;
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.services.client.serialization.JaxbSerializationProvider;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;

public class StartProcessWithPOJO {

  /*
   * Set the parameters according your installation:
   */
  private static final String DEPLOYMENT_ID = "org.kie.example:project1:3.0";
  private static final String PROCESS_ID = "project1.proc_start";
  private static final String PROCESS_PARAM_NAME = "myPOJO";
  private static final String APP_URL = "http://localhost:8080/business-central/rest";
  private static final String USER = "jesuino";
  private static final String PASSWORD = "redhat2014!";

  public static void main(String[] args) throws Exception {
    // List of commands to be executed:
    List<Command> commands = new ArrayList<>();

    // A sample command to start a process:
    StartProcessCommand startProcessCommand = new StartProcessCommand();
    JaxbStringObjectPairArray params = new JaxbStringObjectPairArray();
    params.getItems().add(new JaxbStringObjectPair(PROCESS_PARAM_NAME, new MyPOJO("My POJO TESTING")));
    startProcessCommand.setProcessId(PROCESS_ID);
    startProcessCommand.setParameter(params);
    commands.add(startProcessCommand);
    List<JaxbCommandResponse<?>> response = executeCommand(DEPLOYMENT_ID, commands);
    System.out.printf("Command %s executed.\n", response.toString());
    System.out.println("commands1" + commands);
  }

  private static List<JaxbCommandResponse<?>> executeCommand(String deploymentId, List<Command> commands) throws Exception {

    URL address = new URL(APP_URL + "/execute");
    ClientRequest request = createRequest(address);

    request.header(JaxbSerializationProvider.EXECUTE_DEPLOYMENT_ID_HEADER, DEPLOYMENT_ID);
    JaxbCommandsRequest commandMessage = new JaxbCommandsRequest();
    commandMessage.setCommands(commands);
    commandMessage.setDeploymentId(DEPLOYMENT_ID);
    String body = convertJaxbObjectToString(commandMessage);
    request.body(MediaType.APPLICATION_XML, body);
    ClientResponse<String> responseObj = request.post(String.class);
    String strResponse = responseObj.getEntity();
    System.out.println("RESPONSE FROM THE SERVER: \n" + strResponse);
    JaxbCommandsResponse cmdsResp = convertStringToJaxbObject(strResponse);

    return cmdsResp.getResponses();
  }

  private static ClientRequest createRequest(URL address) {
    return new ClientRequestFactory()
      .createRequest(address.toExternalForm())
      .header("Authorization", getAuthHeader());
  }

  private static String getAuthHeader() {
    String auth = USER + ":" + PASSWORD;
    byte[] encodedAuth = Base64.encodeBase64(auth.getBytes(Charset.forName("US-ASCII")));

    return "Basic " + new String(encodedAuth);
  }

  private static String convertJaxbObjectToString(Object object) throws JAXBException {
    // Add your classes here.

    Class<?>[] classesToBeBound = { JaxbCommandsRequest.class, MyPOJO.class };
    Marshaller marshaller = JAXBContext
      .newInstance(classesToBeBound)
      .createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    StringWriter stringWriter = new StringWriter();
    marshaller.marshal(object, stringWriter);
    String output = stringWriter.toString();
    System.out.println("REQUEST CONTENT: \n" + output);

    return output;
  }

  private static JaxbCommandsResponse convertStringToJaxbObject(String str)
    throws JAXBException {
      Unmarshaller unmarshaller = JAXBContext
        .newInstance(JaxbCommandsResponse.class)
        .createUnmarshaller();

      return (JaxbCommandsResponse) unmarshaller.unmarshal(new StringReader(str));
    }
}

In this example, the org.kie.remote.jaxb.gen package classes are used for the client, which are in the org.kie.remote:kie-remote-client artifact. The deployment ID is set using a new HTTP header Kie-Deployment-Id that is also available as the JaxbSerializationProvider.EXECUTE_DEPLOYMENT_ID_HEADER Java constant.

The /execute call takes the JaxbCommandsRequest object as its parameter. The JaxbCommandsRequest object contains a list of org.kie.api.command.Command objects. The commands are stored in the JaxbCommandsRequest object, which are converted to a string representation and sent to the execute REST call. The JaxbCommandsRequest parameters are deploymentId and a Command object.

When you send a command to the /execute endpoint, a Java code is used to convert the Command object to String in an XML format. Once you generate the XML, you can use any Java or non-Java client to send it to the REST endpoint exposed by Business Central.

Note that the org.MyPOJO class must be the same in your client code as well as on the server side. To achieve this, share it through a Maven dependency: create the org.MyPOJO class using the Data Modeler in Business Central and in your REST client, add the dependency of the project which includes the org.MyPOJO class. An example of the pom.xml file with the dependency of the project created in Business Central that contains the org.MyPOJO class and other required dependencies follows.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.redhat.gss.jbpm</groupId>
  <artifactId>bpms-start-process</artifactId>
  <version>1.0</version>
  <name>Start process using execute</name>
  <properties>
    1
    <version.org.jboss.bom.eap>6.4.7.GA</version.org.jboss.bom.eap>
    2
    <version.org.jboss.bom.brms>6.4.0.GA-redhat-2</version.org.jboss.bom.brms>
    <maven.compiler.target>1.7</maven.compiler.target>
    <maven.compiler.source>1.7</maven.compiler.source>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.jboss.bom.brms</groupId>
        <artifactId>jboss-brms-bpmsuite-platform-bom</artifactId>
        <type>pom</type>
        <version>${version.org.jboss.bom.brms}</version>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>org.jboss.bom.eap</groupId>
        <artifactId>jboss-javaee-6.0-with-tools</artifactId>
        <version>${version.org.jboss.bom.eap}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>org.jboss.bom.brms</groupId>
        <artifactId>jboss-javaee-6.0-with-brms-bpmsuite</artifactId>
        <version>${version.org.jboss.bom.brms}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.kie.remote</groupId>
      <artifactId>kie-remote-client</artifactId>
    </dependency>
    <dependency>
      <groupId>org.drools</groupId>
      <artifactId>drools-core</artifactId>
    </dependency>
    <dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-jaxrs</artifactId>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
    </dependency>
    <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
    </dependency>
    <!-- A Business Central project dependency which contains the POJO. -->
    <dependency>
      <artifactId>remote-process-start-with-bean</artifactId>
      <groupId>com.redhat.gss</groupId>
      <version>1.0</version>
    </dependency>
  </dependencies>
</project>

In the example, com.redhat.gss:remote-process-start-with-bean:1.0 is the kJAR created by Business Central. The kJAR includes the org.MyPOJO class. By sharing the dependency, you ensure that your org.MyPOJO class on the server matches with the one on the client.

Another way to achieve this is to create a data model using Red Hat JBoss Developer Studio, export the JAR file, and add it as a dependency of both the Business Central kJAR and your REST client.

<?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>

<?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>

<?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>

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

http://SERVER:PORT/business-central/rest

You can use the following roles:

When you deploy Business Central on the Java EE application server, it automatically creates the following JMS queues:

The KIE.SESSION and KIE.TASK queues are 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 queue and command request messages that involve managing human tasks should be sent to the KIE.TASK queue.

Although there are two different input queues, KIE.SESSION and KIE.TASK, it is to provide multiple input queues to optimize processing: command request messages will be processed in the same manner regardless of which queue they are sent to. However, in some cases, users may send 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 byte message that contains a serialized JaxbCommandsRequest object. At the moment, only XML serialization is supported as opposed to, for example, JSON or protobuf.

JMS queue KIE.EXECUTOR is used in the Job Executor component to speed up processing of asynchronous tasks and defined jobs. See Section 11.12.3, “Job Executor for Asynchronous Execution” for more information about Job Executor. Note that the executor can work without JMS. You can disable JMS, for example, when you deploy Red Hat JBoss BPM Suite on container without full JMS support out of the box, such as Tomcat. To disable JMS, set the following property: org.kie.executor.jms=false.

The following example shows the usage of the JMS API. The numbers (callouts) in the example refer to notes below that explain particular parts of the example. It is provided for the advanced users that do not wish to use the Red Hat JBoss BPM Suite Remote Java API which otherwise incorporates the logic shown below.

// Usual Java imports skipped.

import org.drools.core.command.runtime.process.StartProcessCommand;
import org.jbpm.services.task.commands.GetTaskAssignedAsPotentialOwnerCommand;
import org.kie.api.command.Command;
import org.kie.api.runtime.process.ProcessInstance;
import org.kie.api.task.model.TaskSummary;
// 1
import org.kie.services.client.api.command.exception.RemoteCommunicationException;
import org.kie.services.client.serialization.JaxbSerializationProvider;
import org.kie.services.client.serialization.SerializationConstants;
import org.kie.services.client.serialization.SerializationException;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandsRequest;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandsResponse;
import org.kie.services.client.serialization.jaxb.rest.JaxbExceptionResponse;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class DocumentationJmsExamples {

  protected static final Logger logger = LoggerFactory.getLogger(DocumentationJmsExamples.class);

  public void sendAndReceiveJmsMessage() {

    String USER = "charlie";
    String PASSWORD = "ch0c0licious";

    String DEPLOYMENT_ID = "test-project";
    String PROCESS_ID_1 = "oompa-processing";
    URL serverUrl;
    try {
      serverUrl = new URL("http://localhost:8080/business-central/");
    } catch (MalformedURLException murle) {
      logger.error("Malformed URL for the server instance!", murle);
      return;
    }

    // Create JaxbCommandsRequest instance and add commands:
    Command<?> cmd = new StartProcessCommand(PROCESS_ID_1);
    int oompaProcessingResultIndex = 0;
    // 5
    JaxbCommandsRequest req = new JaxbCommandsRequest(DEPLOYMENT_ID, cmd);
    // 2
    req.getCommands().add(new GetTaskAssignedAsPotentialOwnerCommand(USER, "en-UK"));
    int loompaMonitoringResultIndex = 1;
    // 5
    // Get JNDI context from server:
    InitialContext context = getRemoteJbossInitialContext(serverUrl, USER, PASSWORD);

    // 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);
    }

    // Set up queues:
    Queue sendQueue, responseQueue;
    try {
      sendQueue = (Queue) context.lookup("jms/queue/KIE.SESSION");
      responseQueue = (Queue) context.lookup("jms/queue/KIE.RESPONSE");
    } catch (NamingException ne) {
      throw new RuntimeException("Unable to lookup send or response queue", ne);
    }

    // Send command request:
    Long processInstanceId = null; // needed if you are doing an operation on a PER_PROCESS_INSTANCE deployment
    String humanTaskUser = USER;
    JaxbCommandsResponse cmdResponse = sendJmsCommands(DEPLOYMENT_ID, processInstanceId, humanTaskUser, req, connectionFactory, sendQueue, responseQueue, USER, PASSWORD, 5);

    // Retrieve results:
    ProcessInstance oompaProcInst = null;
    List<TaskSummary> charliesTasks = null;

    // 6

    for (JaxbCommandResponse<?> response : cmdResponse.getResponses()) {
      if (response instanceof JaxbExceptionResponse) {
        // Something went wrong on the server side:
        JaxbExceptionResponse exceptionResponse = (JaxbExceptionResponse) response;
        throw new RuntimeException(exceptionResponse.getMessage());
      }

      // 5

      if (response.getIndex() == oompaProcessingResultIndex) {
        oompaProcInst = (ProcessInstance) response.getResult();
      // 6
      } else if (response.getIndex() == loompaMonitoringResultIndex) {
    	// 5
        charliesTasks = (List<TaskSummary>) response.getResult();
      // 6
      }
    }
  }

  private JaxbCommandsResponse sendJmsCommands(String deploymentId, Long processInstanceId, String user, JaxbCommandsRequest req, ConnectionFactory factory, Queue sendQueue, Queue responseQueue, String jmsUser, String jmsPassword, int timeout) {

    req.setProcessInstanceId(processInstanceId);
    req.setUser(user);

    Connection connection = null;
    Session session = null;
    String corrId = UUID.randomUUID().toString();
    String selector = "JMSCorrelationID = '" + corrId + "'";
    JaxbCommandsResponse cmdResponses = null;
    try {
      // Setup:
      MessageProducer producer;
      MessageConsumer consumer;
      try {
        if (jmsPassword != null) {
          connection = factory.createConnection(jmsUser, jmsPassword);
        } 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);
      }
      // 7

      JaxbSerializationProvider serializationProvider = new JaxbSerializationProvider();
      // If necessary, add user-created classes here:
      // xmlSerializer.addJaxbClasses(MyType.class, AnotherJaxbAnnotatedType.class);

      // Create msg:
      BytesMessage msg;
      try {
        msg = session.createBytesMessage();
        // 3
        // Set properties:
        msg.setJMSCorrelationID(corrId);
        // 3
        msg.setIntProperty(SerializationConstants.SERIALIZATION_TYPE_PROPERTY_NAME, JaxbSerializationProvider.JMS_SERIALIZATION_TYPE);

        // 3

        Collection<Class<?>> extraJaxbClasses = serializationProvider.getExtraJaxbClasses();
        if (!extraJaxbClasses.isEmpty()) {
          String extraJaxbClassesPropertyValue = JaxbSerializationProvider.classSetToCommaSeperatedString(extraJaxbClasses);
          msg.setStringProperty(SerializationConstants.EXTRA_JAXB_CLASSES_PROPERTY_NAME, extraJaxbClassesPropertyValue);
          msg.setStringProperty(SerializationConstants.DEPLOYMENT_ID_PROPERTY_NAME, deploymentId);
        }

        // Serialize request:
        String xmlStr = serializationProvider.serialize(req);
        msg.writeUTF(xmlStr);

      // 3

      } 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(msg);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to send a JMS message.", jmse);
      }

      // Receive:
      Message response;

      // 4

      try {
        response = consumer.receive(timeout);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to receive or retrieve the JMS response.", jmse);
      }

      if (response == null) {
        logger.warn("Response is empty, leaving");
        return null;
      }
      // Extract response:
      assert response != null : "Response is empty.";
      try {
        String xmlStr = ((BytesMessage) response).readUTF();
        cmdResponses = (JaxbCommandsResponse) serializationProvider.deserialize(xmlStr);
      } 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 cmdResponses != null : "Jaxb Cmd Response was null!";
    } finally {
      if (connection != null) {
        try {
          connection.close();
          session.close();
        } catch (JMSException jmse) {
          logger.warn("Unable to close connection or session!", jmse);
        }
      }
    }
    return cmdResponses;
  }

  private InitialContext getRemoteJbossInitialContext(URL url, String user, String password) {

    Properties initialProps = new Properties();
    initialProps.setProperty(InitialContext.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
    String jbossServerHostName = url.getHost();
    initialProps.setProperty(InitialContext.PROVIDER_URL, "remote://"+ jbossServerHostName + ":4447");
    initialProps.setProperty(InitialContext.SECURITY_PRINCIPAL, user);
    initialProps.setProperty(InitialContext.SECURITY_CREDENTIALS, password);

    for (Object keyObj : initialProps.keySet()) {
      String key = (String) keyObj;
      System.setProperty(key, (String) initialProps.get(key));
    }
    try {
      return new InitialContext(initialProps);
    } catch (NamingException e) {
      throw new RemoteCommunicationException("Unable to create " + InitialContext.class.getSimpleName(), e);
    }
  }
}

Business Central in Red Hat JBoss BPM Suite provides a SOAP interface in the form of CommandWebService. A Java client is provided as a generated CommandWebService class and can be used as follows.

Classes generated by the kie-remote-client module function as a client-side interface for SOAP. The CommandWebServiceClient class referenced in the test code below is generated by the Web Service Description Language (WSDL) in the kie-remote-client JAR.

import org.kie.remote.client.api.RemoteRuntimeEngineFactory;
import org.kie.remote.client.jaxb.JaxbCommandsRequest;
import org.kie.remote.client.jaxb.JaxbCommandsResponse;
import org.kie.remote.jaxb.gen.StartProcessCommand;
import org.kie.remote.services.ws.command.generated.CommandWebService;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;

public JaxbProcessInstanceResponse startProcessInstance(String user, String password, String processId, String deploymentId, String applicationUrl) throws Exception {

  CommandWebService client = RemoteRuntimeEngineFactory
    .newCommandWebServiceClientBuilder()
    .addDeploymentId(deploymentId)
    .addUserName(user)
    .addPassword(password)
    .addServerUrl(applicationUrl)
    .buildBasicAuthClient();

  // Get a response from the WebService:
  StartProcessCommand cmd = new StartProcessCommand();
  cmd.setProcessId(processId);
  JaxbCommandsRequest req = new JaxbCommandsRequest(deploymentId, cmd);
  final JaxbCommandsResponse response = client.execute(req);

  JaxbCommandResponse<?> cmdResp = response.getResponses().get(0);

  return (JaxbProcessInstanceResponse) cmdResp;
}

The SOAP interface of Business Central in Red Hat JBoss BPM Suite is currently available for Red Hat JBoss EAP, IBM WebSphere, and Oracle WebLogic servers.

The artifacts that provide the EJB interface to the jBPM services are contained in the following packages:

The org.jbpm.services.ejb.api package mentioned above contains the following service interfaces that can be used by remote EJB clients:

A synchronization service that synchronizes the information between Business Central and EJBs is available as well. The synchronization interval can be set using the org.jbpm.deploy.sync.int system property. However, note that you have to wait for the service to finish the synchronization before trying to access the updated information using REST.

Follow the procedure below to create an EJB Services WAR file using the EJB interface.

For more information about invoking remote EJBs, see the Invoking Session Beans chapter of the Red Hat JBoss EAP Development Guide.

The following common methods can be called on both RemoteRestRuntimeEngineBuilder and RemoteJmsRuntimeEngineBuilder when creating a new instance of RemoteRuntimeEngine:

The RemoteRuntimeEngineFactory class is the starting point for building and configuring a new RemoteRuntimeEngine instance that can interact with the Remote API. This class creates an instance of a REST client builder using the newRestBuilder() method. This builder is then used to create a RemoteRuntimeEngine instance that acts as a client to the remote REST API.

In addition to the methods mentioned in Section 21.5.1, “Common Configuration”, the following configuration methods can be called on RemoteRestRuntimeEngineBuilder:

Once you have configured all the necessary properties, call build() to get access to RemoteRuntimeEngine.

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

package org.kie.remote.client.documentation;

import java.net.URL;
import java.util.List;

import org.kie.api.runtime.KieSession;
import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.api.runtime.process.ProcessInstance;
import org.kie.api.task.TaskService;
import org.kie.api.task.model.TaskSummary;
import org.kie.remote.client.api.RemoteRuntimeEngineFactory;

public class RemoteJavaApiRestClientExample {

 public void startProcessAndStartTask(URL baseUrl, String deploymentId, String user, String password) {

   // The baseUrl should contain a URL similar to
   // "http://localhost:8080/business-central/".

   // RuntimeEngine instance with the necessary information to communicate
   // with the REST services.

   // Select a user with the rest-all role.

   RuntimeEngine engine = RemoteRuntimeEngineFactory
     .newRestBuilder()
     .addDeploymentId(deploymentId)
     .addUrl(baseUrl)
     .addUserName(user)
     .addPassword(password)
     .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.
       ProcessInstance processInstance = ksession.startProcess("com.burns.reactor.maintenance.cycle");
       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);
   }
 }
}

import org.kie.api.task.model.OrganizationalEntity;
import org.kie.api.task.model.Task;

public List<OrganizationalEntity> getPotentialOwnersByTaskId(long taskId) {
    Task task = taskService.getTaskById(taskId);
    return task.getPeopleAssignments().getPotentialOwners();
}

import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.remote.client.api.RemoteRestRuntimeEngineBuilder;
import org.kie.remote.client.api.RemoteRestRuntimeEngineFactory;
import org.kie.remote.client.api.RemoteRuntimeEngineFactory;

import java.net.URL;

...

RuntimeEngine engine = RemoteRuntimeEngineFactory
  .newRestBuilder()
  .addUrl(instanceUrl)
  .addUserName(user)
  .addPassword(password)
  .build();

  // This call does not require the deployment ID and ends successfully:

  engine.getTaskService().claim(23l, "user");

  // This code throws a "MissingRequiredInfoException" because the
  // deployment ID is required:

  engine.getKieSession().startProcess("org.test.process");

RemoteRuntimeEngineFactory works similarly as the REST variation: it is a starting point for building and configuring a new RemoteRuntimeEngine instance that can interact with the remote JMS API. The main use for this class is to create a builder instance of JMS using the newJmsBuilder() method. The builder is then used to create a RemoteRuntimeEngine instance that will act as a client to the remote JMS API.

In addition to methods mentioned in Section 21.5.1, “Common Configuration”, the following configuration methods can be called on RemoteJmsRuntimeEngineBuilder:

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

import java.net.URL;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.kie.api.runtime.KieSession;
import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.api.runtime.process.ProcessInstance;
import org.kie.api.task.TaskService;
import org.kie.api.task.model.TaskSummary;
import org.kie.remote.client.api.RemoteRuntimeEngineFactory;
import org.kie.services.client.builder.objects.MyType;

public class RemoteJavaApiJmsClientExample {

    public void startProcessAndTaskViaJmsRemoteJavaAPI (URL serverUrl, String deploymentId, String user, String password) {
      // The serverURL should contain a URL similar to "http://localhost:8080/business-central".
      // Select a user with the rest-all role.

      // Set up remote JMS runtime engine factory:
      RuntimeEngine engine = RemoteRuntimeEngineFactory
        .newJmsBuilder()
        .addDeploymentId(deploymentId)
        .addJbossServerHostName(serverUrl.getHost())
        .addUserName(user)
        .addPassword(password)
        .build();

        // Interface with JMS API
        KieSession ksession = engine.getKieSession();

        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();
        TaskService taskService = engine.getTaskService();
        List<Long> tasks = taskService.getTasksByProcessInstanceId(procId);
        taskService.start(tasks.get(0), user);
    }
}

Configuration Using InitialContext Instance

When configuring the RemoteJmsRuntimeEngineBuilder with an InitialContext instance as a parameter, it is necessary to retrieve the (remote) instance of InitialContext first from the server. See the following example:

private InitialContext getRemoteJbossInitialContext(URL url, String user, String password) {

  Properties initialProps = new Properties();
  initialProps.setProperty(InitialContext.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
  String jbossServerHostName = url.getHost();
  initialProps.setProperty(InitialContext.PROVIDER_URL, "remote://"+ jbossServerHostName + ":4447");
  initialProps.setProperty(InitialContext.SECURITY_PRINCIPAL, user);
  initialProps.setProperty(InitialContext.SECURITY_CREDENTIALS, password);

  for (Object keyObj : initialProps.keySet()) {
    String key = (String) keyObj;
    System.setProperty(key, (String) initialProps.get(key));
  }

  try {
    return new InitialContext(initialProps);
  } catch (NamingException e) {
      throw new RemoteCommunicationException("Unable to create "
         + InitialContext.class.getSimpleName(), e);
  }
}

You can work with JMS queues directly without using RemoteRuntimeEngine. For more information, see the How to Use JMS Queues Without the RemoteRuntimeEngine in Red Hat JBoss BPMS article. However, this approach is not a recommended way to use the provided JMS interface.

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 list the available methods. Methods not listed in the tables below throw UnsupportedOperationException explaining that the called method is not available.

Available Process-Related KieSession Methods

Available Rules-Related KieSession Methods

Available WorkItemManager Methods

Available Task Operation TaskService Methods

Available Task Retrieval and Query TaskService Methods

Available AuditService Methods

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

By default, you may only work with tasks as the authenticated user. If you try to claim tasks on behalf of another user, you may get an exception similar to:

PermissionDeniedException thrown with message 'User '[UserImpl:'john']' does not have permissions to execute operation 'Claim' on task id 14'

This is caused by the security settings. To bypass the security settings:

If you are still experiencing the exception in your application, configure the UserGroupCallback settings. See Configuring UserGroupCallback for further information.