SOAPRequest node
Use the SOAPRequest node to send a SOAP request to the remote web service.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Express
- Scale
- Adapter
Purpose
The SOAPRequest node is a synchronous request and response node, which blocks processing after sending the request until the response is received. This node enables the HTTP 1.1 Keep-Alive method by default.
The SOAPRequest node is contained in the Web Services drawer of the message flow node palette, and is represented in the IBM® Integration Toolkit by the following icon:
Using this node in a message flow
The SOAPRequest node can be used in any message flow that needs to call a web service.
You can enable reliable messaging for outbound SOAP requests by associating a SOAPRequest node with a policy set configured for WS-RM. For further information, see Web Services Reliable Messaging.
- Basic authentication, see Providing credentials in HTTP requests.
- (Windows only) Integrated Windows Authentication (NTLM, SPNEGO or Kerberos), see Providing credentials for outbound requests by using IWA.
Terminals and properties
The SOAPRequest 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 a message is routed if a failure is detected when the message is propagated to the Out flow (such as a message validation failure). Failures routed to this terminal include failures caused by the retry processing occurring before the retry propagates the message to the Out flow. |
Out | The output terminal to which the message is routed if the SOAP request has been sent and responded to successfully, and if further processing is required within this message flow. If no errors occur within the SOAPRequest node and a none fault SOAP response is received from the external resource it is always sent to the Out terminal first. |
Fault | SOAP fault messages received in response to the sent request are directed to the Fault terminal. If no connection is provided to the Fault terminal no further processing occurs for a received fault within this message flow. |
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).
Some SOAPRequest node properties
are initially set from properties in the imported WSDL. These properties
are parsed differently depending on which URI format is used by the address
element
in the WSDL. For details, see WSDL URI formats for JMS.
The SOAPRequest node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type | The name of the node. |
Short description | No | No | None | A brief description of the node. |
Long description | No | No | None | Text that describes the purpose of the node in the message flow. |
The SOAPRequest node Basic properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Operation mode | Yes | Yes | Invoke a specific web service defined by a WSDL interface | This property allows you to specify the operation mode of the node, which determines whether it acts in WSDL mode or in gateway mode. In WSDL mode, the node performs operations according to the WSDL it is configured with. However, gateway mode allows you to configure your flow to handle generic SOAP request/response and one-way messages, or to act as a façade between multiple web services clients and multiple back-end web services providers. |
WSDL file name | Yes | No | None | This property indicates the location of the WSDL file that you want to use to configure the node. Enter the full path to the WSDL file, or click Browse to locate the WSDL file in your workspace. This property takes a string value. To use a WSDL file in a shared library, the container
that contains your message flow must reference that shared library.
When the SOAPRequest node
uses a WSDL file in a shared library, the shared library name is specified;
for example:
When you select a WSDL file for the WSDL file name property, the WSDL is validated to ensure that it is WS-I compliant. If the WSDL has a binding that uses SOAP/JMS and that is not WS-I compliant, by default no error is shown. To enable strict WS-I validation and display a warning when a SOAP/JMS transport is used, click WS-I BP 1.1: Allow SOAP/JMS as transport URI check box. and clear the Only deployable WSDL files can be used to configure the SOAP nodes. After a valid WSDL file is selected, the message set project to which the WSDL file belongs is added as a referenced project to the corresponding application or library, if the reference does not exist. If the WSDL file is not valid, or an incorrect file name is entered, an error message is displayed in the Properties view and all WSDL properties are blank. The following situations result in an
error condition:
WSDL properties are disabled when the node is configured to act in gateway mode. |
Port type | Yes | No | By default, the first Port type found in the WSDL file, that has an associated HTTP binding with it, is selected. | This property type is
String. The field lists all the Port
types defined in WSDL file selected in the WSDL file name property. Error
Conditions:
WSDL properties are disabled when the node is configured to act in gateway mode. |
Imported binding | Yes | No | This property type is String. This property is updated every time that the Port type value changes. The field lists the imported SOAP bindings with HTTP or JMS transport associated with the selected Port type. When you select a binding, the property tab for the associated transport is enabled; otherwise, it is disabled. Bindings are listed in the same order in which they appear in the WSDL file. The selected binding is the one that has both ports and operations. If there is no such binding, then binding with ports is selected. If no bindings have ports then the first binding in the list is selected. Error
Conditions:
WSDL properties are disabled when the node is configured to act in gateway mode. |
|
Binding operation | Yes | No | This property type is
String. The Binding operation box contains all the operations defined by the selected binding. The first operation in the list is selected by default. This property is updated every time the selected binding value changes WSDL properties are disabled when the node is configured to act in gateway mode. |
|
Service port | Yes | No | This property type is String.
This field is updated every time that the selected binding is updated.
This field lists all the WSDL ports that point to the selected binding.
The first service port for the binding is selected by default. This
property is updated every time the selected binding value changes. Error
Conditions:
WSDL properties are disabled when the node is configured to act in gateway mode. |
|
Target namespace | Yes | No | Target namespace is implemented
as a read-only field. This hidden property type is String. It is updated with the Target namespace of the WSDL file when the WSDL file name is configured. WSDL properties are disabled when the node is configured to act in gateway mode. |
|
Transport | No | No | This property is set automatically when the Imported binding property is selected.
The value of this property shows the transport used by the selected
WSDL binding; for example, HTTP or JMS. If you choose to switch the transport from JMS to HTTP, a dialog box displays, which allows you to reset the JMS-specific properties. You must reset the JMS properties to deploy the message flow to a runtime environment version prior to fix pack V7.0.0.1. |
The SOAPRequest node HTTP Transport properties are described in the following table. These settings are used only when the node uses HTTP transport
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Web service URL | Yes | Yes | SOAP address of the selected port | The URL of the SOAP address
selected. This property is automatically derived from the <soap:address> element
of the selected Service port.
Whenever the selected port is updated, the Web service URL is updated accordingly.
However, if you override the value then your value persists and the
URL is no longer updated from the service port.If you choose to
override this property you must specify it in the form http://<hostname>[:<port>]/[<path>] where:
For more details of how to override this property, see Changing the default URL for a SOAPRequest node or a SOAPAsyncRequest node request. |
webServiceURL |
Request timeout (in seconds) | No | Yes | 120 | The number of seconds that the client waits
for a remote server to respond with a 'message received' acknowledgment.
The timeout might take up to one second longer than the value specified. If no response is received in this time, a SOAP Fault exception is raised and is propagated to the Failure terminal. |
|
HTTP(S) proxy location | No | Yes | The proxy server to which requests are sent.
This value must be in the form hostname:port. If the configured proxy server requires
authentication, the credentials must be set by using the mqsisetdbparms command with
the resource name |
httpProxyLocation | |
Protocol (if using SSL) | No | Yes | TLS | The selected protocol if you use SSL. This property type is Enumerate. The
following options are available:
Both ends of an SSL connection must agree on the protocol to use; therefore, the chosen protocol must be one that the remote server can accept. For a list of the protocols that are supported, see the appropriate level of the IBM SDK, Java™ Technology Edition, product documentation online. For example, for Java 8, see Protocols. |
sslProtocol |
Allowed SSL ciphers (if using SSL) | No | Yes | None | The specific SSL cipher, or ciphers, that you
are using. This setting allows you 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 used by the connection. This set
of ciphers must include one or more that are accepted by the remote
server. You can specify a list of ciphers in priority order. The server selects the first acceptable cipher in the list. If none of the ciphers in the list are suitable, the server returns a handshake failure alert and closes the connection. A comma is used as a separator between the ciphers. The default value is an empty string, which allows the node to use any, or all, of the available ciphers during the SSL connection handshake. This method allows the greatest scope for making a successful SSL connection. |
allowedSSLCiphers |
Use compression | No | No | None | This property controls whether the content of
the HTTP request is compressed. Valid values are none, gzip, zlib
(deflate) and deflate. If the request is compressed, the Content-Encoding
header is set to indicate that the content is compressed. zlib (deflate) represents RFC 1950 + RFC 1951 combined. deflate represents RFC 1951 only. |
requestCompressionType |
Accept compressed responses by default | No | Yes | Cleared | This property indicates whether the request
accepts compressed responses. If this option is selected, it is possible
for the request to 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". |
acceptCompressedResponses |
Perform hostname checking (if using SSL) | No | Yes | No | This property specifies if the host name of the server that is receiving the request must match the host name in the SSL certificate. | hostnameChecking |
SSL client authentication key alias | No | Yes | (empty string) | This property specifies an SSL authentication alias for the client-side of a SOAP connection. Taking the default value means that the first appropriate key is chosen for you automatically. | keyAlias |
Enable certificate revocation list checking | No | Yes | Not selected | This property specifies whether CRL checking should be enabled for SSL connections | enableCRLCheck |
The SOAPRequest node JMS Transport properties are described in the following table. These settings are used only when the node uses JMS transport
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Destination | Yes | Yes | None | The destination to which the node sends outgoing
messages. If the SOAPRequest node
is to be used to send point-to-point messages, enter the Destination
queue name for the JMS queue name that is listed in the bindings file. This
property takes its initial value from a WSDL URI property, depending
on whether the WSDL |
jmsDestination |
Reply To Destination | No | Yes | None | The name of the JMS destination to which the
receiving application must send a reply message. This property is
not used if the JMS operation is one way. For a reply message to be
returned to this JMS destination, the JMS destination name must be
known to the domain of the JMS provider that is used by the receiving
client. If you do not specify a reply-to destination, a temporary
dynamic queue is used as the reply-to destination. If you do not specify
a reply-to destination and you are using the WebSphere® MQ JMS provider, you must configure
JMS temporary dynamic queues. For more information about configuring
JMS temporary dynamic queues, see Configuring JMS temporary dynamic queues for the WebSphere MQ JMS provider. This
property takes its initial value from a WSDL URI property, depending
on whether the WSDL |
jmsReplyToDestination |
Request timeout (in seconds) | No | Yes | 120 | The time the client waits for a remote server to send a response message before timing out. | requestTimeout |
JMS provider name | Yes | No | WebSphere MQ | Select a JMS vendor name from the list, or enter
a name of your choice. The name must match the name of a configurable
service that is defined for the integration node to which you deploy
the message flow. When you select a name from the list, the Initial context factory property is updated automatically with the relevant Java class. If you enter your own JMS provider name, you must also enter a value for the Initial context factory. |
|
Initial context factory | Yes | Yes | com.sun.jndi.fscontext. RefFSContextFactory | The starting point for a JNDI namespace. A
JMS application uses the initial context to obtain and look up the
connection factory and queue or topic objects for the JMS provider. If
you select a JMS provider name from the list in JMS provider name, the Initial context factory property
is updated automatically with the relevant Java class. If you enter your own JMS provider
name, you must also enter a value for the Initial context factory. The default
value is This property takes its initial value from a
WSDL URI property, depending on whether the WSDL |
initialContextFactory |
JNDI URL bindings location | Yes | Yes | The system path or the LDAP location for the
bindings file. The bindings file contains definitions for the JNDI
administered objects that are used by the SOAPRequest node. This property is disabled when the Initial context factory is com.ibm.mq.jms.Nojndi. When
you enter a value for JNDI URL bindings
location, ensure that it complies with the following instructions:
For information about constructing the JNDI administered objects bindings file, see the JMS provider documentation. This
property takes its initial value from a WSDL URI property, depending
on whether the WSDL |
locationJndiBindings | |
Connection factory name | Yes | Yes | The name of the connection factory that is used
by the SOAPRequest node
to create a connection to the JMS provider. This property is initially
configured from the imported WSDL. This name must exist in the bindings
file. The Connection factory
name must be a JMS QueueConnectionFactory. This property
takes its initial value from a WSDL URI property, depending on whether
the WSDL |
connectionFactoryName | |
User Parameters | No | No | This table describes user properties that have been defined in the request. The properties are name-value pairs that exist in the WSDL and are not used by other properties of the SOAPRequest node. | ||
JNDI parameters | No | No | A table mapping JNDI context parameters to their
type. These properties take their initial values from any W3C-style WSDL properties starting with jndi-. IBM-style WSDL does not support JNDI parameters, but you can set these properties on the node. |
The SOAPRequest node Message Delivery properties are described in the following table. This sub tab is enabled only if the selected binding in the Basic tab uses JMS transport.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Target Service | No | No | None | Used by the SOAPRequest node when dispatching
the service request. This property takes its initial value from the targetService WSDL property. |
targetService |
Delivery mode | No | Yes | Persistent | This property controls the persistence mode
that a JMS provider uses for a message. Valid values are:
This property takes its initial value from a WSDL URI property,
depending on whether the WSDL |
deliveryMode |
Message Priority | No | Yes | 4 | This property assigns relative importance to the message and can be used for message selection by a receiving web service. Select a value between 0 (lowest priority) and 9 (highest priority). The default value is 4, which indicates medium priority. Priorities in the range 0 - 4 indicate typical delivery. Priorities in the range 5 - 9 indicate faster delivery. This
property takes its initial value from a WSDL URI property, depending
on whether the WSDL |
messagePriority |
Message Expiration (ms) | No | Yes | 0 | This property controls the length of time, in
milliseconds, for which the JMS provider keeps the output JMS message.
The default value, 0, is used to indicate that the message must not
expire. This property takes its initial value from the timeToLive WSDL property. |
messageExpiration |
Message Type | No | Yes | bytes | Select a value from the list to configure the type of JMS message that is produced by the SOAPRequest node. | messageType |
The SOAPRequest node Transactions properties are described in the following table. This setting does not apply when the node uses HTTP transport.
Property | M | C | Default | Description |
---|---|---|---|---|
Transaction Mode | Yes | No | Automatic | This property controls whether the message is output under a JMS transaction. Valid values are Yes, No, and Automatic. Select No to output the message using a non-transactional JMS session. Select Yes to output the message using a transactional JMS session. The JMS transaction can be either local or XA coordinated. To use an XA coordinated transaction, using an XA JMS session, you must also select the message flow property Coordinated Transaction in the BAR file properties. Select Automatic if you want the message transactionality to be inherited from the Transaction mode setting on the Input node at the start of the flow. This value is only used when the selected operation is one-way. |
The SOAPRequest node Advanced properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
WSDL-defined SOAP response headers | No | No | This table is read-only, and is populated by
the SOAP headers defined in the output part of the selected operations.
By default, the check boxes, in the second column of the table, are
cleared for all entries in the WSDL-defined
SOAP response headers table. You must select the relevant
check box to add the header to the must
understand headers list. SOAP headers that are part of the must understand headers list are incorporated into the flow rather than causing a SOAP fault. Adding headers to the must understand headers list stops SOAP faults being generated by SOAP headers. You do not need to add must understand headers for WS-Addressing and WS-Security as they are understood if you configure WS Extensions. The table is updated automatically when the selected operation is updated. This property is generated in the CMF file.When the node is configured to act in gateway mode, with no WSDL required, this table is cleared. The original values of these fields are restored if the operation mode of the node is changed back to WSDL mode. |
|
User-defined SOAP response headers | No | Yes | None | You can add custom headers (headers that are not defined in the WSDL file) in this table. Use Add, Edit, and Delete for this table. You must select the check box, in the second column of the table, to ensure that the newly added custom header is added to the must understand headers list. This property is generated in the CMF file. |
The SOAPRequest node WS Extensions properties are described in the following table.
Property | M | C | Default | Description | |
---|---|---|---|---|---|
Use WS-Addressing | No | No | This property specifies whether to use WS-Addressing. For more details about WS-Addressing with the SOAPRequest node, see WS-Addressing with the SOAPRequest node. |
||
Place WS-Addressing headers into LocalEnvironment | No | No | Cleared | This property specifies whether the node puts WS-Addressing headers received in the response message into the local environment tree. WS-Addressing headers are not accessible to the flow if this check box is cleared because by default, all headers are processed and removed. | |
Allow MTOM | No | Yes | No | This property controls whether MTOM is enabled
for the parser. Valid values are Yes, No, and Force. For more information about
using SOAP MTOM with the SOAPReply, SOAPRequest, and SOAPAsyncRequest nodes, see SOAP MTOM and the SOAPReply, SOAPRequest, and SOAPAsyncRequest nodes. MTOM support is disabled when the node is configured to act in gateway mode. |
allowMTOM |
WS-Security | No | Yes | This complex property is in the form of a table
and consists of two columns:
|
The SOAPRequest node Response Message Parsing properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Message domain | No | No | SOAP | The domain that is used to parse the response
message. By default, the message that is propagated from the SOAPInput node is in the SOAP
domain. You cannot specify a different domain. For more information,
see SOAP parser and domain. The Response Message Parsing properties are disabled when the node is configured to act in gateway mode. |
Message model | Yes | No | Set automatically from the WSDL file name property. | The name or location of the message model schema
file in which the response message is defined. When a WSDL file is
associated with the node, this property is automatically set to the
location of the WSDL file. If the WSDL file is in a shared library,
this field specifies the name of the shared library in braces, {}. If you set this property, then later update the project dependencies to remove this message model reference, a warning is issued. Either update the Message model property, or restore the reference to this message model. The Response Message Parsing properties are disabled, and this property is cleared, when the node is configured to act in gateway mode. |
Message | No | No | The name of the response message. The node detects the message type automatically. You cannot set this property. | |
Physical format | No | No | The name of the physical format of the response message. You cannot set this property. |
The SOAPRequest node Parser Options properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Parse timing | No | No | On demand | This property controls when a response message
is parsed. Valid values are On
demand, Immediate,
and Complete. The default
value, On demand, causes
parsing of the message to be delayed. For a full description of this property, see Parsing on demand. |
Build tree using XML schema data types | No | No | Set | This property controls whether the syntax elements
in the message tree have data types taken from the XML Schema. The SOAP Parser Options properties determine
how the SOAP parser operates. The SOAP parser options are passed through
to the XMLNSC parser. For more information, see Manipulating messages in the XMLNSC domain. This property is cleared and disabled when the node is configured to act in gateway mode. |
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 a response 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 a response 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 a response 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. 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 SOAPRequest node Validation properties are described in the following table. These properties apply only to the response message; the request message is not validated.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Validate | No | Yes | Content and value | This property controls whether the SOAP parser
validates the body of each response message against XML Schema generated
from the message. Valid values are None, Content and value, and Content. By default, validation
is enabled. The SOAP parser starts the XMLNSC parser to validate the
XML body of the SOAP web service. If a message is propagated to the
Failure terminal of the node, it is not validated. For more details, see Validating messages and Validation properties. Validation properties are disabled, and the Validate property is set to None, when the node is configured to act in gateway mode. |
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 Validation properties are disabled when the node is configured to act in gateway mode. |
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. |
WrittenDestination data
WrittenDestination = (
SOAP = (
Request = (
WSA = (
To = 'URI'
MessageID = 'id'
Action = 'doAllTheStuff'
)
Transport = (
HTTP = (
WebServiceURL = 'http://server:8080/thing'
Compression = (
OriginalSize = 775
CompressedSize = 411
)
JMS = (
Destination = jmsDestination
)
)
)
)
)
Local environment overrides
You can dynamically override set values in the local environment in the same way as setting values in other elements of a message. For a full list of values you can override in the local environment, see Local environment overrides.
HTTPRequest headers
To control the contents of a HTTPRequest header that is included in a message, you must include a Compute node to add a HTTPRequest header to the input message before the HTTPRequest node in the message flow.
SET OutputRoot.HTTPRequestHeader.SOAPAction = InputRoot.HTTPInputHeader.SOAPAction