HTTP(S) Connector

This adapter communicates with servers using the HyperText Transfer Protocol (HTTP) or HTTP Secure (HTTPS) based on the Apache HttpClient in version 4. This adapter provides the standard HTTP methods GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE and PATCH. Moreover, user-defined HTTP methods can be used. It supports HTTP basic, digest and NTLMv2 authentication, as well as proxy servers and preemptive authentication. Moreover, the adapter supports Server Name Indication for HTTPS connections, and client certificates to validate requests.

Please note:

In default mode (parameter fromXML is disabled), the adapter processes, depending on the operation, any input document using its original content type and encoding.
In expert mode (parameter fromXML is enabled), the adapter processes only a specific XML document that may include headers, cookie information etc. and which allows to have more control of the HTTP(S) operation, see parameter fromXML and input description below..
This adapter replaces the existing adapter HTTP(S) Communication, see (7.4.0-en) HTTP(S) Communication (deprecated).

Properties

Operation

Defines the operation executed by the function adapter

Possible values:

Get: Retrieve data from a URL using the method GET
Post: Send data in the body of the HTTP request to a URL using the POST method
Put: Publish data in the body of the HTTP request to a URL using the PUT method
Delete: Delete the resource specified in the HTTP request using the DELETE method
Head: Retrieve header information using the HEAD method
Options: Retrieve a list of supported HTTP methods from the server using the OPTIONS method
Trace: Return the request received by the server, so that the client can see what changes have been made by intermediate servers
Patch: Partially update the data deposited within the HTTP request's body
Execute: Send data within the HTTP request's body with any HTTP method, see also Input example

Parameters

