Geoprocessing service example: Clip And Ship—Documentation

Complexity: BeginnerData Requirement: ArcGIS Tutorial Data for Desktop

About this example
Folder	ClipAndShip
Purpose	Using a polygon digitized by the user, this service clips layers from the study area into a file geodatabase, then creates a .zip file that can be downloaded by the user.
Services	Zion (Map service), ExtractZionData (Geoprocessing service)
Geoprocessing tasks	ExtractZionData
Inputs	Layers to Clip, Area of Interest, Feature Format, Raster Format
Outputs	A ZIP file containing the data.
Data	The example uses a number of datasets from the study area of Utah's Zion National Park.
Extensions	None
Of note	Creates output.zip, a compressed file containing a file with the format specified. This file mimics the arrangement of the layers in the ArcMap document that is published as a geoprocessing service.

Corresponding Folder

The data for this example can be downloaded from ArcGIS.com. Once downloaded, extract the zip file to C:\arcgis\ArcTutor\. The GP Service Examples\ClipAndShip folder contains the completed models and data.

About this example

This example shows the detailed steps of sharing and using a map and a geoprocessing service. The model ExtractZionData used in the service is derived from the Extract Data Task model tool. The geoprocessing task lets the client select the layers they want returned, digitize a polygon (or multiple polygons) that defines the area of interest, and select the output feature and raster data format. Data in the map is clipped to the area of interest, then bundled as a ZIP file ready to ship to the client.

Data

The study area for this example is a Zion National Park. Data includes research area, boundary, tracts, roads, trails, springs, streams, and a hillshade raster of the study area. The data can be found in C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip\ToolData\Zion.gdb.

Make a server managment connection for publishing

Make sure you have the permission to publish to the server. If you do, follow the steps to create, publish, or manage connection to a server:

Go to GIS Servers > Add ArcGIS Server to bring up the ArcGIS Server dialog box.
Check Publish GIS Services or Administer GIS Server.
On the General panel, enter the Server admin URL and provide values for User Name and Password.
Click Finish to complete the connection.

Share a map service

Follow the next steps to create a map service that users of your service can use as a reference map:

From the Catalog window, navigate to C:\arcgis\ArcTutor\GP Service Examples. Copy the folder ClipAndShip from C:\arcgis\ArcTutor\GP Service Examples to a local directory.
From the local directory where you save the folder ClipAndShip, open Zion.mxd.
From the ArcMap menu bar, select File > Share as > Service. The Share as Service wizard opens.
In the first panel of the Share as Service wizard, choose Publish a Service and click Next.
In the Choose a connection drop-down list, choose the name of the server you connected to previously. The default Service name is Zion (the name of the map document). You can accept the default name or enter a new one.
In the next panel, provide your service folder or accept the default of [root] and click Continue. The Service Editor opens.
In the Service Editor, click the Capabilities tab. Mapping and KML are checked by default. KML capability is not needed for this service, so uncheck the KML check box.
In the Service Editor, click the Item Description tab, and enter the required Summary and Tags.
Click the Analyze button on the upper right of the Service Editor. The Prepare window opens.
If you see any warning or error messages in the Prepare window, fix them by right-clicking the row with error or warning message, then click the highlighted message.
After you've resolved any errors, click the Publish button on the upper right of the Service Editor. You should get a successful message when publishing completes.

The Zion map service is published and ready for use.

Share a geoprocessing service

You need to run the tool to create a result to share the tool as a service. To run the tool:

From the local directory where you saved the folder ClipAndShip, open ClipAndShip.mxd.
In the Catalog window, click the Go To Home Folder button. Expand ExtractZion.tbx and double-click the model tool ExtractZionData to open its dialog box.
For the Layers to Clip parameter, set the layers you would like to expose to users in the service.
For the Area of interest parameter, click the Area_of_Interest symbol as illustrated above and digitize a polygon on the map.
You can accept the default values for all other parameters.
Click OK to run the tool.
When the tool finishes executing, a new result will be written to the Results window. To open the Results window, select Geoprocessing > Results in the ArcMap main menu.
Check that the tool executed successfully by examining the result in the Results window. A failed execution will display an error icon next to the result.

To create a geoprocessing service, you share a result.

In the Results window, right-click the ExtractZionData result and select Share As > Geoprocessing Service. The Share As Service wizard opens.
Choose the server you connected to previously and publish to the same folder as the map service you created. The default name of the service is the same as the tool name, ExtractZionData. You can accept the default service name or enter a new name.
On the last panel of the Share As Service wizard, click Continue to open the Service Editor.

You can accept all the default values for the geoprocessing service and click the Publish Publish

button to publish the service.

See the topic A quick tour of publishing a geoprocessing service for more information on using the Service Editor to publish a geoprocessing service.

In the Service Editor, you can refine the choice list of layers a client can choose. Click the Layers to Clip tab to see the list of layers clients can extract. You can uncheck layers you do not want to expose to clients.

Using

The following steps show how to use the map and geoprocessing services that you previously published.

Open a new ArcMap document.
In the Catalog window,
1. Navigate to your server connection under GIS Servers, select the map service Zion, and drag it into the ArcMap table of contents.
2. Expand the Zion map service in the table of contents, and you will see all the layers belonging to the Zion map service.
In the Catalog window, navigate to your server connection under GIS Servers, find the geoprocessing service that you published in a previous section, and expand it. The task ExtractZionData appears.
Double-click the task ExtractZionData to open the task dialog box.
In the ExtractZionData dialog box is the Layers to Clip parameter as illustrated below. Note that the layer names in the check box are the same as the layers of the Zion map service in the table of contents. Check the box next to each layer that you want to be included in your download.

