The data for this example comes from C:\arcgis\ArcTutor\GP Service Examples\ShortestRoute.

Network Dataset

The ToolData folder contains a file geodatabase, SanFrancisco.gdb. This geodatabase contains a network dataset, Streets_ND, within the Transportation feature dataset. This network dataset models the street network for the San Francisco area. It provides a network attribute, DriveTime, which indicates the time taken to travel each street segment.

Basemap

The basemap for this example, SanFranciscoBasemap.mxd, has a layer, Streets, as illustrated below. This layer shows the extent of the network dataset. This means that this task can be used to determine the shortest route only in this extent.

SanFranciscoBaseMap is published as a map service.

Toolbox and map document

The toolbox for the geoprocessing service is ShortestRouteService.tbx, and the source map document for the service is ShortestRouteService.mxd. ShortestRouteService.tbx contains two models and a script tool, Convert directions to HTML. This tool is used within the Calculate Shortest Route and HTML Directions model. ShortestRouteService.mxd contains two source data layers, Streets_ND (the network dataset) and Route (the network analysis layer).

Model overview

The Calculate Shortest Route and Text Directions model is illustrated below. There is one input variable, Input Stops, which are points. The shortest route visits the stops based on the digitized sequence. The model adds the user-digitized points as stops to an existing Route network analysis layer, performs a solve to determine the shortest route, generates driving directions, and writes them to a text file.

Using an existing network analysis layer

In this model, a Network Analysis layer is not created in the model as it is in the DriveTimePolygonsService example. Instead, the existing route layer, Route, is used. (This layer was created using the Make Route Layer tool.) The existing layer can be used because none of the analysis properties for the route layer, such as impedance attribute, are exposed as model parameters. In the DriveTimePolygonsService example, the default break value (an analysis property for Service Area layers) was exposed as a model parameter, so the Make Service Area Layer tool was required as a model process.

Note that if any of the route analysis properties, such as impedance attribute, are to be exposed as model parameters, the Make Route Layer tool has to be used as a first process in the model.

The Route layer used as input variable in the model was created by first adding the Streets_ND network dataset to the ShortestRouteService.mxd and then using the Make Route Layer tool. For this example, the following parameters were used for the Make Route layer tool. Default values were used for the parameters not mentioned in this table.

Parameter	Value
Input analysis network	Streets_ND
Output layer name	Route
Impedance attribute	DriveTime
Accumulators	DriveTime;Meters
U-turn policy	ALLOW_DEAD_ENDS_ONLY

Model Processes

The details about the model follow.

The Add Locations tool adds user-digitized points as stops to the route layer. The Input Locations parameter for the tool is specified through a model parameter, Input Stops. This parameter is feature set data type. The schema and symbology for the feature set are derived from the InputStops.lyr file found within the ToolData folder.

The schema for the Input Stops feature set contains a text field, Name. This field can be used to provide stops names while generating driving directions by mapping the Name property to the name field in the Field Mappings, as illustrated below. If the value for the name field is not specified by the user, a default value of Location 1, Location 2, and so on is used for stop names.

Since the same route layer is used for each model run, any existing stops need to be removed before adding the new stops. To delete existing stops, the Append to existing locations option, illustrated below, is unchecked.

The Solve tool calculates the shortest route based on the DriveTime network attribute and other options as specified in the route layer. The calculated route is written to the Routes sublayer in the output route layer .

Network analysis layers (such as Route) are not supported output parameter data types for ArcGIS Server clients. So the Select Data tool is used to get the routes sublayer from the route layer.

Learn more about the Select Data tool.

The Directions tool is used to generate the driving directions and output them to a text file. The output text file containing driving directions is created in the jobs directory on the server using %ScratchWorkspace%.

The Calculate Shortest Route and Text Directions layer is created by dragging and dropping the Calculate Shortest Route and Text Directions model into the ArcMap table of contents. Since the model updates the existing Route layer, the tool layer output derives its symbology from the Routes sublayer within the Route layer in the table of contents.

SanFranciscoBaseMap.mxd is published as a map service. ShortestRouteService.mxd is published as a geoprocessing service with no result map service, as follows:

1. In ArcCatalog, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
2. Accept all defaults.
3. In ArcCatalog, navigate to your server, right-click and choose Add New Service. Name the service ShortestRouteService and choose Geoprocessing Service as the type.
4. Click Next.
5. In the next panel you choose Synchronous for Execution type. For the tools exposed by the Geoprocessing service are stored in option, select A map option and specify ShortestRouteService.mxd for the Map Document. Since you will test your service, check Show Messages.

6. Click Next. From this point on, you can accept the default values provided by the wizard and create the service.

1. Start ArcMap with a blank document.
2. Optionally, change the background color for the data frame to light blue.
3. Add the SanFranciscoBasemap map service to the ArcMap table of contents.
4. Add the ShortestRouteService geoprocessing service to ArcToolbox.
5. Expand the ShortestRouteService toolbox and open the Calculate Shortest Route and Text Directions tool. The illustration below shows the result of these steps.

6. Add two or more points to create Stops. Optionally, specify names for each stop and click OK to run the task.
7. After the task completes, the table of contents should have the Shortest Route output layer, as illustrated below. The input stops are added to the table of contents from the results tab.

8. The text file containing the directions can be viewed by double-clicking it in the results tab.

The Directions tool used in Calculate Shortest Route and Text Directions model can generate directions in text or XML format. The directions in XML format can be converted to a nicely formatted HTML file by applying a style sheet using a Python script. The script, ApplyStyleSheet.py, found in the Scripts folder within the ShortestRoute folder, can be used to convert directions from XML to HTML format. The scripts folder also contains the style sheet file, Dir2WebDocumentNoMaps.xsl, that specifies the format of the HTML file.

Installing the external Python library

The ApplyStyleSheet.py script uses an external Python library, lib2xml. This library is not provided with ArcGIS and is not supported by ESRI. It is external, third-party software. You will need to download and install this library on your ArcGIS Server SOC machines. Navigate to http://xmlsoft.org/sources/win32/python/, download the latest libxml2 setup for Python 2.5 (for example, libxml2-python-2.6.30.win32-py2.5.exe — earlier versions may not work). After downloading, double-click the .exe to install the library.

Creating the script tool

In order to use the ApplyStyleSheet.py script in the model, it is added to ShoretestRouteService.tbx toolbox as a script tool called Convert Directions to HTML. This script tool takes the style sheet file and the XML file as input and generates an output HTML file.

Adding the script tool to the model

The Generate Shortest Route and Text Directions model is resaved as Generate Shoretest Route and HTML Directions so as to add the Convert Directions to HTML script tool. In this model, the output file type parameter for the Directions tool is changed to XML. This XML file and the Dir2WebDocumentNoMaps.xsl file are used as input variables for the script tool. The output HTML file is written to the jobs directory on the server using %ScratchWorkspace% in line variable.

Publishing and using

The Calculate Shortest Route and HTML Directions model can be published as a new task with in the ShortestRouteService geoprocessing service created earlier as described below.

1. Create the Calculate Shortest Route and HTML Directions tool layer in ShortestRouteService.mxd by dragging and dropping the Calculate Shortest Route and HTML Directions model from ArcToolbox to the ArcMap table of contents.
2. Save ShortestRouteService.mxd.
3. In ArcCatalog, Stop and Start the ShortestRouteService geoprocessing service.

The ShortestRouteService service should now have a second task called Calculate Shortest Route and HTML Directions. This task is similar to the Calculate Shortest Route and Text Directions task except that it generates the directions in HTML format.