Chapter 33. REST Task

The REST task performs REST calls and outputs the response as an object.

RestWorkItemHandler is capable of interacting with the REST service, and supports both types of services:

  • Secured: requires authentication.
  • Open: does not require authentication.

Authentication methods currently supported are:

  • BASIC
  • FORM_BASED

Authentication information can be given on handler initialization and can be overridden using work item parameters. All other configuration options must be given in the work item parameters map:

Input Attributes

Url

Target URL to be invoked. This attribute is mandatory.

It is often necessary to configure the URL attribute with an expression. This gives you the ability to change the URL dynamically throughout the runtime. For example: 

http://DOMAIN:PORT/restService/getCars?brand=#{carBrand}

In this example, carBrand is replaced by the value of the carBrand process variable during runtime.

Method
The method of the request, such as GET, POST, or other. The default method is GET.
ContentType
The data type if you are sending data. The supported data types are application/json and application/xml. This attribute is mandatory for POST and PUT requests. If you want to use this attribute, map it as a data input variable in the Data I/O dialogue of the task.
Content
The data you want to send. This attribute is mandatory for POST and PUT requests. This is an optional parameter. If you want to use it, map it as a data input variable in the Data I/O dialogue of the task.
ConnectTimeout
The connection timeout. The default value is 60 seconds.
ReadTimeout
The timeout on response. The default value is 60 seconds.
Username
The user name for authentication. This attribute overrides the handler initialization user name.
Password

The password for authentication. This attribute overrides the handler initialization password.

User name and password for basic authentication can be passed at construction time using the following: 

RESTWorkItemHandler(String username, String password);
AuthUrl

The URL that is handling authentication when using the AuthenticationType.FORM_BASED authentication method.

Use the following constructor for FORM_BASED authentication: 

public RESTWorkItemHandler(String username, String password, String authUrl, ClassLoader classLoader) {
  this();
  this.username = username;
  this.password = password;
  this.type = AuthenticationType.FORM_BASED;
  this.authUrl = authUrl;
  this.classLoader = classLoader;
}

The following is an example of how the constructor must be used in Deployment descriptor: 

new org.jbpm.process.workitem.rest.RESTWorkItemHandler("username","password","http://mydomain.com/my-j-security-check-url",classLoader)
Important

AuthUrl configuration requires the typical implementation for FORM_BASED authentication in Java EE servers, and therefore should point to the j_security_check URL. Similarly, inputs for user name and password must be bound to j_username and j_password when using FORM_BASED authentication, otherwise authentication may fail.

ResultClass
This attribute determines the class to which the value from the Result attribute will be converted. If not provided, the default value is String.
HandleResponseErrors
An optional parameter that instructs the handler to throw errors in case of unsuccessful response codes. For information on how to handle response errors, see the section called “Handling REST Response Error”.

Output Attributes

Result
The result returned by the REST service.
Status
The variable contains a value from interval 200 to 300 if the REST request was successful, or an error response code if the request was unsuccessful. This variable is not mapped by default. If you want to use this variable, map it manually as an output variable of the REST task.
StatusMsg
If the service returned an error response, this variable will contain the error response message. This variable is not mapped by default. If you want to use this variable, map it manually as an output variable of the REST task.

All output attributes are String by default.

Handling REST Response Error

HandleResponseErrors can be handled in two ways:

  1. In the Process Definition Workflow

    1. Status: When RESTWorkItemHandler produces a Status output variable that includes an HTTP response code. This can be mapped to a process variable and used in a XOR gateway to determine the service outcome.

      user guide REST1
    2. StatusMsg: The output variable StatusMsg includes additional messages sent by the server, and is filled only when the HTTP Code is not between 200 and 300.

  2. Using a Boundary Event

    To enable this feature, set the REST work item input variable HandleResponseErrors to true.

    Important

    The HandleResponse must have a valid boolean expression or be left empty, which is equivalent to false. Otherwise, the REST task will throw an exception.

    When the REST work item input variable HandleResponseErrors is set to true, the RESTWorkItemHandler handler will, upon receiving an HTTP response code outside of the 200-300 interval, throw the following Java exception: 

    public RESTServiceException(int status, String response, String endpoint) {
  super("Unsuccessful response from REST server (status " + status +", endpoint " + endoint +", response " + response +"");

    With the HandleResponseErrors option enabled, this error can be caught using a boundary event:

    user guide REST2

    The provided example includes:

    • A WorkItemHandlerRuntimeException restError process variable.
    • A WorkItemHandlerRuntimeException BoundaryError event-defined output variable that has been mapped to the restError process variable.

    • A Script task that includes the following code: 

      org.jbpm.process.workitem.rest.RESTServiceException x = (org.jbpm.process.workitem.rest.RESTServiceException) restError.getCause().getCause();

      This code allows RestServiceException to be extracted from WorkItemHandlerRuntimeException. Using RestServiceException provides access to the following methods:

    • getResponse
    • getStatus

    • getEndpoint

      The next line in the Script task is: 

      System.out.println("response:"+x.getResponse());

      This provides the full error message as returned by the server.