mstrio > users_and_groups > user_group

class mstrio.users_and_groups.user_group.UserGroup(connection, name=None, id=None)

Bases: Entity, DeleteMixin, TrusteeACLMixin

Object representation of Strategy One User Group object.

Parameters:

  • connection (Connection) –

  • name (str | None) –

  • id (str | None) –

connection

A Strategy One 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

acl_add(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Add Access Control Element (ACE) to the object ACL.

Note

To add rights for the Root Folder and the Freeform Objects, apply the required rights for these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_add(rights=Rights.BROWSE | Rights.EXECUTE,
>>>             trustees=user_obj, denied=True)
acl_alter(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Alter an existing Access Control Element (ACE) of the object ACL.

Note

To alter rights for the Root Folder and the Freeform Objects, change the required rights for these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_alter(rights=Rights.BROWSE | Rights.EXECUTE,
>>>               trustees=user_obj, denied=True)
acl_remove(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Remove Access Control Element (ACE) from the object ACL.

Note

To remove rights from the Root Folder and the Freeform Objects, remove them from these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_remove(rights=Rights.BROWSE | Rights.EXECUTE,
>>>                trustees=user_obj, denied=True)
add_to_user_groups(groups)

Add User Group to passed groups.

Parameters:

groups (str | UserGroup | list[str | UserGroup]) – List of User Group objects or ids

Return type:

None

add_translation(translations)

Adds translations to the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Returns:

A list of translations for the Object.

Return type:

list[’Translation’]

add_users(users)

Add members to the User Group.

Parameters:

users (str | User | list[str | User]) – List of User objects or ids

Return type:

None

alter(name=None, description=None, ldapdn=None, comments=None, owner=None)

Alter User Group name or/and description.

Parameters:

  • name (str | None) – New name of the User Group

  • description (str | None) – New description of the User Group

  • comments (str | None) – Long description of the User Group

  • owner (str | User | None) – owner of the User Group

  • ldapdn (str) –

alter_translation(translations)

Alters translations of the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Return type:

None

apply_security_filter(security_filter)

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, project)

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

Parameters:

  • security_role (SecurityRole | str) – Security Role ID or object

  • project (Project | str) – Project name or object

Return type:

None

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod create(connection, name, description=None, memberships=None, members=None, ldapdn=None)

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

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • name (str) – Name of a newly created User Group

  • description (str | None) – Description of a newly created User Group

  • memberships (list[str] | None) – Specify User Groups which newly created User Group will be member

  • members (list[str] | None) – Specify Users which will be members of newly created User Group

  • ldapdn (str | None) – User group’s LDAP distinguished name

create_shortcut(target_folder_id=None, target_folder_path=None, target_folder=None, project_id=None, project_name=None, project=None, to_dictionary=False)

Create a shortcut to the object.

Parameters:

  • target_folder_id (str, optional) – ID of the target folder. Target folder must be specified, but target_folder_id may be substituted with target_folder_path or target_folder.

  • target_folder_path (str, optional) – Path to the target folder, e.g. ‘/MicroStrategy Tutorial/Public Objects’. May be used instead of target_folder_id.

  • target_folder (Folder, optional) – Target folder object. May be used instead of target_folder_id.

  • project_id (str, optional) – ID of the target project of the new shortcut. The project may be specified by either project_id, project_name or project. If the project is not specified in either way, the project from the connection object is used.

  • project_name (str, optional) – Name of the target project. May be used instead of project_id.

  • project (Project, optional) – Project object specifying the target project. May be used instead of project_id.

  • to_dictionary (bool, optional) – If True, the method will return a dictionary with the shortcut’s properties instead of a Shortcut object. Defaults to False.

Return type:

Shortcut

delete(force=False)

Delete object.

Parameters:

  • force (bool) – If True, then no additional prompt will be shown before deleting object.

  • self (Entity) –

Returns:

True on success. False otherwise.

Return type:

bool

fetch(attr=None)

Fetch the latest object’s state from the I-Server.

Note

This method can overwrite local changes made to the object.

Parameters:

  • attr (Optional[str]) – Attribute name to be fetched. If not specified

  • dictionary. (it will use all getters specified in _API_GETTERS) –

  • None. (Defaults to) –

Raises:

ValueError – If attr cannot be fetched.

Return type:

None

classmethod from_dict(source, connection, to_snake_case=True, with_missing_value=False)
Overrides Dictable.from_dict() to instantiate an object from

a dictionary without calling any additional getters.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (dict[str, Any]) – a dictionary from which an object will be constructed.

  • connection (Connection) – A Strategy One Connection object.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case, default True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

get(name)

Get object’s attribute by its name.

get_settings()

Get the User Group settings from the I-Server.

Return type:

dict

grant_privilege(privilege)

Grant privileges directly to the User Group.

Parameters:

privilege (str | list[str] | Privilege | list[Privilege]) – List of privilege objects, ids or names

Return type:

None

list_acl(to_dataframe=False, to_dictionary=False, **filters)

Get Access Control List (ACL) for this object. Optionally filter ACLs by specifying filters.

Parameters:

  • to_dataframe (bool, optional) – if True, return datasets as pandas DataFrame

  • to_dictionary (bool, optional) – if True, return datasets as dicts

  • **filters – Available filter parameters: [deny, type, rights, trustee_id, trustee_name, trustee_type, trustee_subtype, inheritable]

Return type:

DataFrame | list[dict | mstrio.utils.acl.ACE]

Examples

>>> list_acl(deny=True, trustee_name="John")
list_dependencies(project=None, name=None, pattern=4, domain=2, object_types=None, used_by_recursive=False, root=None, root_path=None, limit=None, offset=None, results_format='LIST', to_dictionary=True, **filters)

List list_dependencies of an object.

Parameters:

  • project (string) – Project object or ID

  • name (string) – Value the search pattern is set to, which will be applied to the names of object types being searched. For example, search for all report objects (type) whose name begins with (pattern) B (name).

  • pattern (integer or enum class object) – Pattern to search for, such as Begin With or Exactly. Possible values are available in ENUM mstrio.object_management.SearchPattern. Default value is CONTAINS (4).

  • domain (integer or enum class object) – Domain where the search will be performed, such as Local or Project. Possible values are available in ENUM mstrio.object_management.SearchDomain. Default value is PROJECT (2).

  • root (string, optional) – Folder ID of the root folder where the search will be performed.

  • root_path (str, optional) –

    Path of the root folder in which the search will be performed. Can be provided as an alternative to root parameter. If both are provided, root is used.

    the path has to be provided in the following format:
    if it’s inside of a project, example:

    /MicroStrategy Tutorial/Public Objects/Metrics

    if it’s a root folder, example:

    /CASTOR_SERVER_CONFIGURATION/Users

  • class (object_types(enum class object or integer or list of enum) – objects or integers): Type(s) of object(s) to be searched, such as Folder, Attribute or User. Possible values available in ENUMs mstrio.types.ObjectTypes and mstrio.types.ObjectSubTypes

  • used_by_recursive (boolean, optional) – Control the Intelligence server to also find objects that are used by the given objects indirectly. Default value is false.

  • results_format (SearchResultsFormat) – either a list or a tree format

  • to_dictionary (bool) – If False returns objects, by default (True) returns dictionaries.

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

  • offset (int) – Starting point within the collection of returned results. Used to control paging behavior. Default is 0.

  • **filters – Available filter parameters: [‘id’, ‘name’, ‘description’ ,’date_created’, ‘date_modified’, ‘acg’]

  • self (Entity) –

  • object_types (TypeOrSubtype | None) –

Returns:

list of objects or list of dictionaries

list_dependents(project=None, name=None, pattern=4, domain=2, object_types=None, uses_recursive=False, root=None, root_path=None, limit=None, offset=None, results_format='LIST', to_dictionary=True, **filters)

List dependents of an object.

Parameters:

  • project (string) – Project object or ID

  • name (string) – Value the search pattern is set to, which will be applied to the names of object types being searched. For example, search for all report objects (type) whose name begins with (pattern) B (name).

  • pattern (integer or enum class object) – Pattern to search for, such as Begin With or Exactly. Possible values are available in ENUM mstrio.object_management.SearchPattern. Default value is CONTAINS (4).

  • domain (integer or enum class object) – Domain where the search will be performed, such as Local or Project. Possible values are available in ENUM mstrio.object_management.SearchDomain. Default value is PROJECT (2).

  • root (string, optional) – Folder ID of the root folder where the search will be performed.

  • root_path (str, optional) –

    Path of the root folder in which the search will be performed. Can be provided as an alternative to root parameter. If both are provided, root is used.

    the path has to be provided in the following format:
    if it’s inside of a project, example:

    /MicroStrategy Tutorial/Public Objects/Metrics

    if it’s a root folder, example:

    /CASTOR_SERVER_CONFIGURATION/Users

  • class (object_types(enum class object or integer or list of enum) – objects or integers): Type(s) of object(s) to be searched, such as Folder, Attribute or User. Possible values available in ENUMs mstrio.types.ObjectTypes and mstrio.types.ObjectSubTypes

  • uses_recursive (boolean) – Control the Intelligence server to also find objects that use the given objects indirectly. Default value is false.

  • results_format (SearchResultsFormat) – either a list or a tree format

  • to_dictionary (bool) – If False returns objects, by default (True) returns dictionaries.

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

  • offset (int) – Starting point within the collection of returned results. Used to control paging behavior. Default is 0.

  • **filters – Available filter parameters: [‘id’, ‘name’, ‘description’ ,’date_created’, ‘date_modified’, ‘acg’]

  • self (Entity) –

  • object_types (TypeOrSubtype | None) –

Returns:

list of objects or list of dictionaries

list_members(**filters)

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’

Return type:

list[’User | UserGroup’]

list_privileges(mode=PrivilegeMode.ALL, to_dataframe=False)

List privileges for user group.

Parameters:

  • mode (PrivilegeMode | str) – Specifies which privileges to list. See: privilege.PrivilegeMode enum.

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

Return type:

list

list_properties(excluded_properties=None)

Fetches all attributes from the server and converts all properties of the object to a dictionary.

Parameters:

excluded_properties (list[str], optional) – A list of object properties that should be excluded from the dict. Defaults to None.

Returns:

A dictionary which keys are object’s attribute names, and

which values are object’s attribute values.

Return type:

dict

list_security_filters(projects=None, to_dictionary=False)

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 (bool) – 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.

Return type:

dict

list_translations(languages=None, to_dictionary=False)

Lists translations for the Object.

Parameters:

  • languages (list, optional) –

    list of languages to list the translations for, only translations from these languages will be listed. Languages in the list should be one of the following:

    • lcid attribute of the language

    • ID of the language

    • Language class object

  • to_dictionary (bool, optional) – If True returns dict, by default (False) returns Translation objects

  • self (Entity) –

Returns:

A list of dictionaries representing translations for the Object or a list of Translation Objects.

Return type:

list[’Translation’] | list[dict]

print()

Pretty Print all properties of the object.

Return type:

None

remove_all_users()

Remove all members from user group.

Return type:

None

remove_from_user_groups(groups)

Remove User Group from passed groups

Parameters:

groups (str | UserGroup | list[str | UserGroup]) – List of User Group objects or ids

Return type:

None

remove_translation(translations)

Removes translations from the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Return type:

None

remove_users(users)

Remove members from User Group.

Parameters:

users (str | User | list[str | User]) – List of User objects or ids

Return type:

None

revoke_all_privileges(force=False)

Revoke directly granted group privileges.

Parameters:

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

Return type:

None

revoke_privilege(privilege)

Revoke directly granted User Group privileges.

Parameters:

privilege (str | list[str] | Privilege | list[Privilege]) – List of privilege objects, ids or names

Return type:

None

revoke_security_filter(security_filter)

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, project)

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

Parameters:

  • security_role (SecurityRole | str) – Security Role ID or object

  • project (Project | str) – Project name or object

Return type:

None

set_custom_permissions(to_objects, object_type, project=None, execute=None, use=None, control=None, delete=None, write=None, read=None, browse=None)

Set custom permissions to perform actions on given object(s).

Function is used to set rights of the trustee to perform given actions on the provided objects. Within one execution of the function rights will be set in the same manner for each of the provided objects. None of the rights is necessary, but if provided then only possible values are ‘grant’ (to grant right), ‘deny’ (to deny right), ‘default’ (to reset right) or None which is default value and means that nothing will be changed for this right. All objects to which the rights will be given have to be of the same type which is also provided.

Parameters:

  • to_objects (str | list[str]) – (str, list(str)): List of object ids on access list to which the permissions will be set

  • object_type (int, ObjectTypes) – Type of objects on access list

  • project (str, Project) – Object or id of Project in which the object is located. If not passed, Project (project_id) selected in Connection object is used.

  • execute (str) – value for right “Execute”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • use (str) – value for right “Use”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • control (str) – value for right “Control”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • delete (str) – value for right “Delete”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • write (str) – value for right “Write”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • read (str) – value for right “Read”. Available are ‘grant’, ‘deny’, ‘default’ or None

  • browse (str) – value for right “Browse. Available are ‘grant’, ‘deny’, ‘default’ or None

  • self (UserOrGroup) –

Returns:

None

Return type:

None

set_permission(permission, to_objects, object_type, project=None, propagate_to_children=None, propagation_behavior=None)

Set permission to perform actions on given object(s).

Function is used to set permission of the trustee to perform given actions on the provided objects. Within one execution of the function permission will be set in the same manner for each of the provided objects. The only available values of permission are: ‘View’, ‘Modify’, ‘Full Control’, ‘Denied All’, ‘Default All’. Permission is the predefined set of rights. All objects to which the rights will be given have to be of the same type which is also provided.

Parameters:

  • permission (Permissions | str) – The Permission which defines set of rights. See: Permissions enum

  • to_objects (str | list[str]) – List of object ids on access list for which the permissions will be set

  • object_type (ObjectTypes | int) – Type of objects on access list. See: ObjectTypes enum

  • project (Project | str | None) – Object or id of Project where the object is located. If not passed, Project (project_id) selected in Connection object is used

  • propagate_to_children (bool | None) – Flag used in the request to determine if those rights will be propagated to children of the trustee

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (UserOrGroup) –

Returns:

None

Return type:

None

classmethod to_csv(objects, name, path=None, properties=None)

Exports MSTR objects to a csv file.

Optionally, saves only the object properties specified in the properties parameter.

Parameters:

  • objects (T | list[T]) – List of objects of the same type that

  • exported. (will be) –

  • name (str) – The name of the csv file ending with ‘.csv’

  • path (Optional[str], optional) – A path to the directory where the file will be saved. Defaults to None.

  • properties (Optional[list[str]], optional) – A list of object’s attribute names that should be included in the exported file. Defaults to None.

Raises:

  • TypeError – If objects is not of type T or list of type T

  • objects. –

Return type:

None

to_dataframe()

Converts all properties of the object to a dataframe.

Returns:

A DataFrame object containing object properties.

Return type:

DataFrame

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

update_properties()

Save compatible local changes of the object attributes to the I-Server. Changes are retrieved from the self._altered_properties dictionary. After the process of update has finished, self._altered_properties is cleared. For this method to work properly, you must override the _alter_properties() method in a subclass.

Raises:

requests.HTTPError – If I-Server raises exception

Return type:

None

mstrio.users_and_groups.user_group.list_user_groups(connection, name_begins=None, to_dictionary=False, limit=None, **filters)

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 (Connection) – Strategy One connection object returned by connection.Connection()

  • name_begins (str | None) – Beginning of a User Groups name which we want to list

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

  • limit (int | None) – 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’]

Return type:

list[UserGroup]

Examples

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