HTTPRequest node

This topic contains the following sections:

Purpose

Use the HTTPRequest node to interact with a Web service, using all or part of the input message as the request 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.

This node constructs an HTTP request from the specified contents of the input message and sends this to the Web service. It receives the response from the Web service, and parses the response for inclusion in the output tree. It generates HTTP headers if these are required by your configuration.

Because the node interacts directly with an external service using TCP/IP, it can experience the following three types of error:

  1. Errors that are generated by TCP/IP, for example no route to host and connection refused. If the node detects these errors, it generates an exception, populates the exception list with the error information received, and routes the input message unchanged to the failure terminal.
  2. Errors that result from interaction with the Web service, for example Not Found or Permission Denied. If these errors occur, the node generates an exception, populates the exception list with the error information received, and routes the input message unchanged to the failure terminal.
  3. Errors that are returned by the Web service in a SOAP Fault message (which includes an HTTP status code that is outside the range 200 through 299), for example Must-understand parts not understood. If the node detects these errors, it routes the reply in the body of the message to the error terminal. If you have not configured this node to handle redirection, messages with a redirection status code (3xx) are also handled in this way.

You can use this node in a message flow that does not contain an HTTPInput or HTTPReply node.

The HTTPRequest node handles messages in the following message domains:

  • MRM
  • XML
  • XMLNS
  • JMSMap
  • JMSStream
  • BLOB

The HTTPRequest node is represented in the workbench by the following icon:

HTTPRequest node icon

Using this node in a message flow

You can use this node to configure a message flow that acts as an intermediary to the Web service in two different ways:

  1. The Web service is invoked on behalf of a Web service client.

    See the HTTPInput node for a description of this option, and for two examples of its use.

  2. The Web service is invoked on behalf of a client that is not a Web service client.

    You can configure message flows that receive input messages from clients using any transport to connect to the broker, and send output messages to clients using the same or any other transport to connect to the broker. You can use the HTTPRequest node in a message flow to interact with a Web service, regardless of the source application that initiated the input message.

    For example, a WebSphere MQ application puts a message on a queue. You design a message flow that retrieves that message (MQInput node) and propagates it to an HTTPRequest node. The HTTPRequest node interacts with a Web service that returns information associated with the content of the original input message in its response message. For example, it might add current stock prices to a list of stock options, or return listings of URLs in response to a search request. The HTTPRequest node passes the information to a Compute node, which generates a reply to the originating application (through an MQReply node).

Configuring the HTTPRequest node

When you have put an instance of the HTTPRequest node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.

