diff --git a/guide/13-managing-arcgis-applications/introduction_to_dashboards_module.ipynb b/guide/13-managing-arcgis-applications/introduction_to_dashboards_module.ipynb new file mode 100644 index 0000000000..b9f5ad9b4c --- /dev/null +++ b/guide/13-managing-arcgis-applications/introduction_to_dashboards_module.ipynb @@ -0,0 +1,451 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a9e5b180", + "metadata": {}, + "source": [ + "# Introduction to arcgis.apps.dashboards module" + ] + }, + { + "cell_type": "markdown", + "id": "3c886262", + "metadata": {}, + "source": [ + "The `arcgis.apps.dashboards` module, introduced in ArcGIS Python API v2.4.3, provides programmatic tools for managing dashboard items. It enables automation of common tasks such as:\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "2a9dfd7c", + "metadata": {}, + "source": [ + "This module supports only modern ArcGIS Dashboards items and does not work with items created in the retired ArcGIS Dashboards Classic app. \n", + "\n", + "Tip: To check whether a dashboard is supported, you can look at its data using the item’s `get_data()` function. Dashboards with a version shown as a string (such as \"4.30.0\",\"4.31.0\" and so on) or a number of 27 or higher are supported (see helper function below). If you find an older Classic dashboard (those with a version number below 27), you can update it by opening it in ArcGIS Dashboards, switching to Edit mode, and saving it." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "08c28595", + "metadata": {}, + "outputs": [], + "source": [ + "# a helper function to determine if a dashboard item is classic\n", + "def is_classic_dashboard(dashboard_item):\n", + " try:\n", + " item_data = dashboard_item.get_data()\n", + " if 'version' in item_data:\n", + " version = item_data['version']\n", + " # check if version is number and less than 27\n", + " if isinstance(version, (int)) and version < 27:\n", + " return True\n", + " # versions that are strings (eg. \"4.30.0\",\"4.31.0\", etc.,) or a numeric version with value >=27 are supported\n", + " else:\n", + " return False\n", + " except Exception as e:\n", + " print(f\"Error checking dashboard version: {e}\")\n", + " return False" + ] + }, + { + "cell_type": "markdown", + "id": "7dde42a9", + "metadata": {}, + "source": [ + "
[TBD] Note: Support is currently limited to ArcGIS Online dashboards. ArcGIS Enterprise support will be introduced in a future release.
" + ] + }, + { + "cell_type": "markdown", + "id": "b1b62531", + "metadata": {}, + "source": [ + "## Primary Class: DashboardManager" + ] + }, + { + "cell_type": "markdown", + "id": "50816a33", + "metadata": {}, + "source": [ + "\n", + "`DashboardManager` is the main class for managing dashboard items. It supports operations such as dependency discovery and replacement, copying and upgrading dashboards.\n" + ] + }, + { + "cell_type": "markdown", + "id": "c7ac6789", + "metadata": {}, + "source": [ + "Let's explore how we can leverage `DashboardManager` to manage our dashboard items. " + ] + }, + { + "cell_type": "markdown", + "id": "b5888183", + "metadata": {}, + "source": [ + "### Initialization" + ] + }, + { + "cell_type": "markdown", + "id": "11506f2f-e63f-4faf-9673-906be1b1e75e", + "metadata": {}, + "source": [ + "To begin, import necessary modules including the Dashboards module, and establish a connection to an ArcGIS online organization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9da4162a", + "metadata": {}, + "outputs": [], + "source": [ + "#import libraries\n", + "from arcgis.gis import GIS\n", + "from arcgis.apps.dashboards import DashboardManager, DependencyOptions,ItemMapping, LayerMapping, FieldMapping" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d35f0917", + "metadata": {}, + "outputs": [], + "source": [ + "#connect to ArcGIS Online \n", + "source_gis = GIS( profile='your_online_profile')" + ] + }, + { + "cell_type": "markdown", + "id": "cdd91930", + "metadata": {}, + "source": [ + "Once gis connection is established, instantiate the dashboard manager for a specific dashboard item in the source GIS." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "89bdce07", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "#Instantiate DashboardManager for a specific dashboard item\n", + "dashboard_manager = DashboardManager('8b0248a382f645d69fb9b172a358233a', source_gis)\n", + "dashboard_manager" + ] + }, + { + "cell_type": "markdown", + "id": "d43ef733", + "metadata": {}, + "source": [ + "The screenshot below provides a visual representation of the dashboard item above, illustrating airlines performance at Minneapolis Airport" + ] + }, + { + "cell_type": "markdown", + "id": "00d35c08", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "id": "55c3c420", + "metadata": {}, + "source": [ + "### Discovering dashboard dependencies" + ] + }, + { + "cell_type": "markdown", + "id": "130d11d9", + "metadata": {}, + "source": [ + "The `get_dependencies()` function in the `DashboardManager` class retrieves the dependencies that a dashboard uses, including web maps and scenes, feature layers, embedded apps, and Arcade data expressions. You can optionally retrieve layer IDs and fields by specifying the DependencyOptions object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b9ef8481", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[ItemResult(item_id='0755d6ca21bf4dcebc3baa1c742336a4', source=None, layers=[LayerResult(id='1994e5200eb-layer-5', sublayer_id=None, fields=[FieldResult(name='OBJECTID'), FieldResult(name='CRSDepTime'), FieldResult(name='DepTime'), FieldResult(name='Diverted'), FieldResult(name='Cancelled'), FieldResult(name='dayOfWeek'), FieldResult(name='delayed'), FieldResult(name='CarrierDelay'), FieldResult(name='LateAircraftDelay'), FieldResult(name='NASDelay'), FieldResult(name='WeatherDelay'), FieldResult(name='SecurityDelay'), FieldResult(name='OriginCityName'), FieldResult(name='DestCityName')]), LayerResult(id='1994e5200e9-layer-4', sublayer_id=None, fields=[FieldResult(name='OBJECTID'), FieldResult(name='CRSArrTime'), FieldResult(name='ArrTime'), FieldResult(name='Cancelled'), FieldResult(name='Diverted'), FieldResult(name='LateAircraftDelay'), FieldResult(name='CarrierDelay'), FieldResult(name='NASDelay'), FieldResult(name='WeatherDelay'), FieldResult(name='SecurityDelay'), FieldResult(name='OriginCityName'), FieldResult(name='DestCityName')]), LayerResult(id='1994e5200e5-layer-3', sublayer_id=None, fields=None), LayerResult(id='1994e52a6b7-layer-130', sublayer_id=None, fields=None)])]" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "#Get dependencies with layers and fields\n", + "options = DependencyOptions(include_layers=True, include_fields=True)\n", + "dependencies= dashboard_manager.get_dependencies(options)\n", + "dependencies" + ] + }, + { + "cell_type": "markdown", + "id": "6dcc8c57", + "metadata": {}, + "source": [ + "### Updating dashboard dependencies" + ] + }, + { + "cell_type": "markdown", + "id": "0875080c", + "metadata": {}, + "source": [ + " The `replace_dependencies()` function allows you to update existing dependencies and data sources by replacing them with new ones. The `item_mapping` parameter is a list of `ItemMapping` objects, where each entry maps a source item ID to a target item ID. Within each `ItemMapping`, optional `LayerMapping` and `FieldMapping` objects specify layer-level and field-level details for the replacement.\n", + "\n", + "Here is an example of item_mapping structure -" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "00f08a6c", + "metadata": {}, + "outputs": [], + "source": [ + "#define item mapping\n", + "item_mapping = ItemMapping(\n", + " source_item_id=\"0755d6ca21bf4dcebc3baa1c742336a4\",\n", + " target_item_id=\"32071df690f2434ebe5d40641d53bd21\",\n", + " layer_mappings=[\n", + " LayerMapping(\n", + " source_layer_id='1994e52a6b7-layer-130', # web map operational layer ID\n", + " target_layer_id='1994aa9cbbd-layer-131', \n", + " source_sublayer_id=None,\n", + " target_sublayer_id=None,\n", + " field_mappings=[\n", + " FieldMapping(source_name=\"ObjectId\", target_name=\"FID\"),\n", + " FieldMapping(source_name=\"DepTime\", target_name=\"DepartureTime\"),\n", + " FieldMapping(source_name=\"ArrTime\", target_name=\"ArrivalTime\"),\n", + " ]\n", + " )\n", + " ]\n", + " )" + ] + }, + { + "cell_type": "markdown", + "id": "062f99b4", + "metadata": {}, + "source": [ + "`field_mappings` are optional and only required when the target schema differs from the source. Field replacement is supported for dashboard items with version 4.30.0 and above (i.e, string versions).\n", + "\n", + "When constructing `layer_mappings`,\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "2ad1dd83", + "metadata": {}, + "source": [ + "Now, pass the item_mapping list to `replace_dependencies()` to swap out dependencies of an existing dashboard." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8355d6c2", + "metadata": {}, + "outputs": [], + "source": [ + "#Replace dependencies using item mapping\n", + "dashboard_manager.replace_dependencies(item_mapping=[item_mapping])" + ] + }, + { + "cell_type": "markdown", + "id": "aab3870b", + "metadata": {}, + "source": [ + "The `replace_dependencies()` function updates an existing dashboard, making it ideal for scenarios where you need to fix broken data sources or update data with most current information. \n", + "\n", + "However, if the goal is to simply reuse the design layout and configurations of an existing dashboard and create a copy with different data sources, use the `copy()` function instead. Let's look at how this works below." + ] + }, + { + "cell_type": "markdown", + "id": "ad1e2d3c", + "metadata": {}, + "source": [ + "### Copying dashboard item" + ] + }, + { + "cell_type": "markdown", + "id": "4f489047", + "metadata": {}, + "source": [ + "The `copy()` function duplicates an existing dashboard within the same organization. \n", + "\n", + "> Note: Providing an `ItemMapping` list through the `item_mapping` parameter lets you remap dependencies in the new dashboard; otherwise, the copy will continue to reference the original dependencies.\n", + "\n", + "Optionally, you can specify the title for the new item, tags and the target folder via `title`, `tags` and `folder` parameters respectively." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f680576f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Airlines Performance at ATL\n", + " \n", + "

