Table Of Contents

Publishing Service Information

Overview

About Published Hostnames

Setting the Published Hostname

Generating WSDLs for Services at the ACE XML Gateway

Troubleshooting WSDL-Generation Errors

Publishing WSDLs at the ACE XML Gateway by URL

Publishing WSDLs to a UDDI Registry

Configure the General UDDI Settings

About Usernames and UDDI

Identifying Handler Groups for UDDI Publishing

Publishing Service Information to a UDDI Registry

Using the Service Directory

Viewing the Directory

Using the WSDL Links

Publishing Service Information

---

This chapter describes how to publish information on services exposed by the ACE XML Gateway. It covers these topics:

•Overview

•About Published Hostnames

•Generating WSDLs for Services at the ACE XML Gateway

•Troubleshooting WSDL-Generation Errors

•Publishing WSDLs at the ACE XML Gateway by URL

•Publishing WSDLs to a UDDI Registry

•Using the Service Directory

Overview

The Web Services Description Language (WSDL) is a standard mechanism for describing the properties and capabilities of web services. A WSDL file describes the service operations available and how to use them. Many integrated development environments support WSDL import as a mechanism for quickly generating the framework code for service client applications. For this reason, client developers often need to be able to access the WSDLs describing the services exposed by the ACE XML Gateway.

You can have the ACE XML Manager generate and publish WSDLs based on the services defined in a policy, making them available to client developers outside of your internal network. You can publish WSDLs to UDDI registries or to a URL location at the ACE XML Gateway. UDDI is a standards-based directory service that service consumers can use to learn about the availability of services.

Developer's with access to the ACE XML Manager have an additional option for accessing WSDL and service information. The service directory is a page in the ACE XML Manager that describes the services available at the ACE XML Gateway, and from where users with developer accounts in the ACE XML Manager can access WSDLs for those services. The ACE XML Manager web console includes a user account type intended for developer users who only need to log into the console to view service availability.

About Published Hostnames

A WSDL file must contain the hostname that clients address to access the services described by the WSDL. When generating WSDLs, the ACE XML Manager does not attempt to anticipate the hostname to use for several reasons.

In production environments, Gateways are usually clustered behind a load-balancer. The ACE XML Manager cannot determine the hostname of the load-balancer automatically, so it cannot provide a meaningful value for the externally resolvable hostname in the WSDL.

Therefore, the ACE XML Manager simply writes its own IP address as the default value of the hostname when it generates a WSDL file. The only time this default value can be left unaltered is when one standalone appliance protects all backend services without benefit of a load-balancer. For all other configurations, you must specify the externally accessible hostname the ACE XML Manager writes into automatically generated WSDL files.

In general, the WSDL generated by the ACE XML Manager should give as the published address the domain name of the appliance that will receive the initial client connection. When a cluster of appliances uses a load-balancer to distribute traffic, it is the address of the load-balancer (not of any of the clustered appliances) that must serve as the published address of the ACE XML Gateway.

Setting the Published Hostname

To change the hostname used for publishing the availability of services at the ACE XML Gateway:

---

Step 1 While logged in to the ACE XML Manager web console as an administrator user, click the System Management link in the navigation menu.

Step 2 Click the Gateway Settings link, located in the right side of the ACE XML Manager section, near the top of the page.

Step 3 In the WSDL Publishing section near the page bottom, enter the new hostname in the Published Hostname field.

This should be the externally resolvable address of the ACE XML Gateway or Gateway cluster.

Step 4 Click Save to accept the new published hostname.

---

Now, when you generate WSDLs from the ACE XML Manager, the hostname value for the service providers in the WSDL will reflect the published hostname you entered:

...

<soap:address location="http://mygateway.example.com:80/service/order"/>
</port>

Generating WSDLs for Services at the ACE XML Gateway

The ACE XML Manager can generate WSDLs that describe the services virtualize at the ACE XML Gateway. In terms of the policy, a WSDL corresponds to a given handler group, with service operations corresponding to each compatible service in the handler group.

The ACE XML Manager can generate Document/literal or RPC/literal style WSDLs. Document/encoded or RPC/encoded are not supported in WSDL generation by the Manager, although they can be used in WSDL import for policy development. (Note that Document literal and RPC literal are WS-I compliant, while encoded WSDL binding styles are not.)

To have the Manager generate a WSDL for a particular handler group, click the View WSDL link next to the handler group. The WSDL is generated based on the last deployed version of the policy. If using UDDI or "?WSDL" URL-based WSDL publishing, the Manager automatically generates the appropriate WSDLs a policy deployment.

For more information on WSDL generation, see the following section, "Troubleshooting WSDL-Generation Errors".

