This component invokes a web service (usually externally hosted on a third-party system) based on the configured WSDL. This component uses Axis2 API to invoke web services.

Unlike most static web service client options (like Axis wsdl2java) which generate client stub code for an invocation of a given WSDL, this component employs a dynamic invocation mechanism to ensure that no code needs be written or deployed for invoking a component.

The incoming request parameters are automatically wrapped in a SOAP request packet (handling different types of SOAP headers for handling web service security, transactions etc.) and sent to underlying transport (usually the response is sent back to the client.

Configuration and Testing

Properties can be configured in the Configuration Property Sheet (CPS) of the component.

Component Configuration

Figure 1: Component Configuration panel in CPS

General

Use Operation Details from Input

If this property is enabled, the component will use the webservice operation details from the input request. If this property is set to true the properties Use Connection Details From Input, Load WSDL From, WSDL URL, WSDL File, WebService Operation, WSDL Service, WSDL Port, Endpoint Address, Action, SOAPBody Namespace, Input parameter, Output Parameter will be disabled.

Use Connection Details from Input

If this property is set to true, then the property "End Point Address" can be provided dynamically in the input request. If this property is selected and the "End Point Address" is not given in the input request, then the value given in this panel for that property will be used.

Pre Processing XSL Configuration

Pre Processing XSL configuration can be used to transform request message before processing it. Click the small button against the property to configure the properties.

Post Processing XSL Configuration

Post Processing XSL configuration can be used to transform response message before sending it to the output port.

Process Message Based on Property

The property helps components to skip certain messages from processing.

Error Handling Configuration

Click on the ellipsis button against the Error handling configuration property to configure Error Handling properties.

Figure 2: Error Handling Configuration

The actions to be taken when a particular error occurs can be configured here.

Please refer Error Handling section Common Configurations page for details.

Load WSDL From

Source for WSDL can be configured here. It can be a File or a valid WSDL URL.

WSDL File

When File is selected, the WSDL file location can be configured.

Figure 3: Specifying WSDL File

WSDL URL

When URL is selected, the WSDL URL can be configured.

Figure 4: Specifying the WSDL URL

Use WSDL at Configuration

When this expert property is disabled, the component will not try to parse WSDL to generate schema on ports or to select operations. If it is disabled, the Web service Operation property (explained below) will be hidden in the CPS.

WebService Operation

The web service operation to be invoked can be configured here.
Click the ellipsis button against this property to select the operation from the available list of operations for the respective WSDL that is loaded.

Figure 5: WSDL operations

WSDL Service Configuration

The Operation can also be typed manually in offline mode but all the other properties have to be populated manually.

Figure 6: WSDL Service Configuration

WSDLService

The service element defines the ports supported by the Web service. For each of the supported protocols, there is one port element. The service element is a collection of ports.

Endpoint Address

Provides a unique network address that a client uses to communicate with a service endpoint.

Action

The SOAP Action field can be used to indicate the intent of the SOAP HTTP request. The value is a URI identifying the intent.

WSDL Port

Name of a single endpoint defined as a combination of a binding and a network address; it represents the endpoint of the web service.

Socket Timeout

Sets the socket timeout used when executing a request with the underlying HTTP client that is being used. WebsServiceConsumer uses Apache HttpClient as the default HTTP client implementation and therefore the property will set "http.socket.timeout" property of Apache HttpClient. A timeout value of zero is interpreted as an infinite timeout.

Connection Timeout

The timeout until a connection is established. A value of zero means the timeout is not used.

SOAP Body Namespace

Namespace attribute of soap:body element. This is usually specified in case of RPC encoded web services.

Use WSDL At Runtime

WSDL will be parsed during runtime. This property will be available only if the Use WSDL at configuration is disabled.

Input Parameter

Input parameter name of the selected Operation. This is used to identify correct operation in the case of overloaded operations in the WSDL.

Output Parameter

Output parameter name of the selected Operation. This is used to identify correct operation in the case of overloaded operations in the WSDL.

HTTP Header protocol

Select the HTTP Protocol header to use. Chunked transfer will be used in HTTP/1.1 protocol. If there is a "Transport error: 501 Error: Not Implemented" with HTTP/1.1, HTTP/1.0 should be used.

Security - Request

Figure 7: Properties pertaining to Security - Request 

UsernameToken WS-Security (Request)

If the web service performs UsernameToken identification for the request, then this property should be enabled. Username and password values are added to the message headers.

Order of UsernameToken (Request)

Determines the order of the UsernameToken security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

User

This property is used as the username for the UsernameToken security function. It is also used as the alias name in the keystore to get user's certificate or private key to perform signing for the Signature security function in case of "Signature User" is null and "Signature WS-Security (Request)" is set to yes. It is also used as the fallback for the encryption security function in case of "Encryption User" is null and "Encryption WS-Security (Request)" is set to yes.

Password Callback class (Request)

This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement javax.security.auth.callback.CallbackHandler class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class should be added as a resource to the component. Password callback class is not required if the Password Type is selected as PasswordNone

Password type

The Password type specifies how the client sends the password value to the server.

• PasswordText: Password is sent in raw text format within the security header of the soap request.
• PasswordDigest: Password is sent in digest format within the security header of the soap request.
• PasswordNone: No password will be sent in the security header. This option is useful when the user wants to specify the username without any password.

Nonce Security element

Specifies whether to use nonce element in the security header or not. When UsernameToken security function is used, then nonce security element can be employed to prevent message replay attacks. A nonce is a random value that the client creates to include in each UsernameToken that it sends. Although using a nonce is an effective countermeasure against replay attacks, it requires the server to maintain a cache of used nonces, consuming server resources.

Created Security element

Specifies whether to use Created element in the security header or not. This element denotes the time of creation of a nonce. Combining a nonce with a creation timestamp has the advantage of allowing a server to limit the cache of nonces to a "freshness" time period, establishing an upper bound on resource requirements.

Timestamp WS-Security (Request)

If this property is set, a timestamp will be added as security header in the soap request. In this case, the message is valid for 5 minutes or 300 seconds after the creation of the message.

Precision in Milliseconds (Request)

If this is set, timestamps will have precision in milliseconds. Otherwise, it will be seconds.

Timestamp format (Request)

Timestamp format in WS-Security request header for Timestamp.

Time To Live

The time difference between creation and expiry time in the WSS Timestamp. This should be specified in seconds.

Order of Timestamp (Request)

Specifies the order of the Timestamp security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Encryption WS-Security (Request)

This property can be set to perform encryption on the entire soap message or some parts of the soap message.

Order of Encrypt (Request)

Specifies the order of the Encrypt security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Encryption User

Username for the encryption function. The encryption function uses the public key of this user's certificate. If this parameter is not set, then the encryption function falls back to the "User" parameter to get the certificate. The encrypt function will not authenticate the user. So there is no need to set any password call back class for encrypt.

Encryption Properties filename (Request)

The name of the crypto property file to use for SOAP Encryption. If this parameter is not specified and if both "Signature Properties filename (Request)" and "Signature WS-Security (Request)" are set, then the encryption function uses a signature property file. Otherwise, the handler throws an AxisFault.

Description for each property in the sample above:

• org.apache.ws.security.crypto.provider: Implementation class for the security provider. Fiorano internally uses bouncycastle, to use the same this property must be set to "org.apache.ws.security.components.crypto.Merlin". To use other providers, the provider jar must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\lib' and the fully qualified name of the appropriate provider class has to be set for this property.
• org.apache.ws.security.crypto.merlin.file: The path to the keystore file.
• org.apache.ws.security.crypto.merlin.keystore.type: The keystore type, for example, JKS for the Java key store. Other keystore types, such as pkcs12 are also possible but depend on the actual Crypto implementation.
• org.apache.ws.security.crypto.merlin.keystore.password: The password to read the keystore. If this property is not set, then the pwcallbackproperty must be defined.
• org.apache.ws.security.crypto.merlin.keystore.alias: The alias name under which the private key/certificate stored in keystore
• org.apache.ws.security.crypto.merlin.alias.password: Password for private key/certificate inside keystore stored under given alias (not used for encryption)

Encryption Parts

The parameter specifies which parts of the request shall be encrypted. The value of this parameter is a list of semi-colon separated element names that identify the elements to encrypt. An encryption mode specifier and a namespace identification, each inside a pair of curly brackets, may preceed each element name. The encryption mode specifier is either {Content} or {Element}. 'Element' encryption mode will encrypt the entire element including start and end tags. 'Content' encrypt mode will encrypt only the content of the specified element. The default encryption mode is 'Content'. For example, if we set "{Element}{http://example.org/paymentv2\}CreditCard;{}{}UserName" list to this property, then the first entry of the list identifies the element CreditCard in the namespace http://example.org/paymentv2, and will encrypt the entire element. In the second entry, the encryption modifier and the namespace identifier are omitted. In this case, the encryption mode defaults to Content and the namespace is set to the SOAP namespace. The element name, the namespace identifier, and the encryption modifier are case sensitive. To specify an element without a namespace use the string Null as the namespace name (this is a case-sensitive string) If no list is specified, the handler encrypts the SOAP Body in Content mode by default.

Encryption Key Identifier

Select the key identifier type to use.

• DirectReference: The security function takes the signing certificate, converts it to a BinarySecurityToken, puts it in the security header. Thus the whole signing certificate is transferred.
• X509KeyIdentifier: The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data. The certificate is converted into a KeyIdentfier token and sent to the server. Thus the complete certificate data is transferred.
• SKIKeyIdentifier: The security function uses SKIKeyIdentifier.
• IssuerSerial: The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data. The issuer name and the serial number of the signing certificate are sent to the server.

Signature WS-Security (Request)

If this security function is selected the digest of the message is created and encrypted before sending. The property "User" must be specified to get the private key/certificate of the respective user from the keystore for signing.

Order of Signature (Request)

Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Signature User

This name is used as the alias name in the keystore to get user's certificate and private key to perform signing. If this parameter is not set, then the signature function falls back to the "User" parameter to get the certificate. Password for the user to get certificates from the keystore should be provided in the Password Callback class.

Signature Properties filename (Request)

The name of the crypto property file to use for SOAP Signature. Please see the description of "Encryption Properties filename" for the details of the properties file.

Signature Parts

The parameter specifies which parts of the request shall be signed. Please see the description of "Encryption Parts" for the syntax.

Signature Algorithm (Request)

The parameter specifies signature algorithm to be used. If an algorithm is not specified then the algorithm "http://www.w3.org/2000/09/xmldsig#rsa-sha1" will be used by default.

Canonicalization Method

The parameter specifies the canonicalization method to be used in the process of signing the request. If no method is specified then the method "http://www.w3.org/2001/10/xml-exc-c14n#" will be used by default.

Signature Key Identifier

Select the key identifier type to use. Please see the description of "Encryption Key Identifier" for the descriptions of key identifiers.

SAML WS-Security (Request)

Select this property to perform SAML Token Identification.

Order of SAML (Request)

Specifies the order of the SAML security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Signed SAML (Request)

Specifies whether to use signed SAML or unsigned SAML. If Signed SAML is used, then the client performs two actions inserting a SAML Token (unsigned) and an associated Signature. So define both the actions SAML Unsigned and Signature at the server to resolve these security headers. If Signed SAML is used, the signature properties should be specified without selecting the property "Signature WS-Security (Request)".

SAML Properties filename (Request)

The name of the SAML properties file. This file should be added as a resource to the component.

Security - Response

Figure 8: Properties pertaining to Security - Response

Ignore Order

If this is set, Order of Security actions will be ignored for the incoming response.

UsernameToken WS-Security (response)

Determines whether the response from the server contains Username token headers or not.

Order of UsernameToken (response)

Determines the order of the Username Token security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Password Callback class (response)

This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement javax.security.auth.callback.CallbackHandler class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class must be added as a resource to the component.

Is Password Required

This property should set to false if the Username security token is used without a password. No need to provide Password callback class if this property is set to no.

Timestamp WS-Security (response)

Specifies whether the soap response contains timestamp headers or not.

Precision in Milliseconds (response)

If this is set, timestamps will have precision in milliseconds. Otherwise, it will be seconds.

Timestamp Format (Response)

Timestamp format in WS-Security response header for Timestamp

Order of Timestamp (response)

Specifies the order of the Timestamp security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Encryption WS-Security (response)

Specifies whether the soap response or some parts of the soap response are encrypted or not. If this property is set then the client validates the user, so password callback class should be specified.

Order of Encrypt (response)

Specifies the order of the encrypted security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Encryption Properties filename (response)

The name of the crypto property file to use for decryption of the soap response. If this parameter is not specified and if both the "Signature Properties filename (response)" and "Signature WS-Security (response)"is set to yes, then the decryption function uses a signature property file. Otherwise, the handler throws an AxisFault. Please see the description of "Encryption Properties filename (Request)" for the details of the crypto properties file.

Signature WS-Security (response)

Specifies whether the soap response or some parts of the soap response are signed or not.

Order of Signature (response)

Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Signature Properties filename (response)

The name of the crypto property file to use for SOAP Signature. Please see the description of "Encryption Properties filename (Request)" for the details of the properties file.

SAML WS-Security (response)

Specifies whether the soap response uses SAML Token Identification or not.

Order of SAML (response)

Specifies the order of the SAML security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Store imported schemas

Save schemas imported in WSDL to schema repository.

Target Namespace

The Target Namespace used while generating the input and output schema.

Refer to the Target Namespace section under the Common Configurations page.

Input Elements to Encrypt/Decrypt

Select elements to encrypt/decrypt in the Input Message.

Refer to the Encrypt Decrypt Configuration section in the Common Configurations page for details.

Output Elements to Encrypt/Dencrypt

Select elements to encrypt/decrypt in the Output Message.

Refer to the Encrypt Decrypt Configuration section in the Common Configurations page for details.

Advanced

Figure 9: Advanced property parameters

HTTP Authentication

Click the ellipsis button to configure authentication details.

Use HTTP Authentication

This enables authentication, which provides properties to choose the type of Authentication to be used to connect to the web server and properties to provide the credentials required.

There are three Authentication types, which are Basic, Digest, and NTLM.

Authentication Type - Basic

When Authentication Type is 'Basic', the following fields have to be specified.

Figure 10: Basic Authentication Type

• Username: User Name to connect to the web server.
• Password: Password for the username mentioned.

Authentication Type - Digest

When Authentication Type is 'Digest', the following fields have to be specified.

Figure 11: Digest Authentication Type

• Username: User Name to connect to the webserver.
• Password: Password for the username mentioned.
• Hostname: Host that needed to be authenticated with.
• Port: Port of the host that needed to be authenticated with.
• Domain: Domain name needed by NT Credentials for NT Domain.

Authentication Type - NTLM

When Authentication Type is 'NTLM', the following fields have to be populated.

Figure 12: NTLM Authentication Type

• Username: User Name to connect to the web server.
• Password: Password for the username mentioned.
• Hostname: Host that needed to be authenticated with.
• Port: Port of the host that needed to be authenticated with.
• Realm: Realm for authentication scope.

Proxy Settings

For details regarding Proxy Settings, please refer to the Proxy Settings section in Common Configurations page.

SSL Security

Configure these SSL properties if SSL support is required.  Refer to the SSL Security section in the Common Configurations page.

JMS Transport Settings

Please refer the corresponding section in the Common Configurations page for details; descriptions are the same.

Input Schema

The input schema is auto-generated based on the configuration provided. Below is a sample Schema.

Figure 13: Input Schema

When the property "Use Connection Details From Input" is chosen, an additional element 'ConnectionProperties' is added to the input schema, as shown in the figure. We can provide End Point Address under this element. If JMS Transport is enabled, properties pertaining to JMS Transport MUST be filled. If JMS Transport is enabled, then endpoint address can be left empty, as component takes details from filled properties, but if URL is specified, they should follow guidelines laid by Apache Axis2

Figure 14: Input schema with ConnectionProperties

When the property "Use Operation Details From Input" is chosen, the WSDL operation details are added to the input schema, as shown in the figure. If JMS Transport is enabled, properties pertaining to JMS Transport MUST be filled. If JMS Transport is enabled, then endpoint address can be left empty, as component takes details from filled properties,but if URL is specified, they should follow guidelines laid by Apache Axis2.

Figure 15: Input schema with Operation Details

Output Schema

The output schema is auto-generated based on the configuration provided. For the Input schema shown above, the schema would be as below.

Figure 16: Output Schema

Functional demonstration

Scenario 1

Invoking a web service operation using a WSDL from the following URL
http://www.webservicex.net/CurrencyConvertor.asmx?WSDL

Configure the Web Service Consumer component as described and use Feeder and Display components to send sample input and check the response respectively.

Figure 17: Feeder and Display components connected to demonstrate Scenario 1

Sample Input

Figure 18: Sample input provided using feeder

Sample Output

Figure 19: Output displayed in Display Window

Scenario 2

Invoking a web service operation using a WSDL from the following URL, by setting the property "Use Operation Details From Input" to true
http://www.webservicex.net/CurrencyConvertor.asmx?WSDL

Configure the Web Service Consumer component as described and use Feeder and Display components to send sample input and check the response respectively.

Figure 20: Feeder and Display components connected to demonstrate Scenario 2

Sample Input

Figure 21: Sample input provided using feeder

Sample Output

Figure 22: Output displayed in Display Window