Getting Started with Web Services on the webMethods Integration Platform

January 2002

Copyright 2002 webMethods, Inc. All rights reserved. Trademarks The webMethods logo is a registered trademark of webMethods Inc. Other product names used herein may be trademarks or registered trademarks of webMethods or other companies. Statement of Conditions WEBMETHODS SOFTWARE CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT LIMITED TO THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL WEBMETHODS BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OR DATA, INTERRUPTION OF BUSINESS, OR FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND, EVEN IF WEBMETHODS HAS BEEN ADVISED OF THE POSSIBLITY OF SUCH DAMAGES ARISING FROM ANY DEFECT OR ERROR IN THIS PUBLICATION OR IN THE WEBMETHODS SOFTWARE. webMethods, Inc. may revise this publication from time to time without notice. Some states or jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. All rights reserved. No part of this work covered by copyright herein may be reproduced in any form or by any means - graphic, electronic or mechanicalincluding photocopying, recording, taping, or storage in an information retrieval system, without prior written permission of the copyright owner. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the U.S. government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 (October 1988) and FAR 52.227-19 (June 1987).

TABLE OF CONTENTS
INTRODUCTION.................................................................................................................4 PREREQUSITES ..................................................................................................................4 INSTALLING WEBMETHODS INTEGRATION SERVER AND DEVELOPER VERSION 4.6..................4 IMPLEMENTING YOUR FIRST WEB SERVICE IN WEBMETHODS INTEGRATION SERVER..............................................................................................................................5 CREATE A SERVICE IN THE INTEGRATION SERVER ................................................................5 GENERATE THE WSDL DOCUMENT ....................................................................................5 PUBLISH THE WSDL DOCUMENT ........................................................................................6 INVOKING EXTERNAL WEB SERVICES FROM WEBMETHODS INTEGRATION SERVER..............................................................................................................................7 LOCATE AND DOWNLOAD THE WSDL DOCUMENT ................................................................7 CREATE A W EB SERVICE CONNECTOR ................................................................................7 INVOKING THE REMOTE W EB SERVICE ................................................................................8 ADVANCED WEB SERVICES TOPICS .............................................................................9 W EB SERVICES STANDARDS ...............................................................................................9 SOAP ...........................................................................................................................9 WSDL .........................................................................................................................10 UDDI...........................................................................................................................11 SOAP RPC VS. SOAP DOCUMENT .................................................................................12 PUBLISHING MULTIPLE SERVICES IN A SINGLE WSDL DOCUMENT......................................12 W EB SERVICE CLIENT GENERATION AND RUNTIME BINDING ...............................................13 ACCESSING W EB SERVICES FROM OTHER WEBMETHODS PLATFORM COMPONENTS ...........13 SETTING SERVICE INPUT AND OUTPUT FIELD CONSTRAINTS WHEN USING SOAP RPC .......14 W EB SERVICES SECURITY ................................................................................................14 ABOUT WEBMETHODS, INC. .........................................................................................16

2001 webMethods, Inc. All rights reserved.

Page 3

INTRODUCTION
WebMethods Inc., the leading provider of integration software, offers the industrys most comprehensive solution for linking business processes, enterprise and legacy systems, databases, and workflows, both within and across enterprises. WebMethods is committed to supporting open standards and applying Internet technologies to address customers business needs. As part of that commitment, webMethods provides robust out-of-the-box Web services support that enables enterprises to participate in and leverage this emerging trend. This tutorial explains how to implement a Web service using the Integration Server component of the webMethods Version 4.6 integration platform.

Prerequisites
This tutorial assumes you are proficient at developing integration services using webMethods Integration Server and Developer (previously known as the webMethods B2B Server and B2B Integrator). You will use Integration Server Version 4.6 and Developer Version 4.6 or later to complete the tasks described in this tutorial. Some understanding of the Simple Object Access Protocol (SOAP), Web Services Description Language (WSDL), and Universal Description Discovery and Integration (UDDI) will be helpful.

