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:

Although external capabilities files give you more flexibility, they require 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 of 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 have at least one WMS capabilities file ready. You can create the file from scratch, but it's often easier to first publish your service with a system-generated capabilities file, then use that file as a template for creating the external capabilities file.

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 of the necessary capabilities files, name them with a common prefix (for example, "capabilities") plus the unique 3-digit version number (For example: "capabilities100", "capabilities110", "capabilities111","capabilities130"). Place all of your capabilities files under a common folder which is accessible from a URL. Then follow the steps below to configure your service to use the files:

ArcGIS Server Manager instructions

1. Click the Services tab in Manager.
2. Find your service and click the Edit (pencil) icon.
3. Click the Capabilities tab.
4. Find WMS in the list of Capabilities. 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 and you 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

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 list of Capabilities. 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 and you 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 Development 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 server, 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 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. Then save the change. (The xlink:href attribute can be unique among the four <OnlineResource> tags.)
5. Repeat Steps 2 through 4 for other versions (e.g. 1.1.1, 1.1.0, or 1.0.0) of external capabilities files.
6. Access the external capabilities files through URL 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, then 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 can not 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.