mstrio.users_and_groups package

Submodules

mstrio.users_and_groups.user module

class mstrio.users_and_groups.user.User(connection: mstrio.connection.Connection, username: Optional[str] = None, name: Optional[str] = None, id: Optional[str] = None)

Bases: mstrio.utils.entity.Entity, mstrio.utils.entity.DeleteMixin, mstrio.utils.acl.TrusteeACLMixin

Object representation of MicroStrategy User object.

connection

A MicroStrategy connection object

id

User ID

name

User name

username

User username

full_name

full name of the User

initials

User initials, derived from user’s last name or username

abbreviation

User login name

description

User description

memberships

IDs and names of direct parent groups for user

security_roles

security roles that the user is a member of

addresses

addresses for the user

privileges

user privileges per project

trust_id

Unique user ID provided by trusted authentication provider

enabled

Specifies if user is allowed to log in

owner

owner ID and name

ancestors

List of ancestor folders

password_modifiable

If user password can be modified

require_new_password

If user is required to change new password

standard_auth

If standard authentication is allowed for user

date_created

Creation time, DateTime object

date_modified

Last modification time, DateTime object

type

Object type

subtype

Object subtype

ext_type

Object extended type

version

Version ID

acg

Access rights (See EnumDSSXMLAccessRightFlags for possible values)

acl

Object access control list

add_address(name: Optional[str] = None, address: Optional[str] = None, default: bool = True) → None

Add new address to the user object.

Parameters

  • name – User-specified name for the address

  • address – The actual value of the address i.e. email address associated with this address name/id

  • default – Specifies whether this address is the default address (change isDefault parameter).

add_to_user_groups(user_groups: Union[str, UserGroup, List[Union[str, UserGroup]]]) → None

Adds this User to user groups specified in user_groups.

Parameters

user_groups – list of UserGroup objects or IDs

alter(username: Optional[str] = None, full_name: Optional[str] = None, description: Optional[str] = None, password: Optional[str] = None, enabled: Optional[bool] = None, password_modifiable: Optional[bool] = None, password_expiration_date: Optional[str] = None, standard_auth: Optional[bool] = None, require_new_password: Optional[bool] = None, ldapdn: Optional[str] = None, trust_id: Optional[str] = None, database_auth_login: Optional[str] = None) → None

Alter user properties.

Parameters

  • username – username of user

  • full_name – user full name

  • description – user description

  • password – user password

  • enabled – specifies if user is allowed to log in

  • password_modifiable – Specifies if user password can be modified

  • password_expiration_date – Expiration date of user password, “yyyy-MM-dd HH:mm:ss” in UTC

  • standard_auth – Specifies whether standard authentication is allowed for user.

  • require_new_password – Specifies if user is required to provide a new password.

  • ldapdn – User’s LDAP distinguished name

  • trust_id – Unique user ID provided by trusted authentication provider

  • database_auth_login – Database Authentication Login

apply_security_filter(security_filter: Union[SecurityFilter, str]) → bool

Apply a security filter to the user.

Parameters

security_filter (string or object) – identifier of security filter or SecurityFilter object which will be applied to the user.

Returns

True when applying was successful. False otherwise.

assign_security_role(security_role: Union[mstrio.access_and_security.security_role.SecurityRole, str], project: Union[Project, str] = None) → None

Assigns a Security Role to the user for given project.

Parameters

  • security_role – Security Role ID or object

  • project – Project name or object

classmethod create(connection: mstrio.connection.Connection, username: str, full_name: str, password: Optional[str] = None, description: Optional[str] = None, enabled: bool = True, password_modifiable: bool = True, password_expiration_date: Optional[Union[str, datetime.datetime]] = None, require_new_password: bool = True, standard_auth: bool = True, ldapdn: Optional[str] = None, trust_id: Optional[str] = None, database_auth_login: Optional[str] = None, memberships: Optional[list] = None) → mstrio.users_and_groups.user.User

