Read this information if you are using
HTTP message flows to interact with Web services. You might find it useful
to read this in conjunction with the subsequent Web services scenarios section.
- HTTPS
- For help with using HTTPS see Implementing SSL authentication.
- Setting the HTTP Status Code for a reply
- The default HTTP Status Code is 200, which indicates success. If you want
a different status code to be returned, take one of the following actions:
- Set your status code in the field Destination.HTTP.ReplyStatusCode in
the LocalEnvironment tree (correlation name OutputLocalEnvironment). This
field overrides any status code that is set in an HTTPResponseHeader header.
This action is the preferred option, because it provides the greatest flexibility.
- Set your status code in the field X-Original-HTTP-Status-Code in the HTTPReplyHeader
header.
- Set your status code in the field X-Original-HTTP-Status-Code in the HTTPResponseHeader
header. This option is typically useful if you include an HTTPRequest node
before the HTTPReply node in your flow, because the HTTPResponseHeader header
is created for you. In this scenario, an HTTPResponseHeader header has been
created in the logical tree, representing the HTTP headers in the response
from another Web service. If you have selected the Generate
default HTTP headers from reply or response property in the HTTPReply
node, values for the response header are set as default values when the reply
message is created.
- Using LocalEnvironment.Destination.HTTP.RequestIdentifier
- When the HTTPInput node receives an input request message, it sets the
LocalEnvironment field Destination.HTTP.RequestIdentifier to a unique value
that identifies the Web service client that sent the request. You can refer
to this value, and you can save it to another location if appropriate.
For
example, if you design a pair of message flows that interact with an existing WebSphere MQ application (as described in Broker calls existing Web service),
you can save the identifier value in the request flow, and restore it in the
reply flow, to ensure that the correct client receives the reply. If you use
this technique, you must not change the data and you must retain the data
as a BLOB.
The HTTPReply node extracts the identifier value from the
LocalEnvironment tree and sets up the reply so that it is sent to the specific
client. However, if you are using an HTTPReply node in a flow
that does not have an HTTPInput node, and this field has been deleted or set
incorrectly, message BIP3143S is issued.
If you design a message
flow that includes both an HTTPInput and an HTTPReply node, the identifier
value is set into the LocalEnvironment by the HTTPInput node, but the HTTPReply
node does not use it. Therefore, if your message flow includes both nodes
and a Compute node in the same flow, you do not have to include the LocalEnvironment
tree when you specify which components of the message tree are copied from
input message to output message by the Compute node (the Compute
mode property).
- Setting the HTTPRequest node URL dynamically
- You can set the property Default Web
service URL on the HTTPRequest node to determine the destination
URL for a Web service request. You can configure a Compute node before the
HTTPRequest node within the message flow to override the value set in the
property. Code ESQL that stores a URL string in LocalEnvironment.Destination.HTTP.RequestURL;
the HTTPRequest node retrieves and uses the URL string in place of the node
property value.
Although you can also set the request URL in the special
header X-Original-HTTP-URL in the HTTPRequestHeader header section of the
request message (which overrides all other settings) in a Compute node, use
the LocalEnvironment tree content for this purpose for greater flexibility.
- Setting Generate default HTTP headers
from reply or response for the HTTPReply node
- If you select Generate default HTTP headers
from reply or response in the HTTPReply node properties, the node
includes a minimum set of headers in the response that is sent to the Web
service client.
To set any headers explicitly, create them in an HTTPReplyHeader header.
For example, a Compute node propagates a message in the XMLNS domain and modifies
the Content-Type as follows:
CALL CopyMessageHeaders();
SET OutputRoot.HTTPReplyHeader."Content-Type" = 'text/xml';
SET OutputRoot.XMLNS = InputRoot.XMLNS;
Do not use the ContentType
property to set the Content-Type unless you are working in the MIME domain.
The ContentType property is specifically intended to set the value of Content-Type
used in MIME.
The full set of HTTP headers used in the request is built
by selecting the headers using the algorithm defined in the following steps:
- Select any headers in an HTTPReplyHeader header.
- If no Content-Type header is yet defined, create one using any non-empty
value in the ContentType property.
- Select any headers in an HTTPResponseHeader header (an HTTPResponseHeader
header is propagated on return from an HTTPRequest node).
- If no Content-Type header is yet defined, create one with the default
value text/xml; charset=utf-8.
- Create or overwrite the Content-Length header.
Attention: The HTTPReply node always rewrites the Content-Length
header, even if you have cleared Generate
default HTTP headers from reply or response. This action ensures
that the content is correct.
If an HTTPReplyHeader header section
existed in the message received by the HTTPReply node, and the Output terminal
of the HTTPReply node is connected, the HTTPReplyHeader header section is
updated with any changed or added values.
- Setting Generate default HTTP headers
from input for the HTTPRequest node
- If you select Generate default HTTP headers
from input in the HTTPRequest node properties, the node includes
a minimum set of headers in the request that is sent to the server.
To
explicitly set headers , create them in an HTTPRequestHeader header. For example,
a Compute node propagating a message in the XMLNS domain can modify the Content-Type
as follows:
CALL CopyMessageHeaders();
SET OutputRoot.HTTPRequestHeader."Content-Type" = 'text/xml';
SET OutputRoot.XMLNS = InputRoot.XMLNS;
Do not use the ContentType
property to set the Content-Type unless you are working in the MIME domain.
The ContentType property is specifically intended to set the value of Content-Type
used in MIME.
The full set of HTTP headers used in the request is built
by selecting the headers using the algorithm defined in the following steps:
- Set the Host header, based on either the request URL or the incoming HTTPRequestHeader
header section of the message.
- Select any headers in an HTTPRequestHeader header.
- If no Content-Type header is yet defined, create one using any non-empty
value in the ContentType property.
- Select any headers in an HTTPInputHeader header (an HTTPInputHeader header
is created automatically by an HTTPInput node).
- If no Content-Type header is yet defined, create one with the default
value text/xml; charset=utf-8
- If no SOAPAction header is yet defined, create one with the
default value ''.
- Create or overwrite the Content-Length header.
Attention: The HTTPRequest node always rewrites the Content-Length
header, even if you have cleared Generate
default HTTP headers from input or request. This action ensures that
the content is correct.
If an HTTPRequestHeader header exists in the received message, the HTTPRequestHeader
header is updated with any changed or added values.
- Collecting HTTPListener trace if you have problems with HTTP
- If you have problems with HTTP, you can trace the HTTPListener:
- Use the mqsichangetrace command to start
trace with the following options:
mqsichangetrace component -t -b
where component is
the broker name.
- Retrieve the HTTPListener trace log using the mqsireadlog command
with the HTTPListener qualifier for the -b parameter.
- Format the trace log using the mqsiformatlog command
so that you can view its contents.