PortalPy module

This help topic lists all the classes and methods in the PortalPy module that you can use to write administrative scripts against Portal for ArcGIS.

Class: Portal

An object representing a URL connection to a portal. To instantiate a Portal object, execute the code like this:

PortalPy.Portal(portalUrl, user, password)

The available Portal methods are listed in the sections below. Before working with the methods, consider the following:

• Group IDs—Many of the group functions require a Group ID. The ID is different than the group's name or title. To determine the Group ID, use the search_groups function and specify the title to obtain the Group ID.
• Time—Many of the methods return a time field. All time returns as milliseconds since 1 January 1970. Python expects the time in seconds since 1 January 1970; therefore, divide times from PortalPy by 1,000. The following example shows you how to convert PortalPy time to Python time.

  group = portalAdmin.get_group('67e1761068b7453693a0c68c92a62e2e')
  pythontime = time.ctime(group['created']/1000)

PortalPy methods

The available Portal methods are described below.

_init_

The Portal constructor. This requires the portal's URL and optionally, a user name and password.

_init_(self, url, username=None, password=None, key_file=None, cert_file=None, expiration=60, referer=None, proxy_host=None, proxy_port=None, connection=None, workdir=r'c:\users\davi3690\appdata\local\temp\2')

add_group_users

Adds users to the specified group. Only use this method if the user for the Portal object is an administrator for the entire portal or the explicit owner of the group.

add_group_users(self, user_names, group_id)

Arguments

Parameter	Description
user_names	Required string, comma-separated users
group_id	Required string, specifying group ID

Return value

A dictionary with a key of not_added that contains users not added to the group.

create_group

Creates a group and returns a group ID if successful.

create_group(self, title, tags, description=None, snippet=None, access='public', thumbnail=None, is_invitation_only=False, sort_field='avgRating', sort_order='desc', is_view_only=False)

Arguments

Parameter	Description
title	Required string, name of the group
tags	Required string, comma-delimited list of tags
description	Optional string, describes group in detail
snippet	Optional string, less than 250 characters summarizes group
access	Optional string, can be private, public, or org
thumbnail	Optional string, URL to group image
isInvitationOnly	Optional Boolean, defines whether users can join by request
sort_field	Optional string, specifies how shared items with the group sort
sort_order	Optional string, asc or desc for ascending or descending
is_view_only	Optional Boolean, defines whether the group is searchable

Return value

A string that is the group ID.

create_group_from_dict

Creates a group and returns a group ID if successful. In most cases, it is recommended to use create_group instead, as this method can take a group dictionary returned from another PortalPy call and copy it.

create_group_from_dict(self, group, thumbnail=None)

Arguments

Parameter	Description
group	dict object
thumbnail	URL to image

Example

create_group({'title': 'Test', 'access':'public'})

delete_group

Deletes a group.

delete_group(self, group_id)

Arguments

Parameter	Description
group_id	String containing the ID for the deleted group.

Return value

A Boolean indicating if the operation succeeded or failed.

delete_user

Deletes a user from the portal, optionally deleting or reassigning groups and items. You cannot delete a user in the portal if that user owns groups or items. If you choose to cascade, those items and groups are reassigned to the user identified in the reassign_to option. If you choose not to cascade, the deletion succeeds or fails depending on whether the user's items and groups have previously been transferred.

When cascading, this method deletes up to 10,000 items. If the user has more than 10,000 items, the method fails.

delete_user(self, username, cascade=False, reassign_to=None)

Arguments

Parameter	Description
username	Required string, the name of the user
cascade	Optional Boolean, true means reassign items and groups
reassign_to	Optional string, new owner of items and groups

Return value

A Boolean indicating if the operation succeeded or failed.

generate_token

Generates and returns a new token, but doesn't log in again. This method is not needed when using the Portal class to make calls into the portal. It's provided for the benefit of making calls into the portal outside of the Portal class.

The portal uses a token-based authentication mechanism where a user provides their credentials and a short-term token is used for calls. Most calls made to the ArcGIS REST API require a token and this can be appended to those requests.

generate_token(self, username, password, expiration=60)

Arguments

Parameter	Description
username	Required string, the name of the user
password	Required password, the password of the user
expiration	Optional integer, number of minutes until the token expires

Return value

A string with the token.

get_group

Returns group information for the specified group_id.

get_group(self, group_id)

Arguments

Parameter	Description
group_id	Required string, indicating the group

Return value

A dictionary object with the group's information. The keys in the dictionary object may include:

