This topic contains the following sections:
Use the HTTPRequest node to interact with a Web service, using all or part of the input message as the request that is sent to that service. You can also configure the node to create a new output message from the contents of the input message, augmented by the contents of the Web service response, before you propagate the message to subsequent nodes in the message flow.
Depending on the configuration, this node constructs an HTTP or an HTTP over SSL (HTTPS) request from the specified contents of the input message, and sends this request to the Web service. The node receives the response from the Web service, and parses the response for inclusion in the output tree. The node generates HTTP headers if these are required by your configuration.
You can use this node in a message flow that does or does not contain an HTTPInput or HTTPReply node.
The HTTPRequest node handles messages in the following message domains:
The HTTPRequest node is represented in the workbench by the following icon:
This topic contains information about using the HTTPRequest node to issue a request to a Web service.
The URL is of the format http://<address>[:port]/<function>; for example, http://localhost:7080/request. This URL can be specified statically in the HTTPRequest node parameters as a field in the message itself, or as a field in the LocalEnvironment. The data to be sent to the Web service can be the whole, or a portion of, the message tree, as specified in the HTTPRequest node parameters.
The data has to be in CCSID 1208 format for most requests. The reply can replace the input message, or be inserted into the message tree; the location is specified in the HTTPRequest node parameters. The domain for the reply is XMLNS. If the request is successful, the HTTPResponse is inserted into the front of the message tree, the reply placed in the specified location in the tree, and the request propagated to the Out terminal. If the HTTPRequest node is not able to issue the request, an ExceptionList is inserted into the message tree and the tree is propagated to the Failure terminal.
Set OutputRoot.XMLNS.error850 = CAST(InputRoot.XMLNS.error.BLOB as CHAR CCSID 850);Standards for HTTP requests (RFC 2616) are available online. For more information about HTTP return codes, see HTTP Response codes.
You can specify a timeout interval, so that if the request takes longer than the specified duration, the request is propagated to the Error terminal with an appropriate message. For each request that the HTTPRequest node processes, it opens a connection, and then closes it when the response is returned. If the timeout interval is specified, then the socket is closed after the interval. This closure ensures that a request gets only the correct response, and any response data for a request that has timed out is discarded.
You can use the HTTP proxy to route a request via an intermediate site. You can run tools as a proxy to see the request and the response, and so debug your flows. The HTTP destination is as seen by the proxy; if you specify the HTTP destination of localhost, and the HTTP proxy is running on a different computer, the request is routed to the remote proxy computer, not the computer from which the original request was issued.
This topic contains information about using the HTTPRequest node in a message flow.
The HTTPRequest node can be used in any message flow that needs to send an HTTP request. The most common example of this is a message flow that invokes a Web service. For information on Web service applications, see Web service applications.
The node interacts directly with an external service using TCP/IP, so it can experience the following types of error:
If the node detects these errors, it generates an exception, populates the exception list with the error information that is received, and routes the input message unchanged to the Failure terminal.
The reply is produced as a BLOB message because the node cannot determine in what format the reply will be. If you have not configured this node to handle redirection, messages with a redirection status code (3xx) are also handled in the same way.
The HTTPRequest node treats the 100 series status codes as a "continue" response, discards the current response, and waits for another response from the Web server.
The 200 series status codes are treated as success, and the response is routed to the Out terminal of the node, while following the settings on the various tabs on the node for the format of the output message that is generated.
The 300 series status codes are for redirection. If the Follow Redirection property is selected, the node does not resend the request to the new destination that is specified in the response received. If the Follow Redirection property is not selected, the codes are treated as an error, as described in Handling errors in the Using the HTTPRequest node to issue a request to a Web service section.
The 400 and 500 series status codes are errors, and are treated as described in Handling errors in the Using the HTTPRequest node to issue a request to a Web service section.
If you select the Replace input message with web-service response or Replace input with error property, the header for the input message (the header that belongs to the message as it arrives at the In terminal of the HTTPRequest node) is not propagated with the message that leaves the HTTPRequest node. However, if one of the properties that specifies a location in the message tree is specified, the input message’s headers are propagated.
The HTTPResponse header, which contains the headers that are returned by the remote Web service, is the first header in the message (after properties) that is propagated from the node. This is true regardless of the options that are chosen. Therefore, for the reply from the HTTPRequest node to be put to an MQ queue, manipulate the headers so that an MQMD is the first header (after properties).
If you are replacing the input message with a response, you can copy the input message's MQMD to the Environment tree before the HTTPRequest node, and then copy it back into the message tree after the HTTPRequest node. If you are specifying a location for the response, in order to maintain existing input message headers, you must move or remove the HTTP Response header so that the MQMD is the first header.
SET OutputRoot = InputRoot; SET OutputRoot.HTTPResponseHeader = NULL;
SET OutputRoot = InputRoot; DECLARE HTTPHeaderRef REFERENCE TO OutputRoot.HTTPResponseHeader; DETACH HTTPHeaderRef; ATTACH HTTPHeaderRef TO OutputRoot.MQMD AS NEXTSIBLING;
SET OutputLocalEnvironment.Destination.HTTP.RequestLine.Method = 'GET';To use the HTTP GET method, send your data (name-value pair) in the form URL?name1=value1&name2=value2, and so on.
This topic contains information about configuring the HTTPRequest node.
When you have put an instance of the HTTPRequest node into a message flow, you can configure it. To display its properties, either double-click the node, or right-click the node and click Properties.
All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.
Configure the HTTPRequest node as follows:
The first two options provide dynamic methods to set a URL for each input message as it passes through the message flow. To use either of these options, include a Compute node in the message flow, before the HTTPRequest node, to create and initialize the required value.
The third option provides a value that is fixed for every message that is received in this node. Set this property to contain a default setting that is used if the other fields have not been created, or contain a null value. If either field contains a value, the setting of this property is ignored. The Web Service URL property must contain a valid URL or the deploy will fail. Ensure that the value that you set in X-Original-HTTP-URL or the LocalEnvironment.Destination.HTTP.RequestURL is also a valid URL; if it is not, the node generates an exception and the message is propagated to the Failure terminal.
If a URL begins http://, the request node makes an HTTP request to the specified URL. If the URL begins https://, the request node makes an HTTP over SSL (HTTPS) request to the specified URL, using the parameters that are specified on the SSL tab for the node.
If you select HTTP/1.1, you have the option of also using HTTP/1.1 keep-alive.
Note that both ends of an SSL connection must agree on the protocol to use, so the chosen protocol must be one that the remote server can accept.
Leave Message Set blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.
Leave Message Type blank for XML, XMLNS, XMLNSC, JMS, MIME, BLOB, and IDOC parsers.
Leave Message Format blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.
For the Web service error message to be included in the output message with part of the input message content, clear this check box and set the Error message location property. If you clear this property, the node copies the input message to the output message and writes the Web service error message over the output message content at the specified location (the input message itself is not modified).
You can enter any valid ESQL field reference, including expressions within the reference and new field references (to create a new node in the message tree for the response). For example, enter:
OutputRoot.XMLNS.ABC.DEFor
Environment.WSError
If you select the Replace input with Error check box, this property is ignored.
For the request message to contain a subset of the input message, clear this check box and set the Request message location in tree property.
You can enter any valid ESQL field reference, including expressions within the reference. For example, enter:
InputRoot.XMLNS.ABC
If you select the Use whole input message as request check box, this property is ignored.
When the appropriate message tree content is parsed to create a bit stream, the message properties (domain, set, type, and format) that are associated with the input message body and stored in the Properties folder are used.
For the Web service response message to be included in the output message with part of the input message content, clear this check box and set the Response message location in tree property. If you clear this property, the node copies the input message to the output message and writes the Web service response message over the output message content at the specified location (the input message itself is not modified).
You can enter any valid ESQL field reference, including expressions within the reference, and including new field references (to create a new node in the message tree for the response). For example, enter:
OutputRoot.XMLNS.ABC.DEFor
Environment.WSReply
If you select the Replace input message with web-service response check box, this property is ignored.
When the response bit stream is parsed to create message tree contents, the message properties (domain, set, type, and format) that you have specified in the node Response Message Parsing properties (described below) are used.
If you do not want the node to generate an HTTPRequestHeader for the request message, clear the Generate default HTTP headers from input check box (the default setting is selected). To control the contents of the HTTPRequestHeader that is included in the request message, include a Compute node that adds an HTTPRequestHeader to the input message before this HTTPRequest node in the message flow, and clear this check box.
It also adds the Web service headers shown in the following table, with default values, if these are not present in the HTTPRequestHeader or the HTTPInputHeader.
Header | Default value |
---|---|
SOAPAction | "" (empty string) |
Content-Type | text/xml; charset=utf-8 |
Host | The hostname to which the request is to be sent |
It also adds the optional header Content-Length with the correct calculated value, even if this is not present in the HTTPRequestHeader or the HTTPInputHeader.
For more details refer to Validating messages and Validation properties.
Connect the Out, Error, or Failure terminal of this node to another node in this message flow to process the message further, to process errors, or to send the message to an additional destination. If you do not connect the Error terminal, the message is discarded. If you do not connect the Failure terminal, the broker provides default error processing, described in Handling errors in message flows.
This topic contains information about the HTTPRequest node Terminals and properties.
The HTTPRequest node terminals are described in the following table.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing by the node. |
Failure | The output terminal to which the message is routed if a failure is detected during processing in the node. |
Out | The output terminal to which the message is routed if it represents successful completion of the Web service request, and if further processing is required within this message flow. |
Error | The output terminal to which messages that include an HTTP status code that is not in the range 200 through 299, including redirection codes (3xx) if you have not set property Follow HTTP redirection. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk on the panel 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 HTTPRequest node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type, e.g. Input | 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 HTTPRequest node Basic properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Web Service URL | Yes | Yes | The URL for the Web service. You must provide this in
the form http://<hostname>[:<port>]/[<path>] where
|
|
Request Timeout (sec) | Yes | No | 120 | The time in seconds that the node waits for a response from the Web service. The valid range is 1 to (231)-1. You cannot enter a value that represents an unlimited wait. |
The HTTPRequest node HTTP Settings properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
HTTP(S) Proxy Location | No | Yes | The proxy server to which requests are sent. This value must be in the form hostname:port. | |
Follow HTTP(S) redirection. | No | No | Cleared | If you select the check box, redirections are followed. If you clear this check box, redirections are not followed. |
HTTP Version | No | Yes | 1.0 | The HTTP version to use for requests. Valid values are 1.0 and 1.1. |
Enable HTTP/1.1 Keep-Alive | No | Yes | Selected (if HTTP Version is 1.1) | Use HTTP/1.1 Keep-Alive |
The HTTPRequest node SSL properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Protocol | No | Yes | SSL | The SSL protocol to use when making an HTTPS request. |
Allowed SSL Ciphers | No | Yes | A comma-separated list of ciphers to use when making an SSL request. The default value of an empty string means use all available ciphers. |
The HTTPRequest node Response Message Parsing properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Message Domain | No | No | The domain that will be used to parse the response message that is received from the Web service. | |
Message Set | No | No | The name or identifier of the message set in which the response message is defined. | |
Message Type | No | No | The name of the response message. | |
Message Format | No | No | The name of the physical format of the response message. |
The properties of the Parser Options for the HTTPRequest node are described in the following table.
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. Refer to Parsing on demand for a full description of this property. |
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 appears under XMLNSC in nodes that are connected to the output terminal when the input RFH2 header or Response Message Parsing properties 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. |
The HTTPRequest node Error Handling properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Replace Input with Error | No | No | Selected | If you select this check box, the input message content is replaced by the error message content. If you clear this check box, you must specify Error message location. |
Error message location | Yes | No | OutputRoot | The start location at which the parsed elements from the Web service error bit stream are stored. This property takes the form of an ESQL field reference. |
The HTTPRequest node Advanced properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Use whole input message as request | No | No | Selected | If you select this check box, the whole input message body is to be passed to the Web service. If you clear this check box, you must select Request message location in tree. |
Request message location in tree | Yes | No | InputRoot | The start location from which the bit stream is created for sending to the Web service. This property takes the form of an ESQL field reference. |
Replace input message with web-service response | No | No | Selected | If you select this check box, the Web service response message replaces the copy of the input message as the content of the output message that is created. If you clear this check box, you must select Response message location in tree. |
Response message location in tree | Yes | No | OutputRoot | The start location at which the parsed elements from the Web service response bit stream are stored. This property takes the form of an ESQL field reference. |
Generate default HTTP headers from input | No | No | Selected | If you select this check box, an HTTPRequestHeader is generated. If you clear this check box, a valid HTTPRequestHeader must exist in the input message. |
The Validation properties of the HTTPRequest node are described in the following table.
Refer to Validation properties for a full description of these properties.
Property | M | C | Default | Description |
---|---|---|---|---|
Validate | No | Yes | None | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. |
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. |
Include All Value Constraints | No | No | Selected | This property cannot be edited. The default action, which is indicated by the check box being selected, is that basic value constraint checks are included in Content and Value validation. |
Fix | No | No | None | This property cannot be edited. |