ArcGIS Resource Center

In this post, guest author Jeff Barrette of ESRI Olympia explains how to create a
geoprocessing service for selecting features in ArcGIS Explorer.

ArcGIS Explorer users may want to zoom to specific locations based upon data
that is available to them either locally or from a server. In ArcGIS Desktop,
users can simply select features of interest based upon feature attribute
values and then zoom to the extent of the resulting selected features. ArcGIS
Explorer does not have the equivalent of a Select By Attribute function
available but it can easily be added as a custom task. This post discusses the
steps necessary to build a geoprocessing select task that can be added into
ArcGIS Explorer to give users zoom to selected features functionality.

The general steps include first using ArcGIS Desktop to build a map document
(MXD) that contains the feature layers that need to be queried along with the
resulting selection symbology. The next step involves building a geoprocessing
model or script that performs the selection capabilities. Next, the
geoprocessing tool and the results map document need to be published and served
using ArcGIS Server. Finally, the new capabilities are added into ArcGIS
Explorer as a new, custom task.

For this example, the data referenced in the steps below is the States feature
class that is available from the ESRI Data and Maps data collection. The data
is located on the ArcGIS 9 Data & Maps StreetMap USA DVD under the
usa\census\ folder. This post is written for use with ArcGIS Desktop 9.2 (SP5),
ArcGIS Server 9.2 (SP5), and ArcGIS Explorer (build 440).

Setup

1. Create a new folder on the file system called “SelectTask”.
   It is best to organize all of the components necessary to publish a
   geoprocessing task (file based data, SDE connection files, MXDs, toolboxes,
   etc) in a single location to minimize file access and permission issues. The
   graphic below also includes a folder called Publish. It is used to organize all
   published tasks as individual project folders.
   
2. Copy the states feature class to this new location.
3. Set the appropriate permissions.
   Ideally, this folder is located on the same machine that ArcGIS Server is
   installed on. If the data is on the server, then permissions on the data should
   be all set. If on a different network drive, this folder should be shared and
   the SOC account should be granted access to it.
4. Create a connection to the ArcGIS Server as an admin user.
   If this is the first time you are publishing something to ArcGIS Server, you
   are first required to establish a connection to the server.
5. In ArcCatalog, expand GIS Servers.
   This is a node in the Catalog Tree.
6. Double-click Add ArcGIS Server.
7. Select Manage GIS Services and click Next.
8. Provide the necessary connection information and click Finish.

Note: It is also recommended that you read through the Troubleshooting
Tips section at the end of this post before proceeding with the steps
below to ensure user accounts and permissions are set appropriately.

Designing a Map Document (part 1)

1. Open a new ArcMap session and add the States layer. It is not necessary
   to modify the symbology because with the steps in this document, we will not be
   consuming and displaying the map service, but rather using the layers in it to
   query against its features. In the steps to follow, you will symbolize the
   results layer to control how the results appear in ArcGIS Explorer (or in other
   applications).

   Note: If your data source is an ArcSDE geodatabase, then see the Working
   with ArcSDE Geodatabase Data Sources section below for some suggestions
   on how to manage the ArcSDE server connections. There are some additional steps
   that should be taken to ensure ArcGIS Server can connect to the data. Copying
   the SDE connection file to the project folder makes access much easier to
   manage rather than having to set permissions on your personal profile folders.

2. Set relative paths for the data sources.
   This can be set via File > Document Properties > Data Source Options.
   Relative paths are not necessary if the ArcMap and ArcGIS Server applications
   are on the same machine but they do make it much easier to move a project
   folder from one server to another or to multiple servers all with the same data
   and models. Hard-coded paths are best if there are multiple SOC machines but
   all pointing to a single drive to access data.
3. Check the “Overwrite the outputs of geoprocessing operations” option.
   This can be set via Tools > Options > Geoprocessing tab. It is important
   that the output file name remain the same after multiple executions. If this
   option is left unchecked the output name would change (i.e., increment by one
   each time the model is run) and the applications would not be able to reference
   the correct output result.
4. Uncheck the “Results are temporary by default” option.
   This can be set via Tools > Options > Geoprocessing tab. If the results
   are going to be used in subsequent applications, it is important the results
   are not immediately cleared.
5. Save the MXD to the new folder location and name it “SelectStates.MXD”.
6. Keep ArcMap open. You will come back to the same MXD in a few steps.

Building a geoprocessing model

1. In ArcCatalog, create a toolbox called “CustomToolbox”.
   Right-click the SelectTask folder and click New > Toolbox. Your folder
   should look similar to the following:
   
2. In ArcMap, open ArcToolbox.
3. Add your CustomToolbox.
   Right-click ArcToolbox > Add Toolbox, browse to the Select Task folder, and
   click Open.
4. Set the ScratchWorkspace environment variable to the location of your project
   folder (Example: C:\Publish\SelectTask).
   Right-click ArcToolbox > Environments > General Settings > Scratch
   Workspace. It is important to do this at the application level and not just at
   the tool or model level because it is the ArcMap application that needs to
   manage the output data.
   
5. Create a new model.
   Right-click your CustomToolbox and click New > Model.