Troubleshooting WSDL-Generation Errors

Sometimes the ACE XML Manager can't provide a WSDL file for a handler group. There can be several reasons for this, such as configuration errors, or certain characteristics of correctly configured handlers in the group. To determine why a handler group doesn't offer a WSDL link, you can inspect the handler group in the Virtual Services browser.

One reason that a handler group might lack a generated WSDL file is that it may contain no handlers for which WSDL can be generated. For example, the ACE XML Manager cannot generate WSDL files that describe TIB/RV services, because such services do not support WSDL descriptions. If every handler in a group routes traffic only to services that do not support WSDL descriptions, then no WSDL file can be generated for the group.

Generally speaking, the kinds of errors that prevent the proper generation of WSDL files fall into two categories:

•Generation errors include conflicting target namespaces, unprovisioned handlers, handlers incompatible with HTTP access, and so on.

•Validation errors, such as duplicate handler names, are caught when the ACE XML Manager validates a newly generated WSDL file before making it available.

You can view WSDL generation error information in the Virtual Services browser. The ACE XML Manager reports errors that prevented successful generation of WSDL by handler group. If errors prevent the WSDL from being generated, an error message appears next to the view report link in the Virtual Services browser. Using the information in the report, correct the problems by editing the handler group. If the handler group includes services that do not support WSDL, such as TIB/RV, a "not WSDL-compatible" designation appears next to the view report link.

In other cases, a WSDL not available report appears in the web console. To view the report:

---

Step 1 While logged in as an Administrator user, Policy View user, or Privileged user with the Routing role, click the Virtual Services link in the Routing section of the menu.

The ACE XML Manager displays the handler information page.

Step 2 Look for the handler group in question in the Routing page. By default the page displays the handlers sorted by handler group. If the ACE XML Manager cannot provide an automatically generated WSDL file for the group, the page displays the message "WSDL not available - view errors" in the handler group's heading (instead of generate WSDL).

Step 3 Click the link to display a page that describes the problems that prevent WSDL generation.

---

As discussed, various conditions can prevent WSDL generation for a particular handler group. In particular, for WSDL generation to work, there must be a schema for any XML body.

Note the following points regarding when the ACE XML Manager itself can derive XML schemas and when they must be provided by the policy developer:

•For SOAP RPC services, the ACE XML Manager generates a schema based upon the types of the specified arguments. (You must provide schemas for any complex argument types.)

•For SOAP Document services, the Manager derives the schema from the WSDL if the services were created by WSDL import. If they were not, you must upload the schema for the contents of the SOAP Body directly.

•For HTTP services with post XML bodies, you must provide a schema for the entire XML payload.

---

Note Raw binary body are represented in the generated WSDL with an untyped WSDLMessage part.

---

Services in a handler group do not have schemas for their XML payload are ignored in the WSDL generation process. However, WSDL generation proceeds for a handler group if there is at least one valid handler in the group.

Publishing WSDLs at the ACE XML Gateway by URL

By convention, SOAP frameworks often make the WSDL that describes a service available at a URL composed of the service access URL appended by ?WSDL

For example, a SOAP service hosted at the following URL: http://example.com/service/order.asmx

Would be described by a WSDL available from: http://example.com/service/order.asmx?WSDL

If the port on which the SOAP service is exposed is protected by SSL, the WSDL appears at the protected port: https://example.com:43/service/order.asmx?WSDL

Access control requirements cannot be applied to the WSDLs published at the ACE XML Gateway. Since WSDLs may contain sensitive information, you may choose to enable WSDL publishing only when needed to facilitate client development.

In the context of an ACE XML Gateway policy, each WSDL corresponds to a handler group. However, service operations within a handler group can have different URLs. In this case, the same WSDL is published at each URL in the handler group.

---

Note If the URL path for the WSDL exceeds 1014 characters, the WSDL is not retrievable. Instead, the request for the WSDL goes to the service the WSDL describes (that is, as if the ?WSDL string were not appended to the URL).

---

WSDL publishing is not configurable by service. It is either enabled or disabled for all services exposed in the policy.

To enable WSDL publishing at service URLs:

---

Step 1 In the Manager web console, click the System Management link in the navigation menu.

Step 2 Click the Gateway Settings link.

Step 3 In Gateway Settings page, scroll down to the WSDL Publishing settings.

Step 4 In the Published Hostname field, type the hostname that consumers will use to access the services described by the WSDL.

A WSDL defines service provider endpoints as ports. The port definition includes an attribute, which contains the hostname of the server that hosts the services. By default, the hostname of the ACE XML Manager is used as the service address location value in the generated WSDL. The value in the Published Hostname field will be used as the location address for the service instead of the ACE XML Manager hostname, which is the default.

