Tutorial: Publishing a KML service

Complexity: IntermediateData Requirement: Use your own dataGoal: Create a map and publish it as a KML service to ArcGIS Server.

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 ArcGIS 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 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.

Before beginning this tutorial

If you've just installed ArcGIS Server, you need to complete some preparatory steps before you can connect to the server and publish services:

• For details on how to configure your ArcGIS Server site, see the Getting started after install section of this help system.
• To learn how to make the data referenced by your GIS resource available to the server, see the topic Making your data accessible to ArcGIS Server.

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.

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. Click the Globe Extrusion tab in ArcGlobe.
6. Set an Extrusion value or expression. This determines how far the features will pop out of the map. You can open the Expression Builder if you need help constructing the expression. In this case, the polygon features are extruded by multiplying the value of the POP10_SQMI attribute by 250 (POP10_SQMI *250), and adding this value to the feature base height. This is an arbitrary value selected for appearance only. You may have to experiment with your expression to get the appearance the way you want.

   

7. Once you've set the extrusion for the layer and it looks three-dimensional, right-click the layer and choose Save as Layer File.
8. 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.
9. 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 ArcGIS Earth.
10. Set the layer properties by right-clicking the layer and choosing Properties from the context menu.
11. Click the General tab, set the Scale Range 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.
12. Optionally, click the Display tab and alter the transparency of the layer. A light transparency can help users see through to the basemap below.
13. Optionally, click the Symbology tab and change the rendering properties. A subtle gradient fill can help you distinguish between adjacent 3D features.
14. Click the Fields tab and set the fields that you want to be accessible through the map service. You can also change any field in the feature class to use the KMLSnippet alias. 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.
15. 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.
16. 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.
17. 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.
18. Click OK to dismiss the layer properties, then save your map document by clicking File > Save.

Publishing the KML service

Now that you've finished your map document, you need to publish it as a map service. The map service can generate KML as long as its KML capability is enabled. By default, the KML capability is enabled.

1. In ArcMap, choose File > Share As > Service from the main menu.
2. In the Share as Service window, choose Publish a service. Click Next.
3. In the Publish a Service dialog box, click Connect to ArcGIS Server to create a new connection to ArcGIS Server.
4. In the Add ArcGIS Server window, choose Publish GIS Services. Click Next.
5. For the Server URL, type the URL of the ArcGIS Server site you want to connect to, for example, https://gisserver.domain.com:6443/arcgis.
6. From the Server Type drop-down list, choose ArcGIS Server.
7. During the publishing process, a service definition file is created and temporarily stored locally on disk. When the publishing process completes, the service definition is uploaded to the server and the local file is deleted. For the purposes of this tutorial, accept the default staging folder and continue.
8. If your server administrator has enabled security for ArcGIS Server, enter your User Name and Password. Click Finish.
9. Optionally, in the Publish a Service window, enter a new name for the service. The name cannot be more than 120 characters long and may contain only alphanumeric characters and underscores. Click Next.
10. By default, services are published to the root folder (root) of ArcGIS Server. Services can be organized into subfolders under the root folder. Choose the folder where you want to publish the service, or create a new folder to contain the service. Click Continue.
11. The Service Editor displays. You'll use the Service Editor to choose what users can do with your KML service and take fine-grained control of how the server will expose your KML service. Click the Capabilities tab.
12. By default, mapping and KML are enabled. In the left pane of the Service Editor, click KML and edit the following properties:
    • Choose the allowed operations for the KML service. For a description of each operation, see KML support in ArcGIS Server.
    • 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 Earth, Google Maps, or Google Mobile. This can increase performance.
    • Choose how to limit the features returned by the KML service, the output image size, and output client DPI.
    • Use the Use NetworkLinkControl Tag options to limit how often a service can be requested by a client.

    Tip:

    For information on how to best configure your KML service for deployment, see Tuning and configuring services.

13. Click Analyze . This examines your map document to see if it can be published to the server.

    Tip:

    To give yourself more viewing area when configuring your KML service, click the Collapse button at the top of the Service Editor.

14. Fix any Errors in the Prepare window; this must be done before you can publish. Optionally, you can fix the warnings and informational messages to further improve the performance and appearance of your KML service. For more information about resolving these issues, see Analyzing your GIS resource.

    Note:

    You can register folders and geodatabases with your ArcGIS Server site, thus ensuring that the server can recognize and use your data. If you proceed with the following steps, any data referenced by your map document originating from an unregistered folder or geodatabase will be copied to the server at the time that you publish. This is a precautionary measure to ensure that the server can access all the data used by the service. For full instructions on registering a folder or geodatabase with your ArcGIS Server site, see Registering your data with ArcGIS Server using ArcGIS Desktop.

15. Optionally, in the Service Editor, click Preview . This can give you an idea of how your map will look when viewed on the web. See Previewing your map for more information.
16. Once you've fixed the errors in your map document, click Publish .
17. Your service has now been published, and you can preview it by expanding the GIS Servers node of the Catalog window and dragging the service into the ArcMap Table of Contents.

Exploring REST KML operations exposed in the ArcGIS Server Services Directory

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

1. Open a web browser and navigate to the Services Directory, whose URL is typically https://gisserver.domain.com:6443/arcgis/rest/services.
2. In the services list, click the name of your KML service. If you don't see your service, it may be located in a folder.
3. Click the View Footprint In: ArcGIS 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.
4. Return to the Services Directory and click any layer in your service.
5. 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 KMZ as the format gives you a KMZ document containing the results of your query.
6. Navigate back to your service's page in the Services Directory.
7. At the bottom of the page, click Generate KML. This link displays a web form in which you can select the 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.

Creating a network link from your map service

You can make the KML available on your server in an easily consumable format by creating a KML network link in ArcGIS Server Manager. Then you can add the network link in ArcGIS Earth, ArcGlobe, Google Earth, or Google Maps.

Note:

Ensure that your service is not secured before adding the network link in Google Earth or Google Maps. If the service requires authentication with ArcGIS tokens, it cannot be used by these platforms.

1. Open Manager and log in. For additional help with this step, see Logging in to Manager.
2. Click Services > KML Network Links > Create Network Link.
3. Specify the name of your link. The name you specify is used as the file name and is embedded in the Name tag of the network link file.
4. Optionally, specify the External Hostname.
5. Optionally, provide short and long descriptions. The long description allows embedded HTML tags and URLs.
6. Optionally, specify the snippet behavior. By default, snippets are not configured to appear. Click Next.
7. 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.
8. 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.
9. Optionally, set the default compatibility mode to a specific Google client.
10. Adjust the View-Based Refresh, View Bound Scale, and Time-Based Refresh parameters if you want. Additionally, you can choose to have the browser fly to a view after a refresh. For this tutorial, the default options are sufficient. Click Next.
11. Optionally, set the Latitude, Longitude, Range, Heading, and Tilt parameters according to the way you want the network link to display. For this tutorial, the default options are sufficient.
12. Click Create to create the KML network link.

When you return to the KML Network Links module in Manager, you will see the URL to your new network link (for example, https://gisserver.domain.com:6443/arcgis/kml/networklink01.kmz). Click or copy and paste this URL to add your KML network link to ArcGIS Earth, ArcGlobe, Google Earth, or Google Maps.