Parameter	Description
title	The name of the group
isInvitationOnly	If set to true, users can't apply to join the group
owner	The owner's user name of the group
description	Explains the group
snippet	A short summary of the group
tags	User-defined tags that describe the group
phone	Contact information for group
thumbnail	File name relative to http://<community-url>/groups/<groupId>/info
created	When the group was created, milliseconds since 1 Jan 1970
modified	When the group was last modified, milliseconds since 1 Jan 1970
access	Can be private, org, or public
userMembership	A dictionary with keys username and memberType
memberType	Provides the calling user access (owner, admin, member, none)

get_group_members

Returns members of the specified group.

get_group_members(self, group_id)

Arguments

Parameter	Description
group_id	Required string, indicating the group

Return value

A dictionary with keys: owner, admins, and users.

Parameter	Description
owner	String value, the group's owner
admins	List of strings, typically this is the same as the owner
users	List of strings, the members of the group

Example

Print the users in a group:

response = portal.get_group_members("67e1761068b7453693a0c68c92a62e2e")
for user in response['users'] :
   print user

get_group_thumbnail

Returns the bytes that make up the thumbnail for the specified group_id.

get_group_thumbnail(self, group_id)

Arguments

Parameter	Description
group_id	Required string, specifies the group's thumbnail

Return value

Bytes that represent the image.

Example

response = portal.get_group_thumbnail("67e1761068b7453693a0c68c92a62e2e")
f = open(filename, 'wb')
f.write(response)

get_users

Returns all users within the portal organization.

get_users(self, max_users=1000)

Arguments

Parameter	Description
max_users	Optional integer, the maximum number of users to return

Return value

A list of dictionaries. Each dictionary has the following keys:

Key	Value
username	String
storageUsage	Integer
storageQuota	Integer
description	String
tags	List of strings
region	String
created	Integer, when account created, milliseconds since 1 Jan 1970
modified	Integer, since account was last modified, milliseconds since 1 Jan 1970
email	String
culture	String
orgId	String
preferredView	String
groups	List of strings
role	String (user, publisher, admin, <custom_role_name> [where <custom_role_name> is the name of the custom role, for example, hostedservicepublisher]) Legacy: In Portal for ArcGIS 10.3 and earlier versions, the accepted values for non-custom roles were org_user, org_publisher, and org_admin. At 10.3.1, these values have been deprecated and replaced with the values listed above. You can continue to use the legacy values at 10.3.1, but note that the values may not be accepted in a future release.
fullName	String
thumbnail	String
idpUsername	String

Example

Print all user names in the portal:

resp = portalAdmin.get_users()
for user in resp:
   print user['username']

get_properties

Returns the portal's properties, using cache unless force=True.

get_properties(self, force=False)

get_user

Returns the user information for the specified user name.

get_user(self, username)

Arguments

Parameter	Description
username	Required string, the user name whose information you want

Return value

If the user is found, returns a dictionary object with the following keys. If no user is found, nothing returns.

Key	Value
access	String
created	Integer, when account created, milliseconds since 1 Jan 1970
culture	String, two-letter language code (en)
description	String
email	String
fullName	String
idpUsername	String, name of the user in the enterprise system
groups	List of dictionaries. For a list of dictionary keys, see get_group.
modified	Integer, since account was last modified, milliseconds since 1 Jan 1970
orgId	String, the organization ID
preferredView	String, value is either Web, GIS, or null
region	String, none or two letter country code
role	String (user, publisher, admin, <custom_role_name> [where <custom_role_name> is the name of the custom role, for example, hostedservicepublisher]) Legacy: In Portal for ArcGIS 10.3 and earlier versions, the accepted values for non-custom roles were org_user, org_publisher, and org_admin. At 10.3.1, these values have been deprecated and replaced with the values listed above. You can continue to use the legacy values at 10.3.1, but note that the values may not be accepted in a future release.
storageUsage	Integer
storageQuota	Integer
tags	List of strings
thumbnail	String
username	String

get_version

Returns the software version number, using cache unless force=True. The version information is retrieved when you create the portal object and is then cached for future requests. If you want to make a request to the portal and not rely on the cache, set the force argument to True.

get_version(self, force=False)

Arguments

Parameter	Description
force	Boolean, true=make a request, false=use cache

Return value

A string with the version. The version is an internal number that may not match the version of the installed product.

invite_group_users

Invites users to a group. A user invited to a group sees a list of invitations in the Groups tab of the portal. The user can accept or reject the invitation. The user executing the command must be the group owner.

