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 can also run an R script (.r) that uses the arcgisbinding R library.
Learn more about the R-ArcGIS bridge
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
- Environments
General
The General tab includes properties such as the following:
- Name—The internal unique identifying name used by the tool.
- Label—The name displayed for the tool in the toolbox and when the tool is open on the tool dialog box.
- Description—The short description for the tool that is displayed when you hover over the tool.
- Summary—The description of the tool that is displayed when you hover over the help icon on the open tool dialog box.
- Illustration—An image that displays with the tool summary when you hover over the help icon on the open tool dialog box.
- Icon—A small image that displays when the tool is added to the ribbon, Quick Access Toolbar, or Analysis gallery.
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 illustration or 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.
Note:
If your toolbox is a Legacy toolbox (.tbx), the Summary, Illustration, and Icon properties are not supported.
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.
| Property | Description |
|---|---|
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 page 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.
Environments
The Environments page displays two lists: Supported Environments and Unsupported Environments. You can add or remove environments between these lists. Only the environments in the Supported Environments list will display on the Environments tab of the script tool's dialog box.