Skip to main content
Skip table of contents

HTTP(S) Connector

This adapter communicates with servers via the HyperText Transfer Protocol (HTTP) or HTTP Secure (HTTPS) based on the Apache HttpClient version 4. The adapter provides the standard HTTP methods GET, POST, PUT, DELETE , HEAD, OPTIONS, TRACE, and PATCH. In addition, custom HTTP methods can be used. The adapter supports HTTP Basic, Digest, and NTLMv2 authentication, as well as proxy servers and preemptive authentication. The adapter also supports Server Name Indication for HTTPS connections and client certificates for validating requests.

Note:

  • In standard mode (fromXML parameter disabled), the adapter may process any input document with unchanged content type and character encoding, depending on the operation.

  • In expert mode (fromXML parameter enabled), the adapter processes a specific XML document that can include headers, cookie information, etc., and with which the HTTP(S) operation can be controlled in detail, see parameter fromXML and the description of the input structure.

  • This adapter replaces the existing HTTP(S) Communication adapter, see (7.4.0-en) HTTP(S) Communication (deprecated).

Properties

Operation

Describes which operation the adapter performs.

Possible values:

  • Get: Requests data from a URL using the GET method

  • Post: Sends data in the body of the HTTP request to a URL using POST

  • Put: Publishes data in the body of the HTTP request to a URL using the PUT method

  • DELETE: Deletes the resource called in the HTTP request using the DELETE method

  • Head: Requests header information only using the HEAD method

  • Options: Obtains a list of supported HTTP methods from the server using the OPTIONS method

  • Trace: Returns the request received from the server to make any changes from servers in between visible

  • Patch: Partially updates the data stored in the body of the HTTP request
  • Execute: Sends data in the body of the HTTP request using any HTTP method, also see the input example

Parameters

Adapter

Main class of the adapter (do not change!)

Possible values: de.softproject.integration.adapter.http4.HttpClient4Adapter: Main class (Default)

protocol

AI gateway protocol used (HTTP or HTTPS)

Possible values:

  • http: Use HTTP (unencrypted) (default)

  • https: Use HTTPS (SSL-encrypted)

host

IP address or host name of the IMAP server

Note:

The HOST parameter adds an HTTP header called HOST.

Possible values: Any valid string without protocol specification (e.g. google.com)

vHost

Host name of a logical server (virtual host) if it cannot be uniquely identified by the physical specification in the host parameter

Note:

The vHost parameter overwrites the value for the host HTTP header, see host parameter.

The ports can be specified here, except ports 80 (default for HTTP connections) and 443 (default for HTTPS connections).

Possible values: Any valid string without protocol specification (e.g. google.com)

port

Port number of the HTTP(S) service

Possible values:

  • Any integer (e.g. 8080)

  • -1) Use port 80 for HTTP connections; use port 443 for HTTPS connections (default)

path

Folder path on the server, starting with a forward slash

Possible values: Any path (e.g. /Intl/en_ALL/images/logo.gif)

method

Name of the HTTP method to be used in the Execute operation.
Optionally, the method can also be set via the XML request.

Possible values: Any string

authenticationEncoding

Character encoding for credentials

Possible values: Define a character encoding, e.g. UTF-8 or ISO-8859-1

(info) Using this parameter, umlauts can also be used in the credentials.

query

Argument(s) for the HTTP(S) request

Possible values: Any URL-encoded arguments without a leading question mark (e.g. arg1=V1&arg2=V2)

username

Username for Basic, Digest, or NTLM authentication

Possible values:

  • For HTTP Basic authentication: The user name

  • For HTTP Basic authentication on a Windows domain: String following the pattern <domain>\<username> (e.g. MyDomain\MyUserName)

  • For NTLM authentication on a Windows domain: Only the user name (and specify the domain in the ntlmDomain parameter) (e.g. MyUsername)

password

Password for Basic, Digest, or NTLM authentication

Possible values: Any string

token

Token for Bearer authentication

(info) It is also possible to add the token to the input XML file.

ntlmWorkstation

Client workstation (computer name) (for NTLM authentication only, see allowNtlm parameter)

Possible values: Any valid workstation name

ntlmDomain

Domain name (for NTLM authentication only, see allowNtlm parameter)

Possible values: Any valid domain name (NetBIOS Name)

usePreemptiveBasicAuth

Enables preemptive authentication (using the credentials from the username and password parameters) for HTTP(S) calls (for basic authentication only, see allowBasic parameter)