Create a new user on the I-Server. Returns User object.

Parameters

  • connection – MicroStrategy connection object returned by connection.Connection()

  • username – username of user

  • full_name – user full name

  • password – user password

  • description – user description

  • enabled – specifies if user is allowed to log in

  • password_modifiable – Specifies if user password can be modified

  • password_expiration_date – Expiration date of user password either as a datetime or string: “yyyy-MM-dd HH:mm:ss” in UTC

  • require_new_password – Specifies if user is required to provide a new password.

  • standard_auth – Specifies whether standard authentication is allowed for user.

  • ldapdn – User’s LDAP distinguished name

  • trust_id – Unique user ID provided by trusted authentication provider

  • database_auth_login – Database Authentication Login

  • memberships – specify User Group IDs which User will be member off.

delete(force: bool = False) → bool

Deletes the user. Deleting the user will not remove the user’s shared files.

Args:

force: If True, no additional prompt will be shown before deleting

User.

Returns

True for success. False otherwise.

disconnect(nodes: Optional[Union[List[str], str]] = None) → None

Disconnect all active user connection sessions for the specified node.

Parameters

nodes – list of node names

grant_privilege(privilege: Union[str, List[str], Privilege, List[Privilege]]) → None

Grant privileges directly to the user.

Parameters

privilege – list of privilege objects, ids or names

list_privileges(mode: Union[mstrio.access_and_security.privilege_mode.PrivilegeMode, str] = PrivilegeMode.ALL, to_dataframe: bool = False) → list

List privileges for user.

Parameters

  • mode – Filter by source of privileges. One of: ALL, INHERITED, or GRANTED. See: privilege.PrivilegeMode enum.

  • to_dataframe – If True, return a DataFrame object containing privileges.

list_security_filters(projects: Optional[Union[str, List[str]]] = None, to_dictionary: bool = False) → dict

Get the list of security filters for user. They can be filtered by the projects’ ids.

Parameters

  • projects (str or list of str, optional) – collection of projects’ ids which is used for filtering data

  • to_dictionary – If True returns security filters as dicts, by default (False) returns them as objects.

Returns

Dictionary with project names as keys and list with security filters as values. In case of no security filter for the given user in the particular project, then this project is not placed in the dictionary.

remove_address(name: Optional[str] = None, address: Optional[str] = None, id: Optional[str] = None) → None

Remove existing address from the user object. Specify either address ID or name. Warning, address names are not unique and can potentially remove multiple addresses.

Parameters

  • name – User-specified name for the address

  • address – The actual value of the address i.e. email address associated with this address name/id

  • id – ID of the address.

remove_from_all_user_groups() → None

Removes this User from all user groups.

remove_from_user_groups(user_groups: Union[str, UserGroup, List[Union[str, UserGroup]]]) → None

Removes this User from user groups specified in user_groups.

Parameters

user_groups – list of UserGroup objects or IDs

revoke_all_privileges(force: bool = False) → None

Revoke directly granted user privileges.

Parameters

force – If True, no additional prompt will be shown before revoking all privileges from User.

revoke_privilege(privilege: Union[str, List[str], Privilege, List[Privilege]]) → None

Revoke directly granted user privileges.

Parameters

privilege – list of privilege objects, ids or names

revoke_security_filter(security_filter: Union[SecurityFilter, str]) → bool

Revoke a security filter from the user.

Parameters

security_filter (string or object) – identifier of security filter or SecurityFilter object which will be revoked from the user.

Returns

True when revoking was successful. False otherwise.

revoke_security_role(security_role: Union[mstrio.access_and_security.security_role.SecurityRole, str], project: Union[Project, str] = None) → None

Removes a Security Role from the user for given project.

Parameters

  • security_role – Security Role ID or object

  • project – Project name or object

update_address(id: str, name: Optional[str] = None, address: Optional[str] = None, default: Optional[bool] = None) → None

