Execute Notebook | ArcGIS REST APIs

URL:: https://<root>/notebooks/executeNotebook
Methods:: POST
Version Introduced:: 11.4

Access requirements

Required privileges

The Enterprise Administrator API requires privilege-based access. An administrator must be assigned a specific user privilege, or role, to access any given endpoint. Listed below are the user privileges or roles an administrator can be assigned that provides access to this endpoint. If multiple privileges are listed, only one needs to be assigned to gain access.

Manage licenses Link to organization-specific group Update Delete Security and infrastructure Servers Organization website Organization webhooks

To access notebook-related endpoints, administrators must be assigned a custom role that includes any of the privileges listed above as well as the Create and edit notebooks privilege.

Tokens

This API requires token-based authentication. A token is automatically generated for administrators who sign in to the Enterprise Administrator API directory's HTML interface. Tokens generated in this way are stored for the entirety of the session.

Those accessing the API directory outside of the HTML interface will need to acquire a session token from the generateToken operation in the Enterprise Directory API. For security reasons, all POST requests made to the Enterprise Administrator API must include a token in the request body.

Learn how to generate a token

Description

The executeNotebook operation allows administrators and users with Create and Edit ArcGIS Notebooks privileges to automate running a notebook. The notebook specified in the operation is run with all cells in order. Using this operation and an external scheduling tool, you can schedule a notebook to run automatically either once or as a regular occurrence. This allows you to automate repeating tasks such as data collection and cleaning, content updates, and portal administration.

You can specify parameters to be used in the notebook when it's run. If you specify one or more parameters, they are inserted into the notebook as a new cell. This cell is placed at the beginning of the notebook, unless you added the parameters tag to a cell.

Request parameters

Parameter	Details
`itemId`	The portal item ID of the notebook you want to execute. You can find this value in the Notebook resource in this directory or in the portal as part of the item details page URL. Ensure that the notebook is using a runtime that's compatible with your software version. Example: Use dark colors for code blocksCopy `1 2 itemId=70770e46d4be426dbd3adbec5f9124c8`
`updatePortalItem`	Specifies whether the notebook portal item is updated after execution. The default is `true`. You can 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 new information after execution, such as an administrative notebook that sends email reminders to inactive users. Values: `true` \| `false`
`notebookParameters`	Optional parameters in JSON format that will be added to the notebook for this execution. The parameters are inserted as a new cell directly after the cell you tagged as parameters . The following data types are supported for task parameters: string, long, Boolean, date, feature set, and record set. Example: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 notebookParameters= { "myLongVariable": 100, "epochSecondsDate": 1632326711000, "myStringVariable": "secret.pwd", "myDoubleVariable": 3.14, "myBooleanVariable": false, "myLinearUnitDictionary": { "distance": 345.678, "units": "esriMiles" }, "myFeatureSetJSON": { "geometryType": "esriGeometryPoint", "spatialReference": { "wkid": 4326 }, "fields": [ { "name": "Id", "type": "esriFieldTypeOID", "alias": "Id" }, { "name": "Name", "type": "esriFieldTypeString", "alias": "Name" } ], "features": [{ "geometry": { "x": -104.44, "y": 34.83 }, "attributes": { "Id": 43, "Name": "Feature 1" } }, { "geometry": { "x": -100.65, "y": 33.69 }, "attributes": { "Id": 67, "Name": "Feature 2" } } ] } }
`saveInjectedParameters`	Specifies whether the `notebookParameters` cell is saved in the notebook for future use. The default is `false`. Values: `true \| false`
`f`	The response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`

Response properties

Property	Details
`status`	Indicates whether the operation succeeded in executing the notebook.
`jobId`	A unique Job Id representing the asynchronous `executeNotebook` job.
`maxSnapshotsPerNotebookItem`	The maximum number of snapshots allowed for a notebook. The default value is 5.
`jobUrl`	Job url to monitor the status of `executeNotebook` job.

Example usage

The following is a sample POST request for the executeNotebook operation:

Use dark colors for code blocksCopy
POST /<context>/admin/notebooks/executeNotebook HTTP/1.1
Host: organization.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: [ ]

itemId=70770e46d4be426dbd3adbec5f9124c8&updatePortalItem=true&notebookParameters={"name": "somename", "population": 19927500, "pop_percent": 11.94, "lowest_elevation_ft": -220, "highest_elevation": 12486, "top5cities": ["City 1", "City 2", "City 3", "City 4", "City 5"], "top5Values": [ 100, 98.2, 93.3, 89, 74], "isTrue": false, "value": null, "access": { "allowed": true}}&saveInjectedParameters=false&f=pjson&token=[token]

JSON Response example

Use dark colors for code blocksCopy
{
  "jobId": "j3a581ce0-cf2f-4190-96a5-c5bc0617dd5d",
  "jobUrl": " https://organization.example.com/<context>/admin/jobs/j3a581ce0-cf2f-4190-96a5-c5bc0617dd5d",
  "status": "success"
}