invite_group_users(self, user_names, group_id, role='group_member', expiration=10080)

Arguments

Parameter	Description
user_names	Required string, comma-separated list of users to invite
group_id	Required string, specifies group ID you invite users to
role	Optional string, either group_member or group_admin
expiration	Optional integer, specifies how long the invitation is valid for (in minutes)

Return value

A Boolean indicating if the operation succeeded or failed.

is_all_ssl

Returns true if the portal requires HTTPS.

is_all_ssl(self)

is_logged_in

Returns true if the user is logged into the portal.

is_logged_in(self)

is_org

Returns true if the portal is an organization.

is_org(self)

leave_group

Removes the logged in user from the specified group. The user must be logged in to use this method.

leave_group(self, group_id)

Arguments

Parameter	Description
group_id	Required string, specifying group ID

Return value

A Boolean indicating if the operation succeeded or failed.

logged_in_user

Returns information about the logged in user.

logged_in_user(self)

Return value

A dictionary with the following keys:

Key	Value
username	String
storageUsage	Integer
description	String
tags	Comma-separated string
created	Integer, when account created, milliseconds since 1 Jan 1970
modified	Integer, since account was last modified, milliseconds since 1 Jan 1970
fullName	String
email	String
idpUsername	String, name of the user in the enterprise system

login

Logs into the portal using a user name and password. You can log into a portal when you construct a portal object or you can login later. This function is for logging in later.

login(self, username, password, expiration=60)

Arguments

Parameter	Description
username	Required string
password	Required string
expiration	Optional integer, how long the token generated lasts

Return value

A string including the token.

logout

Logs out of the portal. The portal forgets any existing tokens it was using, and all subsequent portal calls will be anonymous until another login call occurs.

logout(self)

Return value

No return value.

reassign_group

Reassigns a group to another owner.

reassign_group(self, group_id, target_owner)

Arguments

Parameter	Description
group_id	Required string, unique identifier for the group
target_owner	Required string, user name of new group owner

Return value

A Boolean indicating if the operation succeeded or failed.

remove_group_users

Removes users from a group.

remove_group_users(self, user_names, group_id)

Arguments

Parameter	Description
user_names	Required string, comma-separated list of users
group_id	Required string, unique identifier for the group

Return value

A dictionary with a key notRemoved, indicating the list of users not removed.

reset_user

Resets a user's password, security question, and security answer. This function does not apply to portals configured with accounts that come from an enterprise identity store such as ActiveDirectory or LDAP. It only applies to built-in portal users. If a new security question is specified, a new security answer is provided.

reset_user(self, username, password, new_password=None, new_security_question=None, new_security_answer=None)

Arguments

Parameter	Description
username	Required string, account being reset
password	Required string, current password
new_password	Optional string, new password if resetting password
new_security_question	Optional integer, new security question if desired
new_security_answer	Optional string, new security question answer if desired

Return value

A Boolean indicating if the operation succeeded or failed.

search

search(self, q, bbox=None, sort_field='title', sort_order='asc', max_results=1000, add_org=True)

search_groups

Searches for portal groups. Consider the following when using this method:

• The query syntax has many features that aren't described here. To review all features, see Search reference in the ArcGIS REST API.
• When searching groups, you'll commonly search within your organization. As a convenience, the method automatically appends your organization ID to the query by default. If you don't want the API to append to your query, set add_org to false.

search_groups(self, q, sort_field='title', sort_order='asc', max_groups=1000, add_org=True)

Arguments

Parameter	Description
q	Required string, query string
sort_field	Optional string, valid values can be title, owner, or created
sort_order	Optional string, valid values are asc or desc
max_groups	Optional int, maximum number of groups returned
add_org	Optional Boolean, controls whether to search within your org

Return value

A list of dictionaries. Each dictionary has the following keys:

Key	Value
access	String, values are private, org, or public
created	Integer, when account created, milliseconds since 1 Jan 1970
description	String
id	String, unique ID for the group
isInvitationOnly	Boolean
isViewOnly	Boolean
modified	Integer, since account was last modified, milliseconds since 1 Jan 1970
owner	String, user name of owner
phone	String
snippet	String, short summary of group
sortField	String, how shared items sort
sortOrder	String, ascending or descending
tags	List of strings, user supplied tags for searching
thumbnail	String, name of file. Append to http://<community url>/groups/<group id>/info/
title	String, name of group as shown to users