Adapter	Main adapter class (do not change!) Possible values: de.softproject.integration.adapter.http4.HttpClient4Adapter: Main class (Default)
protocol	Used protocol (HTTP or HTTPS) Possible values: `http`: Use HTTP (no encryption) (Default) `https`: Use HTTPS (SSL-encrypted)
host	IP address or host name of the physical server Note: The `host` parameter adds an `HTTP header` named `host`. Possible values: Any valid string without protocol handler (e. g. `google.com`)
vHost	Virtual host name, if it cannot be identified by the physical host within the parameter `host` Note: The `vHost` parameter overrides the value for the `HTTP header` named `host`, see `host` parameter. The ports can be specified, except for ports 80 (default for HTTP connections) and 443 (default for HTTPS connections). Possible values: Any valid string without protocol handler (z. B. `google.com`)
port	Port number of the HTTP(S) service Possible values: Any integer number (e. g. `8080)` `-1`: Use port 80 for HTTP and port 443 for HTTPS (Default)
path	Path on the server, starting with a slash Possible values: Any valid path (e. g. `/intl/en_ALL/images/logo.gif`)
method	Name of the HTTP method to be used for the operation `Execute`. Optionally, the method can also be set via the XML request. Possible values: Any string
authenticationEncoding	Character encoding for the credentials Possible values: Specification of a character encoding, e.g. `UTF-8` oder `ISO-8859-1` With the help of this parameter, umlauts can also be used in the credentials.
query	Argument(s) of the HTTP(S) request Possible values: Any URL-encoded arguments without leading question marks (e. g. `Arg1=V1&Arg2=V2`)
username	User name for basic HTTP, digest, or NTLM authentication Possible values: For HTTP Basic authentication: the user name For HTTP Basic authentication on a Windows domain: a string following the pattern `<Domain>\<User name>` (e. g. `MyDomain\MyUserName`) For NTLM authentication on a Windows domain: only the user name (and specify the domain in parameter `ntlmDomain`) (e. g. `MyUsername`)
password	Password for basic, digest, or NTLM authentication Possible values: Any valid string
token	Token for bearer authentication It is also possible to enter the token in the input xml file.
ntlmWorkstation	Workstation (computer name) of the client (only for NTLM authentication, see parameter `allowNtlm`) Possible values: Any valid workstation name
ntlmDomain	Domain name (only for NTLM authentication, see parameter `allowNtlm`) Possible values: Any valid domain name (NetBIOS name)
usePreemptiveBasicAuth	Use preemptive authentication (using credentials from the parameters `username` and `password`) for all HTTP(S) requests (only for basic authentication, see parameter `allowBasic`) Possible values: `true`: Send credentials directly (preemptively) with each HTTP(S) request `false`: No preemptive authentication (Default)
allowBasic	Use HTTP(S) basic authentication Possible values: `true`: Use basic authentication `false`: Do not use basic authentication (Default)
allowDigest	Use digest authentication Possible values: `true`: Authenticate with digest `false`: Do not authenticate with digest (Default)
allowNtlm	Use proprietary NTLM server authentication by Microsoft Possible values: `true`: Authenticate with NTLM `false`: Do not authenticate with NTLM (Default)
fromXml	Enable expert mode; The adapter now expects a specific XML document including headers, cookie information etc. that allows more control of the HTTP(S) operation Note: In expert mode, the `HTTP header` `host` can be set using the `host` parameter only (not in the XML document). Alternatively, the `host` parameter can be overridden by the `vHost` parameter, see the `host` or `vHost` parameters. Possible values: `true`: Enable expert mode (adapter expects a specific XML document) `false`: Process adapter input directly
toXml	Output an XML document containing all headers as elements and the body content as Base64-encoded string Possible values: `true`: Output an XML document `false`: Output the unmodified response of the server (Default)
hideCookieHeader	Output header elements also with cookie information in the result XML document (when parameter `toXml` is enabled); Disable only for development/test or for non-standard cookies. Possible values: `true`: Do not output cookie information as header in the result XML document (Default) `false`: Output cookie information as header in the result XML document
useProxy	Use a proxy server to connect Possible values: `true`: Connect via the proxy server, specified within the parameter `proxyHost` `false`: No proxy server (Default)
proxyHost	IP address or host name of a proxy server Possible values: Any valid string (e. g. `192.168.1.1`)
proxyPort	Port number of the proxy server Possible values: Any integer number `-1`: Use default port (Default)
proxyUsername	User name for Basic HTTP, digest, or NTLM authentication on a proxy server Possible values: For HTTP Basic authentication: the user name For HTTP Basic authentication on a Windows domain: a string following the pattern `<Domain>\<User name>` (e. g. `MyDomain\MyUserName`) For NTLM authentication on a Windows domain: only the user name (and specify the domain in parameter `ntlmDomain`) (e. g. `MyUsername`)
proxyPassword	Password of a proxy server Possible values: Any valid string
proxyNtlmWorkstation	Workstation (computer name) where the authentication request comes from (for an NTLM authentication via NTLM proxy) Possible values: Any valid workstation name
proxyNtlmDomain	Windows domain for an NTLM authentication via NTLM proxy Possible values: Any valid domain name
proxyUsePreemptiveBasicAuth	Enable preemptive authentication (using credentials from the parameters `proxyUsername` and `proxyPassword`) for the proxy server (only for basic authentication, see parameter `proxyAllowBasic`) Possible values: `true`: Send credentials directly (preemptively) with each proxy request `false`: No preemptive authentication (Default)
proxyAllowBasic	Use basic authentication for the proxy Possible values: `true`: Use basic authentication for the proxy `false`: Do not use basic authentication for the proxy (Default)
proxyAllowDigest	Use digest authentication for the proxy Possible values: `true`: Authenticate proxy with digest `false`: Do not authenticate proxy with digest (Default)
proxyAllowNtlm	Use proprietary NTLM server authentication by Microsoft for the proxy Possible values: `true`: Authenticate proxy with NTLM `false`: Do not authenticate the proxy with NTLM (Default)
connectTimeout	Timeout value for a socket connect in milliseconds Possible values: `>0`: Timeout value in milliseconds `<=0`: No timeout (default)
socketTimeout	Timeout value between two incoming data packages in milliseconds. This is not the maximal request time, only the maximal idle time of the connection. Possible values: `>0`: Timeout value in milliseconds `<=0`: No timeout (default)
redirectsEnabled	Allow URL redirects for server responses with HTTP status `301 Moved Permanently` Possible values: `true`: URL-Redirects ausführen (default) `false`: Keine URL-Redirects ausführen
circularRedirectsEnabled	Allow circular URL redirects for server responses with HTTP status `301 Moved Permanently` Possible values: `true`: Follow circular redirects (default) `false`: Do not follow circular redirects
maxRedirects	Maximum number of URL redirects for server responses with HTTP status `301 Moved Permanently` Possible values: Any integer number `-1`: No limitation (default)
acceptAllCertificates	Disable certificate checking Possible values: `any string`: Certificates are checked on confidence (default) `Yes, I want to disable security by accepting untrusted certificates.`: Certificate check is disabled Please note: The exact string must be entered here!
acceptAllSslHostnames	Disable hostname checking for certificates Possible values: `any string`: Hostname must correspond to the certificate (default) `Yes, I want to disable security by accepting non-matching hostnames.`: Hostname checking is disabled Please note: The exact string must be entered here!
useClientCertificate	Use client certificates to validate the request Possible values: `true`: Use client certificates to validate the request `false`: Do not use client certificates to validate the request (default)
keystoreType	Keystore type for storing client certificates (see http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html#KeyStore) Possible values: `jceks`: Use proprietary keystore implementation by SunJCE `jks`: Use proprietary keystore implementation by SUN `pkcs12`: Use keystore transfer format PKCS12
keystoreURL	Keystore URL to validate the request via client certificates Possible values: Any valid URL, e.g. `file:/C:/Folder/ExampleKeystore`
keystorePassword	Password for the keystore to validate the request via client certificates Possible values: Any valid string
keyAlias	Key alias to access a specific key within the keystore Possible values: Any valid string
aliasPassword	Corresponding password for a specific key within the keystore Possible values: Any valid string

Status values

`-1`	Technical error: Server does not respond, or the adapter input XML cannot be parsed (only if expert mode has been enabled via the parameter `fromXml`)
`>=100`	Three-digit HTTP status code depending on the response, see http://tools.ietf.org/html/rfc2616#section-6.1.1

Input (Default mode)

By default (parameter fromXML is disabled), depending on the operation, this adapter processes any input document using its original content type and encoding.

Input (Expert mode)

In expert mode (Parameter fromXML enabled) the adapter processes a specific XML document that may include headers, cookie information etc. that allows more control of the HTTP(S) operation.

This XML structure corresponds to the adapter's output XML structure, if the parameter toXml is enabled. In addition, it almost completely corresponds to the X4 ReST interface (If in the configuration file <X4>/X4DB/0/restconfig.xml an attribute isDirect="false" has been defined for a URI operation). The main difference to the X4 ReST result XML document is the name of the element that contains the Base64-encoded body (<Content> instead of <Body> for the adapter).

Within the element <Cookies>, cookies can be specified, each within in an element <Cookie>:

HTML/XML

<Request>
   <Headers>
      <Header>
         <Name><!--HTTP header name--></Name>
         <Value><!--Header value--></Value>
      </Header>
      <!-- Or for date values: -->
      <Header>
         <Name><!--HTTP header name--></Name>
         <Date timezone="Timezone"><!--Header date value--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Expiry date" path="Path" domain="Domain">
         <Version><!--Version number--></Version>
         <Secure/>       <!-- If Secure attribute is set -->
         <Persistent />  <!-- For a persistent cookie -->
         <Domain><!--Domain--></Domain>
         <Path><!--Path--></Path>
         <Name><!--Cookie name--></Name>
         <Value><!--Cookie value--></Value>
         <ExpiryDate><!--Expiry date in format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-encoded data of the HTTP request--></Body>
</Request>

Operation Execute

For the operation Execute in conjunction with the activated parameter fromXML, the HTTP method can also be set within the Input XML as follows:

XML

 <Request method="CUSTOM_METHOD">
   <Headers>
      <!-- ... -->
   </Headers>
   <Cookies>
      <!-- ... -->
   </Cookies>
   <Body><!--Base64-encoded data of the HTTP request--></Body>
</Request>

Output

By default (if parameter toXml is disabled) the result document of the HTTP(S) request will be outputted.

If the parameter toXml is enabled, an XML document will be outputted, that contains all HTTP header information of the response within element <Header>. If a header value contains multiple values separated by comma, these parts will be also outputtes each in an element <Element> within the children elements <Name> and <Value>.

The body content will be outputted as Base64-encoded string in the element <Body>. If the parameter hideCookieHeader has been disabled, each header causing the cookie will be outputted additionally.

HTML/XML

<Response>
   <Request line="HTTP request line">
      <Method><!--HTTP method--></Method>
      <URI><!--Path on the server--></URI>
      <Protocol>HTTP/1.1</Protocol>
   </Request>
   <Status line="HTTP status line">
      <Code><!--Three-digit status code--></Code>
      <Reason><!--Status name--></Reason>
      <Protocol><!--HTTP/1.1</Protocol>
   </Status>
   <Headers>
      <Header>
         <Name><!--HTTP header name--></Name>
         <Value><!--Header value--></Value>
      </Header>
      <!-- Or in case of date values: -->
      <Header>
         <Name><!--HTTP header name--></Name>
         <Date timezone="Timezone"><!--Header date value--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Expiry date" path="Path" domain="Domain">
         <Version><!--Version number--></Version>
         <Secure/>       <!-- If attribute secure is set -->
         <Persistent />  <!-- For a persistent cookie -->
         <Domain><!--Domain--></Domain>
         <Path><!--Path</Path>
         <Name><!--Cookie name--></Name>
         <Value><!--Cookie value--></Value>
         <ExpiryDate><!--Expity date in the format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-encoded data of the response body--></Body>
</Response>