Configuring the connector

After using the Installer to install the connector files to your system, you must set the standard and application-specific connector configuration properties.

Setting configuration properties

Connectors have two types of configuration properties: standard configuration properties and connector-specific configuration properties. You must set the values of these properties using System Manager (SM) before running the connector.

Standard configuration properties

Standard configuration properties provide information that all connectors use. See Appendix A. Standard configuration properties for connectors for documentation of these properties. The table below provides information specific to this connector about configuration properties in the appendix.

Property Description
CharacterEncoding

This connector does not use this property.

Locale

Because this connector has not been internationalized, you cannot change the value of this property. See release notes for the connector to determine currently supported locales.

Because this connector supports only InterChange Server (ICS) as the integration broker, the only configuration properties relevant to it are for ICS.

You must set at least the following standard connector configuration properties:

Connector-specific configuration properties

Connector-specific configuration properties provide information needed by the connector agent at runtime. Connector-specific properties also provide a way of changing static information or logic within the connector agent without having to recode and rebuild the agent.

Table 33 lists the connector-specific configuration properties. See the sections that follow for explanations of the properties. Note that some of the properties contain other properties. The + character indicates the entry's position in the property hierarchy.

Table 33. Connector-specific configuration properties
Name Possible values Default value Required
DataHandlerMetaObjectName Data handler meta-object name MO_DataHandler_ Default Yes
UseDefaults UseDefaults false No
JavaProtocolHandlerPackages Valid Java protocol handler packages com.ibm.net.ssl. internal.www.protocol No
ProtocolHandlerFramework This is a hierarchical property and has no value None No
+ProtocolHandlers This is a hierarchical property and has no value No
++Handler1 This is a hierarchical property. For information on its sub-properties, see Handler1. Yes
+++Protocol http Yes
+++HandlerSpecific Each protocol handler can have required properties.
ProtocolListenerFramework This is a hierarchical property and has no value. No
+WorkerThreadCount An integer of 1 or greater that gives the number of available listener threads. 10 No
+RequestPoolSize Integer greater than WorkerThreadCount that gives the resource pool size. 20 No
+ProtocolListeners This is a hierarchical property and has no value
++Listener1 Uniquely named protocol listener Yes
+++Protocol http or https Yes
+++ListenerSpecific Properties unique to or required by the listener See ListenerSpecific.
ProxyServer This is a hierarchical property and has no value No
+HttpProxyHost Host name for the HTTP proxy server No
+HttpProxyPort Port number for the HTTP proxy server 80 No
+HttpNonProxyHosts HTTP host(s) requiring direct connection No
+HttpsProxyHost Host name for the HTTPS proxy server No
+HttpsProxyPort Port number for the HTTPS proxy server 443 No
+HttpsNonProxyHosts HTTPS host(s) requiring direct connection No
+SocksProxyHost Socks proxy server name No
+SocksProxyPort Socks proxy server port No
+HttpProxyUsername Http proxy server username No
+HttpProxyPassword Http proxy server password No
+HttpsProxyUsername Https proxy server username No
+HttpsProxyPassword Https proxy server password No
SSL This is a hierarchical property and has no value No
+SSLVersion SSL, SSLv2, SSLv3, TLS, TLSv1 SSL No
+SSLDebug true, false false No
+KeyStoreType Any valid keystore type JKS No
+KeyStore Path to KeyStore file. No
+KeyStorePassword Password for private key in KeyStore No
+KeyStoreAlias Alias for key pair in KeyStore No
+TrustStore Path to TrustStore file No
+TrustStorePassword Password for TrustStore No
+UseClientAuth true false false No
DataHandlerMetaObjectName

This is the name of the meta-object that the data handler uses to set configuration properties.

Default = MO_DataHandler_Default.

UseDefaults

On a Request Processing operation, if UseDefaults is set to true, the connector checks whether a valid value or a default value is provided for each isRequired business object attribute. If a value is provided, the Request Processing operation succeeds. If the parameter is set to false, the connector checks only for a valid value and causes the operation to fail if it is not provided.

Default = false.

JavaProtocolHandlerPackages

The value of this property gives the Java Protocol Handler packages. The connector uses the value of this property to set the system property java.protocol.handler.pkgs.

Default = com.ibm.net.ssl.internal.www.protocol.

ProtocolHandlerFramework

The Protocol Handler Framework uses this property to load and configure its protocol handlers. This is a hierarchical property and has no value.

Default = none.

ProtocolHandlers

This hierarchical property has no value. Its first-level children represent discrete protocol handlers.

Default = none.

Handler1

The name of an HTTP-HTTPS protocol handler. Note that this is a hierarchical property. Unlike listeners, protocol handlers may not be duplicated, and there can be only one handler for each protocol. Table 34 below shows the sub-properties for the HTTP-HTTPS protocol handler. The + character indicates the entry's position in the property hierarchy.

