# Web Service Repository

## Contents
Overview Testing WS-I Compliance Registering the WSDL File Loading the WSDL File Selecting WSDL Operations WSDL Import Settings Deploy Policy Secure Virtual Service WSDL Import Summary What is Created? Publishing the WSDL

## Overview
The Web Services Repository stores information about Web Services whose definitions have been imported using Policy Studio or Service Manager. The WSDL files that contain these Web Services definitions are stored together with their related XML Schemas. Clients of the Web Service can then query the repository for the WSDL file, which they can use to build and send messages to the Web Service using the Enterprise Gateway. When you import WSDL files into the repository, this auto-generates a Service Handler that is used to control and validate requests to the Web Service and responses from the Web Service. You can import the WSDL file from the file system, a URL, or from a UDDI registry. You can also test the WSDL file for compliance with Web Services Interoperability (WS-I) standards. This topic describes how to test for WS-I compliance, how to import a Web Service definition into the repository, and shows what is created at each step.
## Testing WS-I Compliance
Before importing the WSDL file, you can check it for compliance with the WS-I Basic Profile. The Basic Profile consists of a set of assertions and guidelines on how to ensure maximum interoperability between different implementations of Web Services. For example, there are recommendations on what style of SOAP to use (`document/literal`), how schema information is included in WSDL files, and how message parts are defined to avoid ambiguity for consumers of WSDL files. The Policy Studio uses the Java version of the WS-Interoperability Testing Tools to test imported WSDL files for compliance with the recommendations in the Basic Profile. A report is generated showing which recommendations have passed and which have failed. While you can still import a WSDL file that does not comply with the Basic Profile, there is no certainty that consumers of the Web Service can use it without encountering problems. Important Note: Before you run the WS-I compliance test, you must ensure that the Java version of the Interoperability Testing Tools is installed on the machine on which the Policy Studio is running. You can download these tools from www.ws-i.org. To configure the location of the WS-I testing tools, select Window -> Preferences from the Policy Studio main menu. In the Preferences dialog, select the WS-I Settings, and browse to the location of the WS-I testing tools. You must specify the full path to these tools (for example, `C:\Program Files\WSI_Test_Java_Final_1.1\wsi-test-tools`). For more details on configuring WS-I settings, see the Policy Studio Preferences topic. Running the WS-I Compliance Test To run the WS-I compliance test on a WSDL file, perform the following steps: Select Tools -> Run WS-I Compliance Test from the Policy Studio main menu. In the Run WS-I Compliance Test dialog, browse to the WSDL File or specify the WSDL URL. Click OK. The WS-I Analysis tools run in the background in Policy Studio. The results of the compliance test are displayed in your browser in a WS-I Profile Conformance Report. The overall result of the compliance test is displayed in the Summary section. The results of the WS-I compliance tests are grouped by type in the Artifact: description section. For example, you can access details for a specific port type, operation, or message by clicking the appropriate link in the Entry List table. Each Entry displays the results for the relevant WS-I Test Assertions.
## Registering the WSDL File
The Web Services Repository is displayed as a top-level node in the Policy Studio Policies tree view. WSDL files are imported into Web Service Groups, which provide a convenient way of keeping groups of related Web Service definitions together. You can import a WSDL file into the default group by right-clicking the Web Services node, and selecting Register Web Service. Alternatively, you can add a new Web Services group by right-clicking the default Web Services group, or the Web Services Repository node, and selecting Add a new Web Services group. When the new group is added, you can right-click it in the tree, and select Register Web Service.
## Loading the WSDL File
In the Import WSDL wizard, the Load WSDL screen enables you to choose the WSDL location from the following options: File system URL UDDI registry Select the appropriate option depending on the location of the WSDL that you wish to import. If you wish to retrieve a WSDL file from a UDDI directory, see the Retrieving WSDL Files from a UDDI Registry topic. Click Next.
## Selecting WSDL Operations
The WSDL Operations screen of the wizard displays all operations defined in the WSDL file. The Relative Path, Binding, and Namespace of each operation are also displayed. Select the operations that you wish to create policy resolvers for. The Policy Studio uses the Web Service location, SOAP operation, and SOAP Action specified in the WSDL to create Relative Path, SOAP Operation, and SOAP Action policy resolving filters in the Service Handler. Click Next.
## WSDL Import Settings
In the WSDL Import Settings screen, the Remove unselected operations from the WSDL checkbox specifies whether the Policy Studio removes unselected operations from the WSDL file that is stored in the repository. As a result, removed operations are not exposed to clients that download the WSDL file for the Web Service. Important Note: When a request is made to the Enterprise Gateway for a WSDL file that has been imported into the Web Services Repository, it changes the address of the Web Service specified in the `location` attribute of the `<soap:address>` element to point to the machine on which the Enterprise Gateway is running, rather than the machine hosting the Web Service. This means that when a client downloads the WSDL file for the Web Service, it routes messages through the Enterprise Gateway instead of attempting to send messages directly to the Web Service, which typically is not available on a public IP address. For a detailed example, see Publishing the WSDL. Click Next.
## Deploy Policy
The final screen in the wizard enables you to select where to deploy the newly created policy (or policies). The Deploy Policy screen displays a list of all available Services and their corresponding Relative Paths. Select a Relative Path under which the policy is deployed. All requests arriving on the selected path are dispatched to the newly created policy. Click Finish.
## Secure Virtual Service
When you click Finish in the wizard, the Secure Virtual Service dialog is displayed. This enables you to specify policies to enforce security between a client and the Enterprise Gateway. For more details, see Securing a Virtual Service using Policies. In addition, if the imported WSDL file contains WS-Policy assertions, you are prompted to configure settings to enforce security between the Enterprise Gateway and the Web Service. For more details, see Configuring Security Policies from WSDL Files.
## WSDL Import Summary
When you have finished configuring security policies, the Summary dialog displays details on the imported WSDL file. For example, this includes the location of the WSDL file, and a tab for each Web Service virtualized by the Enterprise Gateway. Each tab includes the path to the Web Service that is published by the Enterprise Gateway. WSDL Import Summary Options The Summary dialog also enables you to configure the following options on the tab for each Web Service:
Validation | If you wish to use a dedicated validation policy for all messages sent to the Web Service, select this checkbox, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom validation policy used by multiple Web Services.
Routing | If you wish to use a dedicated routing policy to send all messages on to the Web Service, select this checkbox, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom routing policy used by multiple Web Services.
WSDL Access Options | Select whether to make the WSDL for this Web Service available to clients. The Allow the Enterprise Gateway to publish WSDL to clients checkbox is selected by default. The published WSDL represents a virtualized view of the Web Service. Clients can retrieve the WSDL from the Enterprise Gateway, generate SOAP requests, and send them to the Enterprise Gateway, which routes them on to the Web Service. For more details, see Publishing the WSDL.
These options enable you to configure the underlying auto-generated Service Handler (Web Service Filter) without having to navigate to it in the Policies tree. These are the most commonly modified Web Service Filter options after importing a WSDL file. Changes made in the Summary dialog are visible in the underlying Web Service Filter. For more details, see the Web Service Filter topic. You can also access these options from the Services tab after the WSDL file has been imported. Right-click the appropriate Web Service Resolver node, and select Quick-Edit Policy to display a dialog that enables you to configure these options.
## What is Created?
What is created when you import the WSDL file depends on whether you configured a policy to enforce security between the client and the Enterprise Gateway, and whether the WSDL file contains any WS-Policy annotations. However, assuming that the default options are selected in the WSDL Import wizard, the following list summarizes what is created by the wizard: Web Service A new Web Service tree node is created for each imported WSDL file in the Policies tree view. This tree node contains the WSDL file, together with any imported resources, such as other WSDL files or schema files. Click the new Web Service node in the tree to view the list of imported WSDL files and XML Schemas. The Schemas are listed by namespace. You can view the imported WSDL file by clicking the location of the WSDL file under the Web Service node in the tree. If you have selected to remove unselected operations from the WSDL, these operations are removed from the stored WSDL. Web Service Resolver A new Web Service Resolver node is created for each imported Web Service in the Services tree view. The Web Service Resolver is used to identify messages destined for this Web Service, and to map them to the Service Handler (Web Service Filter) for the Web Service. Service Handler A Service Handler for the Web Service is created under the generated policy in the Policies tree. This is used to control and validate requests to the Web Service and responses from the Web Service. The Service Handler is named after the Web Service (for example, Service Handler for 'HelloWorldService'). The Service Handler is a Web Service Filter, and is used to control the following: Routing Validation Message request/response processing WSDL options Monitoring options For more details, see the Web Service Filter topic. Policy Container A container for the newly generated policies is created under the Generated Circuits node in the Policies tree. The new container is named after the service (for example, Web Services.HelloWorldService). Policy A policy for the Web Service is created in the generated policy container. The policy name includes the relative path to the service (for example, /HelloWorldService/HelloWorld). Clients can specify `WSDL` on a request query string to retrieve the WSDL file (for example, `http://localhost:8080/HelloWorldService/HelloWorld?WSDL`). For more details, see Publishing the WSDL. Security Policies If you decided to configure a WS-policy to enforce security between the client and the Enterprise Gateway (as described earlier in Secure Virtual Service), or if the imported WSDL file contains WS-Policy assertions, a number of additional policies are automatically created in the generated policy container. These generated policies include the filters required to generate and/or validate the relevant security tokens (for example, SAML tokens, WS-Security Username tokens, and WS-Addressing headers). These policies perform the necessary cryptographic operations (for example, signing/verifying and encryption/decryption) to meet the security requirements of the specified policies.
## Publishing the WSDL
When the WSDL has been imported into the Web Services Repository, it can be retrieved by clients. In effect, by importing the WSDL into the repository, you are publishing the WSDL. In this way, consumers of the services defined in the WSDL can learn how to communicate with those services by retrieving the WSDL for those services. However, to do this, the location of the service must be changed to reflect the fact that the Enterprise Gateway now sits between the client and the defined service. For example, assume that the WSDL file states that a particular service resides at `http://www.example.com/services/myService`:
    <service name="myService">
      <port binding="SoapBinding" name="mySample">
        <wsdl:address location="http://www.example.com/services/myService"/>
      </port>
    </service>