Update existing address. The address ID has to be specified as the name is not unique.

Parameters

  • id – ID of the address

  • name – New user-specified name for the address

  • address – New address value

  • default – Whether the address should be (un)marked as default

mstrio.users_and_groups.user.create_users_from_csv(connection: mstrio.connection.Connection, csv_file: str) → List[mstrio.users_and_groups.user.User]

Create new user objects from csv file. Possible header values for the users are the same as in the User.create() method.

Parameters

  • connection – MicroStrategy connection object returned by connection.Connection()

  • csv_file – path to file containing at minimum ‘username’ and ‘full_name’ headers’.

mstrio.users_and_groups.user.list_users(connection: mstrio.connection.Connection, name_begins: Optional[str] = None, abbreviation_begins: Optional[str] = None, to_dictionary: bool = False, limit: Optional[int] = None, **filters) → Union[List[mstrio.users_and_groups.user.User], List[dict]]

Get list of user objects or user dicts. Optionally filter the users by specifying ‘name_begins’, ‘abbreviation_begins’ or other filters.

Wildcards available for name_begins and abbreviation_begins:

? - any character * - 0 or more of any characters e.g. name_begins = ?onny will return Sonny and Tonny

Parameters

  • connection – MicroStrategy connection object returned by connection.Connection()

  • name_begins – characters that the user name must begin with.

  • abbreviation_begins – characters that the abbreviation must begin with.

  • to_dictionary – If True returns dict, by default (False) returns User objects.

  • limit – limit the number of elements returned. If None (default), all objects are returned.

  • **filters – Available filter parameters: [‘id’, ‘name’, ‘abbreviation’, ‘description’, ‘type’, ‘subtype’, ‘date_created’, ‘date_modified’, ‘version’, ‘acg’, ‘icon_path’, ‘owner’, ‘initials’]

Examples

>>> list_users(connection, name_begins='user', initials='UR')

mstrio.users_and_groups.user_connections module

class mstrio.users_and_groups.user_connections.UserConnections(connection: mstrio.connection.Connection)

Bases: object

Browse and manage active user connections on the environment. Use the fetch() method to fetch the latest active user connections. Filter the user_connections by using filter_connections() method.

connection

A MicroStrategy connection object

user_connections

All active user connections on the environment

disconnect_all_users(force: bool = False) → Optional[List[dict]]

Disconnect all user connections.

Parameters

force – if True, no additional prompt will be shown before disconnecting all users

Returns

  • list of statuses of disconnecting all connections with their ids

    and messages from the I-Server

  • in case of error it returns None

disconnect_users(connection_ids: Union[str, List[str]] = None, users: Optional[Union[List[User], List[str]]] = None, nodes: Union[str, List[str]] = None, force: bool = False, **filters) → Optional[List[dict]]

Disconnect user connections by passing in users (objects) or connection_ids. Optionally disconnect users by specifying the filters keyword arguments.

Parameters

  • connection_ids – chosen ids that can be retrieved with list_connections()

  • users – List of User objects or usernames

  • nodes – Node (server) names on which users will be disconnected

  • force – if True, no additional prompt will be shown before disconnecting users

  • **filters – Available filter parameters: [‘id’, ‘parent_id’, ‘username’, ‘user_full_name’, ‘project_index’, ‘project_id’, ‘project_name’, ‘open_jobs_count’, ‘project_type’, ‘date_connection_created’, ‘duration’, ‘session_id’, ‘client’, ‘config_level’]

Returns

  • list of statuses of disconnecting chosen connections with theirs ids and messages from the I-Server:

    status code 200 is when all connections were disconnected status code 207 is when some connections were disconnected status code 403 without error code is when no connections were disconnected

  • in case of error of nothing to disconnect it returns None

fetch() → None

Populate the UserConnections object by retrieving all active user connections on the environment.

filter_connections(**filters) → Optional[List[Dict[str, Any]]]