Possible values:

  • True: Sends access data directly (preemptively) with every HTTP(S) call

  • 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 via Digest

  • False: Do not authenticate using NTLM (default)

allowNtlm

Use proprietary NTLM server authentication by Microsoft

Possible values:

  • True: Authenticate using NTLM

  • False: Do not authenticate using NTLM (default)

fromXml

Activates the expert mode. The adapter expects a specific XML document including headers, cookie information, etc., with which the HTTP(S) operation can be controlled in detail.

Note:

In expert mode, the host HTTP header can only be set via the host parameter (not in the XML document). Alternatively, the host parameter can be overwritten by the vHost parameter, see the Host or vHost parameters.

Possible values:

  • True: Enables the expert mode (adapter expects a specific input XML document)

  • False: Processes adapter input directly

toXml

Outputs all headers as elements and the body content as Base64-encoded text in an XML document

Possible values:

  • True: Outputs an XML document

  • False: Outputs the server response unchanged (default)

hideCookieHeader

Also outputs header elements with cookie information in the result XML document (if the toXml parameter is enabled). Only disable this parameter for development or testing purposes or in case of cookies that differ from the standard

Possible values:

  • True: No cookie information as a header in the result XML document (default)

  • False: Outputs cookie information as a header in the result XML document

useProxy

Use a proxy server to connect

Possible values:

  • True: Establishes a connection using the proxy server specified in the proxyHost parameter

  • False: No proxy server (default)

proxyHost

IP address or host name of the IMAP server

Possible values: Any valid string (e.g. 192.168.1.1)

proxyPort

Port number of the proxy server

Possible values:

  • Any integer

  • -1): Use the default port (default)

proxyUsername

User name for Basic, Digest, or NTLM authentication on the proxy server

Possible values:

  • For HTTP Basic authentication: The user name

  • For HTTP Basic authentication on a Windows domain: String following the pattern <domain>\<username> (e.g. MyDomain\MyUserName)

  • For NTLM authentication on a Windows domain: Only the user name (and specify the domain in the ntlmDomain parameter) (e.g. MyUsername)

proxyPassword

Password for the proxy server

Possible values: Any string

proxyNtlmWorkstation

Workstation (computer name) from which the authentication request originates (for NTLM authentication via NTLM proxy)

Possible values: Any workstation name

proxyNtlmDomain

Windows domain for NTLM authentication via NTLM proxy

Possible values: Any domain name

proxyUsePreemptiveBasicAuth

Enables preemptive authentication (with the credentials from the proxyUsername and proxyPassword parameters) for the proxy server (for basic authentication only, see proxyAllowBasic parameter)

Possible values:

  • True: Sends access data directly (preemptively) with every HTTP(S) call

  • 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: Use Digest authentication for the proxy

  • False: Do not use Digest authentication for the proxy (default)

proxyAllowNtlm

Use the proprietary NTLM authentication by Microsoft for the proxy

Possible values:

  • True: Use NTLM authentication for the proxy

  • False: Do not use NTLM authentication for the proxy (default)

connectTimeout

Time limit for establishing a connection in milliseconds

Possible values:

  • >0: Timeout value in milliseconds

  • <=0: No timeout (default)

socketTimeout

Timeout value between two incoming data packets in milliseconds; this does not tell you about the total request time.

Possible values:

  • >0: Timeout value in milliseconds

  • <=0: No timeout (default)

redirectsEnabled

Allows URL redirects for a server response with the 301 Moved Permanently HTTP status

Possible values:

  • True: Execute URL redirects (default)

  • False: Do not run URL redirects

circularRedirectsEnabled

Allows circular redirects for a server response with the 301 Moved Permanently HTTP status

Possible values:

  • True: Execute circular transfers (default)

  • False: Do not perform circular transfers

maxRedirects

Maximum number of possible URL redirects for a server response with the 301 Moved Permanently HTTP status

Possible values:

  • Any integer

  • -1: No restriction (default)

acceptAllCertificates

Turns off certificate verification

Possible values:

  • Any string: Certificates are tested for trust (default)

  • Yes, I want to disable security by accepting untrusted certificates.: Certificate verification will be disabled
    Please note: The exact string must be entered here!

acceptAllSslHostnames

Turns off hostname verification for certificates

