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:

PortalPy methods

The available Portal methods are described below.

_init_

The Portal constructor. This requires the portal URL and optionally, a username 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 group specified. You can only use this method if the user for the Portal object is either 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, which contains the users that were 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 are sorted

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 group to be deleted.

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 can not delete a user in the portal if that user owns groups or items. If you choose to cascade, then those items and groups will be reassigned to the user identified in the reassign_to option. If you choose not to cascade, the deletion will either succeed or fail depending on whether the user's items and groups have previously been transferred.

When cascading, this method will delete up to 10,000 items. If the user has more than 10,000 items, the method will fail.

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 re-login. 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 username 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 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_org_users

Returns all users within the portal organization.

get_org_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 (org_user, org_publisher, org_admin)

fullName

string

thumbnail

string

idpUsername

string

Example

Print all usernames in the portal:

resp = portalAdmin.get_org_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 username.

get_user(self, username)

Arguments

Parameter

Description

username

required string, the username whose information you want

Return value

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

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 (org_user, org_publisher, org_admin)

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, then you can 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 who is invited to a group will see a list of invitations in the Groups tab of the portal. The user can either 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, specifying group ID you are inviting users to

role

an optional string, either group_member or group_admin

expiration

an 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

email

string

idpUsername

string, name of the user in the enterprise system

login

Logs into the portal using a username and password. You can log into a portal when you construct a portal object or you can login later. This function is for the situation when you need to log 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 will last

Return value

A string including the token.

logout

Logs out of the portal. The portal will forget 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, username of new group owner

Return value

A boolean indicating if the operation succeded 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 should be 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 succeded 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 are sorted

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'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_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 succeded or failed.

update_group

Updates a group. You only need to provide values for the arguments you wish 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 are sorted

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 succeded or failed.

update_user

Updates the properties of a user. You only need to provide values for the arguments you wish 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 to be updated

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 succeded 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 will change

role

required string, either org_user, org_publisher, or org_admin

Return value

A boolean indicating if the operation succeded or failed.

5/5/2015