Configure the HTTPRequest node as follows:

  1. The HTTPRequest node determines the URL for the Web service to which it sends a request. You must set one of the following three options; the node checks these in the order shown (that is, the first always overrides the second, the second overrides the third):
    1. X-Original-HTTP-URL in the HTTPRequest header in the input message
    2. LocalEnvironment.Destination.HTTP.RequestURL in the input message
    3. The Default Web Service URL property

    The first two options provide you with dynamic methods to set a URL for each input message as it passes through the message flow. If you want to use either of these options, you must 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 received in this node. You might find this useful as 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.

    Ensure that the value that you set in X-Original-HTTP-URL, LocalEnvironment.Destination.HTTP.RequestURL, or in this property is valid; if it is not, the node generates an exception and the message is propagated to the failure terminal.

  2. Set the Request timeout value. This is the length of time that the node waits for a response from the Web service. If a response is received within this time, the reply is propagated through the out terminal to the rest of the message flow. If a response is not received within this time, the input message is propagated through the failure terminal, if it is connected. If the failure terminal is not connected, and a response is not received in this time, an exception is generated.
  3. In HTTP Proxy Location, set the location of the proxy server to which requests are sent.
  4. Select or clear the Follow HTTP redirection check box to specify how the node handles Web service responses that contain an HTTP status code of 300 through 399:
    • If you select the check box, the node follows the redirection provided in the response and reissues the Web service request to the new URL included in the message content.
    • If you clear the check box, the node does not follow the redirection provided. The response message is propagated to the error terminal.
  5. Select Advanced in the properties dialog navigator and set values for the Advanced properties that describe the structure and content of the Web service request and response.
    1. Specify the content of the request message that is sent to the Web service:
      • If you want the request message to be the whole input message body, leave the Use whole input message as request check box selected (this is its default setting).

        If you want the request message to contain a subset of the input message, clear this check box and complete the property Request message location in tree.

      • In Request message location in tree, enter the start location from which the content of the input message tree is copied to the request message. This property is required only if you have cleared the Use whole input message as request property. The node creates a new request message and copies the specified parts of the input message (the input message itself is not modified).

        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) associated with the input message body and stored in the Properties folder are used.

    2. Specify the content of the output message that is propagated to the next node in the message flow:
      • If you want the whole Web service response message to be propagated as the output message, leave the Replace input message with web service response check box selected (this is its default setting).

        If you want the Web service response message to be included in the output message with part of the input message content, clear this check box and complete the property Response message location in tree. 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).

      • In Response message location in tree, enter the start location within the output message tree at which the parsed elements from the Web service response message bit stream are stored. This property is required only if you have cleared the Replace input message with web service response property.

        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.DEF
        or
        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 Default properties (described below) are used.

    3. If you want the node to generate an HTTPRequestHeader for the request message, leave the Generate default HTTP headers from input check box selected (this is the default setting).

      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.

      • If you have selected Generate default HTTP headers from input and the input message includes an HTTPRequestHeader, the node extracts Web service headers from the input HTTPRequestHeader and adds any unique Web service headers, except Host (see table below), that are present in an HTTPInputHeader, if one exists in the input message. (An HTTPInputHeader might be present if the input message has been received from a Web service by the HTTPInput node.)

        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.

      • If you have selected Generate default HTTP headers from input and the input message does not include an HTTPRequestHeader, the node extracts Web service headers, except Host, from the HTTPInputHeader, if it is present in the input message. It adds the required Web service headers with default values, if these are not present in the HTTPInputHeader.
      • If you have cleared Generate default HTTP headers from input and the input message includes an HTTPRequestHeader, the node extracts all Web service headers present in the input HTTPRequestHeader. It does not check for the presence of an HTTPInputHeader in the input message, and it does not add the required Web service headers if they are not supplied by the input HTTPRequestHeader.
      • If you have cleared Generate default HTTP headers from input and the input message does not include an HTTPRequestHeader, no Web service headers are generated. The node does not check for the presence of an HTTPInputHeader in the input message and does not add any required Web service header. The request message is propagated to the Web service without an HTTPRequestHeader. This typically causes an error to be generated by the Web service, unless the Web service is configured to handle the message contents.
  6. Select Error in the properties dialog navigator and set values for the properties that determine how an error message returned by the Web service is handled.
    • If you want the whole Web service error message to be propagated as the output message, leave the Replace input with Error check box selected (this is its default setting).

      If you want the Web service error message to be included in the output message with part of the input message content, clear this check box and complete the property Error message location. 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).

    • In Error message location, enter the start location within the output message tree at which the parsed elements from the Web service error message bit stream are stored. This property is required only if you have cleared the Replace input with Error property.

      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.DEF
      or
      Environment.WSError

      If you select the Replace input with Error check box, this property is ignored.

  7. Select Default in the properties dialog navigator and set values for the properties describing the message domain, message set, message type, and message format that the node uses to determine how to parse the response message returned by the Web service.

    If an error message is returned by the Web service, the values of these properties are ignored, and the message is parsed by the BLOB parser.

    • In the Message Domain field, select the name of the parser that you are using from the drop-down list. You can choose from:
      • MRM
      • XML
      • XMLNS
      • JMSMap
      • JMSStream
      • BLOB
    • If you are using the MRM parser, select the correct message set from the drop-down list in the Message Set field. This list is populated with available message sets when you select MRM as the domain.

      Leave the Message Set field blank for XML, XMLNS, JMS, and BLOB parsers.

    • If you are using the MRM parser, select the correct message from the drop-down list in the Message Type field. This list is populated with messages that are defined in the message set that you have selected.

      Leave the Message Type field blank for XML, XMLNS, JMS, and BLOB parsers.

    • Select the format of the message from the drop-down list in the Message Format field. This list includes all the physical formats that you have defined for this message set. If you have used the default names for the physical formats, the list contains:
      • CWF1 (the default Custom Wire Format id)
      • XML1
      • TDS1
      If you specify different (non-default) names for any of these formats, your names appear in this list.

      Leave the Message Format field blank for XML, XMLNS, JMS, and BLOB parsers.

  8. Select Validation in the properties dialog navigator if you want the MRM parser to validate the body of messages against the dictionary generated from the message set. (If a message is propagated to the failure terminal of the node, it is not validated.)
    • Validate is initially set to None. Change this to Content and Value to request both content validation (type content and composition checks) and value validation (value data type checks, null permitted checks, length checks, range checks, enumeration checks, and so on).
    • To determine what happens if validation fails, select one of the following options for Failure Action:
      • User Trace: write all validation failures to user trace and continue processing.
      • Local Error Log: write all validation failures to the event log and continue processing.
      • Exception: throw an exception on the first validation failure. This is the default behavior.
      The first two options are useful when validation is first invoked, because you see all validation failures, not just the first encountered. When you have analyzed the failures, you might typically select Exception for future use.

      The failure destinations behave like those for Trace node output. So if, for example, User Trace is selected, trace entries are written regardless of the setting of the user trace flag for the message flow.

    • Set a value for Timing:
      • Deferred: validate the message only as each field is parsed. This is the default behavior.
      • Immediate: validate the message immediately but permit subsets to remain unresolved (this supports Composition values of Choice and Message where the element is not yet resolved).
      • Complete: validate the entire message immediately.
      The options available for this property take advantage of the partial parsing capability of parsers, in that you can either validate only the fields that are accessed (Deferred), or validate the entire message (Immediate and Complete). The former improves performance, the latter increases security.
    • The Include All Value Constraints check box property is selected and cannot be changed from its default setting. This setting means that full data type checks and value checks are made.
    • The Fix property cannot be changed from its default setting of None. If Failure Action is not set to Exception, limited remedial action is taken when validation fails. If Failure Action is set to Exception, no remedial action is taken, and an exception is thrown at the first validation failure.
  9. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  10. Click Apply to make the changes to the HTTPRequest node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Connecting the output terminals to another node

