Set script tool parameters

Almost all tools have parameters, and you set their values in the Geoprocessing pane or in a script. When the tool is run, the parameter values are sent to the tool's source code. The tool reads these values and processes them accordingly.

To learn more about parameters, see Understanding script tool parameters.

Script tool parameters can be set when you create a script tool. You can also add, delete, and modify script tool parameters from a tool's Properties dialog box. To access script tool properties, right-click the tool, click Properties, and click the Parameters tab.

To add a parameter, click the first empty cell in the Label column and type the name of the parameter. This is the name that will be displayed in the Geoprocessing pane and can contain spaces. In the Name column, a default parameter name will be created based on the Label value but can be changed. The parameter name is needed for Python syntax and will be validated (including the removal of spaces).

Create a parameter.

After providing the display name of the parameter, choose a data type for the parameter by clicking in the Data Type cell as shown below.

Define a parameter's data type.

To create a parameter that will accept multiple values, check the Multiple values check box. To create a parameter that accepts different data types, that is, a composite data type,click the Add button Add.

Each parameter has additional properties you can set, as shown above and described below.

PropertyDescription

Type

The options are Required, Optional, and Derived. Derived means that the user of the tool does not enter a value for the parameter. Derived types are always output parameters.

Direction

The options are Input and Output. If the Type property is set to Derived, direction is always equal to Output.

Category

Parameters can be grouped into different categories.

Filter

If you want only certain datasets or values to be entered for a parameter, you can specify a filter. There are six types of filters, and the available types depend on the data type of the parameter.

Dependency

This property applies to derived output parameters and input parameter data types. For derived output parameters, this property can be set to the parameter containing the definition of the output. For input parameters, set it to the parameter containing the information needed for input.

Default

The default value for the parameter. When the parameter data type is either feature set or record set, this property is used to define the parameter's schema.

Environment

If the default value for the parameter is to come from an environment setting, this property contains the name of the environment setting.

Symbology

This property applies only to output parameters. The value is the location of a layer file (.lyrx) that contains the symbology for displaying the output.

Parameter properties

Type

Set the Type property to one of the following options:

  • Required—The parameter must have a value for the tool to run.
  • Optional—The parameter does not require a value.
  • Derived—Use derived parameters for the following cases:
    • The output is the same as the input. For example, the Calculate Field tool updates the values of a field in the input table. It doesn't create a table or modify the schema of the input.
    • The tool modifies the schema of the input. For example, the Add Field tool adds a field to the input table.
    • The tool outputs a scalar value such as a number, string, or Boolean value. For example, the Get Count tool returns a derived integer value.
    • The tool creates an output from values in other parameters. For example, the Create Feature Class tool returns a derived feature class path constructed from other parameters that have path and name values.
    • The tool creates data in a known location. For example, you have a script that creates a feature class in a known workspace. Neither the feature class nor the workspace are parameter options.
Note:

When a tool updates a dataset or layer, the tool must have a derived output parameter with a parameter dependency set against an input parameter. This is so that the multithreaded background geoprocessing in ArcGIS Pro identifies the map layers to disconnect during processing to protect against data lock errors and to reconnect after processing and refresh with updated properties such as selections and joins.

Note:

If the script tool has derived output, you need to set the value of the derived output parameter in the script using the SetParameterAsText or SetParameter function.

Output values instead of data

The examples above describe outputting derived datasets. Some tools, however, output values instead of datasets, such as the Get Count tool, which outputs a Long data type containing the number of rows in a table. Outputting values instead of datasets is common. You may have scripts that perform analysis on several related datasets and output only a couple of numbers, or a pass or fail Boolean value.

Output parameters containing value data types, such as Long or Boolean, always use the Derived option rather than Required.

Direction

This property defines whether the parameter is an input to the tool or an output of the tool.

If the parameter type is Derived, the parameter direction will be automatically set to Output.