Dashboard by api_data_owner\n", + "
Last Modified: December 15, 2025\n", + "
0 comments, 0 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "#Copy dashboard with new mappings\n", + "copied_item = dashboard_manager.copy(title=\"Airlines Performance at ATL\", folder=\"Dashboards\", item_mapping=[item_mapping])\n", + "copied_item" + ] + }, + { + "cell_type": "markdown", + "id": "5612ec1a", + "metadata": {}, + "source": [ + "The screenshot below presents a visual of the copied dashboard, highlighting airlines performance at Atanta airport - " + ] + }, + { + "cell_type": "markdown", + "id": "2b102e3a", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "id": "646057ec", + "metadata": {}, + "source": [ + "> Tip - If the goal is to clone dashboards from one organization to another, it is recommended to use `clone_items()` as it has also been enhanced to support dashboard items and the remapping of their dependencies.\n" + ] + }, + { + "cell_type": "markdown", + "id": "d6729aba", + "metadata": {}, + "source": [ + "### Upgrading dashboard item" + ] + }, + { + "cell_type": "markdown", + "id": "5de7b145", + "metadata": {}, + "source": [ + "Use the `upgrade()` function to update a dashboard item to the latest version supported by the portal." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8a1eb568", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "4.34.0\n" + ] + } + ], + "source": [ + "#Upgrade dashboard\n", + "upgraded_dashboard = dashboard_manager.upgrade()\n", + "\n", + "#print upgraded dashboard item data to verify the version\n", + "print(upgraded_dashboard.get_data()['version'])" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.11" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}