Start of change
WebSphere Message Brokers
File: ac56170_.dita
Writer: Kate Hostler

Reference topic

This build: July 31, 2007 21:21:26

SOAPInput node

This topic describes the SOAPInput node.

Purpose

Use the SOAPInput node to process client SOAP messages, thus enabling the broker to be a SOAP Web services provider.

The SOAPInput node is contained in the Web Services drawer of the message flow node palette, and is represented in the workbench by the following icon:

SOAPInput node icon

Using this node in a message flow

The SOAPInput node can be used in any message flow that needs to accept messages in files. Look at the following sample to see how to use this node:
  • SOAPInput sample
Draft comment:
<<LINK TO FileInput SAMPLE>>

You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

Configuring the SOAPInput node

When you have put an instance of the SOAPInput node into a message flow, you can configure it. For more information, see Configuring a message flow node. To display its properties, either double-click the node, or right-click the node and click Properties. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

  1. Optional: use the Description tab to enter a short description, a long description, or both. You an also rename the node on this tab.
  2. Use the Basic tab,
    Draft comment:
    (This tab is similar to the Basic tab of the SOAPAsyncRequest node.
    to configure the following WSDL Properties:
    • WSDL file name.
      Draft comment:
      (Same as SOAPAsyncRequest node)
      This property type is String. This field allows you to change the WSDL file you use to configure this node. This field displays the message 'choose a WSDL file by dragging and dropping a wsdl on the node, clicking the browse button or typing the file name'. The field can be configured in various ways:
      • You can click Browse to select a WSDL file to import from the workspace.
      • You can type in a file name that is relative to the message set project in which the WSDL exists, that is, type in the full path name of the WSDL but exclude the message set project name.
      • You can drag and drop a WSDL file onto the node.

      When you have made a new selection the WSDL file is validated. The WSDL validation is exactly the same as the validation that is done when you drag and drop the WSDL file onto a flow. After the file is validated, the message set to which it belongs is added as a reference project if it does not already exist.

      If the WSDL file is not validated, or an incorrect file name is entered, an error message is displayed on the editor and the corresponding WSDL properties are blank.

      If the same file name is entered into the text box, no validation or updates occur. In order to refresh the WSDL file contents click Browse, or drag and drop the WSDL file onto the node.

      Compile Time Validation: At the time of flow compilation, it is verified that there is one instance only of the referenced WSDL in the symbol table. An error is generated on the node if the referenced WSDL cannot be resolved, or if there are more than one WSDL files of the same name in the workspace. For a multi-file WSDL, verification only takes place for the main WSDL. For a multi-file WSDL it is also verified that the imports inside the main WSDL have been imported.

      The following cases lead to error conditions on this property editor:
      • If the WSDL file does not come from a message set project, or if the WSDL was not imported as described in the following topics:
      • There are no http bindings in the WSDL file.
      • There are no port types in the WSDL file.
      • An empty string is typed in the text box after a valid WSDL file name has been entered.
      • File name entered in the text box does not exist.
    • Port type.
      Draft comment:
      (Same as SOAPAsyncRequest node)
      This property type is String. The field lists all of the port types defined in the WSDL document.
      Draft comment:
      Which document?
      By default, the first port type found in the WSDL that has an associated http binding with it, is selected.
      Error Conditions:
      • Selected port type does not contain at least one operation.
    • Imported binding.
      Draft comment:
      (Same as SOAPAsyncRequest node)
      This property type is String. This property is updated any time the port type value changes. The field lists all SOAP bindings with HTTP transport (6.1) associated with the selected port type. Bindings are listed in the same order in which they appear in the WSDL source. The selected binding initially is the one that has both ports and operations. If there is no such binding, then binding with just ports is selected. Also, if no bindings have ports then the first binding in the list is selected.
      Error Conditions:
      • No SOAP bindings (with HTTP transport) in the WSDL document are associated with the port type.
      • Selected binding does not have any operations.
    • Service port.
      Draft comment:
      (Similar to SOAPRequest node)
      This property type is String. The port field is updated any time the selected binding is updated. The field lists all WSDL ports that point to the selected binding. The first port for the binding is the selected port by default.
      Error Conditions:
      • No ports point to the selected binding.
    • Target namespace. This is a hidden String property on this tab. It is updated with the Target namespace of the WSDL when the WSDL file name is configured.
  3. Use the HTTP Transport tab to set the HTTP transport related properties:
    • URL Selector.
      Draft comment:
      (Same as HTTPInput node)
      This property type is String. This property is automatically set from the SOAP address of the selected port. However, if you override the value then your value persists, and the URL is not configured from the service port.
    • Maximum client wait time (in seconds). This property type is Integer. This is the wait time for a remote server to respond with a 'message received' acknowledgement.
    • Use HTTPS. This is a hidden Boolean property on this tab. This property is also automatically configured from the SOAP address of the selected port.

      If the address contains https URL, the box is marked, otherwise it is not.

      However, if you override this property with another value, this value persists. This means that the value is not configured from the service port URL anymore if you change the Use HTTPS value.

  4. Use the Advanced tab, to define your headers:
    • SOAP role. This property type is String. SOAP 1.1actor (SOAP 1.2 role) is implemented as an editable drop down box, which allows you to enter a new value; the default is Ultimate Destination (Ultimate Receiver).

      Predefined roles are specified in the respective SOAP 1.1 or /SOAP 1.2 specifications, and are used to process SOAP Headers targeted at the specific role.

      Error Conditions:
      • If you select empty, there is an error on flow validation.
    • Enable WS-addressing This property type is Boolean. This indicates whether to engage WS-addressing; the default is Enabled.
    • Set destination list. This property type is Boolean. This property indicates whether to add the incoming SOAP operations to the route to label the destination list.
    • Label prefix. This property type is String. A prefix to add to the method name to generate a label to route to. This is to allow multiple SOAP Input nodes in the same flow without their corresponding label nodes clashing.

      The default prefix is an empty string so that the operation name and the label name are identical, but the field displays the user instruction: <enter a prefix if required>. This property is not enabled if the setDestinationList property is not enabled.

    • Must understand headers. This property type is Complex. This property lists all SOAP headers for the broker runtime to mark as understood.

      This prevents the Axis 2 server from signaling SOAP fault, should the SOAP input message contain one or more of such headers with the must understand bit turned on.

      This property is split into WSDL-defined and User-defined tables, each of which is a complex property. Each table has the following layout:
      • Must understand column. Selecting the checkbox in this column indicates that header listed in this row is added to the must understand header list.
      • Operation name column
      • Header name column
      • Header namespace column
    The WSDL-defined table is read-only, and is populated, based on the SOAP headers defined in the input part of all operations of the selected binding.

    By default, Must understand check boxes are selected for ALL entries in the WSDL-defined table. When the selected binding is updated, the WSDL-defined header table is updated accordingly.

    You can add custom headers, that is, headers not defined in the WSDL, in the user-defined table. This table includes Add, Edit, and Remove buttons. You need to select the must understand checkbox for the newly added custom header, in order for the header to be added to the must understand headers list.

  5. Use the Error Handling tab to set the properties associated with fault processing:
    • Send Failures During Inbound SOAP Processing to Failure Terminal. This property type is Boolean. If a situation arises during inbound SOAP processing that results in a SOAP Fault, instead of immediately sending the SOAP Fault back to the client, send it to the Failure terminal instead, to allow logging, and recovery processing.

      In this situation an exception list is sent down the Failure terminal with the inbound message as a BLOB. The default value of this property is False.

  6. Use the Input Message Parsing tab with its corresponding Parser Options sub tab to set the properties associated with the input message:
    • Message Domain. This property type is String. The value is set to SOAP and the property is greyed out.
    • Message Set. This property type is String. The value is set to be the message set project value, on the drag and drop of WSDL; the property is greyed out.
    • Message Type. This property type is String. This value is set to blank and the property is greyed out.
    • Message Format. This property type is String. This value is set to blank and the property is greyed out.
    Parser Options sub tab. The following properties are listed on this tab:
    • Parse timing. This property type is Enumerate. Enter one of the values On Demand. Immediate, or Complete.
    • Soap Parser Options. This property type consists of check boxes for the following:
      • Build tree using XML schema data types
      • Retain mixed content
      • Retain comments
      • Retain processing instructions
    • Opaque elements. This property type is Complex.
  7. Use the Validation tab to set the properties associated with validating:
    • Validate. This property type is Enumerate. Enter one of the values None. Content and Value, or Content.

      The field is pre-populated with Content and Value.

    • Failure Action. This property type is Enumerate. Enter one of the values User trace. Exception list, Local erroror Exception.
  8. Use the Security tab to implement the security properties associated with the node, and its associated WS-Security sub tab to properties associated with Web Services security:
    • Identity Type: This property type is Enumerate and defines the format of the identity. Enter one of the values None. username, usernameAndPassword, or X.509.
    • Identity Token Location: This property type is String. This an ESQL Path or XPath expression, and must resolve to a token listed in Identity Type.
    • Identity Password Location: This property type is String. This an ESQL Path or XPath expression, and must resolve to a token containing a password when usernameAndPassword is used. Note that this property is enabled only when the usernameAndPassword identity type is selected.
    • Identity Issued By Location: This property type is String. This an ESQL Path, XPath expression, or literal specifying where the identity was defined.
    • Security profile: This property type is String, displayed in a combination box. You can enter your own value, or one of the following values No Security, Default Propagation, Default LDAP, or Default TFIM.
    • Treat Security exceptions as normal exceptions: This property type is Boolean and indicates if the security exceptions should be treated as normal exceptions; the default value is False.
    WS-Security sub tab. This property type is Complex and consists of two columns:
    • XPath Expression and an associated Alias value are added to the WS-Security table.

      The alias is resolved in a Policy Set that is created by the administrator. The Policy Set resolves the alias to either encrypt or sign the part of the message referred to by the XPath expression.

    • Use the Retry tab to define how retry processing is carried out when a failure gets rolled back to the input node:
      • Retry mechanism: This property type is Enumerate and defines the format of the mechanism. Enter one of the values Failure or ShortAndLongRetry.
      • Retry threshold: This property type is Integer and defines the number of retries to correct the failure.
      • ShortRetryInterval: This property type is Integer and defines the time the client waits in seconds before attempting to correct the failure.
      • LongRetryInterval: This property type is Integer and defines the time the client waits in seconds before attempting to correct the failure.

Terminals and properties

The SOAPInput node terminals are described in the following table.

Terminal Description
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 those 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 it has been successfully put to the output queue, and if further processing is required within this message flow. If no errors occur within the input node, a message received from an external resource is always sent to the Out terminal first.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

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).

