IBM BPM version 8570 cumulative fix 2016.09

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.

Tip: For more information about the JavaScript function, objects, and attributes, see the reference information topic JavaScript API.

Invoking a Watson service that requires an API key

The following JavaScript template could be used to invoke an operation named OperationName of a Watson service that is named WatsonServiceName where your Bluemix Watson service credential API key is 12345678fbb24c6b4b969e91a556993b55e074187, and the service flow has an output variable named serviceFlowOutput of business object type BusinessObjectForServiceFlowOutput.

var request = new BPMRESTRequest();

request.externalServiceName = "WatsonServiceName"          // The name used when creating the external service e.g. "AlchemyDataNews";
request.operationName = "OperationName"                    // The name of the operation, e.g. "GetNews";  
//request.httpHeaders = ...;                                             // Consider specifying request headers as required by the specific Watson service
request.parameters = {                                     // The parameters, depends on the specific service
     "apikey": "12345678fbb24c6b4b969e91a556993b55e074187",// The API key found in the Watson service credentials
     "param1" : ...                                   
     ...
  };
 
var response = tw.system.invokeREST(request);

// If the response is JSON, transfer the simple-type fields one by one into the output
var resonseJson = JSON.parse(response.content);
tw.local.serviceFlowOutput = new tw.object.BusinessObjectForServiceFlowOutput(); 
tw.local.serviceFlowOutput.A = responseJson.someString;
tw.local.serviceFlowOutput.B = responseJson.someBoolean;

Invoking a REST service and overriding the service binding information specified for the REST server

By default the JavaScript API invokeREST() uses the service binding specifications provided for the REST server of the external service. You can use the BPMRESTRequest object to selectively override any of these settings.

The following example illustrates how to specifying the endpoint address, user name, password, SSL configuration, request timeout, and response timeout properties of the request object.

// Prepare REST request
var request = new BPMRESTRequest();
request.externalServiceName = "MyExternalService";
request.operationName = "echo";

// Overwrite the endpoint address provided by external service and swagger
request.endpointAddress = "https://localhost:9080/restBasePath";

// Provide operation-specific user credentials using user name/password overriding 
// what is provided by the REST service server of the external service. 
// Note: Web Process Designer does not support operation-level credential specifications.
request.username = "user";
request.password = "password";

// Instead of using username/password, provide invocationCredential, 
// overriding what is specified by the REST service server of the external service
// request.invocationCredential = "MyAuthenticationAlias";

// Set SSL configuration or overwrite the SSL configuration provided by the external service
request.sslConfiguration = "MySSLConfiguration";

// Overwrite the default request and response timeout in milliseconds
request.requestTimeout = 7200;
request.responseTimeout = 7200;

// Provide input parameters needed for the REST request
request.parameters = {"text": "hello world!"};

// invoke the REST service returning a BPMRESTResponse instance
var response = tw.system.invokeREST(request);

// Evaluate the response
log.info("Response - httpStatusCode: " + response.httpStatusCode);
log.info("Response - httpStatusMessage: " + response.httpStatusMessage);
log.info("Response - httpHeaders: " + response.httpHeaders);
log.info("Response - content: " + response.content);

Remember: To invoke REST services that are hosted on servers with certificates that are signed by the most common public certification authorities, you can specify the preconfigured SSL configuration that is named PublicInternetSSLSettings.

Tip: For more information about the BPMRESTRequest and BPMRESTResponse objects, see the reference topic in JavaScript API.

Working with response headers

The following example illustrates how to work with the response headers object that is returned within a BPMRESTResponse object. After making the REST invocation request, for headers that do not include a dash or special characters in their name, you can inspect the headers by using the httpHeaders attribute of the response object as shown below:

 var response = tw.system.invokeREST(request);
 var expires = response.httpHeaders.expires; // retrieve the 'expires' header

If a header contains a dash or special characters in its name, for example Content-Type, you must use the following notation to access the header:

 var response = tw.system.invokeREST(request);
 var contentTypes = response.httpHeaders["Content-Type"]; // retrieve the 'Content-Type' header