ArcGIS Server Banner

GP Service example: Clip and ship

GP Service example: Clip and ship

Release 9.3 E-mail This TopicPrintable VersionGive Us feedback


Folder ClipAndShip.
Purpose Using a polygon digitized by the user, this service clips layers in the Portland map service into a file geodatabase, then creates a .zip file which is downloaded by the user.
Services Portland (map service).

ExtractPortlandData (geoprocessing service).

ExtractAndEmailPortlandData (geoprocessing service).
Geoprocessing tasks ExtractPortlandData.
Inputs Area of interest (polygon Feature Set), a table of layers to download (Record Set), and an email address to send the data.
Outputs ToGo.zip, a compressed file containing the data.
Data The example uses a small dataset of the city of Portland, Oregon.
Extensions None.
Of note Creates ToGo.zip, a compressed file containing a file geodatabase. This file geodatabase mimics the arrangement of the layers in the map service. The ExtractAndEmailPortlandData service sends ToGo.zip to the user via e-mail.

Corresponding Folder

C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip contains the completed models and data.

About this example

A common geoprocessing service is to deliver data to a user. Typically, there is a map service to display the available data and a geoprocessing task that lets the user digitize a polygon of their area of interest. Data in the map is clipped to the area of interest and then bundled and shipped to the user—hence the name "clip and ship." As illustrated below, the ExtractPortlandData task works as follows:

  1. You digitize one or more polygons that represent your area of interest. Downloaded data will be clipped to this area of interest.
  2. In the Layers to Download parameter (a Record Set), you select data you want to download by clicking the Download cell and selecting Yes or No. Note that the layer names in the parameter are the same as the map service table of contents.

Extract data task dialog

For desktop clients, the ToGo.zip file is written to the location set in your geoprocessing scratch workspace environment. To open ToGo.zip, click the Results tab in the ArcToolbox window, expand the result of the task, then double-click ToGo.zip. ToGo.zip will open and you can then extract the data to a location of your choice.

ToGo.zip in the results tab

Using the ExtractPortlandData task with ArcGIS Explorer and Web applications built with ArcGIS Server Manager, the ToGo.zip file remains on the server, as illustrated below. Users of these clients open (that is, download) ToGo.zip at a time of their choosing.

Using Save As in ArcGIS Explorer

ToGo.zip contains a file geodatabase that contains a feature data set for each group layer in the map service table of contents, as illustrated below. Raster layers are stored in the same directory as the geodatabase, not within the geodatabase.

Structure of the delivered data

This service is designed to be configurable to any map service. The Extract Portland Data toolbox in the corresponding ClipAndShip folder contains utility tools for configuring your own clip and ship service, and the section Configuring the service below shows you how.

Emailing ToGo.zip

This example also includes the ExtractAndEmailPortlandData task that e-mails ToGo.zip. E-mailing the result is a simple modification to the ExtractPortlandData task. For more information, see the section on emailing below.

Data

The data is of a small area in the city of Portland, Oregon, and is found in C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip\ToolData\Portland.gdb.

The ExtractPortlandData model uses a Feature Set and a Record Set variable, which in turn need schemas to define their feature types and fields. These schemas can be found in C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip\ToolData\Templates.gdb.

Model

The ExtractPortlandData model, shown below, is found in the ExtractPortlandData toolbox. This model makes use of custom model and script tools also found in the Clip, Zip, and Email utilities toolset in the ExtractPortlandData toolbox. (You can view the contents of these model and script tools when editing ExtractPortlandData in ModelBuilder by right-clicking the tool and clicking Edit.)

Extract Portland Data


