GEOG 863
GIS Mashups for Geospatial Professionals

8.1 Understanding geoprocessing service documentation

PrintPrint

Geoprocessing services appear in the ArcGIS Services Directory with a label of GPServer. For example, on Esri’s sampleserver1 instance of ArcGIS Server, the Elevation folder contains a service called ESRI_Elevation_World. The Network folder contains one called ESRI_DriveTime_US. Let’s explore this second service further.

First, follow the link to the ESRI_DriveTime_US service page.

On the service page, you’ll see a short Service Description and a list of the Tasks the service can perform. Note that this service calculates where a driver can go from some starting point in a specified time (in minutes).

Now, click on the CreateDriveTimePolygons link to learn more about that task. (FYI, as far as I can tell, the CreateDriveTimePolygonsDisks task is identical.)

A critical part of the task’s documentation is the Parameters section. To implement a task in a JavaScript app, you’ll need to pay close attention to the following bits of information:

Label

Description

Parameter

Name of the parameter, which you’ll need to specify in your code

Data Type

The kind of data you must supply for this parameter
Common data types are GPString for a string, GPDouble for a Double, and GPFeatureRecordSetLayer for geometries

Direction

esriGPParameterDirectionInput means the parameter is an input to the task; esriGPParameterDirectionOutput means the parameter is an output of the task

Geometry Type

When the Data Type is GPFeatureRecordSetLayer, this tells you what kind of geometry (Point, Polyline, Polygon) is expected

Parameter Type

Indicates whether the parameter is required or optional

Looking at the CreateDriveTimePolygons task, you should note that it has two input parameters (Input_Location and Drive_Times) and one output parameter (Output_Drive_Time_Polygons).

The Data Type of the Input_Location parameter (GPFeatureRecordSetLayer) may seem a bit confusing, but the important thing to remember as a JS API developer is that you’ll want to use a FeatureSet object in your code to satisfy this parameter. You might recall dealing with this type of object – an array of Graphic objects – earlier when working with the response from FeatureLayer.queryFeatures(). In this context, you’ll create a FeatureSet and assign your own array of Graphics to it. Often the array is just a single point, polyline or polygon drawn on the map by the user.

Getting back to the CreateDriveTimePolygons task, other pieces of the Input_Location parameter’s documentation tell us that the supplied geometry must be a Point and that the parameter is required.

The next parameter, Drive_Times, is a string and is optional. It turns out that more information on this parameter can be found by following the Help URL link near the top of the page. On the task’s Help page, the Usage Tips tell us that this parameter should be space delimited, that the highest value allowed is 15, and that the drive times should be entered from smallest to largest.

Back on the main documentation page, we can see that the output parameter is also a FeatureSet, this time of type Polygon. Based on what we learned from other parts of the documentation, we can expect the output to include one polygon for each value in the Drive_Times string. Finally, we can see the attribute fields (e.g., FromBreak and ToBreak) that the polygons will have.

The task’s documentation page contains one more important bit of information. The Execution Type value (near the top of the page) tells us whether the task should be run synchronously (for quick tasks) or asynchronously (for longer ones). The Supported Operations link (near the bottom of the page) will say Execute Task for synchronous tasks and Submit Job for asynchronous tasks. As we’ll see, these correspond to two different object methods when calling on the service in JS code.