Backup and Restore an ArcGIS Online Dashboard using the ArcGIS API for Python
Glen Bambrick
Table of Contents
The Video
Introduction
The ArcGIS API for Python is a powerful Python library that allows users to interact with and automate tasks in ArcGIS Online (or Portal). The API is excellent for programmatically creating, maintaining, updating and extracting components of ArcGIS Online such as Dashboards. In this blog post we will focus on using the ArcGIS API for Python to export a Dashboard to configuration files that will act as an archive or backup, and then restore or recreate a Dashboard in ArcGIS Online using the exported files. We will export two files, one that represents the Dashboard JSON Definition, and another that represents the Dashboard Item Settings. We will also account for a thumbnail.
The workflow for extracting is the exact same as the Backup ArcGIS Online WebMap Configurations using the ArcGIS API for Python script so we won’t go through that here but you will see it in action in the video above. Here, we will focus on creating a Dashboard from the configurations files.
Discover the power of automation and script-based operations to efficiently manage content in ArcGIS Online. Throughout this course, you will gain practical, hands-on experience with using the ArcGIS API for Python to perform a wide range of content management tasks with ease, such as creating Folders and Groups and managing content within them.
arcgis modules
The API provides access to your organisations ArcGIS Online via the GIS class in the gis module. This GIS class is the gateway to ArcGIS Online. We need the Dashboard class to create a Dashboard object and to save as a Dashboard Item. From the Standard Python Library we import json to aid with getting the JSON from our files, and os to aid with accessing our backup files.
## provides access to ArcGIS Online
from arcgis.gis import GIS
## required to create a new Dashboard item in ArcGIS Online
from arcgis.apps.dashboard import Dashboard
## for reading in our json files
import json
## for accessing config files
import os
Accessing ArcGIS Online
GIS class. There are a handful of ways to achieve access, if you are logged into your ArcGIS Online in ArcGIS Pro you can simply use "home", otherwise, another common way is to provide the ArcGIS Online URL, followed by your username and password.
## Access AGOL
agol = GIS("home")
## Access AGOL
agol = GIS(
url = "https://your_organisation.maps.arcgis.com/",
username = "Your_Username",
password = "Your_Password"
)
Required inputs
We require two user inputs; the folder where the backup files reside, and the name of the new Dashboard to create
## the folder that contains the json config files
archive_folder = "path/to/archive/folder"
## the name for the new webmap
new_dsh_name = "NEW_WEBMAP_NAME"
The JSON Filepaths
We have two JSON files to consider, one that contains the Item Settings and the other that contains the Dashboard Definition.
## the filepath to the Settings json file
json_settings_file = [f.path for f in os.scandir(archive_folder) if f.name.startswith("Settings")][0]
## the fielpath to the WebMap Definition json file
json_definition_file = [f.path for f in os.scandir(archive_folder) if f.name.startswith("Definition")][0]
Get the Item Settings
We load our item settings from the JSON file and workout the thumbnail filepath.
## open the json file for the settings
with open(json_settings_file) as dsh_json:
dsh_settings = json.load(dsh_json)
## get the thumbnail name
thumbnail_name = dsh_settings["thumbnail"].split("/")[-1]
## get the thumbnail filepath
thumbnail_path = os.path.join(archive_folder, thumbnail_name)
Create the Dashboard Object and Save as an Item
Here, we create a Dashboard object and use the save() method to save the Dashboard as n ArcGIS Content Item. While calling save() we can utilise a small number of properties, we will fill out the rest shortly.
## create the Dashboard object
dashboard = Dashboard()
## save the Dashboard as an Item of Content
dsh_item = dashboard.save(
title=new_dsh_name,
description= dsh_settings["description"],
summary = dsh_settings["snippet"],
tags = dsh_settings["tags"]
)
Update the Dashboard Item Object Properties
Via the Item Object we can update some more properties and settings such as delete protection, content status and favorite.
## Delete Protection
dsh_item.protect(enable=dsh_settings["protected"])
## Content Status
if "contentStatus" in dsh_settings:
dsh_item.content_status = dsh_settings["contentStatus"]
## Favorite
dsh_item.favorite = dsh_settings["favorite"]
Update the Dashboard Item Dictionary
We can use the Item object update() method to update more properties and setting listed below.
We also move the Dashboard Item to the original folder if the user running the script is the owner of the original exported dashboard configs.
## set the item properties dictionary
dsh_item_dict = {
"typeKeywords" : dsh_settings["typeKeywords"],
"extent" : dsh_settings["extent"],
"spatialReference" : dsh_settings["spatialReference"],
"accessInformation" : dsh_settings["accessInformation"],
"licenseInfo" : dsh_settings["licenseInfo"],
"culture" : dsh_settings["culture"],
"access" : dsh_settings["access"],
"commentsEnabled" : dsh_settings["commentsEnabled"],
"categories" : dsh_settings["categories"],
}
dsh_item.update(
item_properties = dsh_item_dict
)
## get the folder
if dsh_settings["owner"] == agol.users.me.username:
folder = dsh_settings["ownerFolder"]
dsh_item.move(folder)
Update the Dashboard Definition
So far, we have only created a new empty Dashboard and manipulated the item properties and setting, this final part will load in the Dashboard definition for the different components and widgets.
## set the item properties dictionary
dsh_item_dict = {
"typeKeywords" : dsh_settings["typeKeywords"],
"extent" : dsh_settings["extent"],
"spatialReference" : dsh_settings["spatialReference"],
"accessInformation" : dsh_settings["accessInformation"],
"licenseInfo" : dsh_settings["licenseInfo"],
"culture" : dsh_settings["culture"],
"access" : dsh_settings["access"],
"commentsEnabled" : dsh_settings["commentsEnabled"],
"categories" : dsh_settings["categories"],
}
dsh_item.update(
item_properties = dsh_item_dict
)
## get the folder
if dsh_settings["owner"] == agol.users.me.username:
folder = dsh_settings["ownerFolder"]
dsh_item.move(folder)
Notes
As of the ArcGIS API Version 2.4.0 you will get some deprecation warnings, but just ignore them for now. When these deprecations cease to occur and the functionality removed from the API, I will update this blog with the lates workflow for creating backups and restoring Dashboards.
This workflow is for Dashboards within your own Organisation. In the video we see how to tweak the scripts slighly to get publicly available Dashboards and re-make in your Organisation so you can go in and interrogate how they did it and edit to suit your own needs.
Geospatial Professionals, GIS Analysts, and enthusiasts will discover the power of automation and script-based operations to efficiently interact and update WebMaps in ArcGIS Online. Throughout this course, you will gain practical, hands-on experience in leveraging the ArcGIS API for Python to perform a wide range of WebMap tasks with ease.
We will dissect WebMaps for all that they are and by the end of this course you will be comfortable with manipulating the JSON, which is the behind the scenes configuration of a WebMap, to produce scripts for workflows where there is currently no API Python method, such as grouping layers.
All the code in one place
You can find the entire code workflow below with links to important components in the documentation that were used.
## provides access to ArcGIS Online
from arcgis.gis import GIS
## required to create a new Dashboard item in ArcGIS Online
from arcgis.apps.dashboard import Dashboard
## for reading in our json files
import json
## for accessing config files
import os
################################################################################
## API Reference Links:
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#gis
## https://developers.arcgis.com/python/latest/api-reference/arcgis.map.toc.html#map
## https://developers.arcgis.com/python/latest/api-reference/arcgis.map.toc.html#arcgis.map.Map.save
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#item
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.protect
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.favorite
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.content_status
## https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.update
##
## API Versions: 2.1.0.2, 2.2.0.1, 2.3.0, 2.4.0
##
################################################################################
################################################################################
## ACCESS ARCGIS ONLINE ########################################################
agol = GIS("home")
################################################################################
## USER INPUTS #################################################################
## the folder that contains the json config files
archive_folder = "path/to/archive/folder"
## the name for the new dashboard
new_dsh_name = "I RESTORED THIS DASHBOARD"
################################################################################
## THE JSON FILES ##############################################################
## the filepath to the Settings json file
json_settings_file = [f.path for f in os.scandir(archive_folder) if f.name.startswith("Settings")][0]
## the fielpath to the Dashboard Definition json file
json_definition_file = [f.path for f in os.scandir(archive_folder) if f.name.startswith("Definition")][0]
################################################################################
## GET THE ITEM SETTINGS #######################################################
## open the json file for the settings
with open(json_settings_file) as dsh_json:
dsh_settings = json.load(dsh_json)
## get the thumbnail name
thumbnail_name = dsh_settings["thumbnail"].split("/")[-1]
## get the thumbnail filepath
thumbnail_path = os.path.join(archive_folder, thumbnail_name)
################################################################################
## CREATE DASHBOARD OBJECT AND SAVE AS DASHBOARD ITEM ##########################
## create the Dashboard object
dashboard = Dashboard()
## save the Dashboard as an Item of Content
dsh_item = dashboard.save(
title=new_dsh_name,
description= dsh_settings["description"],
summary = dsh_settings["snippet"],
tags = dsh_settings["tags"]
)
################################################################################
## UPDATE THE DASHBOAD ITEM OBJECT PROPERTIES ##################################
## Delete Protection
dsh_item.protect(enable=dsh_settings["protected"])
## Content Status
if "contentStatus" in dsh_settings:
dsh_item.content_status = dsh_settings["contentStatus"]
## Favorite
dsh_item.favorite = dsh_settings["favorite"]
################################################################################
## UPDATE THE DASHBOARD ITEM DICT PROPERTIES ###################################
## set the item properties dictionary
dsh_item_dict = {
"typeKeywords" : dsh_settings["typeKeywords"],
"extent" : dsh_settings["extent"],
"spatialReference" : dsh_settings["spatialReference"],
"accessInformation" : dsh_settings["accessInformation"],
"licenseInfo" : dsh_settings["licenseInfo"],
"culture" : dsh_settings["culture"],
"access" : dsh_settings["access"],
"commentsEnabled" : dsh_settings["commentsEnabled"],
"categories" : dsh_settings["categories"],
}
dsh_item.update(
item_properties = dsh_item_dict
)
## get the folder
if dsh_settings["owner"] == agol.users.me.username:
folder = dsh_settings["ownerFolder"]
dsh_item.move(folder)
################################################################################
## UPDATE THE DASHBOARD DEFINITION #############################################
## apply the definition from the json file
with open(json_definition_file) as dsh_json:
dsh_def = json.load(dsh_json)
item_properties = {"text":dsh_def}
dsh_item.update(item_properties=item_properties)
################################################################################
print("\nSCRIPT COMPLETE")
