WebServiceConsumer4.0

This component invokes a web service (usually externally hosted on a third-party system) based on the configured WSDL. Unlike most static web service client options (like Axis wsdl2java), which generates Client Stub Code for 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).

Points to note

• If the web service is secured using basic authentication, then the details of the basic authentication should be provided in the Call Properties property during execution time.
• When using WS-Security, the Password Callback class should be the fully qualified name of the class.
• The order in which the WS-Security tokens are specified is important and should be the order in which they are specified at the web service.
• This component supports only WSDL files which are compliant with WS-I Basic Profile 1.0.
• To pass HTTP headers to the web service, the input message should contain properties with the header name prefixed with http_. Example http_Content-Type.
• To pass the attachment path to the WSInvoker component while passing attachments, the user need to add attribute "isUrl" manually to the attachment element and set it to true.
• Type can be specified by an attribute "type".

Configuration and Testing

Managed Connection Factory

The web service connection details can be configured in the Managed Connection Factory panel of CPS.

Attributes

Use Operation Details From Input

If the property "Use Operation Details From Input" is set to true, then the properties Use Connection Details From Input, WSDL, HTTP Basic Authentication, HTTP Username, HTTPPassword will be disabled in Managed Connection Factory Panel, and the properties WSDL Service, WSDL Port, End Point Address, WSDL Operation, Input Parameter, Output Parameter, SOAPBody Namespace will be disabled in Interaction Configurations panel. The required properties need to be provided in the input request. The sample input and output messages are shown in Scenario 2 of Functional Demonstration section.

Use Connection Details From Input

If this property is enabled, then the "Endpoint Address" can be specified from the input also.

HTTP Authentication

Use HTTP Authentication

This property specifies whether HTTP authentication is required or not to connect to web server.

Type

The type of HTTP Authentication can be selected for the drop-down. At present only BASIC authentication is supported.

Username

User Name to connect to the web server.

Password

Password to connect to the web server.

WSDL

This property specifies the WSDL location. WSDL can be specified in the form of URL or File or it can be selected from the UDDI registry.

Server connection can be tested from within the CPS by clicking the Test button in the connection properties panel.

Interaction Configurations

The service and operation can be chosen in the Interaction Configuration panel.

Properties are segregated under various sections as below:

• General
• Call and Addressing
• JMS Transport Settings
• Security - Request
• Security - Response
• Reliable Messaging
• Soap Compression

The properties present in each section is explained in the below sections.

General

WSDL Port

This property specifies the WSDL Port. Once the WSDL Operation is selected, this property will be automatically populated

WebService Operation

This property specifies the Web service operation. The WSDL operations specified in the WSDL provided in the Managed Connection Factory panel will be shown by clicking the eclipse. Once the operation gets selected, the properties WSDL Service, WSDL Port, Endpoint Address, Input parameter and Output parameter will be populated by the respective values.

WSDL Service Configuration

WSDL Service

This property specifies the WSDL Service name which has to be invoked. Once the WSDL Operation is selected, this property will be automatically populated

Endpoint Address

This property specifies the Endpoint Address for the Web service operation. Once the WSDL opration is selected, this properety will be automatically populated

Other Properties in General section:

• Input Parameter: This property specifies the input message name for the selected WSDL Operation. Once the WSDL Operation is selected, this property will be automatically populated
• Output Parameter: This property specifies the output message name for the selected WSDL Operation. Once the WSDL Operation is selected, this property will be automatically populated.

For the attributes Validate Input, Cleanup resources, Target Namespace, Monitoring configuration and Input/Output Elements to Encrypt/Decrypt, please refer the respective sections in the Common Configurations page.

JMS Transport Settings

SOAP Over JMS

If WSDL has JMS properties at URI specified in the endpoint element's address attribute or properties set on endpoint/service/binding, then Enable JMS Transport is automatically set after Webservice operation is selected and some fields in JNDI Settings, Connection configuration, Destination configuration are loaded based on properties set in WSDL. If pre-loaded settings are manipulated, then modified details will be used for setting up connection. If named configurations are already in use for JNDI or configurations of Destination, Connection and Producer then on selecting the webservice operation settings will not be pre-loaded, in this case, details should be manually entered.

