Create a script tool

A script tool is a geoprocessing tool that runs a script or executable file. Script tools run these scripts using a geoprocessing tool as the interface for your script. When you create a script tool, you specify parameters that your script needs to run. The most common parameters are input and output datasets, field names, and strings chosen from a choice list. When the script tool runs, the parameter values are passed to your script and used by your script.

Many script tools run a Python script (.py) that uses ArcPy, a Python site package installed with ArcGIS. ArcPy provides access to geoprocessing tools as well as additional functions, classes, and modules that allow you to create simple or complex workflows. Through ArcPy, your script can access the geoprocessing environment of ArcGIS, providing benefits such as on-the-fly projection, selection set support, validation of inputs, error messaging, and recording of history.

Script tools are created in a toolbox. To create a script tool, right-click a toolbox in the Catalog pane and select New > Script.

Properties

When you create a script tool, that script tool's properties dialog box appears with the following side tabs:

  • General
  • Parameters
  • Execution
  • Validation

General

The General tab includes properties such as the tool name, label, description, and icon. You can change the properties by typing values in the text box, or by clicking the icon to browse for a new image file to use as the icon.

Note:

If your toolbox is a Legacy toolbox (.tbx), there is also a property to store the path of the tool's execution script relative to the toolbox file. If your toolbox is an ArcGIS toolbox (.atbx), this behavior is managed differently. If the script is in the same directory as the .atbx file or is in a child folder from where the .atbx is stored, a relative path is maintained. If the script and .atbx file are completely separate, an absolute path is maintained.

Parameters

The Parameters tab presents a table of parameter properties, where each row is one parameter. The table will be empty by default. For each parameter, you define a number of properties, such as the label that appears for that parameter in the UI, what type of data the parameter accepts, and whether the parameter is optional or required. You must, at a minimum, set the parameter Label, Name, Data Type, Type, and Direction properties.

PropertyDescription

Label

The name of the parameter displayed on the tool.

Name

The name of the parameter when the script tool is called as a function from a different Python script.

Data Type

The type of data the parameter accepts. This determines the control used on the tool. For example, if you select Feature Layer, you can pick a layer from an active map or browse to a feature class.

Type

Parameters can be required or optional. If the parameter is required, it must have a value or the tool cannot run. If the parameter is optional, the tool can run without specifying a value.

Direction

Parameters can be input or output. Input parameters represent existing data to be processed or values to use in processing. Output parameters represent data the tool creates or values that are calculated.

Category

Entering the name of a category puts the parameter in a drop-down group on the tool's dialog box.

Filter

Filters allow you to limit the specific types of a dataset, file, or field; specific values; or values in a range that are acceptable input to a tool. For example, you can filter a feature class parameter so only point feature classes are acceptable, or you can filter a number parameter so only values between 1 and 10 are acceptable.

Dependency

You can make one parameter dependent on another parameter. For example, a field parameter is dependent on a dataset parameter; setting this dependency makes it so you can select a field from the dependent dataset.

Default

A value automatically set for the parameter when the tool's dialog box appears.

Environment

A parameter can derive its default value from a geoprocessing environment. So if the specified geoprocessing environment is set, the value will be used as the default for the given parameter when the tool's dialog box appears.

Symbology

The path to a layer file that defines the symbology of the parameter. For example, you can make an output dataset parameter have the same symbology of the layer file when the output is created and added to the map.

Execution

The Execution tab includes properties related to the execution code of the script tool, or the path to a Python or R script file. The page also includes options to embed and password protect the script tool's execution code, or export the execution code to a new file.

You can choose to embed the execution code within the toolbox, or link to an external script file. Regardless of the execution code location, the page includes a code editor that you can use to modify the execution code, or click the Open in Script Editor button to open the execution code in a script editor. You can specify your preferred script editor in Geoprocessing options.

Validation

The Validation page displays the validation code of the script tool. Validation allows you to customize how tool parameters respond and interact to values and other parameters on the script tool. Validation code is written in Python.

The ToolValidator Python code block gives you control of the appearance, behaviors, and messages of your script tool. You can edit the Validation code directly from a code editor, or click the Open in Script Editor button to open the validation code in your preferred script editor that is set in Geoprocessing options.

Related topics