All script tools should have output parameters so they can be used in ModelBuilder. The fundamental idea of ModelBuilder is to connect the output of tools to inputs of other tools, and if the script tool doesn't have an output parameter, it isn't useful in ModelBuilder. The output might be a dataset that is provided for a parameter value, a derived output in which the location or name is determined in the script, or a derived value that is calculated or determined. At a minimum, you can output a Boolean containing true if the tool completed successfully, and false otherwise.

Category

Parameters can be grouped into various categories to minimize the size of the Geoprocessing pane or to group related parameters that will be infrequently used. You can provide either a new category name or choose from a list if you have set a category for other parameters. Several ArcGIS Network Analyst extension tools use categories, as shown in the image below.

Parameter categories

Categories are shown after noncategorized parameters. Do not put required parameters into categories, as they are hidden from view in the Geoprocessing pane.

Multivalue

If you want a parameter to handle a list of values rather than only one value, set the MultiValue property to Yes.

An example of a multivalue control is illustrated below.

Multivalue control

Multiple values can be accessed as lists when using the arcpy.GetParameter function and iterated using a for loop. Otherwise, multiple values can be accessed as a semicolon-delimited string using the arcpy.GetParameterAsText function. To split a delimited string, use the Python split method as shown in the code example below.

import arcpy
road_types = arcpy.GetParameterAsText(0)
road_list = road_types.split(";")

# Process each road type
for road_type in road_list:
  # road_type contains an individual road type string (ex: "Interstates")
  arcpy.AddMessage("Processing: {}".format(road_type))

Filter

If you want certain values or dataset types to be entered for a parameter, you can specify a filter. Click the appropriate cell under Filter and choose the appropriate filter type from the drop-down list. A dialog box appears where you specify the values for the filter. There are 10 types of filters, which are described below, and the available filter types depend on the data type of the parameter.

Typically, there is only one filter type available. Only Long and Double have choices: Value List and Range.

You can also set filters programmatically with Python by customizing a script tool's ToolValidator class.

Areal Units

The areal units filter defines the permissible unit types: Square Inches, Square Feet, Square Yards, Acres, Square Miles, Square Millimeters, Square Centimeters, Square Decimeters, Square Meters, Ares, Hectares, Square Kilometers, and Unknown.

Feature Type

The feature type filter defines the permissible feature class types: Point, Multipoint, Polygon, Polyline, Annotation, and Dimension. More than one value can be provided.

For this filter, select one or more filter values. Input feature classes will be checked against the filter values. For example, if you specify only Point as the filter value, the user can only enter point feature classes as the parameter value.

Field

The field filter defines the permissible field types: Short, Long, Float, Long (64-bit integer), Double, Text, Date, OID, Time only, Date only, Timestamp with offset, Geometry, Blob, Raster, GUID, GlobalID, and XML. More than one value can be provided.

File

The file filter contains a list of file suffixes that a file may have, such as txt (simple text file) and csv (comma-separated values). You can supply any text for a suffix—it doesn't need to be a suffix that ArcGIS recognizes. The suffix can be any length and does not include the dot. Multiple suffixes are separated by a semicolon delimiter.

Linear Units

The linear units filter defines the permissible unit types: Inches, Points, Feet, Yards, Miles, Nautical Miles, Millimeters, Centimeters, Meters, Kilometers, Decimal Degrees, Decimeters, Degrees, and Unknown. More than one value can be provided.

Range

The range filter has two values: minimum and maximum. The range is inclusive, meaning the minimum and maximum are valid choices. A Long or Double parameter can use this filter.

Time Units

The time units filter defines the permissible unit types: Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Years, Decades, Centuries, and Unknown. More than one value can be provided.

Travel Mode Unit Type

This filter can be used to set the permissible travel mode types based on the unit of the travel mode's impedance attribute. The options are Time, Distance, and Other. The default is to allow all three types.

Value List

