HTTPInput node

Use the HTTPInput node to receive an HTTP message from an HTTP client for processing by a message flow.

The HTTPInput node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose

If you use the HTTPInput node with the HTTPReply and HTTPRequest nodes, the integration node can act as an intermediary for web services, and web service requests can be transformed and routed in the same way as other message formats that are supported by IBM® Integration Bus.

Web service requests can be received either in standard HTTP (1.0 or 1.1) format or in HTTP over SSL (HTTPS) format. For more information about web services, see Processing web service messages.

You can configure security for the HTTPInput node by using either Basic-Auth, or Integrated Windows Authentication (NTLM, SPNEGO or Kerberos). For more information about IWA, see Authenticating incoming requests with IWA on Windows, and Authenticating incoming requests with IWA on Linux or UNIX.

The HTTPInput node supports HTTP POST and HTTP GET. For more information about enabling HTTP GET, see HTTPRequest node.

If your message flows are processing SOAP messages, use the SOAP nodes in preference to the HTTPInput node to take advantage of enhanced features, including WS-Addressing and WS-Security.

The HTTPInput node handles messages in the following message domains:

DFDL
XMLNSC
JSON
BLOB
MIME
XMLNS
MRM

HTTP messages are always non-persistent, and have no associated order.

HTTP messages are non-transactional. However, if the message flow interacts with a database or another external resource, such as a WebSphere® MQ queue, these interactions are performed in a transaction. The HTTPInput node provides commit or rollback, depending on how the message flow ended, and how it is configured for error handling (how failure terminals are connected, for example). If the message flow is rolled back by this node, a fault message is generated and returned to the client. The format of the fault is defined by the Fault format property.

If an exception occurs downstream in this message flow, and it is not caught but is returned to this node, the node constructs an error reply to the client. This error is derived from the exception, and the format of the error is defined by the Fault format property.

If you include an output node in a message flow that starts with an HTTPInput node, the output node can be any of the supported output nodes (including user-defined output nodes). You can create a message flow that receives messages from web service clients, and generates messages for clients that use all the supported transports to connect to the integration node. You can configure the message flow to request the integration node to provide any conversion that is necessary.

If you create a message flow to use as a subflow, you cannot use a standard input node; you must use an Input node as the first node to create an In terminal for the subflow.

The HTTPInput node is contained in the HTTP drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:

HTTPInput node icon

Using this node in a message flow

If you include an HTTPInput node in a message flow, you must either include an HTTPReply node in the same flow, or pass the message to another flow that includes an HTTPReply node (for example, through an MQOutput node to a second flow that starts with an MQInput node). In the latter case, the request from, and reply to, the client are coordinated by the request identifier that is stored in the local environment by the HTTPInput node.

You cannot use a SOAPReply node to respond to a web service request that is received by an HTTPInput node; the integration node generates an exception when the reply is attempted.

When the HTTPInput node receives a message from a web service client, the node starts the appropriate parsers to interpret the headers and the body of the message, and to create the message tree that is used internally by the message flow. The node creates a unique identifier for the input message and stores it as a binary array of 24 bytes in the local environment tree at LocalEnvironment.Destination.HTTP.RequestIdentifier. This value is used by the HTTPReply node, therefore you must not modify it.

By default, HTTP and HTTPS messages are handled by the integration node listener, which is started when a message flow that includes an HTTP node is started. All inbound and outbound HTTP messages are routed through this listener, for all HTTP nodes that are deployed to all message flows in all integration servers on the integration node.

You can configure an integration server to use its embedded listener to service the HTTP nodes in all message flows that are deployed to that integration server. The embedded listener communicates directly with the client and the nodes.

If you configure the integration server to use its embedded listener for HTTP nodes, you must deploy the flow that includes the HTTPReply node to the same integration server. If your integration node is configured to start the integration node listener to support HTTP nodes, you must deploy the reply flow to the same integration node, but the integration server is not significant.

