An Introduction to the ArcGIS API for Python from ArcGIS Pro
Automation has always been a great bonus for the GIS professional using Esri’s ArcGIS tools. Many experienced users will have used Visual Basic for Applications in ArcMap to author custom workflows for both GIS and GIS administration tasks. While VBA is largely frowned upon by professional developers (according to Wikipedia, VBA has held its position as "most dreaded" language for developers for the last 2 years) its strength lay in its low barrier for entry and ease of use. However, when your workflows got more complex and your VBA codebase grew over several iterations of enhancements and improvements, the cracks started to show, and maintaining complex VBA became troublesome.
Esri, along with many in the wider IT industry, have embraced Python as the customisation language of choice. Python also has the benefits of a low barrier for entry and ease of use, but enjoys wide spread support among professional and casual developers alike (as of December 2020 Python ranked third in TIOBE's index of most popular programming languages, behind C and Java).
Python runs on many operating systems. The language design encourages code readability (the use of whitespace, for example, has significant meaning within the code). Python can be written as procedural or object-oriented code. There are many supporting libraries which extend the core functionality of Python in all manner of areas, for example, Machine Learning, Data Science, Image Manipulation, Graphing, and, of course, GIS.
In this post I’m going to concentrate on using Python, and the ArcGIS API for Python from within ArcGIS Pro to automate administration tasks for your ArcGIS Online or ArcGIS Enterprise.
The aim is to demonstrate the ease of use of the language and its environment, and to encourage you to explore some more complex use cases. There’s a lot of community support, both for Python in general and for the ArcGIS API for Python. Hopefully you can find answers to your questions there, or even contribute some of your code and experiences.
First up, though, how do you get started?
Well you’ll be glad to know that if you are an existing ArcGIS Pro user, there are no additional installations or configurations required to get started. Python and a Jupyter Notebooks environment are both installed along with ArcGIS Pro, and while you can enhance your environment, you can get a lot done and explore many areas with what comes out-of-the-box.
So, how do you access Python from within ArcGIS Pro?
Figure 1 - New Python Notebook in ArcGIS Pro
From your ArcGIS Pro project, select “New Notebook” from the “Insert” tab on the toolbar ribbon. This will create and initialise a new Python notebook called “New Notebook”.
Figure 2 - The Catalog view
I like to right-click on the Notebook in the Catalog view and rename it to something more relevant.
Figure 3 - Rename your notebook
You are then faced with a “cell” labelled “In”. This is your interactive Python environment. Code entered in the “In” cell is executed when the cursor is in the cell and you hit the Run button. A new “Out” cell will display any output from your Python code.
Let’s look at who is registered with your portal. In these examples, I’ll be using our ArcGIS Online organisation account, for which I’m an admin user. Many of the same options will be available against a local deployment of ArcGIS Enterprise or your own ArcGIS Online account. Note that you will be afforded the same privileges by the ArcGIS API for Python as you are interactively, so you will require administrator privileges to get results from some of the examples below.
First, we need to import the ArcGIS API for Python, and establish a connection to our portal.
Figure 5 - Code snippet: Connecting to your Portal
By using the “home” parameter when connecting and creating my gis object, I’m defaulting to connecting to the same portal, with the same user, that ArcGIS Pro is connected to. In this case, I’m connected with my user to the Esri Ireland ArcGIS Online organisation.
Figure 6 - ArcGIS Pro Connected User
If I was going to administer a different portal, I would supply the appropriate URL and user credentials.
Figure 7 - Code snippet: Solicit user details
Here, I’m also importing a library called “getpass” which allows me to solicit a password without it showing up on the screen. I’ve specified the URL an ArcGIS Enterprise instance; you’d replace that with your local URL.
Not much to see yet, just confirmation of the gis connected.
Now that we have our connection, we can query which users are registered. There are a couple of different ways to do this, in this example I’ll be querying what types of users are registered, and how many of each there are.
Figure 8 - Code snippet: Listing user types
I can then extend this to drill into a specific type of user to retrieve the details for each of the users.
Figure 9 - Code snippet: Listing users in each user type
Note: The # symbol in Python denotes a comment – the lines starting with the # aren’t code that is executed, merely a note of what the intent of the code is. Code indentation in python is an integral part of the language. The code within the for loops above, for example, is only deemed to be within the loop by virtue of the indent. It’s one of those things you’ll either love, or hate, about python!
\t is used to put a [tab] in the output.
We have 96 creator user types in our organisation, of which my user (acullen) is one. I can use the following line to retrieve my user directly, and then I can see fine grained details for that user, including when I last logged into the portal.
Figure 10 - Code snippet: Showing User details and last login
We could use this method to determine who is actively using our portal, and those less active.
To investigate the content owned by this user, select items belonging to the username and iterate through them.
Figure 11 - Code snippet: Listing content for a given user
I own several hundred items in ArcGIS Online, and the output cell from the above is formatted in a scrolling panel for ease of reading.
Each Content Item in ArcGIS Online or ArcGIS Enterprise has an ItemID – this can be found programmatically, or, as shown below, just looking at the item in the browser interface.
Figure 12 - ItemId in the address bar and item in ArcGIS Online
The ItemID for this AllIslandWindfarms test layer is highlighted in the URL. Using the ID we could directly reference the layer from our Python code.
Figure 13 - Code snippet: Selecting an item by ItemId and displaying it
The content_status is used to flag an item’s status. It can be blank, or set to 'org_authoritative' or 'deprecated'.
Figure 14 - Code snippet: Showing an item’s status
Looking at the windfarm data in ArcGIS Online (below), we can see it doesn’t have Delete Protection set. Delete Protection gives an extra prompt to a user to avoid the item being accidentally deleted.
Here’s a fun one, I can programmatically send my users a notification.
Figure 18 - Code snippet: Sending a notification to a user
Which then shows up in their alerts status.
Figure 19 - User notification in ArcGIS Online
This is just the tip of the iceberg in terms of automating administration of your ArcGIS Portal. You can create and maintain Groups, share content, manage your Movers/Joiners/Leavers, and keep an eye on what is and isn’t being used regularly in your Organisation.
The Python Notebooks created in ArcGIS Pro can be shared with colleagues, and better still be saved and executed directly on ArcGIS Online even without ArcGIS Pro.
Of course, these are just some simple examples, and even with these, I’m skipping over many of the nuances to the code I’m presenting. What I hope it demonstrates, though, is how, with a few lines of Python, some powerful automations can be achieved.
I’d encourage you to delve into the world of Python and the ArcGIS API for Python, and would love to get feedback on the custom automations you create to help you with your workflows, be it from an administration point of view (on boarding new users, for example), or a GIS or data analysis task.
The code snippets referenced in this article can be downloaded here.
Andrew has a background in software development dating back to the early nineties, having cut his teeth with BASIC programming on the 1983 Atari 800 home computer, pushing the limits of its 48 kilobytes of RAM and cassette tape drive. He has been with Esri Ireland for the past 15 years, starting out as a software engineer and currently as a Solution Architect.
When not found in front of a hot keyboard either in the Esri world, or toying with development, video and audio editing, Andrew can be found in front of a hot stove, indulging his passion for cooking.