Enable JMS Transport

This property is automatically set if properties specific to SOAP over JMS bindings are specified at any of the port, service, binding levels or through JMS endpoint.

The types of configurations to be specified, which appears on enabling JMS Transport are:

• JNDI Configuration
• Connection Configuration
• Destination Configuration
• Producer Configuration

Each one of the above is explained in the sections below.

JNDI Configuration

Click the ellipsis button to configure the properties.

Initial Context Factory

Automatically loads value from property jndiInitialContextFactory in the WSDL on selecting the webservice operation. If this field is modified, then updated InitialContextFactory is used to create JMS Connection

JNDI username

Enter JNDI username

JNDI password

Enter JNDI password

Initial Context Properties

Context parameters in WSDL are loaded here. If parameters are specified at the endpointURI level, then all properties with 'jndi-' as a prefix in their names are loaded here.

Connection Configuration

Click the ellipsis button to configure the properties.

Connection Configuration:

Server URL

Automatically loads value from property jnduURL in the wsdl on selecting the webservice operation

CF lookup name

Automatically loads value from property jndiInitialContextFactory in the wsdl on selecting the webservice operation

JMS username

Enter JMS username.

JMS password

Enter JMS password.

Destination Configuration

Click the ellipsis button to configure the properties.

Destination Name

Automatically loads value from WSDL. In case of modification, a request is sent to  the updated destination.The response is listened on a temporary destination which will be deleted after the shutdown of the component.

Destination Type

If jmsVariant is 'jndi', a request is sent irrespective of destination type provided here. If jmsVariant is either 'Topic' or 'Queue', then set destination type used to create JMS Connection.

Producer Configuration

Delivery Mode

• PERSISTENT
  Instructs the JMS provider to take extra care to ensure that a message is not lost in transit in case of a JMS provider failure. A message sent with this delivery mode is logged to stable storage when it is sent.
• NON-PERSISTENT
  The NON_PERSISTENT delivery mode does not require the JMS provider to store the message or otherwise guarantee that it is not lost if the provider fails.

Time to Live

The time to live (in milliseconds) of the message to be sent to the destination. After the timeout, the message will be discarded.

Priority

The priority of the message to be sent to the destination.

Call and Addressing

SOAPBody Namespace

This property specifies the SOAP Body namespace. Once the WSDL Operation is selected, this property gets filled automatically.

Call Properties

Advanced properties which can be used to optimize and change the behavior SOAP Invocation Call. The description for the axis call properties can be found at http://ws.apache.org/axis/java/apiDocs/org/apache/axis/client/Call.html

Enable WS-Addressing

If this property is selected, it enables the support for WS-Addressing headers. The input and output schema contain WS-Addressing headers.

Authentication Type

This Property defines the Authentication Type used while invoking a Webservice. Supports NTLM and Basic.

This Property appears only when HTTP Authentication is enabled in Managed Connection Factory Panel.

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.

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.file=C:\\Desktop\\fiorano.jks
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=fiorano
org.apache.ws.security.crypto.merlin.keystore.private.password=fiorano
org.apache.ws.security.crypto.merlin.keystore.alias=fiorano

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.

org.apache.ws.security.saml.issuerClass=org.apache.ws.security.saml.SAMLIssuerImpl
org.apache.ws.security.saml.issuer.cryptoProp.file=crypto_wsc.properties
org.apache.ws.security.saml.issuer.key.name=fiorano
org.apache.ws.security.saml.issuer.key.password=fioranopassorg.apache.ws.security.saml.issuer=fiorano
org.apache.ws.security.saml.subjectNameId.name=uid=mule,ou=people,ou=samldemo,o=example.com
org.apache.ws.security.saml.subjectNameId.qualifier=www.example.com
org.apache.ws.security.saml.authenticationMethod=password#
org.apache.ws.security.saml.confirmationMethod=senderVouches
org.apache.ws.security.saml.confirmationMethod=keyHolder

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.