When deployed behind the Enterprise Gateway, this URL is no longer accessible to consumers of the service. Because of this, clients must send SOAP messages through the Enterprise Gateway to access the service. In other words, they must now address the machine hosting the Enterprise Gateway instead of that directly hosting the service. When the WSDL file has been published to the repository, clients can retrieve it. However, when returning the WSDL to the client, the Enterprise Gateway dynamically changes the value of the `location` attribute in the `service` element in the WSDL file to point to the machine on which the Enterprise Gateway resides. The details regarding the physical location of the Web Service are preserved in the Connection filters, which are responsible for routing messages on to the service. Assuming that the Enterprise Gateway is running on port `8080` on a machine called `SERVICES`, the location specified in the exported WSDL file is changed to the following:
    <service name="myService">
      <port binding="SoapBinding" name="mySample">
        <wsdl:address location="http://SERVICES:8080/services/myService"/>
      </port>
    </service>
When the modified WSDL file is distributed to the client, it now routes messages to the machine hosting the Enterprise Gateway instead of attempting to directly access the Web Service. Accessing the WSDL For the client to access this modified WSDL file, the Policy Studio provides a WSDL retrieval facility whereby clients can query the Web Services Repository for the WSDL file for a particular Web Service. To do this, the client must pass the name `WSDL` on the query string to the Relative Path mapped to the policy for this Web Service. For example, if the policy is deployed under `http://SERVICES:8080/services/getQuote`, the client can retrieve the WSDL for this Web Service by sending a request to `http://SERVICES:8080/services/getQuote?WSDL`. When the client has a copy of the updated WSDL file, it knows how to create correctly formatted messages for the service, and perhaps more importantly, it knows to route messages to the Enterprise Gateway rather than to the Web Service directly. Publishing to UDDI For details on how to publish a WSDL file registered in the Web Services Repository to a UDDI directory, see the Publishing WSDL Files to a UDDI Registry topic.