Specifying authentication, modifying binding information, and working with response headers

Draft comment:
This topic is shared by BAW, CP4BA, CP4BASaaS. Last updated on 2025-03-13 12:15

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 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.

Draft comment:
Possible future improvement: Split this example into 3 realistic examples - one for each authorization option. 2016-09-15

// 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);

Draft comment:
What are the default timeout values? 2016-09-15 Mick

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

Draft comment:
For CF2016.12 removed the example: Exchanging headers between activities:

Because the httpHeaders attribute of the BPMRESTRequest and BPMRESTResponse are of type Object, which can't be passed in or out of an activity without modification, you can convert it to a string and pass it between the activities by using an input and output variable.

The following example illustrates how to pass HTTP headers from Activity1, which has an output variable headersOut that is mapped to the input variable headersIn in Activity2.

In Activity1:

  var response = tw.system.invokeREST(request);
  // convert headers object into a String
  tw.local.headersOut = response.httpHeaders.toString();

In Activity2:

  // set http headers retrieved from the headersIn input variable
  // tw.local.headersIn is of type String
  var headers = JSON.parse(tw.local.headersIn);
  log.info("Response content from the request in Activity1 is of type " + headers["Content-Type"])