Publish a notebook as a web tool

ArcGIS Notebooks allows you to publish notebooks as web tools. Administrators and notebook authors with publish web tool privileges 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 Notebook Server machine 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, and the web tool item is assigned the same sharing permissions as the parent 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 above. To check a notebook's runtime information, click the Info button in the top ribbon of the notebook editor or on the Settings tab on the Notebook Item 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, and Linear unit. For more information, see Geoprocessing services data types in the ArcGIS Notebook Server REST API documentation.

When a web tool is run, ArcGIS Notebook Server automatically runs the notebook on the notebook server machine by opening a new container and running the notebook without any user interaction. Users with notebook privileges and with whom the notebook has been shared can access and run the web tool. In addition to the required notebook privileges, 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 portal item in Portal for ArcGIS or upload and reference the file from a custom data directory registered with ArcGIS Notebook Server.

By default, ArcGIS Notebook Server is configured to run a maximum of 10 concurrent, noninteractive notebook runs per each ArcGIS Notebook Server 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. Provide 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. Provide 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. Provide 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, provide a description for the input parameter.
9. Click Save to save the input parameter.
10. To add additional 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 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. Provide 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. Provide 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. Provide 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. Provide a title and description for the web tool in the Title and Description fields in the Publish pane.
5. Verify any input and output parameters.
6. Click Publish to publish the notebook as a web tool.
7. Once the web tool has published successfully, click View detail to view the item details page for the web tool.

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 geoprocessing service published from a notebook by deleting the web tool item.

1. On the top ribbon of the notebook editor, click Publish.
2. Click View detail 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 Notebook Server.

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 click 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 Classic, the map extent is passed into the notebook as a Python variable named context, along with other input parameters, as seen below.

context = {
    "extent": {
        "ymin": -25203428.462408017,
        "xmin": -46101923.491795965,
        "ymax": 25203428.462407943,
        "xmax": 46101923.491795965,
        "spatialReference": {
            "wkt": "PROJCS[\"WGS_1984_Web_Mercator_Auxiliary_Sphere\",GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",6378137.0,298.257223563]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],PROJECTION[\"Mercator_Auxiliary_Sphere\"],PARAMETER[\"False_Easting\",0.0],PARAMETER[\"False_Northing\",0.0],PARAMETER[\"Central_Meridian\",0],PARAMETER[\"Standard_Parallel_1\",0.0],PARAMETER[\"Auxiliary_Sphere_Type\",0.0],UNIT[\"Meter\",1.0]]"
        },
    }
}

You can use the value of the context variable to set the extent of the spatial analysis workflows in your notebook. To test your spatial analysis workflows with a map extent 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

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

1. In a web browser, open the ArcGIS Notebook Server services directory https://notebookserver.domain.com/webadaptorcontext/rest/services.
2. Sign in as the owner of the web tool.
3. Identify the service and browse to the tasks page.
4. Click Submit job.
5. Provides any input parameters and click Submit job.
6. 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.

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