Installing webMethods Integration Server and Developer

Install webMethods Integration Server 4.6 and Developer 4.6 or later using the installation instructions provided with the software.

2001 webMethods, Inc. All rights reserved.

Page 4

IMPLEMENTING YOUR FIRST WEB SERVICE

To create a Web service, you follow these steps: Create a flow service Generate the WSDL document that describes the service Publish the WSDL document

Create a Flow Service

Start webMethods Developer and create a simple Java or flow service that will accept some input values and return some output values.

Generate the WSDL Document

1. Select the services Settings tab in the service editor. 2. At the bottom of the Settings tab, you will find a box labeled Universal Name. You use Universal Name to identify the service to the outside world. Universal Name is made up two parts: Namespace Name and Local Name. You can enter any combination of values into these two boxes that uniquely identify your service. If you do not have to supply a universal name, the system will generate a default universal name that is made of the fully qualified Folder name (for Namespace Name) and the actual Service name (for Local Name). 3. On the Compose menu, click Generate WSD. 4. In the WSD generation dialog box, fill in the appropriate information. The default settings will work in most cases. You can change the host name to the name of the machine that is actually hosting the service if the machine name is registered in DNS. The default protocol for your Web service is SOAP-RPC and the default transport is HTTP. In general, most services that you create can be accessed via SOAP-RPC. Services that accept XML documents directly as input can be accessed via SOAPMSG. HTTP-POST and HTTP-GET also require that the service accept XML documents directly. For this exercise, SOAP-RPC will work. The Target namespace is the namespace to which the generated WSDL elements, attributes, and type definitions belong. You do not have to supply a target namespace name. The default value //localhost will work. Note: the WSDL target namespace and the namespace in the Universal Name are two different namespaces. One is for resolving names in the generated WSDL document; the other is for resolving the actual Web service name in the host server.

2001 webMethods, Inc. All rights reserved.

Page 5

5. Click OK. The system displays a dialog box that asks where to place the generated WSDL document. You can type the directory path or use the directory browser provided by the dialog box to specify the target directory. 6. Click OK to complete the WSDL generation process.

Publish the WSDL Document

The WSDL wizard generates two files: service_name.wsd, where service_name is the local name of the IS service. If you do not supply a local name in the Settings tab, the local name defaults to the actual IS service name. default.xsd

The default.xsd file contains the data type definitions in the form of an XML schema. The service_name.wsdl file contains the rest of the WSDL definition elements (that is, message, operation, port type, binding, port (network access point), and service). The two files are linked through a <include schemaLocation = default.xsd/> reference in the WSDL document. You must place the default.xsd file in the same directory as the WSDL document. You can change the name and location of the XSD file, but you will need to update the <include shemaLocation=/> reference to reflect the correct location and file name. If you intend to store all the WSDL and XSD files in the same directory, you should change the name of the default.xsd file to a unique name for each Web service that you have created. Another alternative is to merge individual .xsd document into a single .xsd document. The generated WSDL and XSD files need to be hosted by a Web server so potential consumers of your Web service can download the files. Integration Server can function as a Web server for this purpose. You can create a package in Integration Server and place the WSDL and XSD files in the packages /pub directory. You should create HTML or DSP pages that provide the navigation aid that consumers need to discover your Web service as well as URL pointers to the WSDL and XSD files. You could also register your Web service in a UDDI registry and create URL pointers to the WSDL and XSD files.

2001 webMethods, Inc. All rights reserved.

Page 6

INVOKING EXTERNAL WEB SERVICES

To create a Web service connector in Integration Server, you follow these steps: Locate and download the WSDL document for the target Web service Create a Web service connector in Integration Server Invoke the remote Web service using the Web service connector

Locate and Download the WSDL Document

You can locate and download a WSDL document using any of these methods: Search a UDDI registry Visit specialized Web sites Query the Web service host server Ask the Web service provider for the Web service

