Usage Remarks

General

  • It is recommended NOT to use Anaconda environment. Please see Installation section for details.

  • Currently it is not possible to use mstrio-py package to update cubes created via Web. Unfortunately it is not possible to use any REST API endpoint to check whether cube was created via Web or via REST API to provide some warning. In case of seeing one of the following error messages it is most probable that cube was created via Web and REST API can’t handle its update, so if you want to update this particular cube you have to use Web.

When we tried to map the new dataset, we detected that some columns are missing or the data type changed, etc.

We could not obtain the data because the DB connection changed and the table does not exist anymore.

Calling mstrio-py Methods

Project as parameter to a method call

In majority of methods in mstrio-py, be it class methods or module functions, you can explicitly provide project the call should refer to. It can be done by providing any one of the below to a method call:

  • project param as instance of Project class

  • project param as string ID

  • project param as project’s name

  • project_id param as string ID

  • project_name param as project’s name

In majority of cases, first three points above should be available. It is suggested to check documentation specifically for a method you are interested in as some of those parameters may not exist on some of the methods due to compatiblity issues.

A code snippet for each of those on how would you call them can be found below. Please see documentation of Connection class method or connect.py code snippet to see how to obtain conn variable.

  1. project param as instance of Project class

from mstrio.project import Project
from mstrio.project_objects.report import list_reports

project = Project(connection=conn, name="MicroStrategy Tutorial")
reports = list_reports(conn, project=project)

  1. project param as string ID

from mstrio.project_objects.report import list_reports

reports = list_reports(conn, project="B7CA92F04B9FAE8D941C3E9B7E0CD754")

  1. project param as project’s name

from mstrio.project_objects.report import list_reports

reports = list_reports(conn, project="MicroStrategy Tutorial")

  1. project_id param as string ID

from mstrio.project_objects.report import list_reports

reports = list_reports(conn, project_id="B7CA92F04B9FAE8D941C3E9B7E0CD754")

  1. project_name param as project’s name

from mstrio.project_objects.report import list_reports

reports = list_reports(conn, project_name="MicroStrategy Tutorial")

You can also declare that a Connection conn, mentioned above, can refer to a specific project (more details in Connection docs and code snippets). If a method you want to call does not receive any project declaration but it requires for it to be provided, mstrio-py will automatically take it from conn Connection instance. Therefore, below code snippet is a valid call to list all reports in “MicroStrategy Tutorial” project.

from mstrio.connection import Connection
from mstrio.project_objects.report import list_reports

conn = Connection(
    base_url="https://your-mstr-server/MicroStrategyLibrary/",
    username="your_username",
    password="your_password",
)
conn.select_project(project="MicroStrategy Tutorial")
reports = list_reports(conn)  # will search "MicroStrategy Tutorial" even though not set explicitly

**filters parameters in listing methods

Some listing methods, besides explicit parameters described in docstring of a method at hand, can receive also filters. Example would be a list_reports method inside mstrio.project_objects.report module. When looking at the docstring you’ll see a set of parametrs under Args section:

connection: Strategy One connection object returned by
   `connection.Connection()`
name (string, optional): value the search pattern is set to, which
   will be applied to the names of reports being searched
to_dictionary (bool, optional): If True returns dict, by default (False)
   returns Report objects
... etc. ...

However, it also lists some filters:

**filters: Available filter parameters: ['id', 'type', 'subtype',
   'date_created', 'date_modified', 'version', 'owner', 'ext_type',
   'view_media', 'certified_info']

You provide those filters the same way as any other parameter:

from mstrio.project_objects.report import list_reports
from mstrio.types import ObjectSubTypes

reports = list_reports(connection=conn, subtype=ObjectSubTypes.REPORT_GRID, id="1234QWER6789POIU")

Almost all of them are strings or integers representing a value or string ID, but there are exceptions.

For example, type and subtype support raw integer values or enum values (see section below Providing `type` or `subtype`).

Another example, you can provide owner as:

  • a string ID

  • instance of User class

  • dict with ID as parameter, ex: {‘id’: ‘1234QWER6789POIU’}

  • None explicitly

However, it is suggested to always provide string ID as there may exist some methods where it is an only valid value due to compatibility issues. Please check the documentation of a specific method at hand for details.

Providing type or subtype

Some methods may require to provide or allow to filter by type or subtype. In all cases those values may seem like arbitrary integers which may be hard to know or find. In mstrio-py there are some helper enums allowing you to find those values or provide them by name and not by raw integer.

Those enums are ObjectTypes and ObjectSubTypes imported from mstrio.types module.

Below are some examples of how you can use those.

from mstrio.project_objects.report import list_reports
from mstrio.types import ObjectTypes, ObjectSubTypes

# providing subtype to a listing method
reports = list_reports(connection=conn, subtype=ObjectSubTypes.REPORT_GRID)

# finding raw integer knowing only type name
print(ObjectTypes.CALENDAR.value)  # -> `81`

# finding type name knowing only raw integer
print(ObjectTypes(81))  # -> `ObjectTypes.CALENDAR`