Administering your GIS¶
ArcGIS administrators can leverage the gis.admin
module of ArcGIS API for Python to assist with and automate their administrative tasks. These tasks can include anything from checking the status of servers, assigning licenses to named user accounts to modifying the GIS's look and feel.
ArcGIS Online Organizations (AGOL) and ArcGIS Enterprise instances vary on the amount of customization you can make. Enterprise organizations can be customized much more than ArcGIS Online organizations as Enterprise allows administrations full access. No matter what your organization is, the API and usage is identical. The table below illustrates the extent to which each can be customized and administered.
Organizational differences
Function | ArcGIS Online | ArcGIS Enterprise |
---|---|---|
collaborations | X | X |
credits | X | |
federation | X | |
license | X | X |
logs | X | |
machines | X | |
metadata | X | X |
password_policy | X | X |
security | X | |
server | X | |
site | X | |
system | X | |
ux | X | X |
Most properties on ArcGIS Online are available on ArcGIS Enterprise except 'credit reporting' because ArcGIS Enterprise does not consume credits.
Note: You need to log in using a named user account with administrator privileges. When you login, the API detects if you are an organizational administrator, then, the GIS object will ensure you gain access to the admin module.
from arcgis.gis import GIS
gis = GIS("https://portalname.domain.com/webadaptor", "username", "password")
Managing named user licenses and entitlements¶
ArcGIS Online and Enterprise support assigning licenses for Esri premium apps such as ArcGIS Pro, Navigator for ArcGIS, AppStudio for ArcGIS Standard, Drone2Map for ArcGIS, ArcGIS Business Analyst web app, ArcGIS Community Analyst, GeoPlanner for ArcGIS, and other apps sold through ArcGIS Marketplace that use a per-member license type.
As an administrator, you use the gis.admin.license
class of Python API to view, manage and specify which members have licenses for these apps. To learn more about named user licensing model visit manage licenses help.
Listing apps licensed through the organization¶
To list all the apps currently licensed through your organization, use the all()
method:
gis.admin.license.all()
You can get the license for a particular app using the get()
method:
pro_license = gis.admin.license.get('ArcGIS Pro')
pro_license
type(pro_license)
Getting available licenses for an app¶
To query the list of all users licensed for an app, call the all()
method from the License
object corresponding to that app:
#get all users licensed for ArcGIS Pro
pro_license.all()
Using the plot()
method of the License
object, you can quickly pull up a bar chart showing the number of assigned and remaining licenses for each extension of the app.
%matplotlib inline
pro_license.plot()
Using the License
object's report
property, you can view the same information as a Pandas DataFrame table
pro_license.report
Querying extensions assigned to a named user account¶
You can find which of the app's extensions are assigned to a particular user using the License
object's user_entitlement()
method:
pro_license.user_entitlement('username')
Assigning licenses and entitlements to a named user account¶
You can assign licenses to an application and its extensions using the assign()
method.
pro_license.assign(username='arcgis_python', entitlements='desktopBasicN')
Revoking licenses from a named used account¶
To revoke an app's license from a user, call the revoke()
method from the corresponding License
object. To revoke all the entitlements, pass *
as a string.
pro_license.revoke(username='arcgis_python', entitlements='*')
Managing ArcGIS Online credits¶
If your GIS is an organization on ArcGIS Online, you would notice a credits
property exposed on your admin
object. You can use this to view, allocate credits to your users, set a default limit etc. To learn more about credits refer here.
Note: ArcGIS Enterprises do not support the concept of credits. Hence if your GIS is an instance of Enterprise, you would not see the `credits` property.
Viewing available credits:¶
gis.admin.credits.credits
Managing credits through credit budgeting¶
The credit budgeting feature of ArcGIS Online allows administrators to view, limit and allocate credits to its users. Learn more about credit budgeting here.
You can use the enable()
method to turn on credit budgeting.
gis.admin.credits.enable()
You can use the is_enabled()
property to verify if credit budgeting is turned on.
gis.admin.credits.is_enabled
Once you turn on credit budgeting, you can set a default limit for the number of credits for each user. In addition to this, you can set custom limits to users as well. Default limit applies when you create a new user and do not set a custom limit.
gis.admin.credits.default_limit
Allocating credits to a user¶
You can use the allocate()
and deallocate()
methods to allocate custom number of credits or remove credits from a named user.
#assign one tenth of the available credits to arcgis_python account
api_acc_credits = gis.admin.credits.credits / 10
gis.admin.credits.allocate(username='arcgis_python', credits=api_acc_credits)
Checking credits assigned and available to a user¶
api_acc = gis.users.get('arcgis_python')
api_acc
When you turn on credit budgeting (using the enable()
method), the User
object gets additional properties to indicate the assignedCredits
and remaining avialableCredits
. Thus, you can verify as shown below:
api_acc.assignedCredits
api_acc.availableCredits
As the user continues to use the credits, the availableCredits
property can be used to check how much is available for that account. If a user does not have a limit set, then the total available credits in the org become their available credits. The account shown below as not custom limit, hence, it inherits the org's total limit.
rohit = gis.users.get('rsingh_geosaurus')
rohit.availableCredits
Disable credit budgeting¶
Yon disable this feature by calling the disable()
method.
gis.admin.credits.disable()
Attaching and removing ArcGIS Servers from your GIS¶
If your GIS is an instance of ArcGIS Enterprise, you can build it up by federating (attaching) ArcGIS Server sites to your Enterprise. During this step, you can assign a role to your server - such as Hosting or Federated. You can also assign a function such as 'Raster Analysis', 'GeoAnalytics' etc. to designate it a purpose. Federating and maintaining your server bank is an important administrative task. To learn more about this topic and the implications of federation, refer here.
Note: Federation only applies to ArcGIS Enterprise orgs. If your GIS is an org on ArcGIS Online, you cannot perform these tasks
The Federation
class of the admin
module allows GIS administrators to script and automate tasks such as listing the servers in a GIS, identifying their role and function, federating new servers, unfederating servers under maintenance, validating the list of servers etc.
Get the list of servers federated to the GIS:
gis.admin.federation.servers
There are 2 servers federated to this GIS, the first is a HOSTING_SERVER
and the second a FEDERATED_SERVER
. The serverFunction
of the second server is set to RasterAnalytics
.
Validating your servers¶
To validate all the servers attached to your GIS, call the validate_all()
method. To validate a particular server, call validate()
and pass the server info.
gis.admin.federation.validate_all()
The second server reports a failure as the Enterprise is unable to reach or ping it. This server requires maintenance.
Unfederating a server¶
You remove a server from the GIS by calling the unfederate()
method and passing the serverId
.
gis.admin.federation.servers['servers'][1]['id']
gis.admin.federation.unfederate('GFyaVzJXiogsxKxH')
Querying Portal logs¶
Portal for ArcGIS records events that occur, and any errors associated with those events, to logs. Logs are an important tool for monitoring and troubleshooting problems with your portal. Information in the logs will help you identify errors and provide context on how to address problems. The logs also comprise a history of the events that occur over time.
For example, the following events are recorded in the logs:
- Installation and upgrade events, such as authorizing the software and creating the portal website
- Publishing of services and items, such as hosted services, web maps, and data items
- Content management events, such as sharing items, changing item ownership, and adding, updating, moving, and deleting items
- Security events, such as users logging in to the portal, creating, deleting, and disabling users, creating and changing user roles, updating HTTP and HTTPS settings, import and export of security certificates, and updating the portal's identity store
- Organization management events, such as adding and configuring groups, adding or removing users from a group, configuration of the gallery, basemaps, utility services, and federated servers, and configuring log settings and deleting logs
- General events, such as updating the portal's search index and restarting the portal
Understanding log messages is important to maintain your GIS. Refer here to learn more about logging in general and here to understand what gets logged and what the messages mean.
Using the Logs
class of the admin
module, administrators can query and work with Portal log messages. You can query the logging level and other settings from the settings
property:
gis.admin.logs.settings
Filtering and querying Portal logs¶
Using the query()
method, you can filter and search for Portal logs. Refer to the query API ref doc for all the arguments supported. In the example below, logs for the previous 10 days is searched.
import datetime
import pandas as pd
now = datetime.datetime.now()
start_time = now - datetime.timedelta(days=10)
start_time
You can pass a Python Datetime
object to the time arguments.
recent_logs = gis.admin.logs.query(start_time = start_time)
#print a message as a sample
recent_logs['logMessages'][0]
You can construct a Pandas DataFrame
from the query result and visualize the logs as a table:
log_df = pd.DataFrame.from_records(recent_logs)
log_df.head(5) #display the first 5 records
Once you have the logs as a DataFrame
, you can save it to disk in any format you choose. For instance, you can save it to a csv
file for archival.
log_df.to_csv('./portal_logs_last_10_days.csv')
Clearing logs¶
You can remove old logs and free up space on your Portal by calling the clean()
method. Note, this action is not reversible.
gis.admin.logs.clean()
Managing GIS security¶
One of the important tasks you carry out as an administrator is managing the security settings of your GIS. With the admin
module, you can accomplish tasks such as setting the password policy, managing security certificates etc.
You can use the PasswordPolicy
class in the admin
module to inspect and update the policy for your GIS. This is applicable if you GIS uses a built-in identity store.
existing_policy = gis.admin.password_policy.policy
existing_policy
Updating password policy¶
You can update this policy to any desired standard. In the example below, the following additional criteria is added.
- Contains at least one letter (A-Z, a-z)
- Contains at least one upper case letter (A-Z)
- Contains at least one lower case letter (a-z)
- Contains at least one number (0-9)
- Contains at least one special (non-alphanumeric) character
- Password will expire after
90
days - Members may not reuse their last
5
passwords
from copy import deepcopy
new_policy = deepcopy(existing_policy)
new_policy['passwordPolicy']['minLength'] = 10
new_policy['passwordPolicy']['minUpper'] = 1
new_policy['passwordPolicy']['minLower'] = 1
new_policy['passwordPolicy']['minDigit'] = 1
new_policy['passwordPolicy']['minOther'] = 1
new_policy['passwordPolicy']['expirationInDays'] = 90
new_policy['passwordPolicy']['historySize'] = 5
To update the policy, simply set the policy
property with the new values
gis.admin.password_policy.policy = new_policy['passwordPolicy']
Query the GIS to get the updated policy
gis.admin.password_policy.policy
Resetting password policy¶
You can reset the policy to the default by calling the reset()
method.
gis.admin.password_policy.reset()
Working with security configurations¶
The config
property of the Security
class gives you a snapshot of your security configuration
gis.admin.security.config
SSL certificates¶
The SSLCertificates
class provides you with a set of methods to search for certificates, import new certificates and update existing ones. The SSLCertificate
object that you get when you call the get()
or list()
methods on this class allows you to inspect, update or export individual certificates. To learn about all the tasks that can be accomplished, refer to the API REF doc.
gis.admin.security.ssl.list()
You can download or export the certificate to disk:
portal_cert = gis.admin.security.ssl.list()[0]
portal_cert.export(out_path = './')
Enterprise identity store¶
If your GIS uses an enterprise identity store instead of the built-in, you can use the EnterpriseUsers
class and EnterpriseGroups
class to search for users and user groups in the enterprise user database.
gis.admin.security.enterpriseusers
gis.admin.security.groups.properties
Managing Enterprise licenses and system settings¶
As an administrator, you can manage the licenses of the Enterprise and all the apps licensed through your Enterprise using the system.licenses
class of the admin
sub module. This functionality is different from managing named user licenses and entitlements mentioned in the beginning of this guide. This section shows you how to import and remove entitlements for different apps, the number of named user accounts that you are licensed to create and the number remaining etc.
Inspecting licenses for Portal for ArcGIS¶
Calling system.licenses.properties
will return a dictionary containing information about your license for using Portal for ArcGIS application. The dictionary below reveals the license is current, 12
is the number of named user accounts created so far and the 75
is the max licensed. The features
dictionary reveals the details on number of level 1 and 2 users that can be created.
gis.admin.system.licenses.properties
Using Python's datetime
module, you can conver the date to human readable form:
from datetime import datetime
datetime.fromtimestamp(round(gis.admin.system.licenses.properties.expiration/1000))
Releasing ArcGIS Pro licenses checked out for offline use¶
If a user checks out an ArcGIS Pro license for offline or disconnected use, and is unable to check it back in, you can release the license for the specified account by calling release_license()
method. Learn more about offline licenses in ArcGIS Pro.
gis.admin.system.licenses.release_license('username')
Inspecting the machines powering your Portal for ArcGIS¶
You can query the machines powering your Portal for ArcGIS application using the Machines
class at admin.machines
. You can inspect machine status, and unregister those under repair.
gis.admin.machines.list()
mac1 = gis.admin.machines.list()[0]
mac1.properties
Query the status of a machine.
mac1.status()
Inspecting system directories¶
You can inspect the physical location of various system directories used by the Portal for ArcGIS application:
portal_dir_list = gis.admin.system.directories
portal_dir_list[0].properties
for portal_dir in portal_dir_list:
print(portal_dir.properties.name + " | " + portal_dir.properties.physicalPath)
Inspecting web adaptors¶
You can query the web adaptors serving the Portal for ArcGIS application using the system.web_adaptors.list()
method. This returns you a list of WebAdaptor
objects. You can use this object to query the properties such as IP address, version and also unregister the adaptor for maintenance.
gis.admin.system.web_adaptors.list()
wa = gis.admin.system.web_adaptors.list()[0]
wa.properties
wa.url
Inspecting other system properties¶
Database
gis.admin.system.database
Index status
gis.admin.system.index_status
Supported languages
gis.admin.system.languages
Feedback on this topic?