This filter can be used to provide a set of keywords. Many tools have a predefined set of keywords, such as the Field Type parameter in the Add Field tool or the Join Attributes parameter of many of the tools in the Overlay toolset.

The Value List filter can be used for Long and Double data types. For these types, you provide the allowable numeric values.

If you want the user to be able to select more than one of the values, set the Multivalue property to Yes.

The Value List filter can be used for Boolean data types. For Boolean data types, the Value List filter contains true and false values. The true value is the first value in the list. These values are used in the command line for specifying the value. For an example, see Add Field and the {NULLABLE | NON_NULLABLE} keywords used for the field_is_nullable parameter.

Workspace

The workspace filter specifies the types of input workspaces that are permissible. The values are as follows:

  • File System—A system folder used to store shapefiles, coverages, INFO tables, and grids
  • Local Database—A personal or file geodatabase
  • Remote Database—An enterprise database connection

More than one value can be provided.

Dependency

The Dependency property has the following purposes:

  • For a derived output parameter, Dependency is set to the input parameter that will be modified by the tool. For more information about derived data and the Dependency filter, see the Type property section above.
  • For input parameters, Dependency contains the name of other parameters used by the data type. For example, for an input field data type, Dependency is set to the name of the table parameter containing the fields.

You can only set the Dependency filter for certain input parameters, as shown in the table below.

Parameter data typeDependent parameter data type

Area Unit

A geographic dataset used to determine the default units.

For example, the Feature Layer, Raster Layer, Feature Set, or Record Set data type can be used.

Field

The table containing the fields.

For example, the Table View, Feature Layer, Raster Layer, Feature Set, or Record Set data type can be used.

Field Mappings

A collection of fields in one or more input tables.

For example, the Table View, Feature Layer, Raster Layer, Feature Set, or Record Set data type can be used.

Geostatistical Value Table

A table of datasets and fields to be used in Geostatistical Analyst tools.

Use the Geostatistical Layer data type.

Linear Unit

A geographic dataset used to determine the default units.

For example, the Feature Layer, Raster Layer, Feature Set, or Record Set data type can be used.

Network Analyst Hierarchy Settings

The network dataset containing hierarchy information.

Use the Network Dataset data type.

Network Travel Mode

A list of travel modes.

Use the Network Data Source, Network Dataset, or Network Dataset Layer data type.

SQL Expression

The table containing the fields.

For example, the Table View, Feature Layer, Raster Layer, Feature Set, or Record Set data type can be used.

Dependency data types

For a value table parameter, field columns have an implicit dependency on the first data column in a value table. The parameter's drop-down list for any subsequent field column will automatically include any available fields in the data.

Default

The default value is the contents of the parameter when the script tool opened. It is also the value that will be used if a # is entered for the parameter in scripting. If you don't specify a value for the Default property, the parameter value will be blank when the tool is opened. If you specify a value for this property, the Environment property will become disabled. To enable the Environment property, clear the Default property.

Schema

The Feature Set and Record Set data types allow interactive input of data. The Feature Set option allows the user of a script to interactively create features by clicking the map. The Record Set option allows the user to interactively create rows in a table grid.

When the input parameter data type is specified as Feature Set or Record Set, specify the location of a schema that defines the fields and geometry type of the input. A schema can be a feature class, table, or layer file (.lyrx). When a layer file is specified, the path to the layer file will be internalized, and if the Properties dialog box is reopened, an embedded label will appear in the cell.

Environment

You can set the default value for a parameter to the value of an environment setting by right-clicking the appropriate cell under Environment and choosing the name of the environment setting.

Symbology

If the output of the tool is a feature set, raster, TIN, or layer, you can specify the location of a layer file (.lyrx) in the Symbology property. When the tool is run and output is added to display, it will be drawn using the symbology defined in the symbology layer file.

Caution:

The layer file is read each time the tool is run. If the layer file cannot be found (because it was moved or deleted), default symbology will be used.

Related topics