The SOAPInput 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 SOAPInput node Basic properties are described in the following table:

Property M C Default Description
WSDL file name Yes No <None> The name of the WSDL file used to configure this node
Port type Yes No From WSDL The selected port type from the WSDL file
Imported binding Yes No From WSDL The selected binding from the WSDL file
Service port Yes No From WSDL The selected port from the WSDL file
Target namespace Yes No From WSDL The target namespace from the WSDL file

The SOAPInput node HTTP Transport properties are described in the following table:

Property M C Default Description
URL selector Yes Yes None The HTTP path selector upon which the node accepts inbound messages
Use HTTPS No Yes False If the address contains https URL, the box is marked, otherwise it is not.
Maximum client wait time (sec) Yes Yes 180 The time the client waits for a for a remote server to respond with a 'message received' acknowledgement.

The SOAPInput node Advanced properties are described in the following table:

Property M C Default Description
SOAP 1.1 actor (SOAP 1.2 role) Yes No Ultimate receiver The SOAP role the receiver is acting in
Enable WS-Addressing No Yes True Whether to engage Web Services Addressing.
Set destination list No No True Whether to add the method binding name to the route to label destination list. By default it is added so a route to label node straight after the node works.
Label prefix No No None The prefix to add to the method name when routing to label. This is enabled only if Set Destination List is true.
WSDL defined SOAP headers Header name Yes No Must understand selected Populated, based on the defined SOAP headers.
WSDL defined SOAP headers Header namespace Yes No Must understand selected Populated, based on the defined SOAP headers.
WSDL defined SOAP headers Operation name Yes No Must understand selected Populated, based on the defined SOAP headers.
User defined SOAP headers Header name No Yes None Custom header name
User defined SOAP headers Header namespace No Yes None Custom header namespace
User defined SOAP headers Operation name No Yes None Custom header operation name