6. Change the Name property to “SelectStates”.
   Select Model > Model Properties > General Tab. The name property cannot
   include spaces or underscores.
7. Also change the Label property to “SelectStates” and click OK.
   The label property is what gets displayed in the client application and can
   contain spaces.
8. Drag and drop the States layer onto the model.

9. Drag and drop the Select tool onto the model. You can find this tool in
   ArcToolbox Analysis Tools > Extract > Select.

   Note: The Select By Attribute tool can’t be used by itself because it
   does not create an output result that gets written to disk that can then be
   accessed by other applications. In a model, Select By Attribute can be
   connected to the Copy Features command to generate the necessary file output.
   The Select command accomplishes the same end result.

10. Open the Select tool.
    Right-click on the tool and select Open.
11. Set States to be the Input Features.
    Select the layer with the blue recycle symbol next to it. This represents the
    data source added into the model. The yellow icon represents a layer located in
    the Table of Contents (TOC). If you choose the latter, you will have two
    references to the same data and one will need to be removed.

12. Set the %SCRATCHWORKSPACE% inline variable for the Output Feature Class. The
    input should look similar to the graphic below:
    

    Note: It is best to use the ScratchWorkspace inline variable when output
    results are going to be referenced from other applications. The Managed option
    works great for intermediate results but does not work well on permanent output
    results. The Managed option will automatically increment the output name with
    each successive execution therefore making it difficult for other applications
    to reference the correct data. The ScratchWorkspace inline variable should be
    used instead. In addition to ScratchWorkspace, also use the “Overwrite the
    outputs of geoprocessing operations” option and make sure the “Results are
    temporarily by default” option is turned off. These settings will ensure the
    resulting output is correctly accessed by other applications.

13. Build a default, optional expression (Example: “STATE_ABBR” = ‘AK’). This
    can be left blank but it makes it a much easier for a user to modify an already
    existing expression (i.e., its SQL structure) than it is to type one from
    scratch. Click OK.
14. Create Expression variable/parameter for Select tool.
    Right-click the Select tool and choose Make Variable > From Parameter >
    Expression.
15. Click the Auto Layout and Full Extent buttons.
    This will better organize your view of the model.
16. Set the Expression as a Model Parameter.
    Right-click the Expression object and choose Model Parameter. This will enable
    a user to enter a custom expression within the published task inside the client
    application.
17. Right-click the Expression and rename it “Enter Expression:”. How
    the expression is labeled will control how it appears in the client
    application. This is also true for how you label the model. The following
    graphic shows how the task will appear in ArcGIS Explorer.
    
18. Right-click the model output States_Select.shp and check Model Parameter.
    This will persist an output result on disk. The result is what will be sent
    back to the ArcGIS Explorer application. Note, when output is set as Model
    Parameter it cannot also be set to intermediate (temporary data). Therefore any
    results you want to send back to ArcGIS Explorer should not be intermediate.

19. Check Add to Display. This parameter is only necessary for displaying the
    result in ArcGIS Desktop. This is not necessary when publishing the model as a
    task.
    

    When completed, the model should look similar to the following graphic:
    

20. Save the model.
    Click Model > Save.
21. Close the model. Click Model > Close.

Designing a Map Document (part 2)

1. Drag and drop the Select States tool from ArcToolbox into the top portion of the
   ArcMap TOC.
   This is called a Tool Layer and it can be executed from the TOC. The Tool Layer
   will also include inputs and outputs to the model once it is executed.
2. Run the model from the tool layer.
   Right-click the Select States tool layer and select Open to open the model.
   Then click OK to run the model. A layer named States_Select.shp displaying
   the default selected state of Alaska should have been added to your TOC as part
   of the tool layer.
3. Set the symbology for the States_Select.shp layer.
   However this layer is symbolized is how it will appear in a client application.
   If you only want the result to appear in the ArcGIS Explorer results list but
   you don’t want the feature(s) to display in the view, then set the symbology to
   be nothing.
4. Uncheck the top level tool layer. The tool layer is really intended only
   to be used for publishing purposes. If it is turned on while running the model
   from ArcMap, it won’t be consistent with the layer returned from the result via
   Add to Display. The TOC should look like the following graphic:
   

Note: Models can be published in one of two ways:

First, publish an MXD containing geoprocessing tool layers. Each tool layer
becomes a task in the geoprocessing service. This method is a little easier
because all the symbology can be directly set within the MXD. Also,
geoprocessing capabilities are automatically recognized when the MXD is
published to ArcGIS Server. Both the data and tools can be consumed by client
applications. This will be the method used in the following sections.

Second, a geoprocessing toolbox can be directly published. Each tool in the
toolbox becomes a task in the geoprocessing service. If you want to control the
appearance of the input and output results, then you would need to create
additional layer files with the desired symbology that are referenced by the
tools. Publishing stand alone tools does have an advantage over publishing tool
layers.

Publishing the map with geoprocessing capabilities

1. In ArcCatalog, browse to the SelectTask folder.
2. Right-click the SelectStates MXD and choose Publish to ArcGIS Server. The
   first panel allows you to select an ArcGIS Server, specify the name of the
   service, and select or create a folder to organize your new service. You can
   optionally change these settings. Click Next.
