Skip To Content

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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:

ParameterDescription

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

ParameterDescription

group_id

Required string, indicating the group

Return value

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

max_users

Optional integer, the maximum number of users to return

Return value

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

KeyValue

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

ParameterDescription

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.

KeyValue

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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:

KeyValue

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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:

KeyValue

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

ParameterDescription

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:

KeyValue

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

ParameterDescription

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

ParameterDescription

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

KeyValue

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

KeyValue

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.