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
usacensus folder. This post is written for use with ArcGIS Desktop 9.2 (SP5),
ArcGIS Server 9.2 (SP5), and ArcGIS Explorer (build 440).
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.
- Copy the states feature class to this new location.
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.
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.
In ArcCatalog, expand GIS Servers.
This is a node in the Catalog Tree.
- Double-click Add ArcGIS Server.
- Select Manage GIS Services and click Next.
- 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)
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
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.
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.
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.
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.
- Save the MXD to the new folder location and name it “SelectStates.MXD”.
- Keep ArcMap open. You will come back to the same MXD in a few steps.
Building a geoprocessing model
In ArcCatalog, create a toolbox called “CustomToolbox”.
Right-click the SelectTask folder and click New > Toolbox. Your folder
should look similar to the following:
- In ArcMap, open ArcToolbox.
Add your CustomToolbox.
Right-click ArcToolbox > Add Toolbox, browse to the Select Task folder, and
Set the ScratchWorkspace environment variable to the location of your project
folder (Example: C:PublishSelectTask).
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.
Create a new model.
Right-click your CustomToolbox and click New > Model.
Change the Name property to “SelectStates”.
Select Model > Model Properties > General Tab. The name property cannot
include spaces or underscores.
Also change the Label property to “SelectStates” and click OK.
The label property is what gets displayed in the client application and can
- Drag and drop the States layer onto the model.
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.
Open the Select tool.
Right-click on the tool and select Open.
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.
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.
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.
Create Expression variable/parameter for Select tool.
Right-click the Select tool and choose Make Variable > From Parameter >
Click the Auto Layout and Full Extent buttons.
This will better organize your view of the model.
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
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.
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.
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
When completed, the model should look similar to the following graphic:
Save the model.
Click Model > Save.
- Close the model. Click Model > Close.
Designing a Map Document (part 2)
Drag and drop the Select States tool from ArcToolbox into the top portion of the
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.
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.
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
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
Publishing the map with geoprocessing capabilities
- In ArcCatalog, browse to the SelectTask folder.
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.
Verify that the Mapping and Geoprocessing capabilities are checked and click
Optionally, this service could be made available to KML, WMS, or mobile
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
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
- Open ArcGIS Explorer.
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
Click the Get Tasks button.
This allows you to browse locally for tasks or to connect to other servers to
add additional tasks.
- Make sure the Servers option is selected and click ArcGIS Server.
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”.
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.
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
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.
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’).
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).
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
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
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:Inetpubwwwroot.
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 DataESRI. 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:
- Expand Database Connections. This is a node in the ArcCatalog Tree.
Copy the SDE connection file. Right-click the SDE connection file
and select Copy.
Paste the SDE connection file into the SelectTask folder.
Browse to and right-click the SelectTask folder and select Paste.
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