search_users

Searches for portal users. Consider the following when using this method:

• The query syntax has many features that aren't described here. To review all features, see Search reference in the ArcGIS REST API.
• When searching users, you commonly search within your organization. As a convenience, the method automatically appends your organization ID to the query by default. If you don't want the API to append to your query, set add_org to false.

search_users(self, q, sort_field='username', sort_order='asc', max_users=1000, add_org=True)

Arguments

Parameter	Description
q	Required string, query string
sort_field	Optional string, valid values can be title, owner, or created
sort_order	Optional string, valid values are asc or desc
max_users	Optional int, maximum number of users returned
add_org	Optional Boolean, controls whether to search within your org

Return value

A list of dictionaries. Each dictionary has the following keys:

Key	Value
created	Integer, when account created, milliseconds since 1 Jan 1970
culture	String, two-letter language code
description	String
fullName	String, name of the user
modified	Integer, since account was last modified, milliseconds since 1 Jan 1970
region	String, may be none
tags	List of strings, user supplied tags for searching
thumbnail	String, name of file. Append to http://<community url>/groups/<group id>/info/.
username	String, name of the user

signup

Signs up users to Portal for ArcGIS. This method only applies to Portal for ArcGIS and can be called anonymously. However, self-signup can also be disabled in the portal. It also only creates built-in accounts; it does not work with enterprise accounts coming from an enterprise identity store.

There is another method called createUser that can always be used against Portal for ArcGIS 10.2.1 or later. The method requires administrator access and can be used to create built-in users or add enterprise accounts to the portal.

signup(self, username, password, fullname, email)

Arguments

Parameter	Description
username	Required string, must be unique in the portal, greater than 4 characters
password	Required string, must be greater than or equal to 8 characters
fullname	Required string, name of the user
email	Required string, must be a valid email address

Return value

A Boolean indicating if the operation succeeded or failed.

update_group

Updates a group. You only need to provide values for the arguments you want to update.

update_group(self, group_id, title=None, tags=None, description=None, snippet=None, access=None, is_invitation_only=None, sort_field=None, sort_order=None, is_view_only=None, thumbnail=None)

Arguments

Parameter	Description
group_id	Required string, the group ID to modify
title	Required string, name of the group to modify
tags	Required string, comma-delimited list of tags
description	Optional string, describes group in detail
snippet	Optional string, less than 250 characters summarizes group
access	Optional string, can be private, public, or org
thumbnail	Optional string, URL to group image
isInvitationOnly	Optional Boolean, defines whether users can join by request
sort_field	Optional string, specifies how shared items with the group sort
sort_order	Optional string, asc or desc for ascending or descending
is_view_only	Optional Boolean, defines whether the group is searchable

Return value

A Boolean indicating if the operation succeeded or failed.

update_user

Updates the properties of a user. Only provide values for the arguments you want to update.

update_user(self, username, access=None, preferred_view=None, description=None, tags=None, thumbnail=None, fullname=None, email=None, culture=None, region=None)

Arguments

Key	Value
username	Required string, name of the user update
access	Optional string, values: private, org, public
preferred_view	Optional string, values: Web, GIS, null
description	Optional string, a description of the user
tags	Optional string, comma-separated tags for searching
thumbnail	Optional string, path or URL to a file. Can be PNG, GIF, or JPEG. Maximum size is 1 MB.
fullName	Optional string, name of the user, only for built-in users
email	Optional string, email address, only for built-in users
culture	Optional string, two-letter language code, for example fr.
region	Optional string, two-letter country code, for example FR

Return value

A Boolean indicating if the operation succeeded or failed.

update_user_role

Updates a user's role.

update_user_role(self, username, role)

Arguments

Key	Value
username	Required string, the name of the user whose role changes
role	Required string, either user, publisher, admin, <custom_role_ID> (where <custom_role_ID> is the ID of the custom role, for example 1eo7LSAhbNiG1q9t, which can be found under roles in the ArcGIS Portal Directory sharing location. The URL is in the format https://webadaptorhost.domain.com/<webadaptorname>/sharing/portals/0123456789ABCDEF/roles). Legacy: In Portal for ArcGIS 10.3 and earlier versions, the accepted values for non-custom roles were org_user, org_publisher, and org_admin. At 10.3.1, these values have been deprecated and replaced with the values listed above. You can continue to use the legacy values at 10.3.1, but note that the values may not be accepted in a future release.

Return value

A Boolean indicating if the operation succeeded or failed.