arcgis.gis.nb module

Bases: object

Provides access to the ArcGIS Notebook Server administration API.

property data_access: NotebookDataAccess

Provides access to managing files stored on notebook server.

Returns:

NotebookDataAccess object

property health_check: bool

The health_check verifies that your ArcGIS Notebook Server site has been created, and that its Docker environment has been correctly configured.

This is only available if the site can be accessed through the web adapter

Returns:

Boolean

property info

Returns information about the server site itself

Returns:

PropertyMap

property logs

Provides access to the notebook server’s logging system

Returns:

LogManager

property machine

Provides access to managing the registered machines with ArcGIS Notebook Server

Returns:

MachineManager

property notebooks

Provides access to managing the ArcGIS Notebook Server’s Notebooks

Returns:

NotebookManager

property properties

Properties of the object

property security

Provides access to managing the ArcGIS Notebook Server’s security settings.

Returns:

SecurityManager

property services

Provides access to managing notebook created geoprocessing tools

Returns:

NBServicesManager

property site

Provides access to the notebook server’s site management operations

Returns:

SiteManager

property system

returns access to the system properties of the ArcGIS Notebook Server

Returns:

SystemManager

property url

The URL of the notebook server.

property version

Returns the notebook server version

Returns:

List

Bases: object

Provides access to managing a site’s notebooks. An object of this class can be created using notebooks property of the NotebookServer class

execute_notebook(item: Item, update_portal_item: bool = True, parameters: list | None = None, save_parameters: bool = False, future: bool = False)

The Execute Notebook operation allows administrators and users with the Create and Edit Notebooks privilege to remotely run a notebook that they own. The notebook specified in the operation will be run with all cells in order.

Using this operation, you can schedule the execution of a notebook, either once or with a regular occurrence. This allows you to automate repeating tasks such as data collection and cleaning, content updates, and portal administration. On Linux machines, use a cron job to schedule the executeNotebook operation; on Windows machines, you can use the Task Scheduler.

Note

To run this operation in ArcGIS Enterprise, you must log in with an Enterprise account. You cannot execute notebooks using the ArcGIS Notebook Server primary site administrator account.

You can specify parameters to be used in the notebook at execution time. If you’ve specified one or more parameters, they’ll be inserted into the notebook as a new cell. This cell will be placed at the beginning of the notebook, unless you have added the parameters tag to a cell.

See Execute Notebook for full administration details.

Parameter	Description
item	Required notebook Item. Opens the existing portal notebook.
update_portal_item	Optional Boolean. Specifies whether you want to update the notebook’s portal item after execution. The default is True. You may want to specify true when the notebook you’re executing contains information that needs to be updated, such as a workflow that collects the most recent version of a dataset. It may not be important to update the portal item if the notebook won’t store any new information after executing, such as an administrative notebook that emails reminders to inactive users.
parameters	Optional Dictionary. Defines the parameters to add to the notebook for this execution. The parameters will be inserted as a new cell directly after the cell you have tagged parameters. Separate parameters with a comma. Use formats: “x”:1 when defining number parameters “y”:”text” when defining string parameters See Prepare the Notebook for detailed explanation.
save_parameters	Optional Boolean. Specifies whether the notebook parameters cell should be saved in the notebook for future use. The default is False.
future	Optional boolean. If True, a future object will be returned and the process runs asynchronously, allowing for other work to be done while processing completes. If False, which is the default, the process waits for results before continuing.

Returns:

• If future=False, a Python dictionary

• If future = True, then the result is a concurrent.futures.Future object. Call result() on the object to get the response

# Usage Example:

>>> from arcgis.gis import GIS
>>> gis = GIS("home")
>>> nb_server = gis.notebook_server[0]

>>> notebook_item = gis.content.get('<notebook_item_id>')

>>> nb_mgr = nb_server.notebooks
>>> nb_mgr.execute_notebook(notebook_item)

list()

Returns a list of notebook instances on the Notebook Server

Returns:

List of Notebook objects

open_notebook(itemid: str, templateid: str | None = None, nb_runtimeid: str | None = None, template_nb: str | None = None, *, future: bool = False)

Opens a notebook on the notebook server

