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')