Possible values:

  • Any string: Hostname must match certificate (default)

  • Yes, I want to disable security by accepting non-matching hostnames.: Hostname verification is turned off
    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 (as per http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html#KeyStore)

Possible values:

  • jceks: Use SunJCE's proprietary keystore implementation

  • jks: Use SUN's proprietary keystore implementation

  • pkcs12: Use PKCS12 keystore transfer format

keystoreURL

URL to the keystore for validating 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 used to access a specific key within the keystore

Possible values: Any valid string

aliasPassword

Associated password for a specific key within the keystore

Possible values: Any valid string

Status values

-1

Technical error: Server does not respond or adapter input XML cannot be processed (only if expert mode is enabled via fromXml parameter)

>=100

Three-digit HTTP status code depending on the result of the call, see http://tools.ietf.org/html/rfc2616#section-6.1.1

Input (standard mode)

In standard mode (fromXML parameter disabled), the adapter may process any input document with unchanged content type and character encoding, depending on the operation; see Document Properties Changer.

Input (expert mode)

In expert mode (fromXML parameter enabled), the adapter processes a specific XML document that can include headers, cookie information, etc., and with which the HTTP(S) operation can be controlled in detail.

This XML structure essentially corresponds with both the XML structure that the adapter outputs when the toXml parameter is enabled and the X4 REST interface (if the respective URI operation is defined in the isDirect="false" attribute in the <X4>/X4DB/0/restconfig.xml configuration file). The only difference to the X4 REST result XML document is that it provides the Base64-encoded body in a <Content> element (instead of in <Body> in the adapter).

The <Cookies> element may also contain cookie information in one <Cookie> element respectively:

HTML/XML 
<Request>
   <Headers>
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Value><!--Header-Wert--></Value>
      </Header>
      <!-- Oder bei Datumswerten: -->
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Date timezone="Zeitzone"><!--Header-Datumswert--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Verfallsdatum" path="Pfad" domain="Domäne">
         <Version><!--Versionsnummer--></Version>
         <Secure/>       <!-- Wenn Secure-Attribut gesetzt -->
         <Persistent />  <!-- Bei einem persistenten Cookie -->
         <Domain><!--Domäne--></Domain>
         <Path><!--Pfad--></Path>
         <Name><!--Cookie-Name--></Name>
         <Value><!--Cookie-Wert--></Value>
         <ExpiryDate><!--Verfallsdatum im Format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-kodierte Daten der HTTP-Anfrage--></Body>
</Request>

Execute operation

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

XML 
 <Request method="CUSTOM_METHOD">
   <Headers>
      <!-- ... -->
   </Headers>
   <Cookies>
      <!-- ... -->
   </Cookies>
   <Body><!--Base64-kodierte Daten der HTTP-Anfrage--></Body>
</Request>


Output

By default (if the toXml parameter is disabled), the result document of the HTTP(S) call is output.

If the toXml parameter is enabled, an XML document is output that contains all the HTTP headers of the response in one <Header> element respectively. If a header value contains several values separated by commas, these partial values are also specified in one <Element> element at a time in the <Name> and <Value> child elements.

The body content is contained as a Base64-encoded string in the <Body> element. If the hideCookieHeader parameter has been deactivated, each header that led to the cookie is also output.

HTML/XML 
<Response>
   <Request line="HTTP-Anfragezeile">
      <Method><!--HTTP-Methode--></Method>
      <URI><!--Pfad auf dem Server--></URI>
      <Protocol>HTTP/1.1</Protocol>
   </Request>
   <Status line="HTTP-Statuszeile">
      <Code><!--Dreistelliger Statuscode--></Code>
      <Reason><!--Statusname--></Reason>
      <Protocol><!--HTTP/1.1</Protocol>
   </Status>
   <Headers>
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Value><!--Header-Wert--></Value>
      </Header>
      <!-- Oder bei Datumswerten: -->
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Date timezone="Zeitzone"><!--Header-Datumswert--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Verfallsdatum" path="Pfad" domain="Domäne">
         <Version><!--Versionsnummer--></Version>
         <Secure/>       <!-- Wenn Secure-Attribut gesetzt -->
         <Persistent />  <!-- Bei einem persistenten Cookie -->
         <Domain><!--Domäne--></Domain>
         <Path><!--Pfad</Path>
         <Name><!--Cookie-Name--></Name>
         <Value><!--Cookie-Wert--></Value>
         <ExpiryDate><!--Verfallsdatum im Format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-kodierte Daten im Body der Antwort--></Body>
</Response>



JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close