The Area of Interest parameter is used to digitize an area of interest that will be used to clip each of the layers selected in the Layers to Clip parameter. Click the Area_of_Interest symbol and digitize a polygon on the map.
Other input parameters, Feature Format and Raster Format, can be modified or left as default.
Click OK to run the geoprocessing task.
The output is returned from the server and written to the location set in your geoprocessing scratch workspace environment.

When the task completes, open the Results window to view the results of the task. Double-click output.zip to open the compressed file, then extract the data to a location of your choice.

Customizing the geoprocessing service source model

The previous example uses the model tool Extract Data Task from the Server toolbox. This model does nothing more than set parameters for the Extract Data tool. If you copy the model tool to a new custom toolbox, it can be opened in ModelBuilder and edited. The Extract Data Task model contains the input variables Spatial Reference and Customized Spatial Reference Folder, which are not exposed as model parameters. Spatial Reference has a default value, Same as Input, which means the spatial reference of the output files is the same as the input layers. If you want to get a spatial reference of the output files, which is different from that of the input files, you can set Spatial Reference as an input parameter so that when the model tool dialog box is opened, a different spatial reference can be specified. The variable Custom Spatial Reference Folder is an optional parameter that allows you to specify a path to a folder that contains custom and/or standard spatial references.

In addition to the two spatial reference variables, the Feature Format parameter can also be modified to contain additional formats you need.

The following steps show how to customize the Extract Data Task model by exposing the variable Spatial Reference as a parameter, adding a path for the custom spatial reference folder, and adding new output formats for the Feature Format parameter.

Note:

A toolbox named CustomSPRef.tbx containing a customized ExtractZionSPRef model can be found in C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip. The toolbox and model are the finished product after performing the following steps.

The first step is to create a new toolbox and model. From Catalog, copy the folder ClipAndShip from C:\arcgis\ArcTutor\GP Service Examples to a local directory.
1. From your local directory where you copy the data and model to, open ClipAndShip.mxd.
2. In the Catalog window, click the Go To Home Folder button. Delete the toolbox CustomSPRef.tbx and SpatialReference folder.
3. Right-click the Home folder and select New > Toolbox.
4. Rename the toolbox to CustomSPRef.
In the Catalog window,
1. Expand Toolboxes > System Toolboxes > Server Tools.tbx > Data Extraction.
2. Right-click Extract Data Task and select Copy.
3. Right-click the CustomSPRef.tbx that you created above and select Paste.
  The model Extract Data Task is copied to the toolbox.
4. Right-click the copied model and select Rename, then rename the model to ExtractZionSPRef.
Right-click ExtractZionSPRef and select Edit to open the model in ModelBuilder. In the model, right-click the variable Spatial Reference and select Model Parameter. The letter P appears on the upper right-hand corner of the variable to signify that it is a model parameter.
Create a customized spatial reference folder and a projection file. Save the projection file in the folder.
1. In the Catalog window, right-click the Home folder. Create a new folder by right-clicking the folder and selecting New > Folder.
2. Rename the new folder SpatialReference.
3. From the Home folder, navigate to ToolData/Zion.gdb . Right-click any feature class in the geodatabase and select Properties to open the Properties dialog box. Click the XY Coordinate System tab.
4. Expand Projected Coordinate System/State Plane/NAD 1983 (US Feet). Scroll down the list until you find NAD 1983 StatePlane Utah South FIPS 4303 (US Feet).
5. Right-click NAD 1983 StatePlane Utah South FIPS 4303 (US Feet) and select Save As.
6. Save the projection file in the new folder, SpatialReference, that you created in step b above. Save the file with its default name of NAD 1983 StatePlane Utah South FIPS 4303 (US Feet).prj.
From the Home folder, expand CustomSPRef.tbx, right-click the model ExtractZionSPRef, and select Edit. Double-click the variable Custom Spatial Reference Folder, and enter the path to the new SpatialReference folder you created in the steps above, then click OK. The model will appear similar to the one illustrated above.
With the ExtractZionSPRef model still open in ModelBuilder
1. Go to the Model menu > Properties > Parameters tab.
  The parameter Spatial Reference appears at the bottom of the parameter list.
2. Reorder the parameters so the Output Zip parameter is the last parameter. Select Output Zip and click the Down button to move it to the bottom of the list.

Still in the Parameters tab
1. Select the variable Spatial Reference, then change the Filter value to Value List.
2. Enter the values Same As Input and NAD 1983 StatePlane Utah South FIPS 4303 (US Feet) to the value list. Make sure you enter these values exactly as written. NAD 1983 StatePlane Utah South FIPS 4303 (US Feet) is used by the tool to find the .prj file you saved previously.
3. Click OK to close the Value List dialog box.
4. Click OK to close the model Properties dialog box.
5. Save the model and exit ModelBuilder.

The Feature Format parameter can also be customized by adding more data types to the list of formats.

Learn more about the different data formats supported by the Data Interoperability extension

Save the customized model.
Run the customized model on the desktop. When running the model, choose NAD 1983 StatePlane Utah South FIPS 4303 (US Feet) from the Spatial Reference parameter drop-down list.
Refer to the instructions in the Publishing and Using sections above to publish and use the customized model as a geoprocessing service.