Publish a notebook as a web tool

ArcGIS Notebooks allow you to publish notebooks as web tools. Administrators and notebook authors with the Publish web tools privilege can publish notebooks they own as web tools. When a notebook is published as a web tool, an asynchronous geoprocessing service is created on the ArcGIS Notebooks and registered as a web tool. There is a one-to-one relationship between the notebook and the web tool, meaning only one web tool can be published per notebook. Web tools can be consumed by any client application that can work with RESTful asynchronous geoprocessing services.

Publishing a notebook as a web tool is supported for notebooks with runtime version 6.0 or later. To check a notebook's runtime information, click the Info button on the top ribbon of the notebook editor or on the Settings tab in the notebook's item details page. See View available Python libraries to learn more about notebook runtimes.

The notebook editor allows you to configure input and output parameters for a notebook. Input parameters correspond to input variables in a notebook that you want to externalize for user input when the notebook is run as a web tool. Output parameters represent the output variables in a notebook that you want to return as web tool outputs. When you register one or more input or output variables and publish a notebook, the parameters become available as input or output parameters for the corresponding web tool.

Note:

It is not required to define input or output parameters when publishing a notebook as a web tool. For example, notebooks that perform tasks with predefined inputs and outputs, such as feature layers referenced by itemId, may not require input or output parameters.

Note:

The following data types are supported as input or output parameters: String, Long, Double, Boolean, Feature set, Record set, Date, Linear unit, Raster data layer, and File. For more information, see Geoprocessing services data types in the ArcGIS REST API documentation.

When a web tool is run, ArcGIS Notebooks performs an automated run of the notebook by opening a new container and running the notebook without user interaction. Users with the run web tools privilege and with whom the web tool has been shared can access and run the web tool. In addition to the required run web tools privilege, any other privileges required to run the notebook are required. See the User types, roles, and privileges topic to learn more about privileges.

Note:

When authoring a notebook to be shared as a web tool, if the notebook references a file from your workspace directory as input data, those files will not be accessible by others with whom the notebook or web tool is shared. If you have files that need to be referenced as input data in the notebook, you can either reference the file through a shared item in your ArcGIS content or upload and reference the file from a custom data directory registered with ArcGIS Notebooks.

By default, ArcGIS Notebooks is configured to run a maximum of 10 concurrent, noninteractive notebook runs per each ArcGIS Notebooks machine. This includes runs triggered by web tools, scheduled tasks, the executeNotebook API, and webhook triggers. Administrators can increase this limit, if necessary.

Note:

If you do not see Parameters or Publish options in the notebook editor, you either do not have the Publish web tools privilege or are not the owner of the notebook. If you are in a newly created notebook, the Parameters and Publish options do not display until the notebook has been saved.

Configure input parameters

Input parameters represent input variables in a notebook that are externalized when a notebook is run as a web tool. Using the Parameters pane in the notebook editor, you can configure and add input parameters as variables to your notebook.

1. In the notebook editor, click Parameters.
2. Click Add.
3. Select input for Direction.
4. Enter a name for Variable name.

   Note:

   This must match a variable name that is in the notebook code or is already configured in the notebook.

5. Enter a name for Display name for the web tool parameter.
6. From the Data type drop-down menu, select a data type for the input parameter.
7. Enter a value for Default value for the input parameter. Refer to Geoprocessing services data types for the syntax of the default values for supported data types.
8. For Description, enter a description for the input parameter.
9. Click Save to save the input parameter.
10. To add more input parameters, repeat steps 1 through 9.
11. After adding all of your input parameters, select a cell in your notebook for the parameters to be inserted into and click Insert as variables.
12. Click Save to save the notebook.

Configure output parameters

You can configure output for a notebook published as a web tool by configuring output parameters from the Parameters pane in the notebook editor.

1. In the notebook editor, click Parameters.
2. Click Add.
3. Select output for the Direction parameter.
4. Enter a name for Variable name.

   Note:

   This must match a variable name that is in the notebook code or is already configured in the notebook.

5. Enter a name for Display name for the web tool parameter.
6. From the Data type drop-down menu, select a data type for the output parameter.
7. Enter a value for Default value for the output parameter. Refer to Geoprocessing services data types for the syntax of the default values for supported data types.
8. For Description, type a description for the output parameter.
9. Click Save to save the output parameter.
10. Select a cell in your notebook. Click the Add button to add the Python code snippet to write the output for the web tool.

    It is recommended that you select a cell near the bottom of the notebook, below the cells where the outputs are created.

11. Inspect the added code snippet to ensure the output variable names match the output defined in the notebook, and make any additional adjustments to the code snippet.
12. Repeat steps 1 through 11 for any additional output parameters.
13. Click Save to save the notebook.

Publish a web tool

You can publish a notebook as a web tool from the Publish pane in the notebook editor.

1. Save your notebook to ensure the latest copy of the notebook is published.
2. Manually run the notebook's cells interactively to ensure that no errors exist.

Note:

Skip cells that contain the code snippets for the output parameters, as they do not run in interactive mode.
3. Click Publish on the notebook editor ribbon.
4. Enter a title and description for the web tool in the Title and Description fields in the Publish pane.
5. Specify a number in the Maximum usage time field.

   This is the number of minutes the web tool can continue running before the system cancels it. The maximum allowed timeout value is 100 minutes.

