Using external capabilities files with WMS services

Using external capabilities files gives you absolute control of the WMS service's capabilities file, so you can do things like the following:

• Add metadata about the service.
• Add metadata about each layer.
• Add spatial reference systems from ArcGIS Server's predefined projection list.
• Customize the legend information for each layer.

Although external capabilities files give you more flexibility, working with them requires some familiarity with the OGC WMS specification.

This topic contains instructions for enabling your WMS service to use external capabilities files and outlines some use cases of when you might benefit from external capabilities files.

Note: By using external capabilities files for your WMS service, you are responsible for validating your capabilities files against the DTD or XML schema from OGC. You also assume responsibility for all the synchronization between your capabilities files and the source map document from which your WMS service is published.

Configuring a WMS service to use external capabilities files

To configure a WMS service to use external capabilities files, you must already have at least one WMS capabilities file ready. You can create the file from scratch, but it's often easier to use a system-generated capabilities file as a template. (By default, a set of system-generated capabilities files is created in the ArcGIS Server output directory every time the service starts. These files are deleted when the service stops.)

If you want your WMS service to support different versions of WMS protocol—for example, 1.0.0, 1.1.0, 1.1.1, and 1.3.0—you must have one capabilities file for each version of WMS you want to support. Once you've created all the necessary capabilities files, name them with a common prefix (for example, capabilities) plus the unique three-digit version number (for example, capabilities100, capabilities110, capabilities111, capabilities130). Place all your capabilities files under a common folder that is accessible from a URL. Then follow the steps below to configure your service to use the files:

ArcGIS Server Manager instructions

Steps:

1. Click the Services tab in Manager.
2. Find your service and click the Edit icon.
3. Click the Capabilities tab.
4. Find WMS in the Capabilities list. Make sure the box is checked and click the letters WMS (be careful not to uncheck the box). You'll see some properties appear.
5. Choose Use External capabilities files.
6. In the Specify the location prefix box, type the URL of the folder where you placed your capabilities files, plus the common prefix you used for them (for example, if you used "capabilities" as your common prefix, placed your files under C:\Inetpub\wwwroot\<instance name>\wms, and are using IIS with ArcGIS Server for .NET, you can just type http://<server name>/<instance name>/wms/capabilities).
7. Click Save.

ArcCatalog instructions

Steps:

1. Create an administrative connection to the GIS server on which your service is running.
2. Find your service and stop it if it is running.
3. Right-click the service and click Service Properties.
4. Click the Capabilities tab.
5. Find WMS in the Capabilities list. Make sure the box is checked, then click the letters WMS (be careful not to uncheck the box). You'll see some properties appear.
6. Choose Use external capabilities files.
7. In the Specify the location prefix box, type the URL of the folder where you placed your capabilities files, plus the common prefix you used for them (for example, if you used "capabilities" as your common prefix, placed your files under C:\Inetpub\wwwroot\<instance name>\wms, and are using IIS with ArcGIS Server for .NET, you can just type http://<server name>/<instance name>/wms/capabilities).
8. Click OK and restart the service.

Use case 1: Add more spatial reference systems (SRS/CRS)

Problem: The WMS services you create with ArcGIS Server support hundreds of spatial reference systems, but only two are advertised in the capabilities file: EPSG 4326 (required by every WMS service) and the spatial reference of the data frame from which you published the service. Although you can request a map from the WMS service using any of the hundreds of supported spatial reference systems, some WMS clients will return an error if the spatial reference you request does not appear in the capabilities file. Other clients, such as ArcMap, only allow you to switch among the spatial reference systems listed in the capabilities file.

Solution: By publishing a WMS service with external capabilities files, more spatial reference systems can be added to that WMS service's capabilities so that a WMS client will be aware of them.

Detailed Steps: For a detailed example, see Adding spatial reference systems to a WMS service's capabilities file on the ArcGIS Server Blog.

Use case 2: Redirect WMS requests by configuring OnlineResource tags

Problem: OnlineResource tags in a WMS service's capabilities file tell clients where to send subsequent GetCapabilities, GetMap, and GetFeatureInfo requests after the initial connection. Usually OnlineResource tags contain the same URL as the WMS service, but when a reverse proxy is involved or when the user wants different types of WMS requests to be sent to different servers, it is necessary to make OnlineResource tags configurable.

Solution: By publishing a WMS service with external capabilities files, OnlineResource tags can be configured to point to different URLs for different types of WMS requests.

Detailed Steps:

1. Follow the steps in the Configuring a WMS service to use external capabilities files section of this documentation to publish a WMS service using external capabilities files.
2. Open the external capabilities file for version 1.3.0 (for example, capabilities130.xml) in a text editor.
3. Find all <OnlineResource> tags. There should be four. One is for the WMS service itself, and the other three are for the three types of WMS request, which are GetCapabilities, GetMap, and GetFeatureInfo.
4. Set the xlink:href attribute of <OnlineResource> to the URL where you want that type of WMS request to be sent. Save the change. (The xlink:href attribute can be unique among the four <OnlineResource> tags.)
5. Repeat steps 2 through 4 for other versions (1.0.0, 1.1.0, 1.1.1, and so on) of external capabilities files.
6. Access the external capabilities files through the URLs and make sure the changes are saved correctly.

You don't have to restart the WMS service or its parent map or image service after performing these steps. Refreshing the connection from your client should be enough.

Note: If the same URL, which is not the WMS service URL, is used for all types of WMS requests, there is no need to use external capabilities files. Instead, set the common OnlineResource tag through ArcCatalog or Manager and publish the WMS service with system-generated capabilities files.

Use case 3: Configure and customize layer information in WMS capabilities files

Problem: WMS capabilities files are the only connection between a WMS service and a WMS client, in which the server advertises information while the client consumes it. The WMS specification defines a large set of properties (through XML tags in the capabilities file) to describe each layer in the service, as well as the service itself, but many of those properties of layers cannot be added or configured when you publish a WMS service through ArcGIS Server using system-generated capabilities files.

Solution: By publishing a WMS service with external capabilities files, you can configure and customize any metadata information for each WMS layer in the service.

Example: This example shows how you can add metadata for a WMS layer to the WMS service's capabilities file. This metadata could include abstract, keywords, URL link to the metadata in standard format, attribution, and even the URL link to the feature data.