ArcGIS Runtime SDK for Qt

Geoprocessing

Geoprocessing provides a large suite of tools for performing GIS tasks that range from basic buffer and polygon overlays to complex regression analysis and image classification. You can automate all kinds of GIS workflows using Geoprocessing, from converting a large amount of data from one format to another to using a sequence of operations to model and analyze complex spatial relationships.

Examples include:

  • Calculating optimum paths through a transportation network
  • Predicting the path of wildfire
  • Analyzing and finding patterns in crime locations
  • Predicting which areas are prone to landslides
  • Predicting flooding effects of a storm

There are many reasons why geoprocessing services are good options for these tasks. They can centralize logic to the service. They can help to reduce the workload on the client. Also, geoprocessing services can access tools that aren’t available or efficient to run in the client.

Geoprocessing is based on a framework of data transformation. A typical geoprocessing tool performs an operation on an ArcGIS dataset (such as a feature class, raster, or table) and produces a new dataset as a result. Each geoprocessing tool performs a focused operation on geographic data, perhaps as a small part of the overall analytical process.

Example of a geoprocessing model as seen in ModelBuilder

Geoprocessing allows you to combine a sequence of tools into what is called a model. In a model, the output of one tool is fed into another, which allows you to automate your workflows. Geoprocessing tools and models can be shared with others by creating web services. ArcGIS Runtime uses geoprocessing tools through web services.

A geoprocessing tool is a command or function that performs an operation on GIS data. There are three types of tools, as shown in the table below.

Tool typeDescription

Built-in tool

Built-in tools are created by Esri and provided with ArcGIS

Model tool

Model tools are user-created tools authored using ModelBuilder

Script tool

Script tools run a geoprocessing Python script file

Geoprocessing tools can be system tools built by Esri and included in ArcGIS products, or custom tools built as script or model tools by you and other users. You can use both custom and system geoprocessing tools in the same ways. Learn more about using geoprocessing iin ArcGIS Desktop by taking a quick tour (in the ArcMap documentation).

Use geoprocessing in ArcGIS Runtime

There are two ways an ArcGIS Runtime app can use a geoprocessing tool:

  1. Consume a geoprocessing task. A geoprocessing web service is published from ArcGIS Desktop to ArcGIS Online or ArcGIS Enterprise. This web service and its tasks can be consumed as REST endpoints by web-based clients such as ArcGIS Desktop, Explorer for ArcGIS, custom web apps, and ArcGIS Runtime SDK apps.
  2. Consume a local geoprocessing package (.gpk or .gpkx ) with the Local Server. The Local Server runs on Windows or 64-bit Linux, and is available for use withArcGIS Runtime SDK for .NET, Qt (C++ API), and Java platforms. The geoprocessing tool, script, or model and any data that it uses is packaged and shared from ArcGIS Desktop. The resulting package (.gpk or .gpkx file) can be shared via email, uploaded to ArcGIS Online, or simply copied onto the client machine. This geoprocessing package is used by Local Server to start a local geoprocessing service. The service's tasks can be consumed by ArcGIS Runtime SDK apps running on the machine.

Note:

When preparing a geoprocessing package with ArcGIS Desktop, use the Package Result tool and be sure to check the Support ArcGIS Runtime box in the Parameters pane. If this box is not checked, the .gpkx file will not run as a Local Server service.

Share a package or publish a service

As an ArcGIS Desktop user, you can share a geoprocessing package or publish a web service to enable an ArcGIS Runtime SDK app to consume a geoprocessing task. Learn more about sharing geoprocessing workflows by taking a quick tour (in the ArcMap documentation).

Share a geoprocessing package to ArcGIS Runtime

A geoprocessing package is a convenient way to share geoprocessing workflows by packaging one or more tools and the data they require into a single compressed file (.gpk or .gpkx). All resources (models, tools, scripts, data, layers, and files) needed to execute the tools are included in the package.

Once a geoprocessing tool is authored and run in ArcGIS Desktop, a package can be shared from one or more results in the Results window. For a geoprocessing package to work with the Local Server, it must be created with ArcGIS Runtime support enabled. Not all geoprocessing tools or functionality are supported in Local Server, and which tools you can use and deploy depends on your licensing level.

What is a geoprocessing task?

A geoprocessing task is a REST child resource of a geoprocessing service. A geoprocessing service can host one or more tasks. A task has a set of parameters that define how a client can interact with the task and what kind of input must be passed to it to execute the task. The server executes the task and returns output values to the client. Output values could include a map service to show the results. This allows for the display of complex data and raster data.

The following figure shows the hierarchy of geoprocessing REST resources. Notice that geoprocessing service properties (shown in orange) are inherited by every geoprocessing task. These include the execution type, the maximum number of records to return, and the map service used to return results.

Geoprocessing service and tasks

The format for a geoprocessing task URL is http://<gpservice-url>/<taskName>. The endpoint for a task called BufferPoints hosted on myserver, for example, would be the following.

http://myserver/ArcGIS/rest/services/BufferPoints/GPServer/BufferPoints

Tasks defined in HTML task pages

The ArcGIS Server service directory contains a set of service pages—web pages of information about each service it provides. You can use the service pages of a geoprocessing service to explore its tasks and their parameters, and learn how to code against them—simply open the REST URL in a browser.

What are task parameters?

Task parameters are the inputs and outputs of a geoprocessing task and vary from task to task based on its individual requirements. Each parameter has a set of properties that describe it, such as name, data type, whether it is required or optional, and so on.

When tasks complete, results are returned in a variety of ways. It’s important to understand how a particular geoprocessing task returns results in order to handle them properly. To learn about parameter types, see geoprocessing task parameters.

A geoprocessing task may output a map service result. This prevents the client app from having to symbolize and draw a large number of features or to try to handle a data format that cannot be added directly to the map via the API. When maps from map services are rendered, symbology is applied to the features.

Execution type

The work required of a geoprocessing task can be straightforward and may take a few seconds to execute on the server, or it can support advanced functionality—processing large datasets—and may take longer to execute. Therefore, the REST API provides two execution types, which are options for running the geoprocessing task on the server.

  • Synchronous: Synchronous tasks are suitable for fast running tasks. In synchronous tasks, the client sends a request to run the task and waits for the results of the task to be returned as a response.
  • Asynchronous: Asynchronous tasks are suitable for long running jobs. In asynchronous tasks, the server returns a job ID which the client uses to poll for task status. When the status is completed, the results are created as child resources of the job which the client can access using its job ID.

In ArcGIS Runtime both execution types are accessed asynchronously and the call to the correct REST endpoint is defined by the execution type set on the geoprocessing parameters. Even though the geoprocessing tasks are executed in different manner at the service level, they are accessed through one single API. To learn how you can use geoprocessing in your app, see Run a geoprocessing task.