Skip to main content

Settings for the HTTP Inbound Adapter

Provides reference information for settings of the HTTP inbound adapter, EnsLib.HTTP.InboundAdapterOpens in a new tab.


The inbound HTTP adapter has the following settings:

Group Settings
Basic Settings Call Interval, Port
Connection Settings Job Per Connection, Allowed IP Addresses, OS Accept Connection Queue Size, Stay Connected, Read Timeout, SSL Configuration, Local Interface, Enable Standard Requests
Additional Settings Charset, Force Charset, GenerateSuperSessionID

The remaining settings are common to all business services. For information, see “Settings for All Business Services” in Configuring Ensemble Productions.

Allowed IP Addresses

Specifies a comma-separated list of remote IP addresses from which to accept connections. The adapter accepts IP addresses in dotted decimal form.


IP address filtering is a means to control access on private networks, rather than for publicly accessible systems. InterSystems does not recommend relying on IP address filtering as a sole security mechanism, as it is possible for attackers to spoof IP addresses.

An optional :port designation is supported, so either of the following address formats is acceptable: or If a port number is specified, connections from other ports will be refused.

If the string starts with an exclamation point (!) character, the inbound adapter initiates the connection rather than waiting for an incoming connection request. The inbound adapter initiates the connection to the specified address and then waits for a message. In this case, only one address may be given, and if a port is specified, it supersedes the value of the Port setting; otherwise, the Port setting is used.

Also see “Specifying the Sources of HTTP Requests,” earlier in this book.

Call Interval

This adapter does not use polling. It listens for a connection, and once a connection is established, it listens for messages on that connection (and responds immediately, if possible). It does, however, periodically check to see whether there have been requests to shut down the adapter or make it quiescent. This setting specifies the interval, in seconds, for the EnsLib.HTTP.InboundAdapterOpens in a new tab to perform this check.

The default value is 5 seconds. The minimum is 0.1 seconds.


Specifies the character set of the incoming data. Ensemble automatically translates from this encoding. The setting value is not case-sensitive. Use Binary for binary files, or for any data in which newline and line feed characters are distinct or must remain unchanged, for example in HL7 Version 2 or EDI messages. Other settings may be useful when transferring text documents. Choices include:

  • Auto — Use the encoding declared in the incoming HTTP header Content-Type field. This is the default.

  • AutoXML — Use the encoding declared in the XML header of the incoming XML body content, if any.

  • Binary — Read the raw bytes of the body without performing any character encoding transformation.

  • RawBytes — Read the raw bytes of the body without performing any character encoding transformation.

  • Default — Use the default character encoding of the local Ensemble server.

  • Latin1 — The ISO Latin1 8-bit encoding.

  • ISO-8859-1 — The ISO Latin1 8-bit encoding.

  • UTF-8 — The Unicode 8-bit encoding.

  • UCS2 — The Unicode 16-bit encoding.

  • UCS2-BE — The Unicode 16-bit encoding in big-endian form.

  • Any other alias from an international character encoding standard for which NLS (National Language Support) is installed in Ensemble.

For background information on character translation in Caché, see “Localization Support” in the Caché Programming Orientation Guide.

Force Charset

If this setting is true, the adapter uses the Charset setting instead of any character set declared in the incoming HTTP header Content-Type field. The default is false.

Generate SuperSession ID

This property controls whether the message will have a SuperSessionID, which can be used to identify messages that cross from one namespace to another. If this property is set, the business service first checks the HTTP header of the inbound message for a SuperSession ID. If it has a SuperSessionID value, it uses it; otherwise, it generates a new SuperSession value. It sets the SuperSesssion value in the Ensemble message and can also return the value in any HTTP response it sends to the caller.

Job Per Connection

If this setting is true, the adapter spawns a new job to handle each incoming TCP connection and allows simultaneous handling of multiple connections. If it is false, the adapter does not spawn a new job for each connection. The default is true.

Local Interface

Specifies the network interface through which the connection should go. Select a value from the list or type a value. An empty value means use any interface.

Enable Standard Requests

Specifies that the service can receive data via the CSP Gateway.

  • In order for the CSP mechanism to work, HTTP Services must be configured either with their configuration name the same as the class name, or the invoking URL must include ?CfgItem= giving the config item name, or using a CSP application with a DispatchClass configured and the config item name as the next URL piece after the application name.

  • To specify that the service only receives data from the CSP port and not from the special port, select Enable Standard Requests and set the pool size to 0.

  • Note that if you use the CSP port, you cannot have a First-In-First-Out processing for messages.

  • The default value of Enable Standard Requests for all HTTP services except HL7 is true. To maintain compatibility with previous versions, for HL7 HTTP services the default value of Enable Standard Requests is false.

OS Accept Connection Queue Size

Specifies the number of incoming connections should the operating system should hold open. Set to 0 if only one connection at a time is expected. Set to a large number if many clients will connecting rapidly.


Identifies the TCP port on the local machine where the adapter is listening for HTTP requests. Avoid specifying a port number that is in the range used by the operating system for ephemeral outbound connections. See “Inbound Ports May Conflict with Operating System Ephemeral Ports” in the Ensemble Release Notes for more information.

Read Timeout

Number of seconds to wait for each successive incoming read, following receipt of initial data from remote port.

Stay Connected

Specifies whether to keep the TCP connection open between requests.

  • If this setting is zero, the adapter will disconnect immediately after each message is received.

  • If this setting is positive, it specifies the idle time, in seconds. The adapter disconnects after this idle time.

  • If this setting is -1, the adapter auto-connects on startup and then stays connected.

FeedbackOpens in a new tab