B.3. REST Task Attributes

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=CAR_BRAND

In the provided example, CAR_BRAND will be replaced by the value of the carBrand variable.

Method
The method of the request, such as GET, POST, or similar. The default method is GET.
ContentType
The data type in case of sending data. This attribute is mandatory for POST and PUT requests.
Content
The data you want to send. This attribute is mandatory for POST and PUT requests.
ConnectTimeout
The connection timeout. The default value is 60 seconds.
ReadTimeout

The timeout on response. The default value is 60 seconds.

It is possible to modify the default timeout configuration shown below: 

Integer connectTimeout = getParamAsInt(params.get("ConnectTimeout"));
if (connectTimeout==null) connectTimeout = 60000;
Integer readTimeout = getParamAsInt(params.get("ReadTimeout"));
if (readTimeout==null) readTimeout = 60000;
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.

HandleResponseErrors

An optional parameter that instructs the handler to throw errors in case of unsuccessful response codes.

HandleResponseErrors can be handled in two ways:

  1. Process Definition

    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

    This can be enabled by setting the REST work item input variable HandleResponseErrors to the value true.

    Important

    The HandleResponse must have a valid boolean expression or be left empty (which will default to false), otherwise it will fail.

    When the REST work item input variable HandleResponseErrors is set to true, the RESTWorkItemHandler 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 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.

Output Attributes

Result
The result returned by the REST service.
ResultClass
This attribute determines the class to which the value from the Result attribute will be converted. The default value is String.
Status
This variable will always be filled. It will either have a value from interval 200 to 300 if successful, or an error response code if the request was unsuccessful.
StatusMsg
If the service returned an error response, this will contain the error response message.

All output attributes are String by default.