Table 34. HTTP-HTTPS protocol handler configuration properties
Name Possible values Default value Required
++HTTPHTTPSHandler This is a hierarchical property and has no value. Yes
+++Protocol The kind of protocol the handler is implementing. For HTTP and HTTPS, the value is http.
Note:
If you do not specify a value for this property, the connector will not initialize this protocol handler.
http Yes
+++HTTPReadTimeout An HTTP-specific property that specifies the timeout interval (in milliseconds) while reading from the remote host. If this property is not specified or if set to 0, the HTTP-HTTPS protocol handler blocks indefinitely while reading from the remote host. 0 No
Protocol

The value of this property provides the protocol that the handler must implement.

HandlerSpecific

This property specifies any required protocol handler properties.

ProtocolListenerFramework

The protocol listener framework uses this property to load protocol listeners. This is a hierarchical property and has no value.

WorkerThreadCount

This property, which must be an integer of 1 or greater, establishes the number of protocol listener worker threads available to the protocol listener framework. For further information, see Protocol listeners.Default = 10.

RequestPoolSize

This property, which must be an integer greater than WorkerThreadCount, sets the resource pool size of the protocol listener framework. The framework can process a maximum of WorkerThreadCount + RequestPoolSize requests concurrently.

Default = 20.

ProtocolListeners

This is a hierarchical property and has no value. Each first-level child of this property represents a discrete protocol listener.

Listener1

The name of a protocol listener. There may be multiple protocol listeners. Note that this is a hierarchical property. You can create multiple instances of this property and create additional, uniquely named listeners. When doing so, you can change the listener-specific properties but not the protocol property. The names of multiple listeners must be unique. Possible names (not values): HTTPListener1, HTTPSListener1.

Protocol

This property specifies the protocol this listener is implementing. Possible values: http, https.

Note:
If you do not specify a value for this property, the connector will not initialize this protocol listener.
ListenerSpecific

Listener specific properties are unique to, or required by, the specified protocol listener. For example, the HTTP listener has a listener-specific property Port, which represents the Port number on which Listener monitors requests. Table 35 summarizes the HTTP-HTTPS listener specific properties. The + character indicates the entry's position in the property hierarchy.

Table 35. HTTP and HTTPS protocol listener-specific configuration properties
Name Possible values Default value Required
+++HTTPListener1 Unique name of an HTTP protocol listener. This is a child of the ProtocolListenerFramework -> ProtocolListeners hierarchical property. There can be multiple listeners: you may plug-in additional HTTP listeners by creating another instance of this property and its hierarchy. Yes
++++Protocol http if HTTP protocol listener
https if HTTPS protocol listener
Note:
If you do not specify a value for this property, the connector will not initialize this protocol listener.
Yes
++++HostInfoValidation FailRequest - if host/port info of the request does not match the host/port info of the listener, the error message will be logged and request will be failed with 400 (Bad Request) status.

LogError - if host/port info of the request does not match the host/port info of the listener, the error message will be logged and request execution will continue.

Ignore - there will be no validation performed on the host/port info of the request.

Note: If the property does not exist, HTTP(S) listeners will DEFAULT property value to FailRequest. If the property does not have a valid value, the HTTP(S) listener will fail the initialization.
FailRequest N
++++BOPrefix The value of this property is passed to the data handler. No
++++Host The listener will listen at the IP address specified by value of this property. If Host is not specified, it defaults to localhost. Note that you may either specify a host name (DNS name) or an IP address for the machine on which the listener is running. A machine may have multiple IP addresses or multiple names. localhost No
++++Port The port on which the listener listens for requests. If unspecified, the port defaults to 80 for HTTP and 443 for HTTPS.
If you clone the listener within a connector, then the combination of Host and Port properties is unique or the listener may be unable to bind to the port to accept requests.
80 for HTTP listener
443 for HTTPS listener
No
++++SocketQueueLength Length of the queue (socket queue) for incoming connection requests. Specifies how many incoming connections can be stored at one time before the host refuses connections. The maximum queue length is operating system dependent. 5 No
++++RequestWaitTimeout The time interval in milli-seconds that the listener thread will block on the host and port while waiting for requests to arrive. If it receives a request before this interval, the listener will process it. Otherwise the listener thread checks whether the connector shutdown flag is set. If it is set, the connector will terminate. Otherwise it will continue to block for RequestWaitTimeout interval. If this property is set to 0, it will block for ever. If unspecified, it defaults to 60000ms. 60000 (ms) No
++++HTTPReadTimeout The time interval in milli-seconds that the listener will be blocked while reading a request from a client. If this parameter is set to 0, the listener indefinitely blocks until it receives the entire request message. 0 No
++++HttpAsyncResponseCode The HTTP response code for asynchronous requests to the listener:
200 (OK)
202 (ACCEPTED)
202 (ACCEPTED) No
++++Pingability This property holds 0 or more specifications for ping services for this listener. This property has no value. No
+++++PingService1 This property holds 1 specification for ping service.

