Use the SOAPRequest node to send a SOAP request to the remote Web service.
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:
You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.
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.
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. 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 using SOAP/JMS which 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 and clear the WS-I BP 1.1: Allow SOAP/JMS as transport URI check box. 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. This property takes a string value. 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 | Blank | The location of the proxy server to which requests are sent. | 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. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Destination is set to the value of destinationName found in the WSDL if a W3C-style URI is found, or destination if an IBM-style URI is found. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Reply To Destination is set to the value of replyToName found in the WSDL if a W3C-style URI is found, or to the first of replyToName, replyTo, replyToDestination, or replyDestination if an IBM-style URI is found. If any of these other properties are present, they display as a name-value pair in the User Parameters table. |
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 broker 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 com.sun.jndi.fscontext.RefFSContextFactory, which defines the file-based Initial context factory for the WebSphere MQ JMS provider. This property takes its initial value from a WSDL URI property, depending on whether the WSDL address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Initial context factory is set to the value of jndiInitialContextFactory found in the WSDL if a W3C-style URI is found, or initialContextFactory if an IBM-style URI is found. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. JNDI URL bindings location is set to the value of jndiURL found in the WSDL if a W3C-style URI is found, or jndiProviderURL if an IBM-style URI is found. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Connection factory name is set to the value of jndiConnectionFactoryName found in the WSDL if a W3C-style URI is found, or connectionFactory if an IBM-style URI is found. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Delivery mode is set to the value of deliveryMode found in the WSDL if a W3C-style URI is found, or to the first of deliveryMode or persistence if an IBM-style URI is found. If both these properties are present, the second property displays as a name-value pair in the User Parameters table. |
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 address URI is formatted in the W3C (standards) style, or the IBM (proprietary) style. Priority is set to the value of priority found in the WSDL if a W3C-style URI is found, or to the first of priority or Priority if an IBM-style URI is found. If both these properties are present, the second property displays as a name-value pair in the User Parameters table. |
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 Using SOAP MTOM with 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 set | Yes | No | Set automatically from the WSDL file name property. | The name of the message set in which the response
message is defined. This property is automatically set to the message
set that contains the WSDL file, when the WSDL is associated with
the node. If you set this property, then later update the project dependencies to remove this message set reference, a warning is issued. Either update the Message set property, or restore the reference to this message set project. The Response Message Parsing properties are disabled, and this property is cleared, when the node is configured to act in gateway mode. |
| Message type | No | No | The name of the response message. The node detects the message type automatically. You cannot set this property. | |
| Message 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 using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |
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
)
)
)
)
)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.
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
Last updated Friday, 21 July 2017