For more information about using the embedded listener, see HTTP listeners.

If a client sends a gzip or deflate compressed request to the HTTPInput node, it can be extracted using the Decompress input message option. This decompression occurs only if the integration server is configured so that HTTP nodes use the embedded integration server HTTP listener, and not the integration node HTTP listener.

Using the HTTPInput and HTTPReply nodes to act as a web server

An integration node can support multiple HTTPInput nodes. When you configure the HTTPInput node, specify the requests to which the node listens in the form of a URL path, excluding the host and port details.

For example, if the integration node is listening on address http://localhost:7080, and receives the request http://localhost:7080/Joe/Mary, the listener removes the HTTP address, leaving the request Joe/Mary. The listener then matches this request with the information that is specified in the URL property of the HTTPInput node or nodes.

The match is done from the most specific to the most generic data; you can use a wildcard (an asterisk) to satisfy less specific matches. For example, if you have configured an HTTPInput node to accept requests that match /Joe/Mary, that node receives the message. However if the request is http://localhost:7080/Joe/Sally, the match is not made with this node. It can match with a node that has a more generic URL, such as one of the following values:

/Joe/*
/*

If the request does not match any URL property, and you do not have an input node with /* specified, the HTTPInput node returns a response to the originator.

You can use a URL of /* to catch all requests that failed to match the URLs in the HTTPInput nodes, so that you can send a reply message and take other actions as appropriate.

This example uses port 7080, which is the default HTTP port for the integration node listener. The default port numbers for the embedded integration server listener are 7800 for HTTP and 7843 for HTTPS. You can change these port numbers, and port ranges that are used by the integration server listeners, by using the mqsichangeproperties command.

If you are using SOAP nodes and HTTP nodes in message flows on a single integration node, you can choose to handle HTTP messages by using either the integration node listener or embedded integration server listeners. If a listener in your configuration receives messages that both SOAPInput and HTTPInput nodes might get, you must carefully check the URL specifications in these nodes. If both URL specifications match an incoming message, the wrong type of node might get the message, and processing might fail or produce unexpected results. This situation occurs if you specify identical values for the Path suffix for URL properties of the HTTPInput node and the SOAPInput node. It can also occur if you use wildcards in either or both specifications, and an incoming message matches both properties.

If you want to use the integration node listener for HTTP and HTTPS traffic, check that the integration node properties for the listener ports for HTTP and HTTPS are suitable. The default port for HTTP is 7080; the default port for HTTPS is 7083.

If you want to use the integration server listener, you must configure the integration server by using the mqsichangeproperties command to activate the listener for HTTP and HTTPS messages. The default port for HTTP is 7800; the default port for HTTPS is 7843. You can change these port numbers, and the ranges from which the ports are allocated, by using the mqsichangeproperties command.

If you want to collect trace information about HTTP message processing, see Resolving problems when you use HTTP and SOAP nodes.

Connecting the terminals

The HTTPInput node routes each message that it retrieves successfully to the Out terminal. If message validation fails, the message is routed to the Failure terminal; you can connect nodes to this terminal to handle this condition. If you have not connected the Failure terminal, the message is discarded, the Maximum client wait time expires, and an error is returned to the client. No other situations exist in which the message is routed to the Failure terminal.

If the message is caught by this node after an exception is thrown further on in the message flow, the message is routed to the Catch terminal. If you have not connected the Catch terminal, the message is discarded, the Maximum client wait time expires, and an error is returned to the client.

If the Maximum client wait time expires, by default, the listener returns a fault message to the client to indicate that the timeout expired. If the HTTP Timeout terminal is connected and the integration server is configured such that the HTTP nodes use the embedded listener, this timeout fault message is propagated to the timeout terminal. In this scenario the listener waits again for the interval that is defined by the Maximum client wait time (sec) property, or for 10 seconds, whichever is the shorter interval:

If a response is received before this second interval expires, the listener propagates the response to the client.
If a response is not received before this second interval expires, the listener sends a fault message to the client, indicating that its timeout expired.

Because the listener waits for only a brief interval after the message is propagated through the HTTP Timeout terminal, you must ensure that the sequence of nodes that you connect to the HTTP Timeout terminal includes an HTTPReply node, which sends a response before this interval expires.

Terminals and properties

When you put an instance of the HTTPInput node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

The terminals of the HTTPInput node are described in the following table.

Terminal	Description
Failure	The output terminal to which the message is routed if an error occurs.
Out	The output terminal to which the message is routed if it is successfully retrieved.
HTTPTimeout	The output terminal to which a timeout fault message is routed if the HTTPReply node that is connected to the Out terminal does not respond within the time interval that is specified by the Maximum client wait time property. This terminal is used only if the integration server is configured so that HTTP nodes use the embedded integration server listener.
Catch	The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The HTTPInput node Description properties are described in the following table.

Property	M	C	Default	Description
Node name	No	No	The node type, HTTPInput	The name of the node.
Short description	No	No		A brief description of the node.
Long description	No	No		Text that describes the purpose of the node in the message flow.

The HTTPInput node Basic properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Path suffix for URL	Yes	Yes		This property identifies the location from where web service requests are retrieved. Do not use the full URL. If the URL that you want is `http://hostname[:port]/[path]`, specify either `/path` or `/path fragment/` where is a wildcard that you can use to mean match any.	URLSpecifier
Use HTTPS	No	Yes	Cleared	This property identifies whether the node is to accept secure HTTP. If the node is to accept secure HTTP, select the check box.	useHTTPS

The HTTPInput node Advanced properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Set destination list	No	No	Selected	This property specifies whether to add the method binding name to the route to label destination list. If you select this check box, the method binding name is added so that you can use a RouteToLabel node in the message flow after the HTTPInput node.
Label prefix	No	No	None	The prefix to add to the method name when routing to label. Add a label prefix to avoid a clash of corresponding label nodes when you include multiple IBM Integration Bus input nodes in the same message flow. By default, there is no label prefix, therefore the method name and label name are identical.
Parse Query String	No	No	False	This property causes any query string that is present with an incoming message to be parsed and decoded (according to http://tools.ietf.org/html/rfc3986) into the following location in the local environment as a series of name-value elements that match the names and values present in the query string: `LocalEnvironment.HTTP.Input.QueryString` For example, for this query string: `?myParam1=my%22Value%221&myParam2=my%22Value%222` the following elements are placed into the local environment under the QueryString folder: `myParam1` with a value of `my"Value"1` `myParam2` with a value of `my"Value"2` In addition, if the URI that is exposed by the HTTPInput node contains path segments, perhaps because the URI includes parameters which have an intended meaning for the processing of the message flow, the local environment is populated at this location: `LocalEnvironment.HTTP.Input.Path` For example, consider an HTTPInput node with the Path suffix for URL property set to /MessageFlow1/*. If an HTTP client sends an HTTP post to `http://localhost:7800/MessageFlow1/a%20space/b/c`, the request is routed to the message flow that is deployed with the HTTPInput node, and the path segments are be placed in the local environment tree as follows: `HTTP = ( Input = ( Path = ( Segment = 'a space' Segment = 'b' Segment = 'c' ) ) )` If the `QueryString` uses a character set that is not UTF-8, you can use the `MQSI_HTTP_QUERY_STRING_CCSID` environment variable to specify the CCSID of the `QueryString`. For example, if your HTTPRequest node has a `QueryStringCCSID` of 943, you can set `MQSI_HTTP_QUERY_STRING_CCSID` to 943 to convert the query string parameters to the 943 code page.
Decompress input message	No	Yes	Cleared	This property indicates whether an inbound HTTP request is decompressed or not. This property is used only if the integration server is configured so that HTTP nodes use the embedded integration server HTTP listener. If this option is selected, and the HTTP header Content-Encoding field is "gzip" or "deflate", the input message is decompressed and propagated to the Out terminal, and the Content-Encoding field is removed.	decompressInputMessage

The HTTPInput node Input Message Parsing properties are described in the following table.

The properties of the Parser Options for the HTTPInput node are described in the following table.

Property	M	C	Default	Description
Message domain	No	No	BLOB	The domain that is used to parse the message. If the field is blank then the default is BLOB.
Message model	No	No	Cleared	The name or location of the message model schema file in which the message is defined. When you click Browse, you see a list of available message model schema files for the selected Message domain.
Message	No	No	Cleared	The name or location of the message root within your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected.
Physical format	No	No	Cleared	The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree.

Property	M	C	Default	Description
Parse timing	No	No	On Demand	This property controls when an input message is parsed. Valid values are On Demand, Immediate, and Complete. By default, this property is set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand.
Build tree using XML schema data types	No	No	Cleared	This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value.
Use XMLNSC compact parser for XMLNS domain	No	No	Cleared	This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or the input message Parsing property Message domain is XMLNS.
Retain mixed content	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in an input message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain comments	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an input message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain processing instructions	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in an input message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements	No	No	Blank	This property is used to specify a list of elements in the input message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled.

The HTTPInput node Error handling properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Maximum client wait time (sec)	Yes	Yes	180	The length of time, in seconds, for which the TCP/IP listener that received the input message from the web service client waits for a response from the HTTPReply node in the message flow. The valid range is zero (which means a short wait) through (2³¹)-1. If a response is received within this time, the listener propagates the response to the client. If a response is not received in this time, a fault message is generated indicating that the timeout expired. This fault message is either sent by the listener or timeout terminal processing. For more information about the HTTP Timeout terminal, see Connecting the terminals and Terminals and properties.	timeoutForClient
Fault format	No	Yes	SOAP 1.1	The format of any HTTP errors that are returned to the client. Valid values are SOAP 1.1, SOAP 1.2, and HTML.	faultFormat

The Validation properties of the HTTPInput node are described in the following table. If a message is propagated to the Failure terminal of the node, it is not validated. For more information, see Validating messages and Validation properties.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	No	Yes	None	This property controls whether validation takes place. Valid values are None, Content and Value, and Content.	validatemaster
Failure action	No	No	Exception	This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.

The Security properties of the HTTPInput node are described in the following table. Set values for the properties that control the extraction of an identity from a message when a security profile is associated with the node. For more information about these properties, see Identity, Configuring the extraction of an identity or security token, Message flow security overview, and Setting up message flow security

Property	M	C	Default	Description
Identity token type	No	No	None	This property specifies the type of identity token that is present in the incoming message. Valid values are: Transport Default Username Username + Password SAML Assertion X.509 Certificate If this property is not specified, the identity is retrieved from the Basic-Auth transport header, and the type is set to Username + Password.
Identity token location	No	No	None	This property specifies where, in the message, the identity can be found. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), If this property is not specified, the identity is retrieved from the Authorization Transport headers.
Identity password location	No	No	None	This property specifies where, in the message, the password can be found. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), If you do not specify a value for this property, the password is retrieved from the Authorization Transport headers. You can set this property only if the Identity type is set to Username + Password.
Identity IssuedBy location	No	No	None	This property specifies a string or path expression that describes the issuer of the identity. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), The value specifies the Issuer that is passed to a WS-Trust v1.3 STS provider. If you do not specify a value for this property, the default value is the name of the User Agent, or, if this name is not set, the string HTTP.
Treat security exceptions as normal exceptions	No	No	False	This property specifies whether to treat security exceptions (such as Access Denied) as normal exceptions, and propagate them to the Failure terminal (if wired). This option is turned off by default, which ensures that security exceptions cause the message to be backed out even if the Failure terminal is wired.

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.