This property has no value and name can be any valid property name.
Note: there could be multiple structurally same instances of this property with different values.

If there are any errors during validation of this property, an error will be logged and the protocol listener will fail to initialize.
No
++++++Method HTTP method of the request, case insensitive. Yes
++++++StatusCode Response Status-Code to reply with to request. Yes
++++++ReasonPhrase Reason-Phrase to reply with to request. Yes
++++URLsConfiguration This is a hierarchical property and has no value. It contains 1 or more configurations for URLs supported by this listener and, optionally, mime type and charset values. Note that this is child property of ProtocolListenerFramework->ProtocolListeners->HTTPListener1 hierarchical property. If this property is not specified, the listener assumes default values.

If this property is not specified, the listener will have the following URLsConfiguration defined: >ContextPath: "/"
>Enabled: true
>DataHandler MimeType: equal to the ContentType of the request
>Charset: according to the rules in the Globalization section.
ContextPath: / Enabled: true Data handler MimeType: equal to the ContentType of the request Charset: NONE. For further information, see HTTP and HTTPS protocol listener processing. No
+++++URL1 This is a hierarchical property and has no value. Its children provide the name of the URL supported by this listener. There can be multiple supported URLs. Note that you can plug in additional URLs by cloning this property and its hierarchy. No
++++++ContextPath The URI for the HTTP requests received by the listener. This value must be unique among ContextPath values under the URLsConfiguration property. Otherwise the connector will log an error and fail to start. ContextPath is case sensitive. However it may contain protocol, host name and port which are case-insensitive. If protocol is specified in ContextPath, it should be http. If host is specified, it should be equal to the value of the Host listener property. If port is specified, it should be equal to the value of Port listener property. No
++++++Enabled The value of this property determines if the parent URL hierarchical property is enabled for the connector. True No
++++++TransformationRules This is a hierarchical property and has no value. It holds one or more transformation rules. No
+++++++EmptyRequestRule This is a hierarchical property and has no value. This property holds the transformation rule when an empty request payload is encountered.
++++++++MimeType DataHandler mime type which should be used when calling data handler while processing requests with empty payload. (Note that datahandler will receive Hashtable of request headers in place of config object) Yes
++++++++Charset Charset which should be used when transforming request with empty payload. No
++++++++BOPrefix If defined, the value of this property will override BOPrefix of this protocol listener to be passed to the datahandler. No
++++++++BOName If defined, value of this property will be passed to the datahandler in the headers hashtable with name of the element being BOName.
If there is a protocol header with the same name, protocol header value will take precedence over this property value.
No
++++++++BOVerb If defined, value of this property will be passed to the datahandler in the headers hashtable with name of the element being BOVerb.
If there is a protocol header with the same name, protocol header value will take precedence over this property value.
No
+++++++TransformationRule1 This is a hierarchical property and has no value. It holds the transformation rule. No
++++++++ContentType The value of this property specifies the ContentType of the incoming request for which special handling (data handler mime type or charset) should be applied. If ContentType is not specified by the TransformationRuleN hierarchical property, the connector logs a warning message and ignores the TransformationRuleN property.