3. Verify that the Mapping and Geoprocessing capabilities are checked and click
   Next.
   Optionally, this service could be made available to KML, WMS, or mobile
   clients.
4. Click Finish.
   To dismiss the summary page. A new map service and a new geoprocessing service
   are added to the GIS Server. Both services should be started and ready to go.
   The GIS Server connection in ArcCatalog should look similar to the graphic
   below:
   
5. Verify the service is running. A quick way to determine the service is
   working before continuing is to make sure you can preview the service in
   ArcCatalog. Simply select the SelectStates map service and click on the preview
   tab. If you can see the States displayed, then the service is running properly.
   If you don’t see anything display, then refer to the Troubleshooting Tips
   section near the end of this document.

Adding the custom task into ArcGIS Explorer

1. Open ArcGIS Explorer.
2. Click Select Tools > Manage Tasks
   This dialog allows you to control access to the tasks that can be used within
   ArcGIS Explorer. The tasks listed on the left are all those currently available
   to the application, the tasks on the right are those that are actually being
   used.
3. Click the Get Tasks button.
   This allows you to browse locally for tasks or to connect to other servers to
   add additional tasks.
4. Make sure the Servers option is selected and click ArcGIS Server.
5. Enter the appropriate connection information.
   If you are not sure of the server name or path, then look at the properties of
   the SelectStates map service via a right-click > Service Properties >
   Capabilities tab. Copy the URL information up to and including “/Services”.
   
6. Expand the resulting SelectStates toolbox, click the Select States tool,
   and click Open.
   The task has been made available to the application but is still not available
   to the current map.
   
7. Click the Select States task on the left side and move it right to make it
   available to the current map. Then click OK.
   

Using the task in ArcGIS Explorer

1. Click the Select States task in the Tasks list.
   This will open the custom task in the task window. The labels and text display
   exactly how you set them up in the model.
2. Modify the expression found in the Task Center. Because a default expression was
   created, it is easy to manipulate.
   Keep in mind that this expression could be modified however someone would need
   it to be (Example: “STATE_ABBR” = ‘WA’ OR “STATE_ABBR” = ‘RI’).
   
3. Click Run. Then double-click the result in the Results list to zoom to the
   feature extent (ArcGIS Server Service Pack 5 is required to zoom to the results).

Troubleshooting Tips

• ArcGIS Server must be properly installed using an Administrators account and
  both the GIS Server and Web Applications post installs must be completed.
• The ArcGIS SOM and SOC accounts (the defaults are ArcGISSOM and ArcGISSOC) must
  be a member of the Users group.
• The ArcGIS Web Services account (the default is ArcGISWebServices) must be a
  member of the agsadmin group.
• Be sure that your account (the person publishing the services) is a member of
  the agsadmin group.
• It may be necessary to reboot your machine in order for permissions to take
  effect.
• The ArcGISSOC account must have at least read-only access to the file-based
  data, the MXD files, toolboxes, and SDE connection files. If the local Users
  group has access, then the ArcGISSOC account also does because it is a part of
  the Users group. You would need to explicitly add ArcGISSOC if you wanted it to
  have a different set of permissions than Users (e.g., read vs read/write).
• If these files (above) are on a separate network drive, then the folder must be
  shared and the ArcGISSOC account must have at least read access to this shared
  drive.
• The ArcGISSOC account must have read/write access to the ArcGISServer
  directories. This is where the cache, jobs and output are written too.
• Confirm that IIS is properly installed and running.
• Confirm that the IIS virtual directories (argisoutput, arcgisjobs, and
  arcgiscache) exist and their permissions and local path are correct.
• Confirm that a folder that matches your ArcGIS Server instance name exists.
  This folder is created during the post install of ArcGIS Server and is found by
  default in C:\Inetpub\wwwroot.
• If you’ve made changes to the MXD (e.g., selection symbology), then you will
  need to stop and restart both the map service and the geoprocessing service.
• If you’ve made changes to the model, then remove the tool layer, rerun the
  model and add the tool layer again. Be sure to follow the steps again as
  indicated in the steps above.

Working with ArcSDE Geodatabase Data Sources

When a connection is made to an ArcSDE geodatabase data source, an SDE
connection file (*.SDE) is typically created in your Documents and Settings
folder under Application Data\ESRI\. This folder would need to be shared and
the ArcGIS Server SOC account would need to be given permissions to the folder.
An easier way to manage this is to create a copy of the *.SDE file and copy it
to the SelectTask folder as outlined below:

1. Expand Database Connections. This is a node in the ArcCatalog Tree.
2. Copy the SDE connection file. Right-click the SDE connection file
   and select Copy.
3. Paste the SDE connection file into the SelectTask folder.
   Browse to and right-click the SelectTask folder and select Paste.
4. Update all ArcMap ArcSDE geodatabase data sources to use the new connection
   file. This can be done via the layer properties Source tab. Right-click
   the layer, select properties. Select the Source tab, click the Set Data Source
   button and browse to the new connection file. Do this for each ArcSDE
   connection.