Running custom (model or script) tools in the background

Executing a tool in the background allows you to continue interacting with the application (like ArcMap) and perform other tasks while the tool is running.

By default, model or script tools run in the foreground. If you want your tool to run in the background, you need to resolve the issues described below. After you have ensured that your models and scripts have corrected these issues, you can run your tool in the background with the following steps:

1. In the Catalog or ArcToolbox window, right-click your tool and click Properties. On the General tab, uncheck Always run in foreground and click OK.
2. On the ArcMap menu, click Geoprocessing > Geoprocessing Options. On the Background Processing pane, check Enable.

The issues you have to resolve are

1. Using map document layers—This is both a model and a script tool issue.
2. Using current map document in script tools—This is a script tool specific issue.

Issue 1—Using map document layers

Model example

When a model tool is executed in the background, only the layers that participate as model parameters are available to the background process. For example, the following model allows the user to input an area of interest, a base contour, and a contour interval to produce a contour feature class. This model has four parameters (3 input and 1 output). Note how the Elevation Raster variable is a layer in the ArcMap table of contents but is not set as a model parameter. When this model is run using its tool dialog box, the user inputs the Potential Landfill Site layer for the Area of Interest parameter but does not have to provide the Elevation Raster layer; it's not a parameter.

The above model will run as expected in foreground. However, if this model is set to run in background, it will fail with the warning "None of the processes are ready to run", as illustrated below. The reason it fails is that processes running in the background cannot use layers that are not tool parameters. In this case, the Elevation Raster model variable is not a parameter, so the background process cannot find it and fails with the warning.

Solutions

There are several ways you can change the model so that it runs in the background.

• Make the layer variable a model parameter. Doing so will pass the layer to the background process, and the tool will execute in the background. This is the simplest solution.
• Instead of using a layer, use a dataset on disk. In the above example, you double-click the Extract by Mask tool and change the Input Raster parameter (represented by the Elevation Raster variable) to use a raster dataset rather than a layer from the table of contents. The only issue with this solution is that layers can have selections, while datasets on disk do not. If you are using a layer variable because you need to use layer selections, you cannot use a dataset on disk. In this case, you have two alternatives (other than making the variable a model parameter):
  • In the model, add the Make Feature Layer tool to create a layer variable from a dataset variable and use the layer variable as input to the next model process. (The Make Feature Layer tool allows you to enter a selection expression.)
  • Create a layer file (.lyr) and use the .lyr file in the model. That is, in the above model, the Elevation Raster variable would point to a .lyr file. You can create a .lyr file with the Save To Layer File tool.

Note:

In addition to setting model parameters for input layers, all other layers created or updated by the model must be set as a model parameter.

Script tool example

Script tools have the same issue as model tools when using layers as inputs. Each layer must be passed as both a parameter and must be the appropriate geoprocessing data type. Script tools offer flexibility and choice; for example, they can act against layers by using a string data type that matches a layer name in the table of contents. Even though this method works in foreground, it will not work in background because there is no connection from the map layer reference to the background process. The following illustration demonstrates a parameter layer being passed as a string and the modified script properties to use a layer as input.

Solutions

Ensure that your script tool parameters use appropriate data types, such as Feature Layer, Raster Layer, and Table View.

If your script tool is using a layer that is not a parameter, you will need to

• Make the layer a parameter.
• Instead of using a layer, use the dataset on disk or a .lyr file on disk.

Issue 2—Using current map document in script tools

Script tools that operate against the current map document must be run in the foreground. The MapDocument class is a powerful way to leverage your current map document through script tools. For example, you may have a script that automatically zooms to the features you just selected. Running the following script will produce the error "Object: CreateObject cannot open map document".

Example script that selects features and zooms to them using ArcPy Mapping

import arcpy

idvalue = arcpy.GetParameterAsText(0)

mxd = arcpy.mapping.MapDocument("CURRENT")

arcpy.SelectLayerByAttribute_management(
    "Parcels", "NEW_SELECTION", '"ID" = ' + idvalue)
df = arcpy.mapping.ListDataFrames(mxd)[0]
df.zoomToSelectedFeatures()

Learn more about working with CURRENT in the MapDocument class.

Solution

Script tools that use the current map document must always run in foreground. In the Catalog window, right-click your script tool and click Properties. On the General tab, check Always run in foreground.

Tools running tools

Suppose you have a script tool that uses the current map document as described above, and this tool must always run in the foreground. What happens if you use this script tool in a model tool, and the model tool runs in the background? The answer is that models are aware of tools within the model that must execute in the foreground. If any tools must run in the foreground, the model will automatically run in the foreground.

Note:

If you want to run a model in the background and find you are prevented from doing so because Always run in foreground is checked and disabled, examine the properties of the model or script tools it uses and ensure that Always run in foreground is unchecked for these tools.