Parameter	Description
itemid	Required String. Opens an existing portal item.
templateid	Optional String. The id of the portal notebook template. To get the system templates, look at the sample notebooks group: >>> from arcgis.gis import GIS >>> gis = GIS() >>> grp = gis.groups.search("title:(esri sample notebooks) AND >>> owner:"esri_notebook")[0] >>> grp.content
nb_runtimeid	Optional String. The runtime to use to generate a new notebook.
template_nb	Optional String. The start up template for the notebook.
future	Optional Bool. If True, the job will run asynchronously.

Returns:

Dict or Job

property properties

returns the properties of the resource

restore_runtime()

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

This operation restores the two default notebook runtimes in ArcGIS Notebook Server - ArcGIS Notebook Python 3 Standard and ArcGIS Notebook Python 3 Advanced - to their original settings.

This was deprecated at version 2.4.2. Use the `runtime_manager` instead.

property runtime_manager: RuntimeManager

Returns the manager to manage runtimes

Returns:

RuntimeManager

property runtimes: Iterable[Runtime]

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

Returns a list of all runtimes

Returns:

Iterable[Runtime]

This was deprecated at version 2.4.2. Use the `runtime_manager` instead.

property snapshots

Provides access to managing Notebook’s snapshots

Returns:

SnapshotManager

Bases: object

This represents an individual notebook resource in the notebook server.

close()

This operation stops a running notebook. You can use it to free up space in your notebook container. Idle notebooks are automatically cleaned up according to the duration defined by the idleNotebookThreshold property. The default value for that property is 24 hours.

Returns:

Boolean

property properties

returns the properties of the resource

Bases: object

Represents a specific notebook runtime configured with ArcGIS Notebook Server.

This class provides access to runtime metadata and available libraries, and allows administrators to update or delete the runtime.

Example: Get available notebook runtimes and print their names.

from arcgis.gis import GIS
gis = GIS("home")

# get notebook server instance
notebooks = gis.notebook_server
notebook = notebooks[0]

# get notebook manager instance
notebook_mgr = notebook.notebooks

# get notebook runtime manager
runtime_mgr = notebook_mgr.runtime_manager

# see runtimes
runtimes = runtime_mgr.runtimes
for runtime in runtimes:
    print(f"Runtime Name: {runtime.properties['name']}")

Output:

Runtime Name: ArcGIS Notebook Python 3 Standard
Runtime Name: ArcGIS Notebook Python 3 Advanced

delete()

Deletes the current runtime from the ArcGIS Notebook Server site.

Returns:

Boolean

property manifest

This resource returns a JSON representation of all the Python libraries supported in the specified notebook runtime. Notebook authors who open notebooks using this runtime are able to import any of the libraries in the manifest into their notebooks.

Returns:

List of Dictionaries.

property properties

Gets the properties for the specified Notebook Server runtime.

update(name: str | None = None, image_id: str | None = None, max_cpu: float | None = None, max_memory: float | None = None, memory_unit: str | None = None, max_swap_memory: str | None = None, swap_memory_unit: str | None = None, shared_memory: str | None = None, docker_runtime: str | None = None, shared_unit: str | None = None, version: str | None = None, container_type: str | None = None, pull_string: str | None = None, require_advanced_priv: bool | None = None, manifest: str | None = None)

This operation allows you to update the properties of a notebook runtime in ArcGIS Notebook Server. These settings will be applied to every container to which the runtime is applied.

You can use this operation to update the resource limits of the runtime, such as maximum CPU and maximum memory. You can also use it to extend either of the default notebook runtimes, in order to make additional Python modules available to your notebook authors, or as a step in making ArcGIS Notebook Server able to use graphical processing units (GPUs).

Example: Update maximum memory of a specific notebook runtime in ArcGIS Notebook Server site.

from arcgis.gis import GIS
gis = GIS("home")

# get notebook manager
notebooks = gis.notebook_server
notebook = notebooks[0]
notebook_mgr = notebook.notebooks

# get runtime manager
runtime_mgr = notebook_mgr.runtime_manager
runtimes = runtime_mgr.runtimes

# list runtimes and update first runtime memory
runtimes = list(runtime_mgr.runtimes)
runtimes[0].update(max_memory=6)

Returns:

Boolean

Bases: object

Allows for management and creation of snapshots (save points) for ArcGIS Notebooks.

create(item: Item, name: str, description: str | None = None, notebook_json: dict | None = None, access: bool = False)

Creates a Snapshot of a given item.

Parameter	Description
item	Required Item. The ‘Notebook’ typed item to create a snapshot for.
name	Required String. The name of the snapshot. This is the identifier used to identify the snapshot.
description	Optional String. A piece of text that describes the snapshot.
notebook_json	Optional Dict. If you want to store different JSON text other than what is in the current notebook provide it here.
access	Optional Bool. When false, the snapshot will not be publicly available.

Returns:

Dict

list(item: Item)

Returns a list of snapshots for a notebook item.

Parameter	Description
item	Required Item. The Notebook Item to get all snapshots for.

Returns:

List of SnapShot objects

property properties

Gets metadata for the Notebook Server snapshots endpoint.

Bases: object

Represents a snapshot of a notebook item. Snapshots capture the state of a notebook at a specific point in time.

delete()

Deletes a snapshot associated with the notebook item.

Parameter	Description
item	Required Item. The ‘Notebook’ typed item to remove snapshots from.
snapshot	Required String. The name of the snapshot.

Returns:

Boolean

download()

Downloads a notebook snapshot (.ipynb) to the local file system.

Returns:

String (Path of saved file)

restore(title: str | None = None, preserve: bool = True, description: str | None = None)

Rolls back the notebook to a previous snapshot state.

Parameter	Description
title	Optional string. The Item’s title.
preserve	Optional Bool. If True, the current notebook version is preserved as a snapshot.
description	Optional String. Text describing the restoration point.

Returns:

Dict

save_as_item(title: str)

Converts a snapshot to a new notebook Item.

Parameter	Description
title	Required String. The name of the new notebook.

Returns:

Item

Bases: object

The System resource is a collection of server-wide resources in your ArcGIS Notebook Server site. Within this resource, you can access information and perform operations pertaining to licenses, Web Adaptors, containers, server properties, directories, Jobs, and the configuration store.

property config_store: Dict[str, Any]

The configuration store maintains configurations for ArcGIS Notebook Server. Typical configurations include all the resources such as machines and security rules that are required to power the site. In a way, the configuration store is a physical representation of a site.

Every ArcGIS Notebook Server machine, when it joins the site, is provided with a connection to the configuration store and it can thereafter participate in the management of the site. You can change the store’s properties during runtime using the edit operation.

The Administrator API that runs on every server machine is capable of reading and writing to the store. As a result, the store must be accessible to every server machine within the site. The default implementation is built on top of a file system and stores all the configurations in a hierarchy of folders and files.

Returns:

Dict

property containers: List[Container]

Returns a list of active containers.

Returns:

List of containers

delete_all_jobs() → bool

Administrators can clean up an open notebook and execute notebook jobs on demand. Administrators can view and delete all jobs. Non-administrative users with create and edit notebook privileges can only view and delete their own jobs. Only jobs in completed or failed states will be cleaned up.

Returns:

Boolean

property directories: DirectoryManager

Provides access to registering directories

Returns:

DirectoryManager

job_details(job_id: str) → Dict[str, Any]

A job represents the asynchronous execution of an operation in ArcGIS Notebook Server. You can acquire progress information by periodically querying the job.

Parameter	Description
job_id	Required String. The unique identifier of the job.

Returns:

Dict

property jobs: List[Dict[str, Any]]

This resource is a collection of all the administrative jobs (asynchronous operations) created within your site. When operations that support asynchronous execution are run, ArcGIS Notebook Server creates a new job entry that can be queried for its current status and messages.

Returns:

List

property licenses: Dict[str, Any]

Gets the license resource list. The licenses resource lists the current license level of ArcGIS Notebook Sever and all authorized extensions. Contact Esri Customer Service if you have questions about license levels or expiration properties.

list_jobs(num: int = 100, details: bool = False) → List[Dict[str, Any]]

This resource is a collection of all the administrative jobs (asynchronous operations) created within your site. When operations that support asynchronous execution are run, ArcGIS Notebook Server creates a new job entry that can be queried for its current status and messages. This is used for Notebook Server 10.9+

Parameter	Description
details	Optional Bool. For 10.9+ Notebook Servers, to get the expanded details of a Job, set the details to True. False will provide back a shortened job status.
num	Optional Integer. The number of jobs to return. The default is 100. This is only valid on 10.9+.

Returns:

List

property properties: PropertyMap

ArcGIS Notebook Server has configuration properties that govern some of its intricate behavior. This resource is a container for these properties. The properties are available to all server objects and extensions through the server environment interface.

You can use this property to get and/or set the available properties.

#Usage Example to set property:
>>> nbserver = gis.notebook_server[0]

>>> nbserver.system.properties = {"webSocketSize" : 32}

See the REST API documention for Notebook Server System properties for current complete list of available properties.

Returns:

dictionary-like PropertyMap

property recent_statistics: Dict[str, Any]

returns statistics about the current state of the notebook server

Returns:

Dictionary

property web_adaptors: WebAdaptorManager

returns a list of web adapters

Returns:

List

Bases: object

This represents a single hosted notebook container.

logs(count: int | None = 1000) → List[str]

Returns the container logs

Returns:

List[str]

property notebooks: List[ContainerNotebook]

A list of all notebooks currently open in the container

Returns:

List of ContainerNotebook objects

property properties

returns the properties of the resource

property sessions

When an ArcGIS Notebook is opened in a container, a computational engine called a kernel is launched; the kernel runs while the notebook is active and executes all the work done by the notebook. This resource tracks the active kernels running in the specified container to provide information about current notebook sessions.

Returns:

List of Dict

Response	Description
ID	The unique ID string for the container session.
path	The working path to the running ArcGIS Notebook, ending in .ipynb.
kernel	Properties describing the kernel. They are as follows: last_activity: The date and time of the most recent action performed by the kernel. name: The name of the kernel. At 10.7, this value is python3. id: The unique ID string for the kernel. execution_state: Whether the kernel is currently executing an action or is idle. connections: The number of users currently accessing the notebook.

shutdown()

Terminates the current container

Returns:

Boolean

property statistics: Dict[str, Any]

Returns information about the current container

Returns:

Dict[str,Any]

Bases: object

Represents an individual notebook container

close() → bool

This operation stops a running notebook

Returns:

Boolean

property properties: PropertyMap

The container notebook properties

Returns:

PropertyMap

Bases: object

Manages a collection of registered directories in ArcGIS Notebook Server.

Use this manager to list, register, and unregister directories, and to retrieve directory properties.

Example: Get directories in Notebook Server site and print their names and local path.

from arcgis.gis import GIS
gis = GIS("home")

# get notebook server instance
notebooks = gis.notebook_server
notebook = notebooks[0]

# get system manager instance
system_mgr = notebook.system

# get notebook directory manager
directory_mgr = system_mgr.directories

# get directories properties and print their names and paths
for directory in directory_mgr.properties["directories"]:
    print(f"

Name: {directory[‘name’]}, Path: {directory[‘path’]}”)

list() → List[Dict[str, Any]]

Gets a list of all directories registered in the Notebook Sever site.

Returns:

List

property properties: PropertyMap

Gets the properties for the directories in the Notebook Server site.

register(name: str, path: str, directory_type: str) → bool

This operation registers a new data directory from your local machine with the ArcGIS Notebook Server site. Registering a local folder as a data directory allows your notebook authors to work with files in the folder.

Parameter	Description
name	Required string. The name of the directory.
path	Required string. The full path to the directory on your machine.
directory_type	Required string. The type of directory. Values: DATA | WORKSPACE | OUTPUT

Returns:

Boolean

unregister(directory_id: str) → bool

This operation unregisters an existing directory from the ArcGIS Notebook Server site.

Parameter	Description
directory_id	Required String. The directory ID to remove.

Returns:

Boolean

Bases: object

Represents a single Web Adaptor registered with ArcGIS Notebook Server.

The Web Adaptor functions natively as the reverse-proxy entry point for the Notebook Server site. It forwards user requests, hides internal server details, handles WebSocket traffic, and participates in front-end authentication flows.

This class exposes operations to manage an individual registered adaptor, such as unregistering it from the site.

Example: Retrieve the registered Web Adaptors for a Notebook Server.

wa_mgr = gis.notebook_server[0].system.web_adaptors
web_adaptors = wa_mgr.list()
if isinstance(web_adaptors, list) and web_adaptors:
    first_adaptor = web_adaptors[0]

unregister()

Unregisters this Web Adaptor from the Notebook Server site.

Example: Locate a Web Adaptor by machine name before unregistering it.

wa_mgr = gis.notebook_server[0].system.web_adaptors
target_name = "wa-machine-01"
web_adaptors = wa_mgr.list()

if isinstance(web_adaptors, list):
    target = next(
        (
            wa
            for wa in web_adaptors
            if wa._con.get(wa._url, {"f": "json"}).get("machineName")
            == target_name
        ),
        None,
    )
    confirm = False  # Set to True to perform unregister.
    if target and confirm:
        print(target.unregister())

Returns:

Boolean indicating success, or a dictionary with server error details.

Bases: object

Manages Web Adaptors for ArcGIS Notebook Server.

Use this manager to list registered adaptors, register new adaptors, and get or update web adaptor configuration settings.

Example: Access the Web Adaptor manager for a Notebook Server.

nb = gis.notebook_server[0]
wa_mgr = nb.system.web_adaptors

property config: Dict[str, Any]

Gets the current Web Adaptor configuration.

Example: Retrieve the current Web Adaptor configuration.

wa_mgr = gis.notebook_server[0].system.web_adaptors
cfg = wa_mgr.config
print(cfg)

Returns:

Dictionary containing the current configuration values.

list() → List[WebAdaptor]

Returns all registered Web Adaptors.

Example: List the registered Web Adaptors for a Notebook Server.

wa_mgr = gis.notebook_server[0].system.web_adaptors
web_adaptors = wa_mgr.list()
if isinstance(web_adaptors, list):
    print(len(web_adaptors))

Returns:

List of WebAdaptor objects, or a dictionary on failure.

property properties: PropertyMap

Gets metadata for the Notebook Server web adaptors endpoint.

Example: Retrieve Web Adaptor endpoint metadata.

wa_mgr = gis.notebook_server[0].system.web_adaptors
props = wa_mgr.properties
print(dict(props).keys())

register(name: str, ip: str, webadaptor_url: str, http_port: int, https_port: int, description: str | None = '')

Registers a new WebAdaptor.

Parameter	Description
name	Required string. The machine name of the Web Adaptor.
ip	Required string. The IP address of the Web Adaptor machine.
webadaptor_url	Required string. The public URL of the Web Adaptor endpoint.
http_port	Required integer. The HTTP port used by the Web Adaptor.
https_port	Required integer. The HTTPS port used by the Web Adaptor.
description	Optional string. Description of the Web Adaptor.

Returns:

Boolean indicating success, or a dictionary with server error details.

Example: Register a Web Adaptor with the Notebook Server site.

wa_mgr = gis.notebook_server[0].system.web_adaptors
ok = wa_mgr.register(
    name="wa-machine-01",
    ip="10.0.0.25",
    webadaptor_url="https://notebooks.example.com/arcgis",
    http_port=80,
    https_port=443,
    description="Primary notebook web adaptor",
)
print(ok)

Bases: object

Manages backup and restore operations for an ArcGIS Notebook Server site.

Access this manager through the site property.

Example: Access the site manager for a Notebook Server.

site = gis.notebook_server[0].site
site

Output:

< SiteManager @ https://example.com/notebookserver/admin >

export_site(location: str)

ArcGIS Notebook Server provides this operation to back up the site’s configuration store, along with the importSite operation to restore a site configuration from a backup. The configuration store hosts essential information about the ArcGIS Notebook Server site and its machines.

The output of this operation is a ZIP file with the .agssite file extension.

There are many items and directories that are not backed up by this operation. Among them:

• Notebooks

• Container settings

• Jobs directory

If desired, you can create your own file system backups for these items.

Parameter	Description
location	Required string. The full path to the directory where the site configuration will be exported. The Notebook Server must have access to this directory.

Returns:

Python dictionary. The export response, including the operation status and the location of the exported site configuration.

Example: Export the Notebook Server site configuration to a server-accessible directory.

site = gis.notebook_server[0].site
response = site.export_site("//myserver/Export_April3")

import_site(location: str)

Restores a site configuration from a backup. The backup will have been created and exported by the exportSite() operation as a ZIP file with the .agssite file extension.

Warning

This operation overwrites the current contents of your ArcGIS Notebook Server site’s configuration store with the contents of the backup. Use it only when you intend to replace the current site configuration.

You can use this operation to restore a site configuration in the event of machine failure or human error.

The import operation may take a while to complete. The method does not return until the server responds.

Parameter	Description
location	Required string. The full path to the exported .agssite backup file. The Notebook Server must have access to this file.

Returns:

str or Python dict. The server status string, or the raw response dictionary when no status is returned.

Example: Restore the Notebook Server site configuration from an exported .agssite file.

site = gis.notebook_server[0].site
response = site.import_site("//myserver/Export_April3/arcgisnotebookserver_site.agssite")

property properties

Gets metadata for the Notebook Server site resource.

Example: Retrieve site resource metadata.

site = gis.notebook_server[0].site
properties = site.properties
properties

Output:

  {
      "resources": [
        "machines",
        "notebooks",
        "security",
        "system",
        "services",
        "logs",
        "dataaccess",
        "info",
        "mode"
      ],
      "siteId": "ff165127-e1d2-4591-9d9b-5e1b94c7c5c4",
      "version": "12.1.0"
}

Returns:

PropertyMap containing metadata for the site resource.

Bases: object

Manages logs and log settings for an ArcGIS Notebook Server site.

Access this manager through the logs property.

Example: Access the log manager for a Notebook Server.

logs = gis.notebook_server[0].logs

clean()

Deletes all the log files on all server machines in the site. This is an irreversible operation.

This operation forces the server to clean the logs, which has the effect of freeing up disk space. However, it is not required that you invoke this operation because the server periodically purges old logs.

Example: Delete the log files from all Notebook Server machines.

logs = gis.notebook_server[0].logs
result = logs.clean()

Returns:

bool or dict. A Boolean indicating whether the operation succeeded, or the raw server response when no status is returned.

property properties

Gets metadata for the Notebook Server logs endpoint.

Example: Retrieve log endpoint metadata.

logs = gis.notebook_server[0].logs
properties = logs.properties

Returns:

PropertyMap containing metadata for the logs resource.

query(start_time: datetime | str | None = None, end_time: datetime | str | None = None, since_server_start: bool = False, level: str = 'WARNING', services: str = '*', machines: str = '*', server: str = '*', codes: list[int | str] | str | None = None, process_IDs: list[int | str] | str | None = None, export: bool = False, export_type: str = 'CSV', out_path: str | None = None)

The query operation on the logs resource provides a way to aggregate, filter, and page through logs across the entire site.

Example: Query warning and more severe log messages.

logs = gis.notebook_server[0].logs
messages = logs.query(level="WARNING")

Parameter	Description
start_time	Optional datetime or string. The most recent time to query. Default is now. Time can be specified as a datetime object, in milliseconds since UNIX epoch, or as an ArcGIS Server timestamp. Example for string: “startTime”: “2011-08-01T15:17:20” Example for datetime: “startTime”: datetime.datetime(2011, 8, 1, 15, 17, 20)
end_time	Optional datetime or string. The oldest time to include in the result set. You can use this to limit the query to the last n minutes or hours as needed. Default is the beginning of all logging.
since_server_start	Optional bool. Gets only the records written since the server started (True). The default is False.
level	Optional string. Gets only the records with a log level at or more severe than the level declared here. Can be one of (in severity order): DEBUG VERBOSE FINE INFO WARNING SEVERE The default is WARNING.
services	Optional string. Query records related to a specific service. The default is all.
machines	Optional string. Query records related to a specific machine. The default is all.
server	Optional string. Query records related to a specific server. The default is all.
codes	Optional list or comma-separated string. Gets only the records with the specified codes.The default value is all. See Log codes documentation for full details on options.
process_IDs	Optional list or comma-separated string. Query by the machine process IDs that logged the event.
export	Optional bool. Indicates whether to export the query results. The default is False. When True, out_path must also be provided for the results to be written to a file.
export_type	Optional string. The export file type. CSV or TAB are the choices, CSV is the default.
out_path	Optional string. The path to download the log file to. When export is True and no path is provided, a temporary file is created. If the provided path has no extension, .csv or .txt is appended based on the export type. The path should end in .csv or .txt depending on the export type.

Returns:

A Python dictionary with the following keys: hasMore, startTime, endTime and logMessages of the log items that match the specific query. If export option is set to True, the output log file path is returned.

property settings

Gets or sets the current log settings. When setting this property, provide a dictionary containing the values to modify; unspecified settings are preserved.

Example: Retrieve the current log settings.

logs = gis.notebook_server[0].logs
settings = logs.settings

Example: Update log settings while preserving unspecified values.

logs = gis.notebook_server[0].logs
settings = dict(logs.settings)
settings["logLevel"] = "INFO"
logs.settings = settings

Parameter	Description
value	Required dict. A dictionary containing the key/value pairs to modify the log settings. See the Notebook Server log settings documentation for the available keys and values.

Returns:

PropertyMap

Bases: object

This resource provides the name and URL of the ArcGIS Notebook Server machine in the site. An object of this class can be created using machine property of the NotebookServer class

list()

Returns a list of Machine instances registered in the Notebook Server site.

Returns:

List of Machine objects.

property properties

Returns the properties of the machines registered in the Notebook Server site

Bases: object

This resource provides information about the machine in your ArcGIS Notebook Server site. You can update some of these properties using the Edit Machine operation.

create_self_signed_cert(alias: str, keysize: str, common_name: str, org_unit: str, organization: str, city: str, state: str, country: str, keyalg: str = 'RSA', sigalg: str = 'SHA1withRSA', validity: int = 90, san: str | None = None)

Use this operation to create a self-signed certificate or as a starting point for getting a production-ready CA-signed certificate. ArcGIS Notebook Server will generate a certificate for you and store it in its keystore. The certificate generated should only be used in development and staging environments.

Parameter	Description
alias	Required String. A unique name that easily identifies the certificate.
keyalg	Optional String. The algorithm used to generate the key pairs. The default is RSA.
keysize	Required String. Specifies the size in bits to use when generating the cryptographic keys used to create the certificate. The larger the key size, the harder it is to break the encryption; however, the time to decrypt encrypted data increases with key size. For DSA, the key size can be between 512 and 1,024. For RSA, the recommended key size is 2,048 or greater.
sigalg	Optional String. Use the default (SHA1withRSA). If your organization has specific security restrictions, then one of the following algorithms can be used for DSA: SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA1withDSA.
common_name	Required String. Use the domain name of your server name as the common name. If your server will be accessed on the Internet through the URL https://www.notebookserver.com:11443/arcgis/, use www.notebookserver.com as the common name.If your server will only be accessible on your local area network (LAN) through the URL https://notebookserver.domain.com:11443/arcgis/, use notebookserver as the common name.
org_unit	Required String. The name of your organizational unit, for example, GIS Department.
organization	Required String. The name of your organization, for example, Esri.
city	Required String. The name of the city or locality, for example, Redlands.
state	Required String. The full name of your state or province, for example, California.
country	Required String. The abbreviated code for your country, for example, US.
validity	Required Integer. The total time in days during which this certificate will be valid, for example, 365. The default is 90.
san	Optional String. The subject alternative name (SAN) is an optional parameter that defines alternatives to the common name (CN) specified in the SSL certificate. There cannot be any spaces in the SAN parameter value. If no SAN is defined, a website can only be accessed (without SSL certificate errors) by using the common name in the URL. If a SAN is defined and a DNS name is present, the website can only be accessed by what is listed in the SAN. Multiple DNS names can be specified if desired. For example, the URLs https://www.esri.com, https://esri, and https://10.60.1.16 can be used to access the same site if the SSL certificate is created using the following SAN parameter value: DNS:www.esri.com,DNS:esri,IP:10.60.1.16

Returns:

A JSON-formatted string indicating the success status or error message.

delete_certificate(certificate: str)

Deletes a SSL certificate using the certificate alias.

Parameter	Description
certificate	Required string. The name of the certificate to delete.

Returns:

String stating “success” or error message.

export_certificate(certificate: str)

Downloads an SSL certificate. The file returned by the server is an X.509 certificate. The downloaded certificate can then be imported into a client that is making HTTP requests.

Parameter	Description
certificate	Required string. The name of the certificate in the key store.

Returns:

String containing the local path to the downloaded certificate.

generate_CSR(certificate: str)

Generates a certificate signing request (CSR) for a self-signed certificate. A CSR is required by a CA to create a digitally signed version of your certificate. Supply the certificate object that was created with method ssl_certificate.

Parameter	Description
certificate	Required string. The name of the certificate in the key store.

Returns:

The CSR.

property hardware

This resource displays hardware information for the machine in your ArcGIS Notebook Server site. It updates the information when it detects any change to the configuration of your machine, as well as each time the machine is restarted.

Returns:

Dict

import_CA_signed_certificate(certificate: str, ca_signed_certificate: str)

Imports a certificate authority (CA)-signed SSL certificate into the key store.

Parameter	Description
certificate	Required string. The name of the certificate in the key store.
ca_signed_certificate	Required string. The multi-part POST parameter containing the signed certificate file.

Returns:

A boolean indicating success (True) or failure (False).

import_existing_server_certificate(alias: str, cert_password: str, cert_file: str)

Imports an existing server certificate, stored in the PKCS #12 format, into the keystore. If the certificate is a CA-signed certificate, you must first import the CA root or intermediate certificate using the importRootCertificate operation.

Parameter	Description
alias	Required string. A unique name for the certificate that easily identifies it.
cert_password	Required string. The password to unlock the file containing the certificate.
cert_file	Required string. The multi-part POST parameter containing the certificate file.

Returns:

A JSON-formatted string indicating the success status or error message.

import_root_certificate(alias: str, root_CA_certificate: str)

Imports a certificate authority’s (CA) root and intermediate certificates into the keystore.

To create a production quality CA-signed certificate, you need to add the CA’s certificates into the keystore that enables the SSL mechanism to trust the CA (and the certificates it is signed). While most of the popular CA’s certificates are already available in the keystore, you can use this operation if you have a custom CA or specific intermediate certificates.

Parameter	Description
alias	Required string. The name of the certificate.
root_CA_certificate	Required string. The multi-part POST parameter containing the certificate file.

Returns:

A JSON-formatted string indicating the success status or error message.

property properties

Get/Set the properties on the ArcGIS Notebook Server machine.

Set operation allows you to update properties on the ArcGIS Notebook Server machine.

ArcGIS Notebook Server uses port 11443 for communication. When you create a site, this is assigned as the default. You must ensure that your firewall allows communication through port 11443.

ssl_certificate(certificate: str)

Provides information about the specified ssl certificate.

Note

Even though a self-signed certificate can be used to enable SSL, it is recommended that you use a self-signed certificate only on staging or development servers.

Parameter	Description
certificate	Required string. The name of the certificate in the key store to grab information from.

Returns:

Dict

property ssl_certificates

Gets the list of all the certificates (self-signed and CA-signed) created for the server machine. The server securely stores these certificates inside a key store within the configuration store.

property status

Returns the status and health information of the Notebook Server machine.

Returns:

Dict

unregister()

Removes machine from the Notebook Server site. This server machine will no longer participate in the site or run any of the GIS services. All resources that were acquired by the server machine (memory, files, and so forth) will be released.

Typically, you should only invoke this operation if the machine is going to be shut down for extended periods of time, or if it is being upgraded.

Once a machine has been unregistered, you can create a new site or join an existing site.

Returns:

A boolean indicating success (True) or failure (False).

Bases: object

Manages security settings for an ArcGIS Notebook Server site.

Access this manager through the security property.

Example: Access the security settings manager for a Notebook Server.

security = gis.notebook_server[0].security

property configuration

Gets and sets the security configuration for an ArcGIS Notebook Server site. Getting this property returns the current configuration. Setting this property updates one or more configuration values while preserving values that are not included in the update.

Example: Retrieve the active security configuration.

security = gis.notebook_server[0].security
configuration = security.configuration

Returned Configuration Properties

Property	Description
httpsProtocols	A comma-separated string of TLS protocols enabled for ArcGIS Notebook Server.
serverFunction	The function of the server, such as NotebookServer.
contentSecurityPolicy	The content security policy settings for REST and administrative resources.
serverRole	The role of the server, such as FEDERATED_SERVER.
http2Enabled	Whether HTTP/2 is enabled.
authenticationTier	The tier at which requests to access GIS services are authenticated. Values include WEB_ADAPTOR, NOTEBOOK_SERVER, and ARCGIS_PORTAL.
cipherSuites	A comma-separated string of cipher suites enabled for ArcGIS Notebook Server. The available suites depend on the deployment.
allowInternetCORSAccess	Whether access from Internet origins through CORS is allowed.
serverType	The type of server, such as ARCGIS_NOTEBOOK_SERVER.
allowDirectAccess	Whether direct access to the server is allowed.
tokenServiceKey	The key used to encrypt tokens. This value is sensitive.
authenticationMode	The authentication mode used by ArcGIS Notebook Server. Values include ARCGIS_TOKEN and ARCGIS_PORTAL_TOKEN.
portalProperties	A dictionary containing properties for a federated portal.

Portal Properties

Property	Description
portalMode	The federation mode. The value is ARCGIS_PORTAL_FEDERATION.
portalUrl	The external URL of the portal, in the format https://webadaptorhost.domain.com/webadaptorname.
serverId	The ID of the server federated with the portal.
serverUrl	The external URL of the federated ArcGIS Notebook Server, in the format https://webadaptorhost.domain.com/webadaptorname.
privateHostingServerUrl	The private URL of the portal’s hosting server.
privatePortalUrl	The private URL of the portal.

Additional portal properties may be returned depending on the ArcGIS Enterprise version and federation configuration.

Properties Supported for Updates

Key	Description
portalProperties	Optional dict. Portal properties represented as a JSON object.
httpsProtocols	Optional string. Comma-separated TLS protocols used by ArcGIS Notebook Server. The available protocols depend on the deployment.
cipherSuites	Optional string. Comma-separated cipher suites used by ArcGIS Notebook Server. The available suites depend on the deployment.
allowInternetCORSAccess	Optional boolean. Whether access from Internet origins through CORS is allowed.
http2Enabled	Optional boolean. Whether HTTP/2 is enabled.
authenticationTier	Optional string. The tier at which requests to access GIS services are authenticated. Values: WEB_ADAPTOR | NOTEBOOK_SERVER | ARCGIS_PORTAL. Do not use this property to change the federation state of the Notebook Server.

Example: Update the enabled TLS protocols while preserving other configuration values.

security = gis.notebook_server[0].security
security.configuration = {"httpsProtocols": "TLSv1.2"}

Bases: object

The Data Access Workspace Directory allows notebook authors to manage files used in their notebooks.

create_folder(folder: str) → bool

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the create_folder method found in a NotebookFolder instead. The first folder in the list of folders is the Home folder.

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the create_folder method found in a NotebookFolder instead. The first folder in the list of folders is the Home folder.

Create a folder in your /arcgis/home notebook workspace directory.

Parameter	Description
folder	Required String. The name of the folder to create. To create a folder in a subfolder, use the format subfolder1/subfolder2/foldername. If you want to create a folder in the root directory, use the format foldername.

property files: list[NotebookFile]

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the files property found in a NotebookFolder instead or the get method with DATAACCESSTYPE.FILE.

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the files property found in a NotebookFolder instead or the get method with DATAACCESSTYPE.FILE.

lists files that are located in the workspace directory (/arcgis/home) of the user making the request.

Returns:

list[NotebookFile] - list of NotebookFile objects

property folders: list[NotebookFolder]

Returns the folders in the workspace directory (/arcgis/home) of the user making the request.

Returns:

list[NotebookFolder] - A list of NotebookFolder objects containing the folders in the workspace.

get(name: str, type: DATAACCESSTYPE | str = DATAACCESSTYPE.FOLDER) → NotebookFolder | NotebookFile

Get a notebook folder or file by name.

Returns:

NotebookFolder or NotebookFile - The requested folder or file.

get_workspace(user: User | str) → NotebookDataAccess

Returns the NotebookDataAccess object for the specified user. This is only available to organization administrators.

Parameter	Description
user	Required User instance or string. The user or username for which the workspace will be retrieved.

Returns:

NotebookDataAccess - A NotebookDataAccess object for the specified user.

transfer(source_user: User | str, target_user: User | str | None = None, folder_name: str | None = None) → bool

Transfer the workspace of one user to another user in the organization. This can only be done by an administrator.

This method is useful for transferring the workspace of a user who is leaving the organization to another user.

Parameter	Description
source_user	Required User instance or string. The user or username for which the workspace will be transferred.
target_user	Optional User instance or string. The user or username to which the workspace will be transferred. If not provided, the workspace will be transferred to the current user.
folder_name	Optional String. The name of the folder to which the workspace will be transferred. If not provided, a default name will be used.

Returns:

True if the transfer was successful, False or an error if it was not.

upload(fp: str | list[str], folder: str | None = None) → list[bool]

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the upload method found in a NotebookFolder instead.

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the upload method found in a NotebookFolder instead.

Uploads a file to the Notebook Server

Parameter	Description
fp	Required String or list of Strings. Either: the path to the file to upload, a list of paths to the files to upload, or the path to a folder where all the files in the folder will be uploaded under the folder name.
folder	Optional String. The name of the folder to upload the file to. If not provided, the file will be uploaded to the root directory of the notebook workspace. Example: folder1

Returns:

list of booleans. True if the file was uploaded, False or an error if it was not.

Bases: object

Represents a Single File on the ArcGIS Notebook Server

delete() → bool

Deletes a file from the system. This will permanently delete the file and the action cannot be undone.

Returns:

True if the file was deleted, False or an error if it was not.

download() → str

Copies down the data from the server to the local machine

Returns:

str as file path

erase() → bool

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the delete method instead.

Deprecated since version 2.4.2: Removed in: 2.5.0. Use the delete method instead.

Deletes a file from the system

Returns:

Boolean

move(target_folder: NotebookFolder) → bool | dict[str, Any]

Moves the file to another NotebookFolder.

Parameter	Description
target_folder	Required NotebookFolder. The target folder to move the file to.

Returns:

True if the file was moved successfully, False or an error dictionary otherwise.

property name: str

Get the file name

Returns:

str - The name of the file.

property properties

returns the properties of the resource

Returns:

Dict

rename(name: str) → bool | dict[str, Any]

Rename the file on the server.

Parameter	Description
name	Required String. The new name of the file.

Returns:

True if the file was renamed, False or an error as a dictionary if it was not.

transfer(target_user: User | str | None = None) → bool

Transfer the file to another user in the organization. This can only be done by an administrator. The file will be renamed to _transferred_{file_name} and moved to the target user’s Home folder.

Parameter	Description
target_user	Required User instance or string. The user or username to which the file will be transferred. If a string is provided, it should be the username of the target user.

Returns:

True if the file was transferred successfully, False or an error if it was not.

Bases: object

Represents a folder in the ArcGIS Notebook Server workspace. This class allows you to manage files and subfolders within a specific folder in the notebook workspace directory.

create_folder(folder_name: str) → NotebookFolder

Create a subfolder in the current folder.

Parameter	Description
folder_name	Required String. The name of the subfolder to create. This will create a subfolder within the current folder.

Returns:

NotebookFolder - A NotebookFolder object representing the newly created subfolder.

delete() → bool

Deletes a folder and all content from the system. This will permanently delete the folder and content and the action cannot be undone.

Returns:

True if the folder and content was deleted, False or an error if it was not.

property files: list[NotebookFile]

Returns the files in the folder.

Returns:

list[NotebookFile] - A list of NotebookFile objects representing the files in the folder.

property folders: list[NotebookFolder]

Returns the subfolders in the folder.

Returns:

list[NotebookFolder] - A list of NotebookFolder objects representing the subfolders.

move(target_folder: NotebookFolder) → bool

Move the folder to another folder in the notebook workspace.

Parameter	Description
target_folder	Required NotebookFolder. The target folder to which this folder will be moved. The target folder must be a valid NotebookFolder object.

Returns:

True if the folder was moved successfully, False or an error if it was not.

property name: str

Get or set the name of the folder.

Parameter	Description
new_name	Required String. The name of the folder. This will rename the folder.

Returns:

str - The name of the folder.

rename(name: str) → bool | dict[str, Any]

Rename the folder.

Parameter	Description
name	Required String. The new name of the folder. The name must be a simple, non-empty name without slashes.

Returns:

True if the folder was renamed, False or an error as a dictionary if it was not.

transfer(target_user: User | str | None = None) → bool | dict[str, Any]

Transfer the folder to another user in the organization. This can only be done by an administrator. The folder will be renamed to _transferred_{folder_name} and moved to the target user’s Home folder.

Parameter	Description
target_user	Required User instance or string. The user or username to which the folder will be transferred. If a string is provided, it should be the username of the target user.

Returns:

True if the folder was transferred successfully. If not then, False or an error dictionary.

upload(fp: str | list[str]) → list[bool]

Uploads a file to the Notebook Server in the current folder.

Parameter	Description
fp	Required String or list of Strings. Either: the path to the file to upload, a list of paths to the files to upload, or the path to a folder where all the files in the folder will be uploaded under the folder name.

Returns:

list of booleans. True if the file was uploaded, False or an error if it was not.

Bases: Enum

Enum for data access types.

FILE = 'file'

FOLDER = 'folder'

Bases: object

The NBServicesManager is used to manage the container of services published on the notebook server. An object of this class can be created using services() method of the NotebookServer class

create(item: Item, title: str, description: str = None) → Item

ArcGIS Notebook Server supports publishing a geoprocessing service from a notebook. The create operation creates a service when a JSON representation of the service is submitted to it.

To publish a service on Notebook Server, you must be an administrator or a user with Notebook and Publish Web Tools privileges. The notebook must belong to the user publishing the service.

A notebook-to-web tool relationship is created for maintaining the relation between the notebook and the associated web tool created for the service. This relationship ensures that ownership and sharing permissions are the same for both. When a notebook is deleted, the associated web tool is also deleted.

Parameter	Description
item	Required Item. The notebook Item to create a service from.
title	Required string. The name of the GP tool
description	Required string. The description of the tool.

Returns:

Item of the tool.

# Usage Example:
>>> from arcgis.gis import GIS

>>> gis = GIS(profile="your_enterprise_admin_profile")
>>> notebook_item = gis.content.get("792a18985c2f4f15b8df0e1b545ea73f")

>>> service_manager = gis.notebook_server[0].services
>>> service_tool = service_manager.create(notebook_item, "nb_service", "this is a notebook service")

>>> service_tool

<Item title:"nb_service" type:Geoprocessing Toolbox owner:enterprise_admin>

property properties: dict

Returns the manager’s properties

# Usage Example:
>>> properties = service_manager.properties

property services: tuple[NBService]

Returns a tuple of all NBService created by the Notebook Server.

Returns:

tuple

# Usage Example:
>>> services = service_manager.services

property types: dict

The types resource provides metadata and extensions that can be enabled on GPServer service types supported in ArcGIS Notebook Server. The services framework uses this information to validate a service and construct the objects in the service. The metadata contains identifiers for each object, a default list of capabilities, properties, and other resource information. Type information for a specific service type can be accessed by appending the type name (GPServer, for example) to this URL.

Returns:

Dict

# Usage Example:
>>> types = service_manager.types

Bases: object

A single ArcGIS Notebook Geoprocessing Tool.

delete() → bool

Deletes the notebook service

Returns:

Boolean

property properties

Returns the manager’s properties