Filter the user connections stored in the UserConnections object by specifying the filters keyword arguments.

Parameters

**filters – Available filter parameters: [‘id’, ‘parent_id’, ‘username’, ‘user_full_name’, ‘project_index’, ‘project_id’, ‘project_name’, ‘open_jobs_count’, ‘project_type’, ‘date_connection_created’, ‘duration’, ‘session_id’, ‘client’, ‘config_level’]

list_connections(nodes: Optional[Union[List[str], str]] = None, limit: Optional[int] = None, **filters) → List[Dict[str, Any]]

Get all active user connections. Optionally filter the connections by specifying the filters keyword arguments.

Parameters

  • nodes – Node (server) names on which users will be disconnected.

  • limit – limit the number of elements returned. If None, all objects are returned.

  • **filters – Available filter parameters: [‘id’, ‘parent_id’, ‘username’, ‘user_full_name’, ‘project_index’, ‘project_id’, ‘project_name’, ‘open_jobs_count’, ‘project_type’, ‘date_connection_created’, ‘duration’, ‘session_id’, ‘client’, ‘config_level’]

mstrio.users_and_groups.user_group module

class mstrio.users_and_groups.user_group.UserGroup(connection: mstrio.connection.Connection, name: Optional[str] = None, id: Optional[str] = None)

Bases: mstrio.utils.entity.Entity, mstrio.utils.entity.DeleteMixin, mstrio.utils.acl.TrusteeACLMixin

Object representation of MicroStrategy User Group object.

connection

A MicroStrategy connection object

memberships

User Groups that the User Group is a member of

members

users that are members of User Group

security_roles

security roles that the User Group is a member of

privileges

user privileges per project

id

User ID

name

User name

type

Object type

subtype

Object subtype

ext_type

Object extended type

abbreviation

Object abbreviation

description

Object description

date_created

Creation time, DateTime object

date_modified

Last modification time, DateTime object

version

Object version ID

owner

Owner name and ID

ancestors

List of ancestor folders

settings

Settings of User Group

acg

Access rights (See EnumDSSXMLAccessRightFlags for possible values)

acl

Object access control list

add_to_user_groups(groups: Union[str, List[str], mstrio.users_and_groups.user_group.UserGroup, List[mstrio.users_and_groups.user_group.UserGroup]]) → None

Add User Group to passed groups.

Parameters

groups – List of User Group objects or ids

add_users(users: Union[str, List[str], User, List[User]]) → None

Add members to the User Group.

Parameters

users – List of User objects or ids

alter(name: Optional[str] = None, description: Optional[str] = None)

Alter User Group name or/and description.

Parameters

  • name – New name of the User Group

  • description – New description of the User Group

apply_security_filter(security_filter: Union[SecurityFilter, str])

Apply a security filter to the user group.

Parameters

security_filter (string or object) – identifier of security filter or SecurityFilter object which will be applied to the user group.

Returns

True when applying was successful. False otherwise.

assign_security_role(security_role: Union[mstrio.access_and_security.security_role.SecurityRole, str], project: Union[Project, str] = None) → None

Assigns a Security Role to the User Group for given project.

Parameters

  • security_role – Security Role ID or object

  • project – Project name or object

classmethod create(connection: mstrio.connection.Connection, name: str, description: Optional[str] = None, memberships: List[str] = [], members: List[str] = [])

Create a new User Group on the I-Server. Returns UserGroup object.

Parameters

  • connection – MicroStrategy connection object returned by connection.Connection()

  • name – Name of a newly created User Group

  • description – Description of a newly created User Group

  • memberships – Specify User Groups which newly created User Group will be member

  • members – Specify Users which will be members of newly created User Group

get_settings() → Dict

Get the User Group settings from the I-Server.

grant_privilege(privilege: Union[str, List[str], Privilege, List[Privilege]]) → None

Grant privileges directly to the User Group.

Parameters