Step 5 Select the Serve WSDL files from the ACE XML Gateway option to have WSDLs generated for supporting handler groups and published to the service URL.

Step 6 Click the Save Changes button at the bottom of the page.

Step 7 Deploy the policy to have the WSDLs generated and published to the WSDL location. Note that WSDLs are not generated until policy deployment.

---

Upon deployment, the service WSDL is available to client developers at the ACE XML Gateway.

Figure 31-1 WSDL exposed at the service URL

Publishing WSDLs to a UDDI Registry

The Universal Description, Discovery and Integration (UDDI) protocol defines a method of querying network resources to find descriptions and methods of connection for other network resources. UDDI creates a standard interoperable platform that enables companies and applications to find and use web services easily.

The ACE XML Gateway can publish information about configured handlers to a UDDI registry, enabling consumers to quickly and easily get the information they need to connect to protected services. The information tells consumers where to find the WSDLs that describe the services exposed at the ACE XML Gateway. The ACE XML Manager publishes to the UDDI registry the "?WSDL" URL on the ACE XML Gateway.

UDDI publishing involves these tasks:

---

Step 1 Configure general settings to enable UDDI Registry publishing

Step 2 Choose the handler groups to be published to UDDI

Step 3 After deploying the policy (which generates the WSDLs), publish the WSDLs to UDDI

---

The first step only needs to be performed once—before the first time you publish to UDDI. The second and third steps are required each time you want to update the published information, for example, if there are new handler groups and services at the ACE XML Gateway.

Configure the General UDDI Settings

The first step in UDDI publishing is configuring UDDI registry settings in the policy:

---

Step 1 In the ACE XML Manager web console, click the System Management link in the Administration section of the navigation menu.

Step 2 Click the Gateway Settings link.

Step 3 In the WSDL Publishing and UDDI section near the bottom of the page, enter the hostname consumers use to address the ACE XML Gateway in the Published Hostname field. This value will appear as the Port address in the generated WSDL.

For more information, see "About Published Hostnames" section.

Step 4 Enable the option labelled Serve WSDL files from the ACE XML Gateway. This is a requirement for UDDI publishing to work. The ACE XML Manager will publish to UDDI only the address of WSDL files exposed at the ACE XML Gateway (not the address of WSDL files exposed at the ACE XML Manager).

Step 5 In the UDDI Publishing fields, enter the information required to communicate with the UDDI registry to which you want to publish the service information:

Table 31-1 UDDI publishing settings

Field	Description
Inquiry URL	The URL at which the UDDI registry accepts queries for information about web services.
Publish URL	The URL at which the registry accepts publish requests.
Username	The username under which the ACE XML Manager logs into the UDDI registry. For information regarding UDDI and usernames, see "About Usernames and UDDI" section.
Password	The passphrase the ACE XML Manager uses to log into the UDDI registry.
Repeat Password	Confirm the value entered in the Password field.
Business Name	The name used to construct a UDDI business Record, with which all information about handler groups and WSDL files is associated.

If you don't know the proper values for these fields, contact the administrator of the UDDI registry. The ACE XML Manager requires valid authentication information to connect to the UDDI registry and publish WSDL files.

Step 6 Click the Save Changes button at the bottom of the page when complete.

---

The ACE XML Manager is now configured to publish handler groups to the UDDI registry you specified. Only handler groups you configure for publishing (as described in "Identifying Handler Groups for UDDI Publishing" section) are published.

About Usernames and UDDI

When you publish information about configured handlers to a UDDI registry, the information is associated at the UDDI registry with the username provided in the policy configuration. If you later change that username in the policy, you may encounter problems if you attempt to change the published information, since it is associated with the first username. For security reasons the UDDI registry does not allow a different user to change that published information.

To prevent such problems, follow these steps:

---

Step 1 Before changing the username or password used to publish to the UDDI registry, navigate to the ACE XML Manager's UDDI publishing page.

Step 2 Click the Delete Published Data from UDDI Server button to delete entries on the UDDI registry previously published from the ACE XML Manager.

Step 3 Type the username and password for publishing to UDDI.

Step 4 Return to the UDDI publishing page and click the Publish button to republish handler information to the UDDI registry.

---

The ACE XML Manager now publishes the information using the new UDDI username and password.

Identifying Handler Groups for UDDI Publishing

To publish service information to a UDDI registry, you must first enable UDDI publishing for the handler group to which the virtual service belongs, as follows:

---

Step 1 Click the Virtual Services link in the navigation menu.

Step 2 Click on the name of the handler group that you want to publish on the UDDI registry.

