Tutorial: Publishing a KML service

Complexity: Intermediate Data Requirement: Use your own data

You can serve KML dynamically over the Web by publishing an ArcGIS Server map service with the KML capability enabled. This allows a client to connect to the map service and request KML data for a specific geographic area. The KML can be exposed through either the REST Generate Map, Generate KML, and Query operations; the View in Google Earth link in the ArcGIS Services Directory; or a KML network link document that embeds a properly configured URL to the service.

This tutorial walks you through the process of creating a KML service with 3D extruded features. You'll first use ArcGlobe to create a layer file with some 3D extrusion properties. You'll then add the layer in ArcMap to set the layer symbology and configure descriptive text that will be associated with features in your KML. Next, you'll publish the map as a service with the KML capability enabled. Finally, you'll create a KML network link on your server so that others can easily access the KML.

Preparing the data in ArcGlobe and ArcMap

To publish feature classes with 3D attributes such as z-offsets or extrusion based on attributes, you must first edit the feature class layer properties in ArcGlobe and save them as a layer file, then add the layer file to an ArcMap document. The steps below show how you can apply extrusion in ArcGlobe and save a corresponding layer file that you can use later in ArcMap.

Steps:

1. Start ArcGlobe and add a feature class.
2. In the Table of Contents, right-click the layer and click Properties.
3. Click the Globe Extrusion tab.
4. Check Extrude features in layer and Do not draw bottom face of extruded polygons. Also choose to apply the extrusion by adding it to each feature's base height.
   
5. Set an Extrusion value or expression. This determines how far the features will "pop out" of the map. You can open the Expression Builder (using the button that looks like a pocket calculator) if you need help constructing the expression. In this case, the polygon features are extruded by multiplying the value of the POP04_SQMI attribute by 250 (an arbitrary value selected for appearance only) and adding this value to the feature base height. You may have to experiment with your expression to get the appearance the way you want.
   
6. Once you've set the extrusion for the layer and it looks three-dimensional, right-click the layer and choose Save as Layer File. Save it to disk in a location where your ArcGIS Server SOC Account has permissions to read the data.
7. Now that 3D properties have been determined for the data, it's time to set the 2D layer properties. Open ArcMap and click Add Data.
8. Browse to the layer file (.lyr) you just saved from ArcGlobe and click Add. The layer does not appear in 3D in ArcMap, but it will appear in 3D when you view the map in Google Earth or ArcGIS Explorer.
9. Set the layer properties by right-clicking the layer and choosing Properties from the context menu.
10. Click the General tab, edit the scale dependency of the layer, then enter a description. This description will be used for the KML layer description displayed in KML clients and can contain any valid HTML.
    
11. Click the Display tab and alter the transparency of the layer if you want. A light transparency can help users see through to the map below.
    
12. Click the Symbology tab and change the rendering properties if you want. A subtle gradient fill can help you distinguish between adjacent 3D features.
    
13. Click the Fields tab and set the fields that you want to be accessible through the map service. You can also use the KMLSnippet alias for any field in the feature class. The values of the field that you change to use the KMLSnippet alias will be displayed below each feature's icon in the table of contents of a KML client. The values of the KMLSnippet alias field can contain any valid HTML.
    
14. Optionally, set any definition queries or joins and relates that you want to be applied on your data. Do this using the Definition Query and Joins & Relates tabs, respectively.
15. Optionally, click the Labels tab and specify the labeling you wish to apply. KML will honor color, size, and label expressions for point features. KML does not support labeling for lines or polygons.
16. Click the HTML Popup tab and check Show content for this layer using the HTML Popup tool. Then choose one of the formatting options. This determines the KML description for each feature, or, in other words, the content that appears in the informational balloon when you click a feature. You can use HTML, JavaScript, and style sheets to make the description look fancy, or if you just want to experiment, you can choose the default option to display HTML formatting As a table of the visible fields.
    
17. Click OK to dismiss the layer properties, then save your map document (.mxd) by clicking File > Save.

Publishing the KML service

Once you've finished the map document, you need to publish it as an ArcGIS Server map service. The map service can generate KML as long as its KML capability is enabled. By default, the KML capability is enabled.