Both IBM and Microsoft operate public UDDI nodes. The whole UDDI concept is still relatively new, however, so it is generally not easy to locate useful services in these public UDDI nodes. You might have a better chance of finding useful Web services on public Web sites like www.salcentral.com. No matter which method you use to identify the target Web Service, you will need to download the corresponding WSDL document into a directory that webMethods Developer can access.

Create a Web Service Connector

1. In webMethods Developer, on the File menu, click New. The system opens the New wizard. 2. Click Web Service Connector, then click Next. 3. Click the folder in which you want to create the Web service, then click Next. 4. Specify the directory that contains the target WSDL document by typing the URL or selecting the directory from the local file system. Click Finish and watch the Web service connector being generated and made visible in the service browser in Developer. 5. Depending on the security requirements of the target Web service, you might need to update the login ID and password in your Web service connector flow before you try to use it. If you generated a Web service connector from the test WSDL document that you created earlier, you will probably need to supply the user name and password input parameters to the soapRPC service in the Web service connector flow before it can invoke your test Web service.

2001 webMethods, Inc. All rights reserved.

Page 7

The Web service connector is a custom flow service created from a template. Basically, the Web service connector wizard creates a custom flow service using one of the templates, parses the input WSDL document, extracts various connection parameters from the WSDL document, and updates the flow service with the extracted connection parameters.

Invoke the Remote Web Service

To invoke the remote Web service, run the Web service connector in test mode and supply the appropriate input values. The Web service connector will invoke the remote Web service and display the returned value in the Output tab. You can invoke your test Web service using the Web service connector generated from its WSDL document. Both the service and the connector can run on the same machine. In a real integration scenario, you would build other services that will invoke specific Web service connectors to obtain results from remote Web services as a part of the overall integration logic.

2001 webMethods, Inc. All rights reserved.

Page 8

ADVANCED WEB SERVICES TOPICS

By now, you should have successfully created a Web service using the Integration Server. You should also have successfully invoked remote Web services that are both hosted in your Integration Server and external servers on the Internet. In this section, we will briefly cover some of the more advanced topics on Web services implementation using the webMethods integration platform: Web service standards: SOAP, WSDL and UDDI SOAP RPC vs. SOAP document Publishing multiple services in a single WSDL document Web service client generation and runtime binding Accessing Web service sfrom other webMethods components Web service input and output field constraints Web service security

Web Services Standards

Three standards are typically associated with Web services: SOAP, WSDL and UDDI. SOAP addresses the data transport, messaging and connectivity aspects of Web services; WSDL deals the service description aspect of Web services; and UDDI concerns the service discovery aspect of Web services.

SOAP
SOAP is a lightweight XML protocol for exchanging information in an open network. SOAP specification consists of three parts: 1. An envelope structure for describing what is in a message and how to process it. 2. A set of encoding rules for expressing instances of application-defined data types. 3. A convention for representing remote procedure calls (RPC) and responses in the SOAP message body. SOAP messages must ride on top of a transport protocol. The most widely used transport is HTTP. Even though HTTP can be used to access Web Services in some cases, SOAP provides an extensible messaging mechanism that can provide a much robust messaging capability. From a pure messaging protocol perspective, the current SOAP specification is relatively simple compared to existing messaging mechanisms, such as webMethods message broker. However, SOAP will evolve into a robust standard messaging protocol over time and enable true messaging among disparate platforms. A SOAP message consists of three parts: a header, a body, and trailer blocks. The trailer block is optional and not commonly used. The header block is also optional. Only the body block is required. SOAP message processors usually use the information stored in

2001 webMethods, Inc. All rights reserved.

Page 9