privilege – List of privilege objects, ids or names

list_members(**filters) → List[dict]

List user group members.

Optionally filter the results by passing filter keyword arguments.

Parameters

**filters – Available filter parameters: ‘name’, ‘id’, ‘type’, ‘abbreviation’, subtype’, ‘date_created’, ‘date_modified’, ‘version’, ‘acg’, ‘owner’, source’, ext_type’, ‘username’, full_name’, enabled’

list_privileges(mode: Union[mstrio.access_and_security.privilege_mode.PrivilegeMode, str] = PrivilegeMode.ALL, to_dataframe: bool = False) → list

List privileges for user group.

Parameters

  • mode – Specifies which privileges to list. See: privilege.PrivilegeMode enum.

  • to_dataframe – If True, return a DataFrame object containing privileges

list_security_filters(projects: Optional[Union[str, List[str]]] = None, to_dictionary: bool = False) → dict

Get the list of security filters for user group. They can be filtered by the projects’ ids.

Parameters

  • projects (str or list of str, optional) – collection of projects’ ids which is used for filtering data

  • to_dictionary – If True returns security filters as dicts, by default (False) returns them as objects.

Returns

Dictionary with project names as keys and list with security filters as values. In case of no security filter for the given user group in the particular project, then this project is not placed in the dictionary.

remove_all_users() → None

Remove all members from user group.

remove_from_user_groups(groups: Union[str, List[str], mstrio.users_and_groups.user_group.UserGroup, List[mstrio.users_and_groups.user_group.UserGroup]]) → None

Remove User Group from passed groups

Parameters

groups – List of User Group objects or ids

remove_users(users: Union[str, List[str], User, List[User]]) → None

Remove members from User Group.

Parameters

users – List of User objects or ids

revoke_all_privileges(force: bool = False) → None

Revoke directly granted group privileges.

Parameters

force – If True, no additional prompt will be shown before revoking all privileges from User Group

revoke_privilege(privilege: Union[str, List[str], Privilege, List[Privilege]]) → None

Revoke directly granted User Group privileges.

Parameters

privilege – List of privilege objects, ids or names

revoke_security_filter(security_filter: Union[SecurityFilter, str])

Revoke a security filter from the user group.

Parameters

security_filter (string or object) – identifier of security filter or SecurityFilter object which will be revoked from the user group.

Returns

True when revoking was successful. False otherwise.

revoke_security_role(security_role: Union[mstrio.access_and_security.security_role.SecurityRole, str], project: Union[Project, str] = None) → None

Removes a Security Role from the User Group for given project.

Parameters

  • security_role – Security Role ID or object

  • project – Project name or object

mstrio.users_and_groups.user_group.list_user_groups(connection: mstrio.connection.Connection, name_begins: Optional[str] = None, to_dictionary: bool = False, limit: Optional[int] = None, **filters) → List[mstrio.users_and_groups.user_group.UserGroup]

Get list of User Group objects or User Group dicts. Optionally filter the User Groups by specifying ‘name_begins’ or other filters.

Optionally use to_dictionary or to_dataframe to choose output format. If to_dictionary is True, to_dataframe is omitted.

Wildcards available for name_begins:

? - any character * - 0 or more of any characters e.g. name_begins = ?onny will return Sonny and Tonny

Parameters

  • connection – MicroStrategy connection object returned by connection.Connection()

  • name_begins – Beginning of a User Groups name which we want to list

  • to_dictionary – If True returns dict, by default (False) returns User Group objects

  • limit – limit the number of elements returned. If None (default), all objects are returned.

  • **filters – Available filter parameters: [‘name’, ‘id’, ‘type’, ‘abbreviation’, ‘description’, ‘subtype’, ‘date_created’, ‘date_modified’, ‘version’, ‘acg’, ‘owner’, ‘ext_type’]

Examples

>>> list_user_groups(connection, name_begins='Group',
>>>                  description='New group')

Module contents