Model element name Element type Description
Area to Download Variable: Feature Set, Model Parameter Allows the user to digitize their area of interest. (Any process that creates a polygon can be used here. For example, you could use the Buffer tool and have the user input a point and a buffer distance.)
Layers to Download Variable: Record Set, Model Parameter Contains the list of layers available for download. This list is pre-populated with all the layers in the Portland map service.
Create ToGo Folder Tool: custom model tool Creates a folder named ToGo in the scratch workspace and a file geodatabase within the ToGo folder.
File GDB Name Variable: String; input to Create ToGo folder The name of the file geodatabase to create in the ToGo folder (Portland).
file gdb Variable: Workspace; output of Create ToGo folder File geodatabase created in the ToGo folder.
ToGo folder Variable : Folder; output of Create ToGo folder The ToGo folder created in the scratch workspace.
Buildings Variable: Feature Layer; contains the Land Records\Buildings layer. The Clip By Layer Record Set tool needs a spatial reference in order to create Feature Datasets within the Portland geodatabase. This layer was chosen as the spatial reference.
Create Spatial Reference Tool: System tool Creates the spatial reference for the output data. Output data will be projected into the coordinate system contained in the spatial reference. For example, you could choose to output geographic coordinates rather than the coordinates of the Buildings layer. Or you could use the Area to Download variable (rather than Buildings) as the dataset from which to retrieve the spatial reference. Consult the Create Spatial Reference tool documentation for ways to choose a spatial reference. See Spatial reference considerations for geoprocessing services for a more in-depth discussion of setting and using spatial references.
Clip By Layer Record Set Tool: Custom script tool This script tool does the work of creating a feature dataset for each group layer in the Layers to Download record set, then clipping the layers to the Area to Download polygon, outputting them to the geodatabase in the ToGo folder.
Success Variable: Boolean Contains true if the Clip By Layer Record Set tool completed successfully. Used as a precondition to executing the Zip Folder tool.
Zip Folder Tool: Custom script tool Creates the file ToGo.zip with the contents of the ToGo folder.
ToGo.zip Variable: File, Model Parameter Output of the Zip Folder tool.

Publishing

Portland.mxd is published as a map service.

ExtractPortlandData.mxd contains the ExtractPortlandData tool layer and is published as a geoprocessing service. Since the result of the task, ToGo.zip, cannot be displayed by ArcMap, a result map service is not needed.

Learn more about publishing geoprocessing services with a source map document.

Using

A general description of how to use this service is found in the example overview above.

  1. Start ArcMap with a blank document.
  2. Add the Portland map service to the ArcMap table of contents.
  3. Add the ExtractPortlandData geoprocessing service to the ArcToolbox window.
  4. Expand the ExtractPortlandData geoprocessing service.
  5. Double-click the ExtractPortlandData geoprocessing task to open its dialog.
  6. Enter a polygon for the area to download.
  7. This step is optional. If you do not enter a polygon, all data will be downloaded.

  8. Specify layers to download by clicking a cell in the Download column and choosing Yes to download; otherwise, choose No.
  9. Click OK.

When the task completes, click the Results tab in the ArcToolbox window, expand the result of the task, then double-click ToGo.zip. ToGo.zip will open and you can then extract the data to a location of your choice.

ToGo.zip in the results tab

Configuring the service

This service has a number of features that make for a good clip and ship service.

Steps to configure the service

For the purposes of discussion, suppose you are to provide a clip and ship service for the city of Sacramento, California. In this scenario, there is an existing map service, SacramentoAreaMap, and a toolshare folder named SacramentoService containing the following:

The steps below add new data and documents to the SacramentoService toolshare folder. In the SacramentoService folder:

  1. Make a copy of SacramentoArea.mxd and rename it to ExtractSacramentoData.mxd. This map document will contain the tool layer and will be published as a geoprocessing service.
  2. Copy the ExtractPortlandData toolbox (the toolbox found in this example) from C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip into the SacramentoArea folder.
  3. Right-click ExtractPortlandData and click Properties. In the General tab
  4. Copy the Templates file geodatabase from C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip\ToolData to SacramentoArea\ToolData.

The next set of steps prepares the ExtractSacramentoData map document.

  1. Open ExtractSacramentoData.mxd.
  2. Add the ExtractSacramentoData toolbox to the ArcToolbox window.
  3. Expand the ExtractSacramentoData toolbox.
  4. Right-click the ExtractPortlandData model and click Properties. In the General tab
  5. In the ArcToolbox window, right-click and click Environments. Expand General Settings and set the Scratch Workspace environment to the Scratch folder in the SacramentoArea folder.

