Skip to main content

Publish a notebook as a web tool

Publishing a notebook as a web tool creates a web tool item for an asynchronous geoprocessing service and makes its workflow available to other users without requiring them to open the notebook or view its code.

Note:

You must own the notebook and have the Publish web tools privilege to configure parameters and publish a notebook as a web tool.

Users can run web tools in ArcGIS client applications, such as Map Viewer and ArcGIS Experience Builder, or through scripts and REST API workflows. When a user runs a web tool, ArcGIS Notebook Server runs the notebook it was published from in a new container without user interaction.

Authoring a notebook web tool

The following workflow is recommended when creating and sharing a new notebook web tool.

  1. Plan the intended workflow of the web tool. For example, determine the values users will need to provide and the results the notebook web tool will return.

  2. Develop and test the notebook workflow to ensure that the notebook behaves as expected with appropriate inputs.

    Note:

    Files in the notebook author's workspace are not available to other users that may run the shared web tool. Ensure that any files the notebook needs to run successfully are stored in a content item that users can access or in a custom data directory registered with ArcGIS Notebook Server.

  3. Configure the input parameters and output parameters of the notebook.

  4. Publish the notebook as a web tool.

  5. Test the published web tool.

  6. Share the web tool item.

Configure input parameters

Input parameters expose notebook variables to users and allow them to provide values when they run the web tool. Using the Parameters pane in the notebook editor, follow the steps below to configure and add input parameters as variables to your notebook.

  1. Open the Parameters pane in the notebook editor.

  2. Click Add.

  3. Set Direction to Input.

  4. Enter a Variable name.

    Important:

    This is the notebook variable that the parameter will set. The variable name must exactly match the variable in your notebook code.

  5. Enter a Display name.

    This is the label users will see when they run the web tool in a client application.

  6. Select a Data type.

    See Geoprocessing services data types for supported types and default value syntax.

  7. Set Parameter type to Required or Optional.

  8. Optionally, for String, Long, Double, Feature set, Record set, Date, or Linear unit parameters, enable Allow multiple values to let users provide more than one value.

    When enabled, the values are passed to the notebook as a list.

  9. Optionally, for String, Long, or Double parameters, add a choice list under Choice list (optional) to restrict the values users can provide.

  10. Enter a Default value.

    This value will appear when a user runs the tool in a client application and is used if no value is provided.

  11. Optionally, enter a Description.

  12. Click Save.

Repeat the steps above for each input parameter you want to add to the notebook.

Once you have created and saved your input parameters, follow the steps below in the notebook editor to add your input parameters to your notebook.

  1. Select a cell in your notebook after the imports and setup cells but before the cell where the parameter variables are first used.

  2. Click Insert as variables.

    The notebook editor adds a cell that defines each input variable using their corresponding variable names and default values. At runtime, values provided by the user are inserted after the parameter cell.

    Important:

    Ensure that any other definitions of variables corresponding to input parameters are removed or are above the inserted cell to prevent input values from being overwritten.

  3. Ensure that the notebook code is working properly with the input parameters.

  4. Click Save to save the notebook.

Configure output parameters

Output parameters expose values created by a notebook that can be returned when run as a web tool. Follow the steps below to create output parameters:

  1. Open the Parameters pane in the notebook editor.

  2. Click Add.

  3. Set Direction to Output.

  4. Enter a Variable name.

    Important:

    This is the notebook variable that the parameter will return. The variable name must exactly match the variable in your notebook code.

  5. Enter a Display name.

    This is the label users will see when they run the web tool in a client application.

  6. Select a Data type.

    See Geoprocessing services data types for supported types and default value syntax.

  7. Set Parameter type to Required or Optional.

  8. Enter a Default value.

    This value will appear when a user runs the tool in a client application.

  9. Optionally, enter a Description.

  10. Click Save.

Repeat the steps above for each output parameter you want to add to the notebook.

Once you have created and saved your output parameters, follow the steps below in the notebook editor for each output parameter.

  1. Select a cell in your notebook after the cell where the output value is created.

  2. Click Insert into notebook for the output parameter.

    Note:

    Ensure the inserted code uses the correct output variable name.

    The inserted output code writes the value when the notebook runs as a web tool. Skip this code when testing interactively, as it does not write the output during and interactive notebook run.

  3. Click Save to save the notebook.

Publish a web tool

Follow the steps below to publish a notebook as a web tool.

Note:

Before publishing, ensure that the notebook workflow runs as expected.

  1. Click Publish in the notebook editor.

  2. Enter a Title and Description for the web tool.

  3. Select the folder you want the web tool item to be stored in.

  4. Set the Maximum usage time (minutes).

    This limits how long a run can continue before it is canceled. The maximum allowed value is 100 minutes.

  5. Confirm the listed input and output parameters.

    Note:

    You can publish a notebook as a web tool without configuring input or output parameters. Notebook web tools without parameters will run using the values defined in the notebook's code.

  6. Click Publish.

  7. Click View details to open the web tool's item page.