Web Service Connector

Overview

The Web Service Connector (WS Connector) connects to a web service provider and calls a particular web service operation.
The WS Connector reads the definition of the web service that will be accessed from a WSDL document.
Object and transport protocols supported so far are SOAP and HTTP.
The WS Connector operates in Lookup mode.

 

Using the Connector

The WS Connector operates in Lookup mode, which means that it will most likely be an intermediate Connector in an AssemblyLine.
It will 

  1.  Validate the work Entry Attributes against the given WSDL definition 
  2. Create the necessary SOAP request according to the WSDL definition
  3. Send this request to the web service provider 
  4. Receive the web service provider's SOAP response 
  5. Parse the SOAP response and create the conn Entry object
  6. Validate the conn Entry Attributes against the WSDL definition 

Following this simple scenario, you can extend your AssemblyLines, allowing them to access (a number of) web services at different stages in their work flow.

Any running WS EventHandler can be a web service provider for the WS Connector, but also non-metamerge WS can of course be used.

Note: The WS Connector logic does not need link criteria. The MI engine, however, requires that all Connectors operating in Lookup mode have not empty link criteria defined. If a Connector operating in Lookup mode does not have at least one link criterion, the MI engine throws a "No link criteria configured for connector" exception. That is why the WS Connector requires dummy link criteria to be defined. It doesn't matter what the dummy link criterion will contain - the WS Connector does not use it.

Attribute mapping & validation:

WSDL messages define the names and types of the input and output Attributes of a web service operation. The WS Connector retrieves the input Attributes defined in the WSDL messages from the work Entry. Please note that the Connector looks for Attributes in the work Entry whose names and types match those defined in the WSDL document. It is OK if there are extra Attributes in the work Entry. If, however, some of the WSDL input Attributes cannot be found in the work Entry the WS Connector throws an exception.

On return from the web service the WS Connector checks if the names, types and total number of Attributes in the conn Entry (i.e. the data returned by the web service) match the WSDL output Attributes. If not, an exception is thrown. So if the web service does not return data in accordance to the WSDL document, the WS Connector will fail.

Setting the required data types for the input parameters of a web service operation

The WS Connector gets the input parameters for a web service operation from the work Entry. The WS Connector requires that the types of the Attributes in the work Entry (which will be used as input parameters to the web service operation) match the types which the web service operation expects. You can check what data types a web service operation expects for its input parameters by using the "Query Schema" functionality as explained in the "Configuration steps" section below. That is why you need to set the Attributes' data types as required by the web service operation. You can do that by using the "Attribute map" of the previous Connector (the Connector that comes just before the WS Connector) in your AssemblyLine in the following way:

  1. Go to the "Attribute Map" section of your previous Connector in your AssemblyLine
  2. Select the Attribute whose data type you want to set
  3. Set the "Attribute mapping mode" to "Advanced"
  4. Let's suppose that you have an Attribute called "age" and you want to set its value type to java.lang.Integer (because "Query Schema" says that the web service operation needs the "age" input parameter to be a java.lang.Integer).
  5. Type the following in the script edit box:

    ret.value = new java.lang.Integer(integer_as_string);

    where integer_as_string is the string representation of the "age" Attribute value. If, for example, you have used the default ("Simple") Attribute mapping mode for the "age" Attribute until now (i.e. you don't need any additional processing in the Attribute map), then all you need to type is:

    ret.value = new java.lang.Integer(conn.getAttribute("age").getValue());
    In this way the "age" Attribute will be passed to the WS Connector as a java.lang.Integer.

 

Configuration

Parameter

Description
class com.architech.connector.WebServiceConnector
wsdlURL The URL of the WSDL document containing the web service definition.
wsOperation The name of the web service operation to invoke. The "Operations..." button on the WS Connector user interface form displays all the operations defined in the WSDL document. You have to choose the one that will be invoked by the Connector.
userComment Put your own comments here.
debug Specifies whether more detailed debug information will be written to the log file.

Configuration steps:
  1. Add a dummy link criterion (for example: "dummy-equals-dummy").
  2. Click the "Configure..." button to display the WS Connector configuration form.
  3. Type in the URL of the WSDL document which contains the definition of the web service you wish to connect to.
  4. Click the "Operations..." button. If an exception is thrown then you have either typed the WSDL URL incorrectly or the WSDL document does not follow strictly the WSDL specification and so the WS Connector cannot parse it (see the notes below). A dialog box will appear that shows all the operations defined in the WSDL document you specified. You have to choose the operation to invoke. If the operations list is empty, then the WSDL document does not follow strictly the WSDL specification and so the WS Connector cannot parse it (see the notes below).
  5. Click the "Attributes" tab of the Connector configuration form.
  6. Push the "Connect" button. If an error occurs then you have probably typed the WSDL URL incorrectly.
  7. Push the "Query Schema" button. The form will display all the input, output and input-output Attributes of the web service operation. The [in], [out] and [in, out] syntax prefixes mean that the corresponding Attribute is an input, output or input-output Attribute. An input Attribute is sent to the web service as a parameter of the web service operation. An output Attribute is received from the web service as a return parameter of the web service operation. An input-output Attribute is both sent to and received from the web service. That is why an input-output Attribute's input value is overwritten by this Attribute's output value.
  8. Close the WS Connector configuration form.
  9. Go to the "Attribute Map" section, click the "Select" button and select the Attributes you wish to map.

Note: There are public WSDL documents on the Internet, which do not follow strictly the WSDL specification. These incorrect WSDL documents will not be parsed by the WS Connector. Supplying the WS Connector with a URL of an incorrect WSDL document may result in (a) an exception being thrown or (b) an empty list of operations being shown after clicking the "Operations..." button.

Note: The WS Connector currently supports simple data types only - complex data types are not currently supported. That is why if you specify a web service operation whose input and/or output requires complex data types the WS Connector will fail.

 

Installation

  1. Unzip WebServices.zip with your Metamerge installdirectory as target.  This should give you a directory called webService in your metamerge/jars directory.
  2. Edit "miadmin.lax" (placed in the MI root folder) "lax.class.path" property to contain the path to the following libraries (if it does not already contain them): "client.jar", "dom4j.jar", "jaxm.jar" and "log4j.jar" (i.e. add ";jars/webService/client.jar;jars/webService/dom4j.jar;jars/webService/jaxm.jar;jars/webService/log4j.jar" at the end of the property value).
  3. Edit "miserver.lax" (placed in the MI root folder) "lax.class.path" property to contain the path to the following libraries (if it does not already contain them): "client.jar", "dom4j.jar", "jaxm.jar" and "log4j.jar" (i.e. add ";jars/webService/client.jar;jars/webService/dom4j.jar;jars/webService/jaxm.jar;jars/webService/log4j.jar" at the end of the property value).
Description of non-Metamerge libraries used