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
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:
- 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 service.
- 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.
- 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.
- If the server certificate is signed by a public certification authority, you can use the preconfigured SSL configuration that is named PublicInternetSSLSettings.
- 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.
- Create a new instance of the request object. For example:
var request = new BPMRESTRequest();
- 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:
For formData:request.httpHeaders = {"Content-Type": "application/json", "Accept": "text/plain"};
- 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. - 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:
you must get your administrator to create an SSL configuration and import the server certificate, as described in step 3.b.javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed ...
- Process the response as necessary.
- Create a new instance of the request object. For example:
- Click Save or Finish Editing.
- Passing input parameters
How to use JavaScript to specify different input parameters for a REST service. - Specifying authentication, modifying binding information, and working with response headers
How to use JavaScript to specify authentication information for REST services, override the external service binding information, and work with response headers. - Passing file types
How to use JavaScript to invoke REST services that have an input parameters or a response of type file.
Parent topic: Invoking a REST service