Input modes and parameter data types

When you are publishing your result in the Service Editor, you specify the Input mode for each task parameter. The mode you choose determines how clients will supply a value to the task parameter. The purpose of this topic is to help you understand why some input mode options are not available for a parameter and to suggest methods for creating tasks that work with available input mode options.

To review, there are three input mode options, as follows:

• User defined value: the client provides a value for the parameter.
• Choice list: the client is given a list of strings (the choice list) and must choose one or more of the strings from the choice list. Depending on the data type of the input, the strings in the choice list can be the names of layers or simple keyword options.
• Constant value: the task will use the value you supplied for the parameter when you created the result. Since the value is constant, the client can't change it, so it will not become a task parameter when the service is published.

The input mode choices you have for a particular parameter depends on the tool's parameter data type. There are three categories of data types:

• Dataset: data stored on disk, such as a feature class, table, folder, map document, database, and so on.
• Scalar: anything that's not a dataset, such as numbers and strings.
• Value Table: a special data type that is a multicolumn table of values.

The three sections that follow discuss each of these cases in order.

Datasets

A GIS service has to work with the simplest of all clients: a web browser running on a computer that does not have any GIS capabilities. Such simple clients know only how to transport (send and receive) packets of simple data to a server, such as text, numbers, files, and geographic features and their attributes (fields). In the context of geoprocessing tasks, GIS datasets can be divided into two distinct categories: transportable and non-transportable.

• Transportable datasets are features, rasters, tables, and files. Parameters containing transportable datasets support the User defined value input mode.
• Non-transportable datasets are anything other than features, rasters, tables, and files. There are two categories of non-transportable datasets.
  • Complex datasets are datasets such as geometric networks, network datasets, topologies, TINs, and so on. These data types are known as complex datasets because they model complex relationships between simple features.
  • Container datasets are items such as folders, file and personal geodatabases, and map documents (.mxd). These data types contain a mixed collection of other datasets—hence their name, containers.
  Complex datasets and container datasets are non-transportable and do not support the User defined value input mode.

Determining the data type of a tool parameter

To determine whether a task parameter supports the User defined value input mode you can examine it in the Service Editor and see if the input mode appears as a choice. You can also establish whether User defined value is supported before entering the Service Editor by determining the data type of the tool parameter using any of the following methods:

• In a tool's reference page, the syntax section has a table describing each parameter. The last column of this table contains the parameter's data type.
• In ModelBuilder, right-click a variable, click Properties, then click the Data Type tab. The data type is listed at the top of the dialog box.
• For a script tool, in the Catalog window, right-click the script tool and choose Properties. In the properties dialog box, click the Parameters tab. The data type of each parameter is listed in the parameter table.

The following data types are transportable and support the User defined value input mode: Feature Class, Feature Layer, Feature Set, Raster Layer, Raster Dataset, Table, Table View, Record Set, and File.

Choice lists and non-transportable datasets

If an input parameter value is a layer that references a non-transportable dataset, you can choose Choice list as an input mode option. For example, the illustration below shows the Transportation mode network parameter in a task that finds the best route for the user's transportation mode—car, bike, or walk.

The data type of this parameter is Network Dataset Layer. Network datasets are complex datasets that cannot be transported across the web, so User defined value is unavailable for this parameter. However, you can use a Choice list to specify a choice list of layer names to use. The client will select one of the layer names from the choice list and your task will use the layer the client chooses, accessing the network dataset referenced by the layer and stored on the server.

Most complex datasets have a corresponding layer representation. The above example showed Network Dataset Layers. There are TIN layers, Geostatistical Layers, Parcel Fabric Layers, LAS Dataset Layers, and so on. Whenever you have a non-transportable dataset, you can use its layer representation as the input value. The example task above was created by executing a model and providing the Street network layer as input. If the model was executed by providing the path to a network dataset on disk instead of a layer name, the input mode will be set to Constant value. You must execute the tool using a layer as input in order for the Choice list option to appear.