Reliable Messaging

Client port of WS-ReliableMessaging

The port on which the client listener of WS-RM listens.

Enable WS-ReliableMessaging

Enables the support of WS-ReliableMessaging Headers

Soap Compression

Compression Soap Request

Enables sending requests in the compressed form

Compression Soap Response

Enables sending responses in compression form

Testing

The configuration can be tested by clicking the Test button in the Interaction Properties panel.

Scheduler Configuration

Please refer Scheduler Configurations section in Common Configurations page.

Transport Configurations

Transport Configurations panel is used to configure messaging properties when the component is configured in Scheduling mode, that is, when you select the Enable Scheduling checkbox in the Scheduler Configuration panel,.

Please refer Transport Configurations section in Common Configurations page.

Error Handling

Please refer Error Handling section in Common Configurations page.

Input Schema

The input schema is auto-generated based on the configuration provided. For the configuration shown above, the schema would be
When the property "Use Operation Details From Input" is set to true, we should provide the WSDL service, operation details in the input. 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 Axis If this property set to true, the input schema would be as below:

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

Output Schema

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

Accessing Share Point Web Services

Sample configuration to access Share Point Web Services using Web Service Consumer is mentioned below:

1. Provide WSDL URL as http://www.webservicex.net/CurrencyConvertor.asmx?WSDL (sample WSDL used is present at this URL).
   
   

   

   
   Figure 23: Providing WSDL URL
    
2. To access SharePoint webservices, provide authentication details of the Share Point Webserver as follows. In the MCF Panel, enable HTTP Authentication and provide Username and Password.
   1. Sample Username: demouser
   2. Sample Password: Templates
      
      

      

      
      Figure 24: web service connection configuration to access share point web services
       
3. In the Interaction Configurations panel, click the ellipsis button against "WebService Operation" property to select the WebService operation as shown below.
   
   

   

   
   Figure 25: Selecting WedService Operation
   
   
4. After selecting the operation, click on ellipsis button against the Call Properties property to launch the Advanced Properties dialog box to add the username and password properties.
   1. To add username property, click Add button, select "javax.xml.rpc.security.auth.username" and provide value as demouser
   2. To add password, click Add button, select "javax.xml.rpc.security.auth.password" and provide value as Templates. The properties provided here will be set on the SOAP Invocation Call.
      
      

      

      
      Figure 26: Providing WebService credentials
      
      
5. To test the configuration, click Test button and then click the Execute button in the editor dialog box.

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 in Chapter 2 and use the Feeder and the Display component to send sample input and check the response respectively.

Sample Input

Sample Output

Scenario 2

Invoking a web service operation from the following URL, by enabling the Use Operation Details From Input property.

http://www.webservicex.net/CurrencyConvertor.asmx?WSDL

Configure the Web Service Consumer component and use feeder and display component to send sample input and check the response respectively.

Sample Input

Sample Output

Scenario 3

Using WS-Security

Configure the Web Service Consumer component as described in Security - Request and Response sections.

Use Case Scenario

In a Salesforce Integration scenario, Salesforce updates are performed based on the details in the database.
The event process demonstrating this scenario is bundled with the installer.
Documentation of the scenario and instructions to run the flow can be found in the Help tab of flow when open in Studio.

Useful Tips

• If the web service is secured using basic authentication, then the details of the basic authentication should be provided in the Call Properties property during execution time.
• When using WS-Security, the Password Callback class should be the fully qualified name of the class.
• The orders in which the WS-Security tokens are specified are important and should be the order in which they are specified at the web service.
• This component supports only WSDL files which are compliant with WS-I Basic Profile 1.0.
• To pass HTTP headers to the web service, the input message should contain properties with the header name prefixed with http_. Example http_Content-Type.
• To pass the attachment path to the WSInvoker component while passing attachments, the user need to add attribute "isUrl" manually to the attachment element and set it to true. Type can be specified by an attribute "type".

To understand the service better, refer the examples: Web Service Attachments and Web Service Security which demonstrate WebServiceConsumer 4.0 service features.