How-To Consume a Web Service in a Server Method

Implementation Overview

  1. Create a Proxy DLL that represents the connection to the remote server
  2. Install the Proxy into the Innovator Server code tree
  3. Declare the Proxy’s name space within Innovator Method
  4. Create an instance of the Proxy inside a specific server method,  and transfer data

For the sake of the example let’s assume:

3rd party software is named Saperion

Saperion is running on a server named  “bb1s4002”

URL to the web service is http://bb1s4002/SaperionConnectorService/SaperionConnector.asmx

Web Service Proxy

A web service proxy is a basic object used in the invocation of a web service.
Innovator interfaces to the web service via this proxy. The proxy takes the form of a xxx.dll file. It provides all the connection information to the web service. The proxy Saperion.dll resides on the Innovator server.

A proxy is generated from a web service using the wsdl.exe utility.
Compiling the Saperion.dll is a two step process.
First step is generating a source code file.
Second step is compiling the source code.

Building the Proxy Source Code File

Assuming  C# and Visual Studio 2003 and .NET 1.1.    Adjust your paths accordingly

Add the following to the system default PATH:
 C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin

In a DOS (CMD) Window, run the following command:
WSDL.exe /out:saperion.cs /n:saperionWS /l:CS
http://bb1s4002/SaperionConnectorService/SaperionConnector.asmx

The value Saperion.cs is the name of the source code file that will be created.
The value SaperionWS is the namespace naming convention we will use in the Methods

Note: See Appendix 1 for a complete list of WSDL options

Compiling the Proxy Source Code

Assuming .NET  2.0 and Visual Studio 2003

Add the following to your PATH:
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

In a DOS (CMD) Window, run the following command:
csc /t:library /out:saperion.dll saperion.cs /reference:System.dll,System.Web.dll,System.Web.Services.dll,System.XML.dll /optimize

The value Saperion.cs is the source code file created in the first step
The value Saperion.dll is the compiled proxy that will be created in this step.

Updating the Proxy

IMPORTANT: From time to time, the web service’s methods may be updated.  It is necessary to recompile the proxy when a new method is added, or a method’s parameters have changed.

RECOMMENDATION: Keep the batch file used to create DLL proxies in the same location as the dll, that way it could be run as needed to update the dll.

Registering the Proxy in Innovator

Innovator must be made aware of the Saperion.dll proxy.
This is a 2 step process:
a) First, the Saperion.dll must be copied into innovator file tree
b) Second, the file method-config.xml is modified to include references to the web service namespace and the Saperion.dll file.

Step 1
Place the Saperion.dll file into the /innovator/server/bin directory as seen in Figure 1.

consume-web-service-server-method
Figure 1

Step 2
Make 2 new references in the method-config.xml file, which is located in /innovator/server.

  1. A reference to the web services class (system.web.services.dll)
  2. A reference to the Saperion proxy (Saperion.dll).
  System.dll
  system.xml.dll
  system.web.dll
  system.web.services.dll
  system.data.dll
  $(binpath)/IOM.dll
  $(binpath)/saperion.dll
  $(binpath)/InnovatorCore.dll

The proxy is now ready for use in Innovator server side methods. A typical declaration of the proxy is:
Dim myProxy As New saperionWS.SaperionConnector()

Programming the Innovator Method

Example of calling a Saperion web service method(in VB.net)

Dim ResultItem1 = Me.newItem()
Dim ResultItem2 = Me.newItem()

Dim myProxy As New saperionWS.SaperionConnector()

ResultItem1.dom.loadXML(   myProxy.SearchAndRetrieveDocuments( Me.getProperty(‘query_parameter’)    )
ResultItem2.loadAML( ResultItem1.applyStylesheet("../client/customer/styles/Saperion.xsl","URL")  )

Return ResultItem2
This example assumes the Me object passed into the server method has some property named query_parameter that we need to pass to the web service as a key,  in order to get back the data that we want from the Saperion system.

Note that SaperionConnector() is a method provided by the 2rd party web service.   If you do not have documentation for this system,   I recommend using Visual Studio to inspect the web service to learn the available methods and their required arguments.

The Saperion system returns XML to web service requests,  and here we are loading that XML directly into the DOM of an Innovator item. Since Saperion does not have the same Tag set as AML, there is a XSLT step in the process to make Innovator Items out of the result xml.


Testing the web service in Visual Studio

Example of calling a Saperion web service method(in VB.net)

  1. Open a new VB project in VS (Windows application or ASPX)
  2. Add reference to the new saperion.dll
  3. Place a Gridview item on the form or aspx page.
  4. Add the following Code:
Dim myProxy As New saperionWS.SaperionConnector()
Dim ds As System.Data.DataSet
ds = myProxy. SearchAndRetrieveDocuments(‘query_parameter’ )
Me.GridView1.DataSource = ds
Me.GridView1.DataBind()

Appendix 1 – WSDL

wsdl.exe –
Utility to generate code for xml web service clients and xml web services
using ASP.NET from WSDL contract files, XSD schemas and .discomap discovery
documents.  This tool can be used in conjunction with disco.exe.

wsdl.exe <options> <url or path> <url or path> …

– OPTIONS –

<url or path> –
A url or path to a WSDL contract, an XSD schema or .discomap document.

/nologo
Suppresses the banner.

/language:<language>
The language to use for the generated proxy class.  Choose from ‘CS’,
‘VB’, ‘JS’, ‘VJS’ or provide a fully-qualified name for a class
implementing System.CodeDom.Compiler.CodeDomProvider.  The default is ‘CS’
(CSharp).  Short form is ‘/l:’.

/server
Generate an abstract class for an xml web service implementation using
ASP.NET based on the contracts. The default is to generate client proxy
classes.

/namespace:<namespace>
The namespace for the generated proxy or template.  The default namespace
is the global namespace. Short form is ‘/n:’.

/out:<fileName>
The filename for the generated proxy code. The default name is derived from
the service name. Short form is ‘/o:’.

/protocol:<protocol>
Override the default protocol to implement.  Choose from ‘SOAP’, ‘SOAP12’,
‘HttpGet’, ‘HttpPost’, or custom protocol as specified in the configuration
file.

/username:<username>
/password:<password>
/domain:<domain>
The credentials to use when the connecting to a server that
requires authentication. Short forms are ‘/u:’, ‘/p:’ and ‘/d:’.

/proxy:<url>
The url of the proxy server to use for http requests.
The default is to use the system proxy setting.

/proxyusername:<username>
/proxypassword:<password>
/proxydomain:<domain>
The credentials to use when the connecting to a proxy server that
requires authentication. Short forms are ‘/pu:’, ‘/pp:’ and ‘/pd:’.

/appsettingurlkey:<key>
The configuration key to use in the code generation to read the default
value for the Url property. The default is to not read from the config
file. Short form is ‘/urlkey:’.

/appsettingbaseurl:<baseurl>
The base url to use when calculating the url fragment. The
appsettingurlkey option must also be specified. The url fragment is
the result of calculating the relative url from the appsettingbaseurl
to the url in the WSDL document. Short form is ‘/baseurl:’.

/parsableerrors
Print errors in a format similar to those reported by compilers.

Leave a Reply