Web Service Consumer Transformation Advanced Properties
The Web Service Consumer transformation advanced properties include the tracing level, generic fault ports, web services connection, and concurrent web service request messages.
You can define the following advanced properties for the Web Service Consumer transformation on the Advanced tab:
- Tracing Level
- Amount of detail that appears in the log for this transformation. You can choose terse, normal, verbose initialization, or verbose data. Default is normal.
- SOAP Action
Overrides the SOAP action value defined in the WSDL with a constant value for the Web Service Consumer transformation.
- Enable Generic SOAP Fault Handling
Returns fault messages that are not defined in the WSDL. Creates output ports in a GenericFault output group to handle fault codes and messages.
The following table describes the fault output ports for SOAP 1.1 and SOAP 1.2:
Fault Output Port for SOAP 1.1 | Fault Output Port for SOAP 1.2 | Description |
|---|
Fault Code | Code* | Returns a fault identification code. |
Fault String | Reason* | Returns an explanation of the error in a fault message. |
Fault Detail | Detail | Returns custom information that the web service provider passes to the Web Service Consumer transformation in a generic fault message. |
Fault Actor | Role | Returns information about the object that caused the fault to happen. |
- | Node | Returns the URI of the SOAP node that generated the fault. |
* The Code and Reason output ports are hierarchical. |
Note: You can expand the Code fault output port to extract the SubCode fault output port upto one level.
- Enable HTTP Error Handling
- Returns any HTTP error from the web service. Creates an HTTP error output port in the GenericFault output group.
- Treat Fault as Error
Adds fault messages to the mapping log. When a fault occurs, the Data Integration Service increments the error count for the mapping. Disable this property to allow early selection and push-into optimization. Default is enabled.
- Connection
Identifies the web services connection object to connect to the web service. Create the web services connection in the Developer tool. Edit the web services connection in the Developer tool or the Administrator tool. When you configure a web services connection, configure the endpoint URL, the type of security that the web service requires, and a connection timeout period.
The Web Service Consumer transformation connects to a web service using an endpoint URL. You can define the endpoint URL in the WSDL file, in a web services connection, or in an endpoint URL input port.
Use the following guidelines to determine when to configure a web services connection:
- - Configure a connection if you want to use an endpoint URL that differs from the URL in the WSDL file and if you are not using an endpoint URL input port.
- - Configure a connection if the web service you connect to requires web service security, HTTP authentication, or SSL certificates.
- - Configure a connection if you want to change the default connection timeout period.
Note: You can associate a WSDL data object in the repository with a web services connection. The associated connection becomes the default connection for each Web Service Consumer transformation that you create from that WSDL.
- Enable Compression
- Enables coding of SOAP requests with the GZIP compression method and enables decoding of SOAP responses with GZIP or deflate.
- XML Schema Validation
- Validates the SOAP response message at run time. Select Error on Invalid XML or No Validation.
- Sorted Input
- Enables the Data Integration Service to generate output without processing all of the input data. Enable sorted input when the input data is sorted by the keys in the operation input hierarchy.
- Push-into Optimization
- Enables push-into optimization. Click the Open button in the Push-Into Optimization property to select filter ports that receive filter values. For each filter port, choose the output port that contains the filtered column in the web service response.
- Has Side Effects
- Checkbox that indicates that the web service performs any function besides returning rows. The Web Service Consumer transformation has a side effect if the web service, in addition to returning a rows, modifies an object or interacts with other objects or functions. The web service might modify a database, add to a total, raise an exception, write an email, or call other web services with side effects. Disable the Has Side Effects property in order to allow push-into optimization or early selection optimization. Default is enabled.
- Enable Concurrency
Enables the Web Service Consumer transformation to create multiple concurrent connections to a web service so that it can send multiple web service requests in parallel. When you enable the Web Service Consumer transformation to create multiple concurrent connections to the web service, you can set the total memory consumption limit and the number of concurrent connection limits.
The following table describes the options:
Options | Description |
|---|
Enable concurrency | Creates multiple concurrent connections to a web service. |
Concurrency Connection Limit | The number of concurrent web service connections. Default is 20. |
Total Concurrency Memory Limit (in MB) | The total memory allocation limit for all the concurrent connections. Default is 100 MB. |
Web Service Error Handling
You can configure the Web Service Consumer transformation to pass SOAP faults and HTTP errors downstream in a mapping. You can increment the error count when a fault occurs. Configure web service error handling in the transformation advanced properties.
A web service returns either a response message or it returns a fault. A fault is an error. The web service can generate different faults based on the errors that occur.
The Web Service Consumer transformation can return the following types of faults:
- SOAP faults
- SOAP errors that the WSDL defines. Configure output error ports that return the faults in the web service response message. For a SOAP 1.1 binding, the Data Integration Service returns the fault message, fault code, fault string, and fault actor elements for the fault. For a SOAP 1.2 binding, the Data Integration Service returns the fault message, code, reason, node, and role elements for the fault.
- Generic SOAP faults
- The web service generates generic SOAP faults at run time. The fault elements are different for a SOAP 1.1 binding and a SOAP 1.2 binding. The WSDL does not define generic SOAP faults. Generic SOAP faults include authentication failures and SOAP request errors.
- HTTP errors
- The Developer tool adds the HTTP fault output port when you enable HTTP error handling in the transformation. The Data Integration Service returns HTTP errors from the web service in a single string port. An HTTP error includes an error code and a message.
If the SOAP response from the web service has XML data that is not valid, the Web Service Consumer transformation returns an error.
You can configure whether to treat SOAP faults as errors. When you enable Treat Fault as Error and a SOAP fault occurs, the Data Integration Service increments the error count for the mapping. The fault appears in the message log.
Message Compression
When you enable SOAP message compression, the Web Service Consumer transformation compresses web service request messages and receives compressed web service response messages.
The Web Service Consumer transformation encodes the SOAP request with GZip compression. The transformation accepts a response message encoded with the GZip or the deflate compression.
When the Data Integration Service receives the response from the web service, it checks the Content-Encoding HTTP header in the SOAP message and it decodes the message.
The default is no compression encoding. The web service does not compress the SOAP response.
The following table shows the headers in the request and response messages when compression is on or off:
Compression | Header |
|---|
On | Content-Encoding header: GZip Accept-Encoding header: GZip, deflate |
Off | Empty Content-Encoding header Empty Accept-Encoding header |
Sometimes a web service encodes a response message with a default compression. The Web Service Consumer transformation decodes the message if it is GZip or deflate encoded. The Web Service Consumer transformation logs a message to the mapping log if the web service encodes the response message unexpectedly.
Enable compression in the transformation advanced properties.
Concurrency
You can enable the Web Service Consumer transformation to create multiple concurrent connections to a web service so that it can send multiple web service requests in parallel.
For example, while querying bank information, you can configure the Web Service Consumer transformation for concurrency so that multiple rows are sent in parallel. If there are 20 input rows, you can send 20 requests concurrently for faster processing.
When you enable concurrency in the Web Service Consumer transformation, you can configure the total memory consumption limit.
When you enable concurrency in the Web Service Consumer transformation, you can configure the number of concurrent web service connections.
Rules and Guidelines for Concurrency
Use the following rules and guidelines while using concurrency:
- •Concurrency supports sorted input rows as multiple concurrent connections to a web service. Ordered output rows are not supported.
- •Use concurrency if the data set is more than 100 rows.
- •It is advisable not to increase the number of concurrent web service connections. The number of concurrent web service connections is linked to the number of sockets used by the operating system. Increasing the number of sockets is expensive.
- •Use systems that have multi-core processors with a minimum of 100 MB of RAM for optimal performance while using the concurrency feature.
- •Concurrency memory limit represents the memory consumed by concurrent work flows while invoking web services.
- •When you enable concurrency in the Web Service Consumer transformation, you can configure the memory consumption limit. Ensure that the memory consumption is not more than the physical RAM on the server.
Best Practices for Concurrency
For optimal performance while using concurrency, adhere to the following best practices:
- •Avoid changing the default values of the total concurrency memory limit and concurrency connection limit.
- •Avoid using concurrency for data sets of less than 100 rows.
- •Avoid pass-through ports in the mapping while using concurrency.