The steps below show how to publish the service in the Catalog window of ArcMap. If you want to use Manager to create the service, follow the corresponding steps in Publishing a GIS resource to the server in Manager.

Steps:

1. Remaining in ArcMap, click Windows > Catalog.
2. In the Catalog tree, browse to the map document (.mxd) you want to publish. Note that you can also expose map service definitions (.msd files) as KML if you choose.
3. Right-click the map document and choose Publish to ArcGIS Server.
4. Give your service a name and choose the folder where you want the service to be published. Then click Next.
5. On the second Publish to ArcGIS Server wizard page, notice that the KML capability is enabled. Leave it checked and click Next.
6. In the third wizard page, review the summary of what will be created and click Publish.
7. Your service has now been published, and you can preview it by expanding the GIS Servers node of the Catalog tree and dragging the service into the ArcMap Table of Contents.

Configuring properties for the KML service

After publishing the KML service, you may want to edit its default properties. To do this, follow the steps below:

Steps:

1. In the Catalog tree, right-click the service and click Stop.
2. Right-click the service and click Service Properties.
3. Click the Capabilities tab and click KML (be careful not to uncheck the box).
4. Edit the properties in the lower panel.
   • Choose how to limit the KML returned by the KML service. The KML Compatibility Mode options allow you to choose to include only focused subsets of functionality if the service will primarily be used with Google Maps or Google Mobile. This can increase performance.
   • Choose how to limit the features returned by the KML service, the output DPI, and the output image size.
   • Use the Use NetworkLinkControl Tag options to limit how often a service can be requested by a client.
5. Click OK to close the Service Properties dialog box.
6. In the Catalog tree, right-click the service and click Restart.

Exploring REST KML operations exposed in the ArcGIS Server Services Directory

Every ArcGIS Server exposes a Services Directory by default, which allows you to explore and interact with services using REST. You can use the Services Directory to practice interacting with your KML service.

Steps:

1. Use a Web browser to navigate to the ArcGIS Services Directory, whose URL is http://<ArcGIS Server name>/<ArcGIS Server instance name>/rest/services. Example: http://MyServer/ArcGIS/rest/services.
2. Notice the link View footprints in: Google Earth that shows footprints of all services that have a geographic extent.
3. In the Services Directory, click the link to your newly published service.
4. Click the View in: Google Earth link to open a KMZ document that shows a ground overlay of your service. Or, if your service is cached, you will see a KML regions-enabled super overlay. Note that this link does not return vectors.
5. Back in the Services Directory, click any layer in your service.
6. At the bottom of your page, click the Query link. This opens a form where you can specify many parameters to query a layer. The last option is the format in which you would like the response. Choosing KML here gives you a KMZ document containing the results of your query.
7. Navigate back to your service's page in the Services Directory.
8. At the bottom of your page, click Generate KML. This link displays a Web form in which you can select which layers to return in the KML. You can also choose to return vectors from your service dynamically by choosing the option Vector layers as vectors and raster layers as images.

Publishing a network link

You can make the KML available on your server in an easily consumable format by publishing a KML network link. You'll publish the network link in Manager. Then you can add the network link in ArcGIS Explorer or Google Earth.

Steps:

1. Log in to ArcGIS Server Manager.
2. Click the Services tab and click KML Network Links.
3. Click Create Network Link.
4. Type a name and, optionally, short and long descriptions for your KML. Then click Next.
5. In the Map Service drop-down list, choose the map service you just published. Also choose which layers you want to expose through the KML network link.
6. Choose the option to draw Vector layers as vectors and raster layers as images. Your extruded features are vectors, so you need to choose this option. Otherwise, you will see a flat rasterized image. Click Next.
7. In this final page of the wizard, you can adjust the Refresh, View, and Hostname parameters if you want. Additionally, you can choose to suppress the default KML snippet behavior of adding the first two lines of the description to every feature in the table of contents. In this tutorial, it's okay to accept the defaults.
8. Click Finish to create the KML network link. When you return to the KML Network Links page in Manager, you will see the URL to your new network link (for example: http://myServer/ArcGIS/kml/networklink1.kmz). Click or copy and paste this URL to add your KML network link to Google Earth or ArcGIS Explorer.