Preparing map documents containing tool layers

Map documents containing tool layers can be published to ArcGIS Server as a geoprocessing service. Each tool layer in the map document becomes a task within the geoprocessing service. The workflow for configuring and preparing a map document containing tool layers for publication includes:

• Setting geoprocessing options
• Setting the scratch workspace environment
• Creating tool layers
• Opening and running tool layers to create output datasets
• Changing layer symbology if necessary
• Removing unneeded layers
• Making sure all layers are connected for result map services

The steps below assume that you have built a model suitable for publishing to ArcGIS Server.

Change the name of tool layers

When you add a toolbox or model to a map as a tool layer, the resulting tool layer and output sublayer(s) will be given the same name as the original model and its output parameter(s), respectively. If you change the tool layer name in the table of contents and publish the map to use in a Web application, task results will not be able to be returned to the Web application. Do not change the tool layer or output sublayer names.

Re-create tool layers when underlying tool changes

If, after creating a tool layer, you change the parameters of the model on which it is based, you must delete and re-create the tool layer. If you change the schema of a feature set, you must also re-create the tool layer.

Tool layers contain the definition of the parameters of the underlying tool. If you change the parameters in any way, you must delete and re-create the tool layer so that the new tool layer contains the new parameter definitions. It is not necessary to re-create the tool layer if you change the model or script logic—it is only necessary when you change anything related to input and output parameters.

Set geoprocessing options

1. In ArcMap, click Geoprocessing menu > Geoprocessing Options.
   • The Results are temporary by default option should be unchecked.
2. Check that you have not set the scratch workspace environment at the tool level:
   • In the ArcToolbox or Catalog window, right-click the model tool you want to publish, then click Properties.
   • Click the Environments tab.
   • If the Workspace check box is unchecked, the scratch workspace environment is not set, and you can click Cancel. If the Workspace check box is checked, expand it and make sure that Scratch Workspace is unchecked.

   • ModelBuilder allows you to set the scratch workspace environment for any process in a model. However, you should not publish models that set the scratch workspace for any process. If you are working with a model that you did not author, you should check with the model author to determine if they set the scratch workspace for any model processes. Setting the scratch workspace for model processes is not standard practice, so it is rare that you would encounter this. To check if model processes have set the scratch workspace, edit the model, right-click a tool element, click Properties, then click the Environments tab. Under Workspace, theScratch Workspace setting should be unchecked.

Set scratch workspace environment

In the above section, you made sure that the scratch workspace was not set at the tool or model process level. However, you do need to set the scratch workspace at the application level:

1. In ArcMap, click Geoprocessing menu > Environments.
2. On the Environment Settings dialog box, expand Workspace settings.
3. For the Scratch workspace environment setting, enter the path to a system folder.

Note:

• Do not set the scratch workspace to a geodatabase.
• Setting the scratch workspace is not necessary if your model does not output datasets on disk.

What happens if I do not set the scratch workspace environment?

If you leave the scratch workspace blank, the system default workspace is used. This default workspace is in the Documents and Settings folder. Windows mangles the path to the default workspace as follows:

C:\DOCUME~1\<username>\LOCALS~1\Temp\

After running your tool, your outputs are written to this location. When you publish your map document, ArcGIS Server looks for data in this location and cannot find it because the path is mangled, and your document will not publish.

Create tool layers

Creating a tool layer

To create a tool layer, drag and drop your tool from the ArcToolbox or Catalog window onto the ArcMap table of contents or map display. If the outputs of the tool exist when the tool layer is created, the tool layer will contain sublayers for each output. If the outputs do not exist, no sublayers will be created.

Open and run tool layers

After creating the tool layer, you need to run the tool layer to create all outputs of the tool.

1. Right-click the tool layer and click Open.
2. Provide the necessary inputs for your tool and click OK to run.
3. After the tool finishes running, the tool layer should contain a sublayer for each output of the tool.

The illustration below shows the tool dialog box for the Create Watershed tool found in the Watershed example.

Change layer symbology if needed

If you are creating a geoprocessing service with a result map service, the symbology defined for each sublayer in your tool layer will be used by the map service to draw results.

To change the symbology of a sublayer in the tool layer, right-click the sublayer, click Properties, then click the Symbology tab.

Learn more about symbolizing output data

Remove unneeded layers

Before publishing your map document, you should remove all unnecessary layers. For example, you may have layers from previous runs of your model or layers used to define feature set schemas. You should only keep tool layers and those layers used by your models.

Ensure that layers are connected

If you are publishing a geoprocessing service with a result map service, every layer within the map document must be a valid layer—it cannot be a disconnected layer, as illustrated below. Otherwise, the result map service cannot draw your data.

Tool layers contain a sublayer for each output of your tool. Data for these sublayers must exist for your data to be drawn.

Note:

This is a requirement only if you are using a result map service.

If you are not using a result map service, you can publish with disconnected layers. Typically, disconnected layers are the result of writing data to memory.

Note that services have a recycling schedule for automatically restarting services. By default, this restarting occurs every 24 hours at midnight. If data is deleted after publishing, your result map service will not be able to draw your data.