Connect the out, error, or failure terminal of this node to another node in this message flow to process the message further, process errors, or 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.

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 properties dialog 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 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
  • http://<hostname> must be specified
  • <port> defaults to 80. If you specify a value, you must include the : before the port number
  • <path> defaults to /. If you specify a value, you must include the / before the path.
Request Timeout 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.
HTTP Proxy Location No Yes   The proxy server to which requests are sent. This must be in the form hostname:port.
Follow HTTP redirection Yes No Cleared Whether HTTP redirections are followed. If you select the check box, redirections are followed. If you clear this check box, redirections are not followed.

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

Property M C Default Description
Use whole input message as request Yes No Selected Whether the whole input message body is to be passed to the Web service. If you select this check box, this action is performed. If you clear this check box, you must specify 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 Yes No Selected Whether the Web service response message replaces the copy of the input message as the content of the output message created. If you select this check box, this action is performed. If you clear this check box, you must specify 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 Yes No Selected Whether an HTTPRequestHeader is generated. If you select this check box, this action is performed. If you clear this check box, a valid HTTPRequestHeader must exist in the input message.

The HTTPRequest node Error properties are described in the following table.

Property M C Default Description
Replace Input with Error Yes No Selected Whether the input message content is to be replaced by the error message content. If you select this check box, the action is performed. 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 Default properties are described in the following table.

Property M C Default Description
Message Domain No No   The domain of the response message received from the Web service.
Message Set No No   The message set of the response message.
Message Type No No   The type of the response message.
Message Format No No   The format of the response message.

The HTTPRequest node Validation properties are described in the following table.

Property M C Default Description
Validate Yes No None Whether validation takes place. Valid values are None and Content and Value.
Failure Action Yes No User Trace What happens if validation fails. You can set this property only if you set Validate to Content and Value. Valid values are User Trace, Local Error Log, and Exception.
Timing Yes No Deferred When validation occurs. You can set this property only if you set Validate to Content and Value. Valid values are Deferred, Immediate, and Complete.
Include All Value Constraints Yes No Selected You cannot change this property.
Fix Yes No None You cannot change this property.

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

Property M C Default Description
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.

Related concepts
WebSphere MQ Web Services Transport
Message flows
ESQL
ESQL field references

Related tasks
Deciding which nodes to use
Handling errors in message flows
Configuring ESQL within nodes
Editing configurable properties

Related reference
Compute node
HTTPInput node
HTTPReply node
MQInput node
MQReply node