Tutorial: Publishing a geoprocessing service

With ArcGIS Server, you can publish geoprocessing services that allow you to submit jobs to the server and get back a set of results. The server accesses the model and does the work, freeing your computer’s resources and eliminating the problem of sharing copies of the model.

Many ArcGIS applications can use geoprocessing services, including ArcMap, ArcGIS Explorer, and Web mapping applications that you create with ArcGIS Server. This tutorial focuses on building a geoprocessing service for use within a Web mapping application. If you’re interested in building a geoprocessing service that will be mainly used in ArcMap, see the similar documents in the ArcGIS Desktop Help called Example geoprocessing service and Example map service with geoprocessing

Concepts

Before getting started with creating a geoprocessing service, you should know the following:

What’s required to create a geoprocessing service?

Building a geoprocessing service requires that you first create a model using the ModelBuilder feature in ArcGIS Desktop. A model is a logical sequence of geoprocessing tools and scripts that help you automate a GIS operation. A model contains tools from ArcToolbox and, optionally, scripts that you’ve written to help automate your work. You can’t publish individual tools or scripts as geoprocessing services; you can only publish models. It’s possible, however, to publish a model that contains only one tool or script.

If you haven’t previously worked with models in ArcGIS, or you need a review, a good place to start is An Overview of Models in the ArcGIS Desktop help.

What types of data can you use in your model?

Geoprocessing services support a limited set of input and output data types. In order for your model to run correctly on the server, you need to verify that all of the input and output data types used by your model are supported. There are different strategies for modifying your model so that it uses only supported input and output data types. You can find these strategies, along with a list of all supported data types, in the topic Considerations for authoring and publishing models.

The server jobs directory

When you install ArcGIS Server, a directory gets created for working with geoprocessing services. This is called the server jobs directory, and by default, it’s located at c:\arcgisserver\arcgisjobs. When you use a geoprocessing service, intermediate and output data from the model are stored in the server jobs directory. Each execution of the model, or job, has its own unique folder in the server jobs directory. This allows different people to use the service at the same time without the results getting confused.

Because the server jobs directory takes care of managing your intermediate and output data, you don’t have to worry about setting the scratch and current workspaces in the model environment.

Implementation

This example walks you through the process of building a simple model, publishing it as a geoprocessing service, and running the service in a Web mapping application. The steps include tips and best practices for working with geoprocessing services.

Building the model

The model you’ll create in this example uses two tools: Buffer and Clip. When you run the model, you’ll interactively define a set of points on the map along with a buffer distance. When the model runs, it will buffer the points at the specified distance. In order to exclude areas in the ocean, the model will then clip the resulting buffers to the shape of a feature class representing the coastline.

To build this model, you can use any data of your own, preferably with a feature class representing a boundary or coastline that you can clip to. The illustrations in this example use some data of the San Diego area. The model will clip to a feature class called Land.

This model also requires that you’ve previously saved a point layer file somewhere on disk, containing the symbology you want to use for your input points.

Follow these steps to build the model:

1. Open ArcMap to a new empty map document and, if necessary, make ArcToolbox visible.

2. Create a new toolbox by right-clicking ArcToolbox and selecting New Toolbox. You can name this toolbox 'GeoprocessingTutorial'

   

   Tip: Where did this toolbox get created in the file system? By default, it’s added to your user profile. The path is probably similar to C:\Documents and Settings\myUserName\Application Data\ESRI\ArcToolbox\My Toolboxes\GeoprocessingTutorial.tbx. This is important to know because when you publish the toolbox as a service, you must make sure the SOC account has permissions to access this file.

3. Create a new model by right-clicking the toolbox and selecting New > Model. By default, the model is called simply ‘Model’. You can change this later.

   

4. When you create a new model, the ModelBuilder window opens for you. At this point you can start adding the tools that you want in the model. Begin by finding the Buffer tool in the Analysis Tools > Proximity toolset. Drag the Buffer tool from the toolbox into the ModelBuilder window.

   
5. The end user will be able to select both the points to buffer and the buffer distance, so we need to make these variables and set them as model parameters. Make the first variable by right-clicking the Buffer tool and selecting Make Variable > From Parameter > Input Features. An oval with the name Input Features appears in the model, connected to the Buffer tool.
6. Right-click the Input Features oval and check Model Parameter. The model parameters are the inputs and settings that the end user can enter when running the model.