the root tag of a body element to determine the processing logic to invoke. The webMethods default SOAP processor and SOAP RPC processor use the root tag name and the xmlns attribute value to determine the target service to invoke. A sample SOAP request message is shown below: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsd-cr="http://www.w3.org/2000/10/XMLSchema" xmlns:xsd-lc="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SOAPENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <ser-root:multiplyInts xmlns:ser-root="//www.mycompany.com/myNamespace"> <num1 xsi:type="xsd:string" id="id1">5</num1> <num2 xsi:type="xsd:string" id="id2">2</num2> </ser-root:multiplyInts> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

multiplyInts and //www.mycompany.com/myNamespace are the local and namespace names for the IS service, respectively. This particular SOAP message is a SOAP RPC message. A SOAP document message is encoded the same way, except that it might contain multiple body entries (a body entry is an immediate child element of the SOAP BODY element (<SOAP-ENV:Body>). The payload (body entry) of a SOAP RPC message is de-serialized directly by SOAP RPC processor and handed to the application in its native format. The payload a SOAP document message in general has to be deserialized by the application itself.

WSDL
WSDL is an XML file format for describing your Web services. A WSDL document contains these elements: Types Message Operation Port Type Binding Port Container for data type definition using some type system (such as XSD) Abstract, typed definition of the data being communicated Abstract description of an action supported by the service Abstract set of operations supported by one or more endpoints Concrete protocol and data format specification for a particular port type Single endpoint defined as a combination of a binding and a network address Collection of related endpoints (ports)

Service

2001 webMethods, Inc. All rights reserved.

Page 10

The type, message, operation, and port type definitions are sometimes referred to as abstract interface definition; binding, port and services are sometimes referred as concrete implementation. For a given abstract interface, there can be multiple concrete implementations. The mapping between the WSDL abstract definition elements and webMethods namespace elements are: webMethods Record Service Input/Output Service Folder/Namespace Name WSDL Type Message Operation Port Type

The information for the WSDL binding element is supplied by the dialog box during the WSDL generation process. The binding name is derived by appending Binding to the namespace-name portion of the universal name of your IS service. If you did not supply a namespace name for your IS service, the namespace name is default to the fully qualified folder path to your IS service (separated by .). The WSDL port name is derived by appending Port0 to the namespace name of your IS service. The WSDL service name is derived by appending Service to the namespace name. By storing the type definition in a separate .xsd file, you gain some flexibility in reusing the data type definitions. WSDL functions as the client library that is normally required in building client/server applications. The WSDL document contains all the necessary information for the Web service consumer to create the client code to invoke the Web service using standard connection libraries (for example, SOAP or HTTP).

UDDI
UDDI is a specification for publishing and discovering information about services. The original intent of UDDI was to enable electronic catalogs in which businesses and their services can be listed. UDDI has two components: the registry and the interface. The UDDI registry is the physical server that houses the business and service descriptions. The UDDI interface is a SOAP/HTTP-based API that client program can use to access the registry. Most UDDI registries also support Web browser-based user interfaces. Originally designed as public registries to be hosted directly on the Internet, UDDI registries can also be deployed in an intranet environment (sometimes referred to as private registries). Although UDDI is commonly associated with Web services, it is not a necessary component of the Web services architecture. There are other ways to list services, such as Web pages, databases, or directory products. Several Web services vendors have

2001 webMethods, Inc. All rights reserved.

Page 11

pushed Web services deployment models that require the use of UDDI in the context of runtime binding of Web but, for most practical deployment of Web Services in the near term, UDDI is not a required component. Please see the webMethods white paper title Demystifying Web Services for more detailed discussions on Web service standards and architecture.

SOAP RPC vs. SOAP Document