In summary:

• Clients can send and receive (transport) simple features, rasters, tables, and files across the Internet.
• Complex datasets, such as Network Datasets, TINs, Parcel Fabrics, and so on, are non-transportable. Container datasets, such as folders, geodatabases, map documents, and so on, are also non-transportable. That is, there is no way for a client to create these complex datasets or containers and transport them across the Internet. This is true even for full-featured clients, such as ArcMap.
• Most complex datasets have a layer representation; that is, you can add the dataset to ArcMap and a layer is created in the table of contents.
  • You can create a choice list of layer names, and the client will choose one or more of these layer names as input to your task. Your task will then use the dataset referenced by the layer.
  • To create a choice list of layer names, you must execute your tool using a layer as input. In the Service Editor, the choice list will be populated from the applicable layers in the table of contents.
  • If you execute your tool using the path to a dataset on disk, the Choice list option will be unavailable, even if you have layers of the correct type in the table of contents.

Note:

When you publish a choice list of layer names, the data referenced by the layers becomes project data and will be copied to the GIS server unless it can be found in the server's data store.

Constant value and complex datasets

If an input to your task is a path to a complex dataset (for example, D:\mydata\chicago.gdb\transportation\streetnetwork, a Network Dataset), the Input mode will be fixed to Constant value. If you publish with the input mode set to Constant value, the dataset will be copied to the server (unless it's found in the server's data store) and your task will use the copied dataset.

If you can add the dataset to ArcMap to create a layer, you can rerun your tool using the layer as input. This will create a new result you can share, and the Service Editor will support Choice list as an input mode.

Note:

Layers cannot be made for geometric networks. Parameters containing geometric networks will always have their input mode set to Constant value.

Constant value and container datasets