7. Right-click the Input Features oval, click Properties, and click the Data Type tab. Note that the data type is set to Feature Layer by default. Remember that geoprocessing services cannot take all data types as inputs; Feature Layer is not a supported input type, but Feature Set is. Change the value in the dropdown to be Feature Set. Additionally, while you are looking at this tab, browse to any point layer file to designate the symbology you want to use for your input points.

   
8. Repeat the previous three steps (5-7) to make an additional variable for the Buffer tool for Distance [value or field]. Make this a model parameter, and set the data type as Linear Unit. Once you're done creating the variable, double-click it and set a default value (for example, using the San Diego data, 2 kilometers might be an appropriate default buffer distance).
9. Set the output location for the buffers by double-clicking the green oval named 'Output Feature'. An example recommended output location is %SCRATCHWORKSPACE%\buffer.shp. SCRATCHWORKSPACE is a variable that in this case ensures the intermediate data will be written to a temporary location in the server jobs directory. You don’t have to set any special model properties to manage the output; in fact, when building a model that will be published as a geoprocessing service, do not set the scratch workspace at the model level.
10. Right-click 'Output Feature' and uncheck Model Parameter. Once you’ve added all of the tools to the model, this will be intermediate data, so you won’t want the end user of the model to set this value.

11. To make the model easier to read, rename ‘Distance [value or field]’ to ‘Buffer distance’ and rename your output features (probably now called ‘Buffer.shp’) to ‘Buffers’. To rename these model components, right-click them and select Rename.

    You may need to drag around the model components in order to see everything. Your model should look similar to the one below:

    

12. It’s time to add the second tool to the model. In the Analysis Tools > Extract toolset, find the Clip tool and drag it onto the right side of the model. Use the Add Connection button to connect ‘Buffers’ to the Clip tool.

    Important: There are two Clip tools in ArcToolbox. Make sure you use the one in Analysis Tools, not in Data Management Tools.

    Tip: Switch back to the Select tool immediately after performing this step.

13. Double-click the Clip tool and set the Clip Features to be the boundaries or coastline feature class that you want to clip to. This example uses the ‘Land’ feature class to eliminate buffer areas that are in the ocean.

    Tip: Remember where the clip features are located. When you publish the geoprocessing service, you must make sure the SOC account has access to this location.

14. Set the Output Feature Class location. An example recommended output path is %SCRATCHWORKSPACE%\ClippedBuffers.shp. When you click OK, you’ll see that a new component has been added to your model.
15. Right-click the green oval representing your output (in this example ClippedBuffers.shp) and check Model Parameter.

16. You’ve completed the model! It should look similar to the one below. Save your model and close the ModelBuilder window.

    
17. Find your model in ArcToolbox. It should still be called simply ‘Model’. Rename it ‘BufferAndClip’. Then save your map document and go on to the next section.

Preparing the model and an associated map for publishing

Now that you’ve created the model, you can take the next steps to get its functionality into a Web application. At this point you need to put some thought into what will happen in the Web application. The Web application can draw the model results in two ways: it can send the results data to the client to be drawn there, or it can draw the results on the server and then send the completed image to the client.

If you decide that the client machine should draw the results, you don’t need to make any additional preparations in ArcGIS Desktop; you only need to publish the toolbox as a geoprocessing service. There is, however, a limitation when drawing the results directly on the client: only symbology from the Web ADF’s graphics layer can be used. Available symbology includes simple marker, line, and fill symbols, as well as a few other symbol types listed in Considerations for authoring and publishing models. Cartographic line symbols, as well as gradient fill symbols and other types of complex symbologies require that the results be drawn on the server.

If the results are drawn on the server, they can use a much greater variety of symbols. This is because the geoprocessing service works with an associated map service that can do the rendering necessary for all of the symbols. Additional advantages to drawing the results on the server include the ability to use layers in the map service as input to the model, and the ability to work with large numbers of features in the results (if you tried to send a lot of features to be drawn on the client, it might take a long time or might not be permitted by the server administrator).

This example shows how to draw the results on the server, which requires you to create an associated map service. You need to create a map that can be used to visualize the inputs and results of the model. Once you’ve created the map, you need to add your model to the map as a tool layer. The following steps explain this process:

1. Open the map document that you created in the previous section and add some data. This should be base map data on top of which you can add the model inputs and outputs.
2. In order to use your model as a tool layer, you need to have run it at least once. In ArcToolbox, find the BufferAndClip model that you created in the previous section. Double-click the model and use the interactive pointer tool to place a few input points on the map. Click OK to run the tool.
3. The clipped buffers should appear on the map. You’ve now completed the requirement to run the model once, so you can remove this layer.

4. Now create the tool layer. Do this by dragging the BufferAndClip model from ArcToolbox into the table of contents with the rest of the layers.

   Remember: Having a tool layer in your map is the key to getting a geoprocessing service that will work with your map service.

   

5. The input features for the model are already symbolized according to the schema you imported in step 7 above. Now, use the layer properties to set the symbology that you want for the output features.

   Remember: In this example, the output features are symbolized with an angled, line fill symbol as shown below. This symbology is only possible when the server draws the results using an associated map service; it would not be available if you attempted to draw the results on the client.

   
6. Make the output features (shown above as ClippedBuffers.shp) invisible (unchecked) in the table of contents. If you leave it visible, it will display the results of the last tool execution you made prior to publishing.
7. You now have everything you need to publish the services. Save your map document and continue with the next section.

