Http Adapter

Http Adapter

Functionality

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.

Parameter Description Required
AdapterUniqueID Unique name assigned to this adapter; the name is used to reference the adapter in the workflow.
The ID has following requirements:
  • START with a letter or _ (underscore)
  • FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)
x
Host Settings:

Address URL or IP of the backend HTTP Server x
Port TCP Port of the backend HTTP Server x
Transport Settings:

Protocol version of the HTTP protocol to be used (e.g. v1.1)
RequestPath Path to the page or service you are trying to request
The value can be overridden by specifying a request path in the scripting-API.

RequestParameter Get parameter to send to the backend with every request e.g ?parameter1=value1&parameter2=value2
ConnectionPoolSize
The number of connections maintained so that connections can be reused for future requests to the HTTP server.
x
Username In the case of basic authentication this will specify the username to be used in the connection
Password Type the password for basic authentication, this password will be encrypted automaticly.
Security Settings:

SecurityProtocol SSL protocol version to be used for connection to the backend. Valid options are: none, default, sslv3, tlsv1 or was
  • no SSL (protocol = none)
  • default SSL settings (protocol = default)
  • explicit SSL settings (protocol = sslv3 or tlsv1)
  • WebSphere setting (protocol = was).
if the selected protocol is none. None of the following Security Settings are required. However if you do place them in the security element, they should be correct
x
TrustRemote Default set to false, this way the certificate of the server has to be in the truststore configured in the config.xml. Set to true if you don't want to check the certificate.
x1
CookieStore Maintain cookies across redirects. Default is set to false.

Name Name of this server to reference. x
UseApacheLibrary Wether or not to use the apache library or revert to the default JDK. If not in a websphere 8+ environment it is recommended to use the apache library because the jdk doesn't use a thread pool so it can potentially lock up your server.
x

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

headers 2 dimensional array of response arrays
charset Charset of the response
contentType Content Type of the response
getHeader(name) Header with name to return as string
getResponseBody() Response as String
getResponseBodyAsBase64() Response as a Base64 encoded string (for binary responses)
close() Closes the response after reading

Response Codes

Status Substatus Description Note
0 HTTP response code Good response codes 200 <= code < 300
1 HTTP response code Bad response codes 100 <= code < 200 or 300 <= code < 600
2 HTTP response code Strange response codes Other
3 1 Connection timeout error The host / port is not valid, unreachable, ...
3 2 Socket timeout error The request could not be handled within the required time
3 3 SSL error SSL handshake error, ...
3 4 Socket error Generic socket error
3 5 Unknown host error
3 7 IO Exception Remotely Closed
4 1 Internal error Something is seriously wrong or some exception was not properly handled.
4 2 Invalid request document
4 3 No server could handle the request

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);
    }
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.