Almost all tools have parameters, and you set their values on the tool dialog box or within a script. When the tool is executed, the parameter values are sent to your tool's source code. Your tool reads these values and proceeds with its work.
To learn more about parameters, see Understanding script tool parameters.
Script tool parameters can be set when creating a new 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 new parameter, click the first empty cell under the Label column and type the name of the parameter. This is the name that will be displayed on the tool dialog box and can contain spaces. Under the Name column, a default parameter name will be created based on the Label but can be changed if needed. The parameter name is needed for Python syntax and will be validated (including removal of spaces).
After entering the display name of the parameter, choose a data type for the parameter by clicking in the Data Type cell as shown below.
If you need to create a parameter that will accept multiple values, check the Multi values check box. If you need to create a composite data type, that is, a parameter that accepts different data types, you can check multiple data types.
Each parameter has additional properties you can set as shown earlier and described below.
| Property | Description |
|---|---|
Can be Required, Optional, or Derived. Derived means that the user of your tool does not enter a value for the parameter. Derived types are always output parameters. | |
Can be Input or Output. If the parameter Type is Derived, direction is always equal to Output. | |
Parameters can be grouped into different categories. | |
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 type of filter you can choose depends on the data type of the parameter. | |
This property applies to derived output parameters and input parameter data types. For derived output parameters, Dependency can be set to the parameter containing the definition of the output. For input parameters, Dependency is set to the parameter containing the information needed for input. | |
The default value for the parameter. When the parameter data type is either feature set or record set, Default is used to define the parameter's schema. | |
If the default value for the parameter is to come from an environment setting, this property contains the name of the environment setting. | |
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. |
Type
There are three choices for Type:
- A Required parameter requires an input value from the user. The tool cannot be executed until the user supplies a value.
- An Optional parameter does not require a value from the user.
- A Derived parameter is only for output parameters (see Direction below). A derived output parameter does not show on the tool dialog box.
There are five uses for a derived output parameter as follows:
- The output is the same as the input, such as Calculate Field. Calculate Field changes the values of a particular field on the input table—it doesn't create a new table or modify the schema of the input. Other examples of tools whose output is the same as the input can be found in the Editing toolbox.
- The tool modifies the schema of the input, such as Add Field. Add Field adds a field to the input table—it doesn't create a new output table.
- The tool creates output using information in other parameters, such as the Create Feature Class tool. With the Create Feature Class tool, you specify the workspace and the name of the new feature class, and the feature class is created for you.
- The tool outputs a scalar value as opposed to a dataset Get Count, for example, outputs a long integer (the number of records). Whenever a tool outputs a scalar value, the output is Derived.
- The tool will create data in a known location. For example, you may have a script that updates an existing table in a known workspace. The user doesn't need to provide this table on the dialog box or in scripting.
Note:
If your script tool has derived output, you need to set the value of the derived output parameter in your script using the SetParameterAsText or SetParameter function.
Output values instead of data
The examples above show 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 of your own that perform analysis on several related datasets and output nothing more than a couple of numbers, or a pass/fail Boolean value.
Output parameters containing value data types (such as Long or Boolean) are always Derived 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 your script tool doesn't have an output parameter, it isn't very useful in ModelBuilder. The output might be a dataset that is entered in a parameter value, a derived output where the location and or name is determined within the script, or a derived value that is calculated or determined. At the very least, you can output a Boolean containing true if the tool completed successfully, and false otherwise.
Category
Parameters can be grouped into different categories to minimize the size of the tool dialog box or to group related parameters that will be infrequently used. You can enter 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 below.
Categories are always shown after noncategorized parameters. Do not put required parameters into categories, as they are hidden from view on the tool dialog box.
Multivalue
If you want a parameter to be able to handle a list of values rather than just one value, set the MultiValue property to Yes.
An example of a multivalue control is illustrated below.
Multivalues can be accessed as lists when using the arcpy.GetParameter() function and iterated over using a for loop. Otherwise, multivalues can be accessed as a semicolon-delimited string using arcpy.GetParameterAsText(). To break apart 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))Default
The default value will be the contents of the parameter when the script's tool dialog box is 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 script's dialog box 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
When the input parameter data type is a Feature Set or Record Set, you must specify the location of a schema that defines the fields and geometry type of the features to be entered. A schema is either a feature class, table, or layer file (.lyrx).
The Feature Set and Record Set data types allow interactive input of data. A Feature Set allows the user of your script to interactively create features by clicking on the map. The Record Set allows your user to interactively create rows in a table grid.
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.
Filter
If you want only 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 opens and you specify the values for the filter. There are six types of filters, and the type of filter you can choose depends on the data type of the parameter.
Usually, there is only one filter type you can choose. Only Long and Double have two 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
For this filter, choose one or more filter values. Input feature classes will be checked against the filter values. For example, if you select only Point as the filter value, the user can only enter point feature classes as the parameter value.
A feature type filter defines the permissible feature class types: Point, Multipoint, Polygon, Polyline, Annotation, and Dimension. More than one value can be supplied to the filter.
Field
The field filter defines the permissible field types: Short, Long, Float, Double, Text, Date, OID, Geometry, Blob, Raster, GUID, GlobalID, and XML. More than one value can be supplied to the filter.
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 have to be a suffix that ArcGIS recognizes. The suffix can be of any length and does not include the dot. Multiple suffixes are separated by a semi-colon 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 supplied to the filter.
Range
A Long or Double parameter can have a Range filter. Range filters have two values: minimum and maximum. The range is inclusive, meaning the minimum and maximum are valid choices.
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 supplied to the filter.
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 valid options are Time, Distance, and Other. The default is to allow all three types.
Value List
The Value List filter is very useful for providing a set of keywords. Many tools have a predefined set of keywords, such as the Field Type parameter found in Add Field or the JoinAttributes parameter of many of the tools in the Overlay toolset.
A Value List filter can be used for Long and Double data types. For these types, you enter the allowable numeric values.
If you want the user to be able to choose more than one of the values, set the Multivalue property to Yes.
A Value List can be used for Boolean data types. For Boolean data types, the Value List contains two values: true and false. The true value is always the first value in the list. These values are used in the command line for specifying the value. See, for example, Add Field and the {NULLABLE | NON_NULLABLE} keywords used for the IsNullable property.
Workspace
The workspace filter specifies the types of input workspaces that are permissible. The three 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 supplied.
Dependency
The Dependency property has the following two purposes:
- For a derived output parameter, Dependency is set to the input parameter that will be modified by the tool. For more information on derived data and Dependency, see the discussion of the Type property 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 Dependency for certain input parameters as shown in the table below.
| Input data type | Obtained from data type | Description |
|---|---|---|
Field or SQL Expression | Table | The table containing the fields |
INFO Item or INFO Expression | INFO Table | The INFO table containing the items |
| Coverage Feature Class | Coverage | The coverage containing features |
Area Units or Linear Units | GeoDataset | A geographic dataset used to determine the default units |
| Coordinate System | Workspace | A workspace used to determine the default coordinate system |
| Network Analyst Hierarchy Settings | Network Dataset | The network dataset containing hierarchy information |
| Geostatistical Value Table | Geostatistical Layer | The analysis layer containing tables |
| Network Travel Mode | Network Data Source, Network Dataset, Network Dataset Layer | List of travel modes |
Symbology
If the output of your tool is a feature set, raster, TIN, or layer, you can specify the location of a layer file (.lyrx) in the Symbology property. When your 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.