Techniques to use web tools in web apps

The geoprocessing service that powers a web tool can be consumed in a custom web app, providing the clients of your web app with geoprocessing and analysis solutions. You can build a web app from scratch using ArcGIS API for JavaScript. Alternatively, you can deploy a configurable web app using Web AppBuilder in ArcGIS Enterprise.

Regardless of the method you use to build a web app, the communication of the underlying geoprocessing service occurs through REST and connects to the service end point on ArcGIS Server.

• The service end point is a URL, typically in the following format: http://<server>/arcgis/rest/<ServiceName>.
• Each service end point has information that describes the service, the operations that can be performed, and the resources that compose the service. In the geoprocessing context, one or more tools compose the resources of a service.

To learn more about using web tools with ArcGIS REST API, see Geoprocessing services.

Web tools in custom web apps

Typically, a custom web app is constructed using ArcGIS API for JavaScript. Although you can construct any app that can communicate with the service over REST, the following discussion focuses on JavaScript. If you're already comfortable with JavaScript and geoprocessing, you may want to review the samples and code snippets. Otherwise, the remainder of this section outlines the following process to add geoprocessing to a web app:

1. Initializing the geoprocessing service
2. Setting up input parameters
3. Running the geoprocessing service
4. Getting and handling the result or results

The following JavaScript code is taken from the Calculate Viewshed sample with only the relevant pieces to demonstrate the four steps required to run geoprocessing tools. The sample in the JavaScript help provides a complete example, whereas the following only produces a working web page with additional code:

// esri.tasks.Geoprocessor is required for using Geoprocessor.
//  Add it along with other dojo.require statements.
dojo.require(esri.tasks.Geoprocessor); 

// Step 1: Initialize the geoprocessing and point to the REST URL
var gpUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/ESRI_Elevation_World/GPServer/Viewshed";
var gp = new Geoprocessor(gpUrl);	

// Set output spatial reference 
gp.outSpatialReference = { wkid: 102100 };

function computeViewshed(event) { 
   graphicsLayer.removeAll();

   // Step 2: Set up input parameters and assign or collect inputs from user
   var point = new Point({ 
        longitude: event.mapPoint.longitude,
        latitude: event.mapPoint.latitude  
   });  

   var inputGraphic = new Graphic({
      geometry: point, 
      symbol: markerSymbol 
   }); 
   graphicsLayer.add(inputGraphic); 

   var inputGraphicContainer = [];
   inputGraphicContainer.push(inputGraphic);
   var featureSet = new FeatureSet();
   featureSet.features = inputGraphicContainer;  

   var vsDistance = new LinearUnit();  
   vsDistance.distance = 5;
   vsDistance.units = "miles";  
   var params = {  
      "Input_Observation_Point": featureSet,
      "Viewshed_Distance": vsDistance  
   };  

   // Step 3: Run the service. In this instance, the service is Synchronous; Execute
   // will be called. An Asynchronous service will use gp.submitJob.
   gp.execute(params).then(drawResultData); 
}  

// Step 4: Render the result. Symbology is assigned and the graphics are added to the map.
function drawResultData(result) { 
   var resultFeatures = result.results[0].value.features;  
   // Assign each resulting graphic a symbol  
   var viewshedGraphics = resultFeatures.map(function(feature) { 
      feature.symbol = fillSymbol;     
      return feature; 
   });       
   // Add the resulting graphics to the graphics layer  
   graphicsLayer.addMany(viewshedGraphics);
}

In the sample above, the Geoprocessor class must be loaded, and the REST URL to the service is used with a global variable to define the geoprocessing task. The next step is to construct the parameters specific to the tool the app will be running. This example requires a point (feature) input and a distance (linear unit). The REST URL specific to the tool in the service will define input parameters. A service will be set up as either synchronous or asynchronous, and this setting controls whether the service is run as submit GP job or execute GP task. The output for each tool is also explained on the same page as the input parameters; information about the type and how it can be displayed is provided.

Web tools in Web AppBuilder

To use a web tool with Web AppBuilder, you only need the service URL of the web tool; no code is required. The URL is displayed in your portal, on the tool's item details page, in the URL section.

To use a web tool in Web AppBuilder, you configure a geoprocessing widget. First create a web app in your portal. Once you select the style and map, you can add a geoprocessing widget and configure it.

The widget configuration allows you to set input and output options as they relate to a web tool. These input and output parameters that define the web tool determine the options that are available through the widget configuration. For example, the widget configuration allows you to control the type of feature (square, circle, freehand, and so on) that a user can enter if the web tool was published to accept feature input. The same premise applies to the output. A web tool that's set up to output features allows you to configure the symbology and how the web app will render the web tool output. A web tool that's configured with a result map layer will have the result added to the web app and be symbolized based on settings you specify during the initial publishing process.

Web tools in ArcGIS Experience Builder

When publishing a web tool to ArcGIS Enterprise 11.3 or later, you can use the Analysis widget after you have added the web tool as a utility service. Most input and output parameters are available to use in the analysis widget.

You can configure the input and output parameters behavior, such as allowing or disallowing the sketch functionality for an input feature parameter, and displaying or hiding certain inputs and outputs. There can be multiple web tools in the analysis widget, as long as you added them as utility services. To learn more about Experience Builder, see Create your first web experience.

Web tools in Map Viewer

When publishing a web tool to ArcGIS Enterprise 11.3 or later, you can open Map Viewer from your portal and browse the custom tools in the Tools pane of the Analysis pane. To run web tools in Map Viewer, you must meet the licensing requirements. To learn more about web tools in Map Viewer, see Use custom web tools.