Http adapter

The HTTP-Adapter allows TrustBuilder to perform various operations against an HTTP-server.

Prerequisites

To use HTTPS a configured truststore is mandatory. Even when trustremote is set to true, the store must exist. Making HTTPS connections without this will raise errors while connecting to the remote server.

Configuration

The adapter configuration specifies the adapter instance (adapter id), the global load-balancing settings and the configuration of one or more servers.

Workflow Settings

A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:

• Input Property: the variable containing the instructions the adapter have to execute

• Output Property: the variable the adapter will store the response in after execution

• Before Adapter Script: script that will be executed before calling the adapter

• After Adapter Script: script that will be executed after the adapter fulfilled its task

Request -API

httpRequest Create an HTTP request.

tb.httpRequest(options);

where options may contain:

• method : All known http verbs are supported (default = get)

• headers : key value pair (default = no headers)

• body : string to pass in the body of the request if this is a json object it will be transformed into request parameters

• path : request path of the request

• encoding : encoding to use (default = utf8)

• server : target a specific server

• includeResponseHeaders : include the headers of the response in the response object (true/false)

Example:

tb.httpRequest({
  method: 'get',
  headers: {"A" : "a"},
  body: '<a></a>',
  path: 'path'
});

Response - API

Common Properties The response API can be applied to the variable specified in the “output property” (see “Workflow Settings”): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.

All responses have four properties in common:

• status Status flag indicating whether the response is ok (0) or not (1).

• substatus Response specific number indicating what the problem was, eg. http status code

• message Response specific message in case there was a problem (can be null)

• rc Return Code, a human readable code based on the substatus

The status flag indicates whether a request was valid yes or no; consequently, the message or return code (rc) can be used to give the end-user a reasonable explanation or send the information to the underlying logging system.

Adapter Specific Properties

Response Codes

Additional Notes

Load Balancing The adapter supports load balancing, read more in the Loadbalancing chapter.

Connection Pool TrustBuilder maintains a pool of connections. By default they are persistent, but backend server response may force the connection to be closed. Connections may also be closed because of timeouts. TrustBuilder will create connections on demand, up to the ConnectionPoolSize. Connections stay in the pool until they become stale or are closed explicitly, e.g. by a response. If more threads are active than the ConnectionPoolSize, then they wait for a connection to become available.

SSL The security options specify whether to use plain HTTP transport or secure HTTP transport. If the “Security” tag is absent, plain HTTP will be used. Specifying the tag with a “none” value for the “protocol” attribute has the same result. (In this case key store, trust store and password files will be ignored, but if present they must still be correct.) SSL can also be configured within the application server that the TrustBuilder application is installed on.

HTTP Proxy Server

Some environments could force the application to use a HTTP Proxy Server which will process your request to the outside world. This can be set as a JAVA environment variable in the Java options.

java -Dhttp.proxyHost=webcache.example.com -Dhttp.proxyPort=8080

Example

Example 1 - POST REQUEST

The example below describes a POST request containing an XML structure body. The XML structure is not described in the schema as it depends on the backend server and the requirements of a specific project. HTTP Post Request Example

function httppostrequest(workItem){
    workItem.httpInput = 
        tb.httpRequest({
           method:'post',
           headers: { A : "A text", B : 'B Text', C: 'C Text' },
           body:"<Authentication> <Username>testuser</Username> <Password>testpwd</Password> </Authentication>",
           path:"HttpAdapterServer/DefaultServlet",
           server : "Test Server",
           includeResponseHeaders : true
         });
}

for more information, see the Base Api Functions chapter.

Response

The response of an HttpAdapter request partly depends on the request options. HTTP Response Handling

function httpAdapterHandler(workItem){
    var response = workItem.httpOutput;
    var status = response.status;
    if(status === 0) {
        log("Response from the adapter: "+response.getResponseBody());
        var bodyAsByteArray = response.getResponseAsBytes();
        log(response.getHeader('User-Agent')); // eg. 'Mozilla'
        var headers = response.headers;
        for(var i = 0;i < headers.length; i++){
            log('Header #'+i+' -> Name : '+headers[i][0] +' Value : '+headers[i][1]);
        }
    } else {
        log("Error Message: "+workItem.httpOutput.message);
    }
}

Example 2 - GET REQUEST

The example below describes a GET request. HTTP Get Request Example

function httpgetrequest(workItem){
    workItem.httpInput = tb.httpRequest({
                               headers: { A : "A text", B : 'B Text', C: 'C Text' },
                               body:"",
                               path:"/",
                               server : "Test Server",
                               includeResponseHeaders : true
                            });
}

Response

The response of an HttpAdapter request partly depends on the request options. HTTP Response Handling

function httpAdapterHandler(workItem){
    var response = workItem.httpOutput;
    var status = response.status;
    if(status == 0) {
        log("Response from the adapter: "+response.getResponseBody());
        var bodyAsByteArray = response.getResponseAsBytes();
        log(response.getHeader('User-Agent')); // eg. 'Mozilla'
        var headers = response.headers;
        for(var i = 0;i < headers.length; i++){
            log('Header #'+i+' -> Name : '+headers[i][0] +' Value : '+headers[i][1]);
        }
    } else {
        log("Error Message: "+workItem.httpOutput.message);
    }
}