About this task
When you have put an instance of the HTTPRequest node into a message
flow, you can configure the node; see Configuring a message flow node.
The properties of the node are displayed in the Properties view.
All
mandatory properties are marked with an asterisk.
Procedure
- Optional: On the Description tab,
enter a Short description,
a Long description, or both. You can also rename the node on this tab.
- On the Basic tab:
- The HTTPRequest node
determines the URL for the web service to which it sends a request.
Select one of the following three options; the node checks these options
in the order shown (that is, the first always overrides the second,
the second overrides the third):
- X-Original-HTTP-URL in the HTTPRequest header in the input message
- LocalEnvironment.Destination.HTTP.RequestURL in the input message
- The Web service URL property
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 deployment fails.
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 uses the default setting
from the Web service URL property.
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, by using the parameters that are specified on the SSL tab
for the node.
- Set the value of the Request
timeout (sec) property, which is the length of time, in seconds,
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.
- On the HTTP Settings tab:
- In HTTP(S) proxy location,
set the location of the proxy server to which requests are sent.
- Select Follow HTTP(S)
redirection to specify how the node handles web service responses
that contain an HTTP status code of 300 to 399:
- If you select the check box, the node follows the redirection
that is 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.
- Select one of the options for the HTTP version property. Valid values
are 1.0 or 1.1.
If you select
the HTTP version property
value 1.1, you can also
select Enable HTTP/1.1 keep-alive.
- Select one of the options for the HTTP method property. Valid values
are POST, GET, PUT, DELETE, and HEAD.
- Select one of the options for the Use compression property to specify
the compression of the content of the HTTP request. You
can select:
- gzip
- zlib (deflate)
- deflate
- none
The value zlib (deflate) represents
RFC 1950 and RFC 1951 combined, and deflate represents
RFC 1951 only. The default value is none,
meaning that the content of the request is not compressed.
- On the SSL tab, if you want to use
HTTP over SSL (HTTPS) requests, set the values for HTTPS requests:
- Specify the Protocol property
that you want to use to make the request. Both ends of
an SSL connection must agree on the protocol to use. Therefore, the
selected protocol must be one that the remote server can accept. The
following options are available:
- SSL. This option
is the default. This option tries to connect by using the TLS protocol
first, but enables the handshake to fall back to the SSLv2 protocol
where the SSLv2 protocol is supported by the underlying JSSE provider.
- SSLv3. This option
tries to connect with the SSLv3 protocol only. Fallback to SSLv2 is
not possible.
- TLS. This option
tries to connect with the TLS protocol only. Fallback to SSLv3 or
SSLv2 is not possible.
- Set the Allowed SSL
ciphers property. Use this setting to specify
a single cipher (such as SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA) or a
list of ciphers that are the only ones that are used by the connection.
This set of ciphers must include one or more that are accepted by
the remote server. A comma is used as a separator between the ciphers.
The default value is an empty string, which enables the node to use
any, or all, of the available ciphers during the SSL connection handshake.
This method gives the greatest scope for making a successful SSL connection.
- Use the SSLKeyAlias property
to specify a SSL authentication alias for the client-side of an HTTP
connection. The server checks an access control list for
this client-side key. The key alias that identifies the key in the integration node or integration server
keystore that is to be used for the SSL connection. Set this optional
property if your keystore contains more than one key. The default
value "" (or none), means that an SSL key alias is not used. Any other
string value identifies the alias.
- On the Response Message Parsing tab,
set values for the properties that describe 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 Message domain, select
the name of the parser that you are using from the list. If
the field is blank, the default value is BLOB. Choose from the following
options:
- DFDL
- XMLNSC
- JSON
- BLOB
- MIME
- MRM
- XMLNS
You can also
specify a user-defined parser, if appropriate.
- If you are using the DFDL parser, the MRM parser
or the XMLNSC parser in validating mode, select the relevant Message model from the list. This
list is populated with available message sets when you select MRM
or XMLNSC as the Message domain,
or with available DFDL schema files when you select DFDL as the Message domain.
- If you are using the DFDL or MRM parsers, select the
correct message from the list in Message.
This list is populated with messages that are defined in the Message model that you have selected.
- If you are using the MRM parser, select the format of
the message from the list in Physical
format. This list includes all the physical formats that
you have defined for this Message
model.
- On the Parser Options subtab, Parse timing is, by default, 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. If you are using the XMLNSC parser, set values for the properties
that determine how the XMLNSC parser operates. For more information,
see Manipulating messages in the XMLNSC domain.
- On the Error Handling tab, set values
for the properties that determine how an error message returned by
the web service is handled:
- For the whole web service error message to be propagated as
the output message, leave Replace
input with error selected (the default setting).
- For the web service error message to be included in the output
message with part of the input message content, clear Replace input with error 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).
- In the Error message
location field, 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 Replace
input with error.
You can enter any valid ESQL field reference,
including expressions within the reference and new field references
(to create a node in the message tree for the response).
For example, enter:
OutputRoot.XMLNSC.ABC.DEF
or Environment.WSError
If you
select Replace input with error,
this property is ignored.
- On the Advanced tab, set values
for the Advanced properties that describe the structure and content
of the web service request and response:
- Specify the content of the request message that is sent
to the web service:
- For the request message to be the whole input message body, leave Use whole input message as request selected
(the default setting).
For the request message to contain a subset
of the input message, clear Use whole
input message as request and set the Request message location in tree property.
- In the Request message location
in tree field, 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 Use
whole input message as request. The node creates a 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.XMLNSC.ABC
If you select Use whole input message as request,
this property is ignored.
When the appropriate message tree content is parsed to create
a bit stream, the message properties (Message
domain, Message set, Message type, and Message format) that are associated
with the input message body and stored in the Properties folder are
used.
- Specify the content of the output message that is propagated
to the next node in the message flow:
- For the whole web service response message to be propagated as
the output message, leave Replace
input message with web-service response selected (the default
setting).
For the web service response message to be included in
the output message with part of the input message content, clear Replace input message with web-service response 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).
- In the Response message location
in tree field, 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 Replace input message
with web-service response.
You can enter any valid ESQL
field reference, including expressions within the reference, and including
new field references (to create a node in the message tree for the
response). For example, enter:
OutputRoot.XMLNSC.ABC.DEF
or Environment.WSReply
If you
select Replace input message with
web-service response, this property is ignored.
When the response bit stream is parsed to create message
tree contents, the message properties (Message
domain, Message set, Message type, and Message format), that you have specified
in the Response Message Parsing properties of the node, are used.
- For the node to generate an HTTPRequestHeader for the
request message, leave Generate default
HTTP headers from input selected (the default setting).
If you do not want the node to generate an HTTPRequestHeader
for the request message, clear Generate
default HTTP headers from input. 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 HTTPRequest node extracts web
service headers from the input HTTPRequestHeader and adds any unique
web service headers, except Host (see the following table), 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.)
The HTTPRequest node 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=ccsid of
the message body Unless the input message
is in the JSON domain, where the default is:
application/json;
charset=ccsid of the message body
|
Host |
The host name to which the request is to be
sent. |
The HTTPRequest node
also adds the optional header Content-Length with the correct calculated
value, even if this value 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 HTTPRequest node extracts web
service headers, except Host, from the HTTPInputHeader (if it is present
in the input message). The HTTPRequest node adds the required
web service headers with default values, if these values 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. The node 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 HTTPRequest 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
action typically causes an error to be generated by the web service,
unless the web service is configured to handle the message contents.
If you have selected
Use
compression or
Accept compressed
responses by default, the Content-Encoding and Accept-Encoding
HTTP header fields are populated regardless of whether you have selected
Generate default HTTP headers from input:
- If the value of Use compression is
not the default of None,
the Content-Encoding HTTP header is populated with this value, and
the bit stream is compressed. If the Content-Encoding header is already
present in an existing HTTP header, this field is updated with the
value of the Use compression property.
If the existing Content-Encoding header already starts with the named
compression function, then no further compression takes place. If
the Content-Encoding header starts with deflate, then no compression takes
place irrespective of whether ZLIB
(deflate)or deflate is
selected.
- If you have selected Accept compressed
responses, the Accept-Encoding field is populated. If this
field is already present in an existing HTTP header, the existing
value overrides the property on the node. However, if a compressed
response is received, it is not decompressed.
- Select the Accept compressed
responses by default property to indicate whether the request
accepts compressed responses. If you select this option,
the request can receive responses with a Content-Encoding of gzip or deflate. If such a response is
received, the content is decoded and the Content-Encoding header is
removed. If the Request Header does not contain an Accept-Encoding
header, then selecting this option sets the Accept-Encoding header
to "gzip, deflate".
- On the Validation tab, set Validation
properties if you want the parser to validate the body of response
messages against the Message set.
(If a message is propagated to the Failure terminal of the node, it
is not validated.) These properties do not cause the input message
to be validated. It is expected that, if such validation is required,
the validation has already been performed by the input node or a preceding
validation node.
For more information, see Validating messages and Validation properties.
What to do next
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 integration node provides default error
processing, see Handling errors in message flows.