IBM BPM version 8570 cumulative fix 2016.09

Invoking a REST service by using JavaScript

Invoke a REST service from a script task in a service flow. This allows you to invoke service operations that cannot be selected as an implementation of a service task in a service flow in web Process Designer.

About this task

By using JavaScript to invoke a REST service you have more capabilities and control over setting the input parameters, request headers, authentication information, processing the output parameters, and handling errors.

Procedure

Make sure that you have a local copy of the OpenAPI (formerly known as Swagger) specification for the REST service and any necessary invocation credentials to be able to call the REST service.
Using web Process Designer, create an external service. and discover which operations are supported:
1. In your Process App, select Services > + > External Service > Discover an existing service, then select the local OpenAPI specification file as input. For more information about discovering an external REST service, see Invoking a REST API service.
2. If any errors are reported for operations, those operations cannot be called from a service task. If the discovered service operation that you want to invoke can be selected as an implementation of a service task in a service flow, that is simpler, however, if you want to use types other than application/json, you must use the JavaScript API to invoke the service.
3. To find the information that you need about the REST service that you want to invoke, such as operation name, parameters (including headers), security requirements, and response object structure, click the Source tab for the External service to view the OpenAPI specification source. For other information about the service, see the REST server configuration for the external service.
Check the server certificate for the REST service that you want to invoke. By using JavaScript you can override any SSL configuration that is specified as part of the REST server.
1. If the server certificate is signed by a public certification authority, you can use the preconfigured SSL configuration that is named PublicInternetSSLSettings.
2. If the server certificate is not signed by one of the public certification authorities that are included in the preconfigured SSL configuration, an administrator should create a new SSL configuration for this service and import the server certificate into a new trust store. For information about administering SSL configurations, see Creating a Secure Sockets Layer configuration and Retrieving signers from a remote SSL port.
If you already have a service flow defined, select it. Otherwise create a service flow by clicking Services > + > Service flow. For more information about creating a service flow, see Creating a service flow.
In web Process Designer, add a script task to your service flow.
Add JavaScript to the script task to perform the following actions.
1. Create a new instance of the request object. For example:
```
var request = new BPMRESTRequest();
```
2. Set the request object's attributes as necessary, such as the mandatory external service name, operation name, HTTP headers, and parameters for the operation, and optional attributes such as credentials and SSL configuration name. Any attributes that you specify in the request object override any corresponding values that are specified as part of the REST server for the external service in Process Designer.
  The request object has the following attributes:
  externalServiceName
  The name of the REST service. For example:
  request.externalServiceName = "language-translator-v2";
  operationName
  If the OpenAPI specification file specifies an operationId for the operation that you want to invoke, you must specify it as the operationName, otherwise, you must specify httpMethod and path. For example:
  request.operationName="checkout";
  httpMethod and path
  If the OpenAPI specification file does not specify an operationId for the operation, to identify the operation to be invoked you must specify the HTTP method and path instead of the operationName property. For example:
  request.httpMethod="GET"; request.path="/v1/orders";
  endpointAddress
  Optionally overrides the scheme, hostname, port, and base path that are specified in the OpenAPI specification file. For example:
  request.endpointAddress = "https://localhost:9080/restBasePath";
  httpHeaders
  A JSON object that specifies HTTP headers. For example:
  request.httpHeaders = {"Content-Type": "application/json", "Accept": "text/plain"};
  For formData:
  If it includes a file, specify content type multipart/form-data.
  
  If it does not include a file, specify content type multipart/form-data or application/x-www-form-urlencoded.
  parameters
  A JSON object that contains all necessary parameters for the operation. For example:
  request.parameters = {"priority": "high", "customer": "Max", "age" : "23"};
  requestTimeout
  The time in milliseconds to wait until the request will timeout. For example:
  request.requestTimeout = 2000;
  responseTimeout
  The time in milliseconds to wait until the response will timeout. For example:
  request.responseTimeout = 7200;
  username and password
  The user name and password, when using basic authentication. For example:
  request.username = "user"; request.password = "password";
  invocationCredential
  Provide the invocation credentials instead of the username and password for basic authentication. For example:
  request.invocationCredential = "MyAuthenticationAlias";
  sslConfiguration
  The name of the SSL configuration to use. For example:
  request.sslConfiguration = "MySSLConfiguration";
  Important: Make sure that you pass in the correct values that are required for a successful REST invocation. IBM® BPM passes values onto the REST service without validating them.
3. Call the tw.system.invokeREST() function on the request object, assigning the result to a new response object of type BPMRESTResponse(). For example:
```
var response = tw.system.invokeREST(request);
```
  Tip: If you get the following error:
```
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: 
PKIX path building failed ...
```
  you must get your administrator to create an SSL configuration and import the server certificate, as described in step 3.b.
4. Process the response as necessary.
For more information about the BPMRESTRequest() request object and the BPMRESTResponse response object, see JavaScript API.
Click Save or Finish Editing.