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.

Figure 1: Managed Connection Factory configuration

Attributes

Use Operation Details From Input

Enable this if the Webservice Operation details have to be fetched from the Input request. The properties required need to be provided in the input request. The sample input and output messages are shown in Scenario 2 in the Functional Demonstration section.

Use Connection Details From Input

If this property is enabled, then the "Endpoint Address" can be specified from the input also. Enable this if the connection details have to be fetched from the Input request. If a connection property is not present in the input request, then the values provided in the CPS will be considered.

HTTP Authentication

Figure 2: HTTP Authentication configuration dialog box

Use HTTP Authentication

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

Type

The type of HTTP Authentication can be selected for the drop-down.

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.

Figure 3: WSDL input dialog box

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

Figure 4: Sample connection test result showing the loaded WSDL

Proxy Settings

Parameters to be  to configure a proxy server if required. Refer to the Proxy Settings section in the Common Configurations page.

Connection Pool Params

Parameters to be used in connection pooling of the EIS system. Refer to the Connection Pool Params section in the 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.

Interaction Configurations

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

Properties are segregated under various sections as below:

General

Figure 5: The Webservice Operation Properties under the General section

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.

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

Figure 6: WSDL service configuration dialog box

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

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.

Validate Input

If this check box is selected, the service validates the input received.

Cleanup resources (excluding connection) after each document

This closes all the resources except for the connection used after every request. If the less processing time is more important the less memory usage, then it is recommended to disable this property and vice versa.

 

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.

Figure 9: JMS Transport Settings

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.

Figure 10: JNDI Settings

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.

Figure 11: Connection Configuration

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.

Figure 12: Destination Configuration

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

Figure 13: 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.

Security - Request

Figure 14: Security - Request Properties

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 15: Security - Response Properties

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

Figure 16: Reliable Messaging properties

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

Figure 17: Soap Compression properties

Compression Soap Request

Enables sending requests in the compressed form

Compression Soap Response

Enables sending responses in compression form

Attachments

Figure 18: Attachment properties

Enable MTOM

Enable this property to use Message Transmission Optimization Mechanism to send attachments.

Write Decrypted Attachments To File

To save decrypted attachments which are encrypted using Ws-Security.

Figure 19: Option to provide the Attachments directory path

Attachments Directory

Provide the path of the directory where decrypted attachments need to be saved.

Testing

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

Figure 20: Sample input

Figure 21: Sample output

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:

Figure 22: Input schema with Operation Properties

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.

Figure 23: Input schema with Connection Properties

Output Schema

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

Figure 24: Output Schema

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 25: 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 26: 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 27: 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 28: 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

Figure 29: Sample Input to demonstrate Scenario 1

Sample Output

Figure 30: Output for the sample input

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

Figure 31: Sample Input to demonstrate Scenario 2

Sample Output

Figure 32: Output for the sample input

Scenario 3

Using WS-Security

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

Figure 33: Sample WS-Security - Response configuration

Figure 34: Output in the Display window for the configuration in Figure 31

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