6. Verify any input and output parameters.
7. Click Publish to publish the notebook as a web tool.
8. Once the web tool has published successfully, click View details to view the item details page for the web tool.
9. Click Share to open the Share window.
   1. Select Organization to share the web tool with all users in your organization.
   2. Click Edit group sharing to share the web tool with specific groups.
   3. Select the groups you want to share with.
   4. Click OK.
   5. Click Save.

Share a web tool

To share or update the sharing settings for an existing notebook web tool with your organization or specific groups in your organization, follow the steps below.

Note:

Users with whom the web tool is shared must have the Run web tools privilege and any additional privileges necessary to run the notebook to be able to run the shared web tool.

Note:

Introduced at 11.2, you can now share a notebook web tool to a different level than that of the level the notebook was published at. For example, a notebook web tool can be shared with the organization even while the notebook itself is unshared with the organization. To ensure that a web tool published in a previous release is able to utilize this change, overwrite the web tool.

1. Verify that you are signed in to your organization and have sufficient privileges to share content.
2. Click Content.
3. Check the box next to the title of the web tool you want to share.
4. Click Share.
   1. Select Organization to share the web tool with all users in your organization.
   2. Click Edit group sharing to share the web tool with specific groups.
   3. Select the groups you want to share with.
   4. Click OK.
   5. Click Save.

Overwrite a web tool

Overwriting a web tool will update a web tool to use the latest snapshot of that notebook. You can overwrite a notebook web tool in the Publish pane in the notebook editor.

1. If an existing input or output parameter needs to be updated, follow the steps in the Edit an existing input or output parameter section of this topic.
2. If you are adding new input or output parameters, follow the steps in the Configure input parameters or the Configure output parameters sections of this topic.
3. Click Save to ensure that the latest copy of the notebook is published.
4. Manually run each cell in the notebook to ensure that no errors exist.

   Note:

   Do not run cells that contain the code snippets for the output parameters, as they will not run in interactive mode.

5. Click Publish.
6. Click Overwrite to overwrite the web tool.

Delete a web tool

You can delete a web tool published from a notebook by deleting the web tool item.

1. On the top ribbon of the notebook editor, click Publish.
2. Click View details to view the item details page for the web tool.
3. Click Settings.
4. Click Delete item and confirm that you want to remove the web tool item and the geoprocessing service published on ArcGIS Notebooks.

Note:

If the notebook item from which the web tool is published is deleted, the web tool item will also be deleted.

Edit an existing input or output parameter

You can make changes to an existing input or output parameter from the Parameters pane in the notebook editor.

Note:

If a notebook has already been published as a web tool, you must turn on the Enable editing toggle button in the Parameters pane before you can make changes to your parameters. Be cautious when making changes to your parameters after the notebook has been published as a web tool, as these changes can potentially break any web apps using the web tool.

1. On the top ribbon of the notebook editor, click Parameters.
2. Click the options button next to the parameter and click Edit.
3. Update the parameter and click Save.
   1. If an input parameter was updated, manually clear or remove the existing cell with the input variables and repeat the step to insert the input parameters as variables into the notebook.
   2. If an output parameter was updated, manually clear the code snippet corresponding to the output variable and repeat the steps to add the code snippet for the output parameter to the notebook.
4. Click Save to save the notebook.

Delete an existing input or output parameter

You can delete existing input or output parameters from the Parameters pane.

1. On the top ribbon of the notebook editor, click Parameters.
2. Click the options button next to the parameter and click Delete.
3. Click delete to permanently remove the parameter.
4. Manually clear or remove the input variable or output code snippet in the notebook.
5. Click Save to save the notebook.

Use the map extent

When you run a web tool in Map Viewer, if the processing extent and output coordinate system are modified, they will be passed into the notebook as a Python variable named context, along with other input parameters, as seen below.

context = {
    "extent": {
        "ymin": 1759249.9654418486,
        "xmin": 6481923.176042713,
        "ymax": 1795442.256243616,
        "xmax": 6531137.243576055,
        "spatialReference": {"latestWkid": 2229, "wkid": 102645},
    },
    "outSR": {"latestWkid": 4269},
}

You can use the value of the context variable to set the extent and output coordinate system of the spatial analysis workflows in your notebook. To test your spatial analysis workflows before publishing the notebook as a web tool, declare the context variable with a default value.

When you are ready to publish, insert the input parameters as variables after the cell where you declare the context variable.

Troubleshoot a web tool run

After publishing a notebook as a web tool, you can validate whether the web tool runs successfully by running the task from the ArcGIS REST services directory.

1. Click to the item page of the web tool item.
2. Click and open Service URL in the Tools section.
   1. Sign in if prompted.
3. Enter any input parameters and click Submit job.
4. Optionally, click the Check Job Details Again link to check the status of the job.

   If the web tool completes successfully, links to the outputs are provided. An HTML preview of the notebook run is provided as output by default, for both successful and failed runs.

5. Download and view the HTML preview of the notebook to verify whether there were any issues with the run of the web tool.
6. If the web tool fails, confirm that the notebook runs successfully in the notebook editor.