A script tool is a geoprocessing tool that runs a script or a file type than can be run. Script tools run these scripts using a geoprocessing tool as the interface for the script. When you create a script tool, you specify parameters that the 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 and used by the 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, a 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 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 click 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 tab
The General tab includes the following properties:
- Name—The internal unique identifying name of the tool.
- Label—The name of the tool that is displayed 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.
- Attributes:
- Show banner that tool modifies the input data—Check this option to display a banner at the top of the tool dialog box to indicate that the tool modifies the input data.
- Do not add tool outputs to map—Check this option to automatically add the tool's output dataset to an open map.
Note:
If the Add output datasets to an open map geoprocessing option is also checked, the tool property attribute will still be honored.
- Show Enable Undo toggle—Check this option to display the Enable Undo toggle button next to the Run button on the tool dialog box.
- Show banner that tool consumes ArcGIS credits—Check this option to display a banner at the top of the tool dialog box if the tool consume credits.
- 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 providing 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 the toolbox is a Legacy toolbox (.tbx), there is also a property to store the path of the tool's source script relative to the toolbox file. If the 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 the toolbox is a Legacy toolbox (.tbx), the Summary, Illustration, Icon, and Attributes properties are not supported.
Parameters tab
The Parameters tab contains a table of parameter properties, where each row is a parameter. The table will be empty by default. For each parameter, define a number of properties, such as the label that is shown in the Geoprocessing pane, the type of data that the parameter accepts, and whether the parameter is optional or required. 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 | Specifies the type of data the parameter accepts. This determines the control used on the tool. For example, if you select Feature Layer, you can select 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. |
Description | Document help for each tool parameter, including instructions, information, and acceptable data types or values. Parameter descriptions display on the tool dialog box when you hover over the Information button |
Category | Providing 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 that is automatically set for the parameter when the tool's dialog box appears. |
Environment | A parameter can derive its default value from a geoprocessing environment. When 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. |
next to the parameter label.Execution tab
The Execution tab includes properties related to the source code of the script tool, or the path to a Python or R script file. The tab also includes options to embed and password protect the script tool's source code, or export the source code to a new file.
You can embed the source code within the toolbox, or link to an external script file. Regardless of the source code location, the tab includes a code editor that you can use to modify the code, or click the Open in Script Editor button to open the code in a script editor. You can specify your preferred script editor in the geoprocessing options.
Validation tab
The Validation tab displays the validation code of the script tool. Validation allows you to customize how tool parameters respond and interact with 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 the 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 which can be set in the geoprocessing options dialog box.
Environments tab
The Environments tab displays the Supported Environments and Unsupported Environments lists. 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.