Specifying the special value */* for this property enables the protocol listeners to apply this rule to any ContentType. Note that if a listener finds more than one rule for the same context path that shares a ContentType, the listener logs an error and fails to initialize.
No
++++++++MimeType The mime type to use when calling a data handler to process requests of the specified ContentType. No
++++++++Charset Charset to use when transforming the request of the specified ContentType into a business object. No
++++++++BOPrefix If defined, the value of this property will override BOPrefix of this protocol listener to be passed to the datahandler. No
++++++++BOName If defined, value of this property will be passed to the datahandler in the headers hashtable with name of the element being BOName.
If there is a protocol header with the same name, protocol header value will take precedence over this property value.
No
++++++++BOVerb If defined, value of this property will be passed to the datahandler in the headers hashtable with name of the element being BOVerb.
If there is a protocol header with the same name, protocol header value will take precedence over this property value.
No

Figure 18 shows the properties as displayed in Connector Configurator.

Figure 18. HTTP(S) protocol listener properties
ProxyServer

Configure the values under this property when the network uses a proxy server. This is a hierarchical property and has no value. The values specified under this property are used by the HTTP-HTTPS protocol handlers.

Figure 19 shows the ProxyServer properties as displayed in Connector Configurator.

Figure 19. ProxyServer properties
HttpProxyHost

The host name for the HTTP proxy server. Specify this property if the network uses a proxy server for HTTP protocol.

Default = none

HttpProxyPort

The port number that the connector uses to connect to the HTTP proxy server.

Default = 80

HttpNonProxyHosts

The value of this property gives one or more hosts (for HTTP) that must be connected not through the proxy server but directly. The value can be a list of hosts, each separated by a "|".

Default = none

HttpsProxyHost

The host name for the HTTPS proxy server.

Default = none

HttpsProxyPort

The port number that the connector uses to connect to the HTTPS proxy server.

Default = 443

HttpsNonProxyHosts

The value of this property gives one or more hosts (for HTTPS) that must be connected not through the proxy server but directly. The value can be a list of hosts, each separated by a "|".

Default = none

SocksProxyHost

The host name for the Socks Proxy server. Specify this property when the network uses a socks proxy.

Note:
The underlying JDK must support socks.

Default = none

SocksProxyPort

The port number to connect to the Socks Proxy server. Specify this property when the network uses a socks proxy.

Default = none

HttpProxyUsername

The username for the HTTP proxy server. If the destination for the request is an HTTP URL and you specify ProxyServer ->HttpProxyUsername, the HTTP-HTTPS protocol handler creates a Proxy-Authorization header when authenticating with the proxy. The handler uses the CONNECT method for authentication.

The proxy-authentication header is base64 encoded and has the following structure:

Proxy-Authorization: Basic
Base64EncodedString

The handler concatenates the username and the password property values, separated by a colon (:), to create the base64 encoded string.

Default = none

HttpProxyPassword

The password for the HTTP proxy server. For more on how this value is used, see HttpProxyUsername.

Default = none

HttpsProxyUsername

The username for the HTTPS proxy server. If the destination for the request is an HTTPS URL and you specify ProxyServer ->HttpsProxyUsername, the HTTP-HTTPS protocol handler creates a Proxy-Authorization header for authentication with the proxy. The handler concatenates the HttpsProxyUsername and HttpsProxyPassword configuration property values, separated by colon (:), to create the base64 encoded string.

Default = none

HttpsProxyPassword

The password for the HTTPS proxy server. For more on how this value is used, see HttpsProxyUsername.

Default = none

SSL

Specify values under this property to configure SSL for the connector. This is a hierarchical property and has no value.

Figure 20 shows the SSL properties as displayed in Connector Configurator.

Figure 20. SSL properties
SSLVersion

The SSL version to be used by the connector. For further information, see IBM JSSE documentation for the supported SSL versions.

Default = SSL

SSLDebug

If value of this property is set to true, the connector sets the value of thejavax.net.debug system property to true. IBM JSSE uses this property to turn on the trace facility. For further information, refer to IBM JSSE documentation.

Default = false

KeyStoreType

The value of this property gives the type of the KeyStore and TrustStore. For further information, see IBM JSSE documentation for valid keystore types.

Default = JKS

KeyStore

This property gives the complete path to keystore file. If KeyStore and/or KeyStoreAlias properties are not specified, KeyStorePassword, KeyStoreAlias, TrustStore, TrustStorePassword properties are ignored. The connector will fail to startup if it cannot load the keystore using the path specified in this property. The path must be the complete path to the keystore file.

Default = None

KeyStorePassword

This property gives the password for the private key in the Keystore.

Default = None

KeyStoreAlias

This property gives the alias for the key pair in the KeyStore. HTTPS listeners use this private key from the KeyStore. Also, the HTTP-HTTPS protocol handler uses this alias from the KeyStore when invoking HTTPS services that require client authentication. The property must be set to a valid JSSE alias.

Default = None

TrustStore

This property gives the complete path to the TrustStore. TrustStore is used for storing the certificates that are trusted by the connector. TrustStore must be of the same type as KeyStore. You must specify the complete path to the TrustStore file.

Default = None

TrustStorePassword

This property gives the password for the Truststore.

Default = None

UseClientAuth

This property specifies whether SSL client authentication is used. When it is set to true, HTTPS listeners use client authentication.

Default = false

Creating multiple protocol listeners

You can create multiple instances of protocol listeners. Protocol listeners are configured as child properties of the ProtocolListenerFramework -> ProtocolListeners connector property. Each child (of ProtocolListenerFramework -> ProtocolListeners) identifies a distinct protocol listener for the connector. Accordingly, you can create additional protocol listeners by configuring new child properties under the ProtocolListeners property. Make sure that you specify all of the child properties of the newly created listener property. Each listener must be uniquely named. However, you do not change the listener Protocol property (http or https), which remains the same for multiple instances of a listener.

Note:
The Protocol property is very important because it serves as a switch. If you do not want to use a listener or a handler, leave this property empty.

If you are creating multiple instances of a HTTP or HTTPS listener, be sure to specify different Port and Host properties for each instance.

You cannot create multiple instances of a handler. There can be only one handler for each protocol.

Copyright IBM Corporation 2003, 2005. All Rights Reserved.