Publishing the service

Once you have a map document with a tool layer, you’re ready to publish these as services. You’ll publish the map document as a service and enable the Geoprocessing capability, which will create a geoprocessing service of the same name. You can use these two services within your Web application to run the model on the server and display the results.

Important: Before publishing your services, be sure to read and follow the guidelines presented in Preparing resources for publishing as services. These will help you ensure that the server has permissions to read and access all of the data for your model and your map. Specifically, the SOC account needs to have read permissions to your model (toolbox), any data referenced by the model (such as the clip features), the map document, and any data in the map document. If you have the components of ArcGIS Server distributed among multiple machines, all of the above data must be referenced using UNC paths so that all machines can read it. Finally, the SOC account needs read and write access to the server jobs directory. If you’re using the default server jobs directory installed with ArcGIS Server (C:\arcgisserver\arcgisjobs) then the install process already applied the appropriate permissions for the jobs directory.

Follow these steps to publish the services:

1. Log in to ArcGIS Server Manager and click Publish a map, globe, or other GIS resource as a service.

   Tip: There are two wizards in Manager that you can use to publish services. This link takes you to the Publish GIS Resource wizard, which is the simplest way to create a service. It asks you the minimum amount of information needed to create a service. Another feature of the Publish GIS Resource wizard is that you can use it to create associated services, like the geoprocessing and map services that you’re going to create in this example.

   The other way to create services is the Add New Service wizard. This wizard is the completely manual way of publishing a service; it prompts you for all of the service parameters. You cannot use the Add New Service wizard to automatically create associated services.

2. On the first panel of the wizard, you’re prompted for the resource that you want to publish. This is the map document with the tool layer. If it’s in a shared directory, you can browse to the map document. If it’s not in a shared location, carefully type the path name of the map document.

3. Give your service a name. The name you enter here will be used for both the map service and the geoprocessing service. Optionally, if you have your services grouped in folders, select the appropriate folder, then click Next to move to the next panel of the wizard.

   

4. In the second panel, notice that two capabilities are enabled by default. Mapping is enabled for all map services. Geoprocessing is enabled because Manager detected that the map you’re publishing has a tool layer. Publishing a map service with the Geoprocessing capability enabled creates an associated geoprocessing service with the same name. Leave these capabilities checked and click Next to move on to the final wizard panel.

   
5. The final panel of the wizard explains that two services will be created and gives their URLs. Click Finish to publish the services and exit the wizard.

Creating a Web application with the Geoprocessing Task

The final step in exposing your model to others is to create a Web application with a Geoprocessing Task. You’ll use ArcGIS Server Manager to create the Web application. Manager will help you select the map service to display and the geoprocessing service that you want to expose to your users through the Geoprocessing Task. Follow these steps to create the Web application in Manager:

1. In ArcGIS Server Manager, click the Home tab and click Create a Web application. This will take you to the first panel of a wizard that will help you set up the application.

2. Enter the host (web server) machine and a name for your application. This name will appear in the URL that users type in their browser when they access your application. Optionally, you can also type a description in this panel that administrators can read when they view the list of Web applications in Manager. When you’re finished with this panel, click Next.

   

3. In the second panel, you select which services will appear in your map. You want to select the map service that you just published in the previous section and click Add to move it to the list of services in your map. You may need to first create a connection to your GIS server. If you need help with this panel, see Selecting layers to display. When you’re finished adding services, click Next to move to the next panel.

   
4. In this panel of the wizard, you will add the Geoprocessing task. In the list of Available Task Items, click Geoprocessing, then click the Add button to add the task.

5. Before configuring the task, you need to designate a geoprocessing service for the task to use. Switch to the Supporting Services tab and, in the same way that you browsed for your map layer on the previous panel, browse to your geoprocessing service and click Add to include it in the list of Selected Services.

   

6. Now switch back to the Select Tasks tab, click Geoprocessing in the list of Current Tasks, then click the Configure button. In this dialog, you can change the task name from ‘Geoprocessing’ to something more descriptive. You can also add a help tip that will appear when users hover the mouse over the task.

   If you have multiple models in your toolbox, this is where you can select the one that will appear in your task. You can only use one model per task.

   In this example, you can keep the defaults for the Geoprocessing Task Settings. The topic Configuring Tasks explains more about results files and synchronous vs. asynchronous tasks, and will help you understand these settings.

   
7. Once you’ve configured the task the way you want it, click OK to exit the dialog and Next to continue creating the Web application. The rest of the wizard allows you to set the color scheme, text, links, and map elements in your application. You can alter these settings however you wish, proceeding through the rest of the wizard. The final panel displays some information about the application that will be created and prompts you to click Finish to create the Web application.

8. Test your Web application by opening the geoprocessing task. Define some points, then run the tool to see the clipped buffers.