Step 3 In the Edit Handler Group page, expand the UDDI Publishing settings.

Step 4 Select the option labeled Enable publishing this handler group to the UDDI server.

Step 5 Type a description of the handler group for server consumers to learn about the services in the UDDI Description field.

Step 6 Click Save Changes.

Step 7 Repeat these steps for each handler group you want to publish.

Step 8 Deploy the policy to have WSDL files generated for the handler groups.

---

To complete the publishing process, follow the steps in the next section, "Publishing WSDLs to a UDDI Registry" section.

Publishing Service Information to a UDDI Registry

If handler groups are configured to write WSDL information about the services they protect, you can publish that information to a configured UDDI registry. Note that the policy must be deployed before you can follow these steps.

To publish WSDL information about handler groups to a UDDI registry:

---

Step 1 Click the UDDI Publishing button on the Policy Manager page.

Step 2 In the UDDI Publishing page, click the Publish Handler Groups To UDDI button.

The ACE XML Manager publishes WSDL data for all of the policy's handler groups that are configured to do so. It publishes the ?WSDL address location of WSDLs exposed at the ACE XML Gateway.

---

If the Publish Handler Groups To UDDI button is not enabled and you have followed the steps in "Identifying Handler Groups for UDDI Publishing" section, errors in WSDL generation may have occurred. For more information, see "Troubleshooting WSDL-Generation Errors" section.

Using the Service Directory

The ACE XML Manager service directory lists the services available at the ACE XML Gateway, provides information on them, and offers a link from which users can download WSDL files describing the services.

ACE XML Manager web console users who have permission to view the Directory can use it as a reference when creating client applications that use the services exposed by the ACE XML Gateway.

The directory shows the name and protocol of each handler, the URL that a consumer uses to connect to it, and a description of the handler's authentication requirements.

Clicking a handler's name provides additional information about it, such as the message specifications for incoming messages and outgoing responses, and a text description of the handler.

Viewing the Directory

A user who has the Policy View or External Developer role sees the directory upon successful log in, which appears to the developer as follows.

Figure 31-2 Directory: Developer View

To view the directory as a privileged user, in the console, click the Service Directory link in the Reports & Tools section of the navigation menu. The Directory Index page appears.

For security reasons, the directory displays only those handlers for which the viewing user has permission to connect. This restriction means that if you log in as a user with the External Developer role, you will not necessarily be able to view the information for all handlers. Any handlers that are not provisioned, for example, are not visible.

Each row in the table indicates the name of a virtual service, the message protocol it accepts, the exposed URL consumers use to connect to the handler, and an iconic description of the handler's authentication requirements.

The name of each handler group appears as a banner across all columns of the page. Underneath the banner are table entries that describe each handler in that group. If all handlers in the group are WSDL-compatible, this banner offers a View WSDL link which you can download the handler group's WSDL file.

•The Handler Name column lists the name of a handler and the protocol it accepts (for example, SOAP 1.1 Document.)

•The Interface column lists the URL consumers must use to connect to the handler. If the handler accepts SOAP documents, its entry in this column also lists the URL of its associated SOAPAction. If the handler receives message bus traffic, this column lists provider and topic information.

The padlock icon in the Description column indicates whether a particular handler requires authentication. Publicly provisioned handlers display an open padlock in the Description column, while handlers that require authentication display a closed padlock icon.

To see more information about a virtual service, click its name. The page that appears provides additional information on the service, such as a short text description, a summary of its provisioning, and descriptions of its message specifications. The handler's creator provides the text description that appears on this page, and the ACE XML Gateway generates all other information that appears here.

Using the WSDL Links

If a handler group in the directory offers a WSDL link, then you can fetch the WSDL file and use it to configure client applications. To use a WSDL file, click the WSDL link and save the file to your local filesystem. Then import the saved file into your WSDL-aware tools.

If you configure handlers by hand and then later use the WSDL files generated for them, you may sometimes notice that the names of handlers as they appear in the generated WSDL files differ from the names you assigned. You can give a handler almost any name you like, but there are restrictions on the text characters that can appear in valid WSDL files. In order to ensure that the WSDL files it generates are valid, without placing undue restrictions on the naming of handlers, the ACE XML Manager automatically replaces illegal characters in handler names with the underscore ('_') character.

Automatically generated names do not appear in the SOAP traffic itself, and don't affect processing of SOAP messages. They appear only in the names of classes that are automatically generated by development frameworks (such as Visual BASIC™ or Java™ development tools) when they import the auto generated WSDL files.

If a handler group does not have a WSDL link, it's possible that there are problems in WSDL generation associated with the handler group. For more information, see "Troubleshooting WSDL-Generation Errors" section.