Containers are items such as folders, file and personal geodatabases, and map documents (.mxd). These data types contain a mixed collection of other datasets—hence their name, containers. Containers are non-transportable, and the general rule is that the container and all its contents will be copied to the server (unless the container is in the server's data store). and your published task will use the copied container. Some common containers are discussed below.

Folders

If the input to your task is a folder, the Input mode will be fixed to Constant value. If you publish with the input mode set to Constant value, the folder and its contents (see note below) will be copied to the server (unless it's found in the server's data store) and your task will use the copied folder.

Note:

When folders are copied to the server as part of the publishing process, only files and geodatasets are copied; no subfolders within the folder are copied. Some geodatasets, such as file geodatabases, rasters, and TINS are technically folders, but they will be copied to the server if found within the folder to be copied.

Map documents (.mxd)

If the input to your task is a map document, the Input mode will be fixed to Constant value. If you publish with the input mode set to Constant value, the map document, all its layers, and all the datasets referenced by the layers will be copied to the server unless the map document can be found in the server's data store. If any of the referenced datasets cannot be found in the server's data store, they will be copied to the server as well. Essentially, the map document is packaged, sent to the server, then unpacked on the server.

Geodatabases

If the input to your task is a geodatabase, the Input mode will be fixed to Constant value. If you publish with the input mode set to Constant value, the geodatabase and its contents will be copied to the server (unless it's found in the server's data store) and your task will use the copied geodatabase.

Personal geodatabases (.mdb) are not supported on server platforms (64-bit Windows and Linux) and will be converted to file geodatabases when copied to the server. Enterprise geodatabases will also be converted to file geodatabases when copied to the server.

Non-transportable output

If the output of your tool is a complex dataset or a container dataset, then it cannot be transported back to the client. In the Service Editor, the output parameter will show a Data type of String. In the illustration below, the value returned by the task will be the name of the TIN dataset created, not the dataset itself.

You have several options for dealing with non-transportable output.

• Use a result map service to send the client the result as a map. No dataset is transported to the client, only a map of the data.
• Convert the dataset to a transportable dataset. For example, you could use the TIN To Raster tool to convert a TIN (non-transportable) to a raster dataset (transportable).
• Create a layer package (.lpk) of the dataset using one of the tools in the Layers and Table Views toolset, then use the Package Layer tool to create the layer package. A layer package is a file, and files are transportable across the Internet. The client will have to unpack the package.
• Use the ZIP utility to create a file of the result dataset or folder and transport the .zip file to the client. The client is responsible for unzipping the file. The clip and ship service example clips layers from a study area into a file geodatabase (and other formats), then creates a .zip file to be transported to the client. If you wish to use this technique, refer to these links below:
  • Zip.py takes an input folder and an output file name and creates a compressed .zip file.
  • Unzip.py takes an input .zip file and an output folder and writes the contents to the folder.

Scalars

A scalar data type contains anything that isn't a dataset. Scalar data types are sometimes referred to as simple data types. There are a lot of scalar data types in geoprocessing, such as Field (a field in a table), SQL Expression, Calculator Expression, Field Mappings, Fuzzy function, and a host of others. Some are rarely used. Others such as Field and SQL Expression are more common.

The following scalar data types are fully supported by all clients and can be sent and received across the Internet without conversion: Boolean, Date, Double, Linear Unit, Long, and String. Any other scalar data type is converted to a string and is referred to as unsupported or non-transportable.

Conversion of unsupported scalar data types to a string is rarely an issue because every data type has a well-defined string representation—you just need to know what it is so you can document it for your client. In some cases, you may want to modify your tool so that it does the work of composing the string representation using other information supplied by the client. Both these techniques are discussed below. One special data type, Value Table, is discussed in its own section below.

Finding the string representation of a parameter

Most string representations are obvious. For example, the string representation of a Field data type is the name of the field. Sometimes, you have to dig a little deeper to find the string representation.

The following example shows the Search radius parameter of the IDW (Inverse Weighted Distance) tool used to interpolate surfaces from points. There are three parts to this one parameter: the method (either Variable or Fixed) and two values for the Search Radius Settings, as illustrated below.

1. To find the string representation of this parameter, first look at the tool's reference page parameter syntax section. The first column of this table contains the parameter name and, for nontrivial cases, the string representation. The last column of the table contains the data type of the parameter. The illustration below shows the contents of the first column for the Search radius parameter referenced above.

   

   You can also view the Python code sample at the bottom of the tool reference page as these samples often use the string representation of parameters.

2. To view the string representation of any parameter, run the tool, right-click the result in the Results window, and choose Copy as Python Snippet. Paste the snippet into a text editor and examine it. Here's the code snippet (initial parameters removed for brevity) for a run of the IDW tool: arcpy.gp.Idw_sa(...,"2","VARIABLE 12 250","#"). Scanning along the line, you'll see that string representation for the search radius (matching the above illustration) is "VARIABLE 12 250". You can make additional runs of the tool, changing the parameter values, and copying the Python snippet to examine the string representation of any parameter.

Once you've determined the string representation, you need to tell your clients what it is. You do this in your task documentation.

Learn more about documenting services and tasks

Composing the string representation within your tool

For string representations that are complex, or put too much burden on the client to construct the string, you can modify your tool to construct the string for the client. A good example of this is the SQL Expression data type. In the model illustrated below, the Expression parameter's data type is SQL Expression, and in order for this model to run as a task, the client must supply a valid SQL expression string.

If the purpose of the task is to select a parcel based on owner name, you can create a model where the client inputs the name of the owner and a valid SQL statement is made for them. This is easily done using variable substitution, as illustrated below. The Owner name variable is a string data type; the client enters the parcel's owner name and a valid SQL expression is created within the model. Other examples of using variable substitution can be found in the topic Examples of inline model variable substitution.

Creating your own choice lists

Many geoprocessing tools define choice lists, also known as value list filters, for their string parameters. The Select Layer By Attribute tool shown above has a choice list of strings for the Selection type parameter (NEW_SELECTION, ADD_TO_SELECTION, REMOVE_FROM_SELECTION, and so on). You can create your own choice lists for string variables using value list filters.

Learn more about Value List filters

Value Tables

A Value Table is a multicolumn table used in the Intersect and Merge tools, among many others. The illustration below shows the Intersect tool, and its Input Features parameter is a Value Table with two columns: Features and Rank.

Value Tables are non-transportable, and their Input mode will be fixed to Constant value in the Service Editor.

If you need your client to enter values rather than using the constant value, you'll need to modify your model or script so that it uses other data types besides Value Table.

Value Tables can have any number of rows, and how you modify your tool depends on whether you want the client to enter a fixed or variable number of rows. If any of the columns in the Value Table contain datasets, then the number of rows will have to be fixed, because each row will need its own parameter to contain the dataset.

The illustration below shows a technique you can use in ModelBuilder to intersect two feature classes, with ranks, without exposing a Value Table. The Streets and Parks variables are automatically created by ModelBuilder when you enter them in the Value Table. The Streets Rank and Parks Rank variables are created as follows:

1. Create two stand-alone variables of type Long. Rename them and make them model parameters.
2. Open the Intersect tool and click a cell in the Ranks column, as illustrated below. You'll be able to choose one of the two Long variables you created.

You can always create a script tool that accepts individual inputs, constructs the Value Table parameter within the script, then calls the tool. The code below performs an intersect of two feature classes without using a Value Table parameter.

# Script tool to intersect two feature classes.
#  
import arcpy

inFeatures1 = arcpy.GetParameterAsText(0)  # data type = Feature layer
inRank1 = arcpy.GetParameterAsText(1)      # data type = Long integer
inFeatures2 = arcpy.GetParameterAsText(2)  # data type = Feature layer
inRank2 = arcpy.GetParameterAsText(3)      # data type = Long integer
outFeatures = arcpy.GetParameterAsText(4)  # data type = Feature class

# Default values
#
joinAttributes = "ALL"
xyTolerance = "#"
outputType = "INPUT"

# Construct the value table parameter, a list of lists
#
valueTable = [ [inFeatures1, inRank1], [inFeatures2, inRank2] ]

arcpy.Intersect_analysis(valueTable, outFeatures, joinAttributes, 
                         xyTolerance, outputType)

The example below uses the Dissolve tool to demonstrate using string representations of parameters and a variable number of rows in a Value Table. The Dissolve tool accepts a feature class or layer of lines or polygons and aggregates features based on values in one or more fields in the Dissolve Field(s) parameter. During aggregation, you can calculate statistics about the aggregated features with the Statistics Field(s) parameter—a Value Table.

As long as the client specifies dissolve fields and statistics fields found on their input features, the task will execute. In order to do this, you need create a script tool that accepts the string representation of the Dissolve Field(s) and Statistics Fields(s) parameters rather than presenting a choice list of fields found in your input features schema. In effect, you're bypassing the intelligence built into tool dialog boxes and the Service Editor and executing the tool using nothing but the string representation of the parameters.

# Script tool code to do a Dissolve using strings for the Dissolve Fields(s) and
#  Statistics Fields(s) parameters
#
import arcpy

inFeatures = arcpy.GetParameterAsText(0)      # data type = Feature layer
outFeatures = arcpy.GetParameterAsText(1)     # data type = Feature class
dissolveFields = arcpy.GetParameterAsText(2)  # data type = String
statFields = arcpy.GetParameterAsText(3)      # data type = String
multi_part = False     # Always produce single-part features
unsplit_lines = True   # Only dissolve lines if the share common vertex

arcpy.Dissolve_management(inFeatures, outFeatures, dissolveFields, statFields, 
                          multi_part, unsplit_lines)

When this script tool is executed, you'll provide the string representation for the Dissolve Field(s) and Statistics Fields(s) parameters. Using the example illustration above, Dissolve Field(s) = DISTRICT and Statistics Fields(s) = POP98 SUM;NAME FIRST. (See above for details on how to find the string representation of a data type.) In the Service Editor, you can set the two parameters to User defined value since they are strings.