PortalPy module
In this topic
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 |
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 |
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 SSL.
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 |
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 |
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 |
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_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. |
Return value
A Boolean indicating if the operation succeeded or failed.