Starting at 10.9.1, ArcGIS Notebooks allow 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 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.
At 10.9.1, the notebook editor has a new feature that 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 performs an automated run of 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 are able to access and run the web tool. In addition to the required notebook privileges, any other privileges required for the run of 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.
- In the notebook editor, click Parameters.
- Click Add.
- Select input for Direction.
- 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. - Enter a name for Display name for the web tool parameter.
- From the Data type drop-down menu, select a data type for the input parameter.
- 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.
- For Description, enter a description for the input parameter.
- Click Save to save the input parameter.
- To add additional input parameters, repeat steps 1 through 9.
- 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.
- 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.
- In the notebook editor, click Parameters.
- Click Add.
- Select output for the Direction parameter.
- 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. - Enter a name for Display name for the web tool parameter.
- From the Data type drop-down menu, select a data type for the output parameter.
- 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.
- For Description, type a description for the output parameter.
- Click Save to save the output parameter.
- 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.
- 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.
- Repeat steps 1 through 11 for any additional output parameters.
- 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.
- Save your notebook to ensure the latest copy of the notebook is published.
- Manually run the notebook's cells interactively to ensure that no errors exist.
- Click Publish on the notebook editor ribbon.
- Enter a title and description for the web tool in the Title and Description fields in the Publish pane.
- Verify any input and output parameters.
- Click Publish to publish the notebook as a web tool.
- Once the web tool has published successfully, click View detail to view the item details page for the web tool.
Note:
Skip cells that contain the code snippets for the output parameters, as they do not run in interactive mode.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.
- 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.
- 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.
- Click Save to ensure that the latest copy of the notebook is published.
- 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. - Click Publish.
- 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.
- On the top ribbon of the notebook editor, click Publish.
- Click View detail to view the item details page for the web tool.
- Click Settings.
- 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 toggle 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.
- On the top ribbon of the notebook editor, click Parameters.
- Click the options button next to the parameter and click Edit.
- Update the parameter and click Save.
- 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.
- 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.
- 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.
- On the top ribbon of the notebook editor, click Parameters.
- Click the options button next to the parameter and click Delete.
- Click delete to permanently remove the parameter.
- Manually clear or remove the input variable or output code snippet in the notebook.
- Click Save to save the notebook.
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 Notebook Server services directory.
- In a web browser, open the ArcGIS Notebook Server services directory https://notebookserver.domain.com/webadaptorcontext/rest/services.
- Sign in as the owner of the web tool.
- Identify the service and browse to the tasks page.
- Click Submit job.
- Enter any input parameters and click Submit job.
- 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.
- Download and view the HTML preview of the notebook to verify whether there were any issues with the run of the web tool.
- If the web tool fails, confirm that the notebook runs successfully in the notebook editor.