The SOAPInput node Input Message Parsing properties are described in the following table:

Property M C Default Description
Message domain Yes No SOAP The value of the message domain can not be changed.
Message set Yes No The value of the message set project value on drag and drop of WSDL The value of the message set can not be changed.
Message type Yes No Blank The value of the message type can not be changed.
Message format Yes No Blank The value of the message format can not be changed.

The SOAPInput node Parser Options properties are described in the following table:

Property M C Default Description
Parse timing Yes Yes On demand If a parser is capable of parsing an input bit stream on demand, instead of immediately parsing the entire bit stream, the Parse Timing property of a message flow node controls the on demand behavior of the parser. You can set the Parse Timing property to On Demand (the default), Immediate, or Complete.
Build tree using XML schema data types No Yes False  
Retain mixed content No Yes False  
Retain comments No Yes False  
Retain processing instructions No Yes False  
Opaque elements No Yes Blank  

The SOAPInput node Error Handling property is described in the following table:

Property M C Default Description
Send failures during inbound SOAP processing to failure terminal No Yes False During inbound SOAP processing, send any fault to the Failure terminal

The SOAPInput node Validation properties are described in the following table:

Property M C Default Description
Validate No Yes Content and value Schema validation properties
Failure action No Yes User trace  

The SOAPInput node Security properties are described in the following table:

Property M C Default Description
Identity token type No Yes None The format of the identity token.
Identity token location No Yes Blank The location of the identity token. This must resolve to a token set in Identity Token Type
Identity password location No Yes Blank Only applicable if Username and password is selected.
Identity issued by location No Yes None An expression specifying where the identity was defined.
Security profile No Yes No security Value for the security profile in which you can enter your own value.
Treat security exceptions as normal exceptions No Yes False Whether security exceptions are treated as normal exceptions.

The SOAPInput node WS-Security properties are described in the following table:

Property M C Default Description
Alias No Yes   This is the alias value associated with an XPath expression. This option is related to Web-services security only.
XPath Expresssion No Yes   The XPath expression added to the Web Services security table. This option is related to Web-Services security only.

The SOAPInput node Retry properties are described in the following table:

Property M C Default Description
Retry mechanism No No Failure  
Retry threshold No Yes 0  
Short retry interval No Yes 0  
Long retry interval No Yes 0  
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:26

ac56170_.dita This topic's URL is:
End of change