Since IS 4.6 supports both SOAP RPC and SOAP document-style messages, which one should you use when publishing a Web service? The answer is that you should publish any service that accepts records as input and output parameters as a SOAP RPC service (the default choice in the WSDL wizard dialog box), and any service that accepts XML documents as input and output as a SOAP document service. To access a service as a SOAP document service, you must wrap the service with a wrapper service that accepts a SOAPRequestData object and returns a SOAPResponseData object. The wrapper service must extract the SOAP body (the application data) from the SOAPRequestData object, then hand it to the target service for processing. When the target service returns, the wrapper service must package the response data into the SOAPResponseData object that is then encoded as the SOAP response message and returned to the requestor by the SOAP processor. See the webMethods Developer Users Guide for details on publishing WSDL for services that must be accessed as SOAP document, and the SOAP Programming Guide for details on constructing SOAP messages using the built-in SOAP services. In general, SOAP RPC is much easier to use in a development environment because it hides all the XML details from the developer and allows the developer to access remote SOAP services without having to explicitly construct the XML document. In the context of webMethods integration platform, SOAP RPC messages are constructed directly from the data in the pipeline, which makes them transparent to the developers who needs to interact with remote SOAP clients or servers.

Publishing Multiple Services in a Single WSDL Document

The WSDL wizard generates oneservice_name.wsdl file, where service_name is the local name of the IS service, and one default.xsd file each time you run the Generate WSD command. The resulting WSDL document contains a single operation and a single port type. There are circumstances in which you might want to publish multiple operations in a single WSDL document. You might also want to group the operations into port types to better organize your Web services interface. You must manually merge the individual WSDL documents to accomplish this. The proper use of the universal name can make the job easier for you. The universal name consists of two parts: namespace name and local name. The namespace name is mapped to WSDL port type and local name is mapped to WSDL operation. By using the same namespace name for a group of related IS services, you

2001 webMethods, Inc. All rights reserved.

Page 12

have effectively grouped them under a single logical interface (port type). Intelligent local name can make the purpose of the operation (IS service) more obvious to users.

Web Service Client Generation and Runtime Binding

Web service client (connector) generation in the IS 4.6 is largely automated. The Web service connector wizard parses the imported WSDL document to extract the relevant configuration parameters to generate the Web service connector from a set of flow templates. There are four types of flow templates defined: SOAP RPC, SOAP MSG, HTTP POST, and HTTP GET. You can also generate a Web service client flow manually by reading the WSDL document yourself, pulling out the relevant connection parameters, and creating the appropriate flow logic. To create a third-party (non-webMethods) Web service client, you will need a Web service toolkit supplied by the third party. The amount of work you will have to do to create a Web service client depends on the sophistication of the toolkit. Some toolkits are primitive and will require you to do some work to create the client. Others are more advanced, like webMethodss, and can generate the client for you automatically. IS 4.6 does not support the generation of a Web service client during the actual runtime of a service; this should not be an issue. The value of being able to generate a Web service client on the fly is that you can use a brand new Web services provider while executing your service. This capability is not particularly practical (at least in the near to medium term) in that you typically will not use a new Web services provider without first qualifying the provider. You would generate the Web service client for the provider after it passes your qualification process. You can implement a form of runtime binding in the IS 4.6 that is more practical dynamically deciding which Web service provider to use based on the contents of the input parameters. You can create a wrapper Web service client flow that houses the logic required to determine the actual Web service provider to use for a particular transaction. The wrapper Web service client flow will invoke the appropriate Web service connector based on the outcome of the decision logic and thus provide runtime service binding capability.

Accessing Web Services from Other webMethods Platform Components

Accessing Web services from other webMethods integration platform components such as Business Integrator, Trading Networks, and Enterprise Server are straightforward processes. Since the Web service connectors are just flow services, they are visible wherever IS services are visible. For example, in Business Integrator, you can send document to an IS service; that IS service can be a Web service connector. Similarly, in Trading Networks, you can invoke IS service; that IS service can be a Web service

2001 webMethods, Inc. All rights reserved.

Page 13

connector as well. Enterprise Server can access a Web service connector through the Enterprise Adapter. Accessing integration logic housed in other webMethods platform components as Web services is equally simple. Once the integration logic is exposed in IS 4.6 as an IS service using the webMethods development tool, that IS service can then be exposed as a Web service. See the webMethods white paper titled Implementing Enterprise Web Services with the webMethods Integration Platform for more information on Web services integration patterns.