Changing the model

Now that the map document, toolbox and model names have been configured for Sacramento, you are ready to make changes to the ExtractSacramentoData model.

Before you edit the ExtractSacramentoData model, you first need to create a schema table for the Layers to Download model parameter. There is a utility tool in the Extract Sacramento Data toolbox that will create this table for you.

  1. Expand the Clip, Zip, and Email utilities toolset found in the Extract Sacramento Data toolbox.
  2. Double-click the Create Download Layer Schema tool.
  3. For the Schema workspace parameter, enter the SacramentoArea/ToolData/Templates geodatabase you copied in the steps above.
  4. Set the Schema table name parameter to LayerSchema.
  5. In the Feature Layers parameter, you will enter the feature layers you want to allow the users to download. The Feature Layers parameter is a multivalue parameter, meaning you can enter multiple values. As illustrated below, you click the drop-down arrow to expose the list of layers. After you select a layer, it will be added to the list of layers found below the drop-down list. Note that the illustration shows the layers in the ExtractPortlandData map document. This list would be different for our hypothetical ExtractSacramentoData map document.
  6. Create Download Layer Schema tool dialog

  7. If there are raster layers you want to allow for download, add them to the Raster Layers parameter.
  8. Learn more about using a multivalue parameter control.

  9. Click OK to run the tool. The schema table will be created in the schema workspace.

Now that you have created the LayerSchema table, you are ready to edit and change the ExtractSacramentoData model. The variables you need to change are illustrated below.

Modifications

  1. Right-click Area To Download and click Properties.
  2. Choose a spatial reference for the output data. Double-click the Create Spatial Reference tool and either
  3. See the Create Spatial Reference tool documentation for more information on ways to choose a spatial reference.

    Learn more about spatial references in geoprocessing services.

  4. Double-click File GDB Name and enter the name of the file geodatabase to contain the extracted data. This geodatabase will be sent to the user. In this scenario, you would enter something like Sacramento.gdb or Features.gdb.
  5. Right-click Layers to Download and click Properties.
  6. Save and close the model.
  7. Create a tool layer for ExtractSacramentoData, save the map, and publish as described above.

If the SacramentoAreaMap map service is updated by adding or deleting layers in SacramentoArea.mxd, you will need to update the ExtractSacramentoData model and map document. The general steps are

Emailing the result

The ExtractAndEmailPortlandData task, illustrated below, adds the ability to e-mail ToGo.zip to the task user. The Email File tool is a script tool and can be found in the Clip, Zip, and Email utilities toolset in the ExtractPortlandData toolbox.

ExtractAndEmailPortlandData

To publish this model as a task, create a tool layer for the ExtractAndEmailPortlandData model and publish.

In order to e-mail the .zip file, you must edit the model and supply the name of your e-mail server. Your system administrator should be able to supply you with the name of your e-mail server. If your e-mail server requires authentication, you will need to edit the Email File script (right-click Email File and click Edit) and follow the instructions in the send_mail routine located near the top of the script, as shown below.

    # If your server requires user/password, uncomment the smtp.login code
    #  below and supply your server user/password.
    #
    # smtp.login(user, password)

Why e–mail the result?

ArcGIS Server clients (ArcGIS Desktop, ArcGIS Explorer, and Web applications) all allow the user to download the ToGo.zip file, so it is not necessary to e-mail the file. However,

By e–mailing ToGo.zip, you avoid any issue with job directory cleanup.

Learn more about the ArcGIS Server job directories.

Note that this is not a problem for ArcGIS Desktop clients since ToGo.zip is immediately downloaded to the user's computer. (It is downloaded to the location specified by the geoprocessing scratch workspace environment setting. If this location is not a system folder, ToGo.zip is downloaded to the user's system temp directory.) In addition, custom Web applications can immediately download the file for the user.

The disadvantage to e–mailing the result is that it may be large and clog up the user's e-mail. There is logic in the Email File script that prevents e-mailing large files.

In addition, the script contains code for e-mailing the URL to the zip file, rather than attaching the zip file.

See Also

  • Guide to the geoprocessing service examples