Setting Service Input and Output Field Constraints when Using SOAP RPC
When you create input and output record definitions using webMethods Developer, the default field constraint for the fields are set to must exist at runtime. In general, this is not an issue because data validation has to be enabled explicitly by the developer through either configuration or by invoking a validation service. However, the SOAP RPC content handler enforces the validation rule when it builds the SOAP RPC response message. If the SOAP RPC content handler cannot find the data field that is specified as must exist at runtime in the record definition in the pipeline, it will throw an exception that it cannot find that field (if there are multiple null fields, the content handler stops at the first one it encounters). This can be avoided only if you set the correct field constraints for the output record. When building a SOAP RPC client manually, you must use the WmPublic:pub.client.soapRPC to construct and send the RPC request message. WmPublic:pub.client.soapRPC also performs validation when it builds the SOAP RPC request message and parses the response message. You control the validation rule by supplying the appropriate record definitions as the input parameters for the targetInputSignature and targetOutputSignature inputs of the soapRPC service. You disable validation by not supplying any signatures. When building a SOAP RPC client by using the Web service connector wizard, the wizard will generate the input and output records for the Web service connector using the type definitions contained in the WSDL document. The wizard will configure the soapRPC service to use the auto-generated input and output records as the input and output signatures. Since the Web service connectors input and output record definitions are generated directly from the WSDL document, they should be consistent with what the Web service provider expects. There should be no need to change the data validation rules for the automatically generated Web service connector.

Web Services Security

SOAP itself does not provide any special provision for security. SOAP protocol (or Web Services) derives its security from the underlying transport they ride on (for example, 2001 webMethods, Inc. All rights reserved. Page 14

HTTP). HTTP provides both basic authentication and secured communication channel (via SSL). However, the security provided by HTTP/S is point-to-point between the requester and the server. For Web service applications that require multiple intermediaries, HTTP/S scheme is not adequate unless the message routing is configured as a star with the hub of star performing authentication with each intermediary. Work on addressing the security aspect of the SOAP protocol is underway. However, before a specification is established, you will have to rely on HTTP/S to provide the required security. See the webMethods white paper titled Requirements for Securing Enterprise Web Services for more information on this topic.

2001 webMethods, Inc. All rights reserved.

Page 15

ABOUT WEBMETHODS, INC.

webMethods, Inc. (Nasdaq:WEBM) is the leading provider of integration software. The webMethods integration platform allows customers to achieve quantifiable R.O.I. by linking business processes, enterprise and legacy applications, databases and workflows both within and across enterprises. By deploying the webMethods integration platform, customers reduce costs, create new revenue opportunities, strengthen relationships with customers, substantially increase supply chain efficiencies and streamline internal business processes. Founded in 1996, webMethods is headquartered in Fairfax, Va., with offices throughout the U.S., Europe and Asia Pacific. webMethods has more than 750 customers worldwide including Global 2000 leaders such as Citibank, Dell, Eastman Chemical, The Ford Motor Company, Grainger, and Motorola. webMethods strategic partners include Accenture, AMS, BMC, BroadVision, Cap Gemini Ernst & Young, Deloitte Consulting, EDS, HewlettPackard, i2 Technologies, J.D. Edwards, KPMG Consulting, Microsoft, Oracle Corp., SAP AG and Siebel Systems. More information about the company can be found at http://www.webMethods.com.

2001 webMethods, Inc. All rights reserved.

Page 16

Contact webMethods
North American Headquarters:
3930 Pender Drive Fairfax, VA 22030 United States of America 1-703-460-2500

European Headquarters:
400 Thames Valley Park Road Reading, Berkshire RG6 1PT United Kingdom +44 (0)118 963 7455

Asia Pacific Headquarters:

Level 15, Philips Building 15 Blue St. North Sydney NSW 2060 Australia +61 2 8913 1111

www.webmethods.com