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.

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)

project param as string ID

from mstrio.project_objects.report import list_reports

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

project param as project’s name

from mstrio.project_objects.report import list_reports

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

project_id param as string ID

from mstrio.project_objects.report import list_reports

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

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

Folder as parameter to a method call¶

Some methods, usually listing methods, allow you to filter items by folder they reside in. In such cases you can provide folder in one of the below ways:

folder param as instance of Folder class
folder param as string ID
folder param as folder’s name
folder param as folder’s path
folder_id param as string ID
folder_name param as folder’s name
folder_path param as folder’s path

Only one of those is required to be passed to filter by or select a proper folder.

In order to pass folder as path, it also can be done in one of 3 ways:

tuple of strings, each representing one level of folder hierarchy
list of strings, each representing one level of folder hierarchy
str with folder levels separated by slashes, e.g. "Level1/Level2/Level3"

Note

When providing the path, the level 1 need to be a Project name, if looking for a project-level folder, or exactly CASTOR_SERVER_CONFIGURATION if looking for a configuration-level folder.

Additionally, all create methods where destination folder is an applicable concept allow to select a destination folder by providing one of the following values:

destination_folder param as instance of Folder class
destination_folder param as string ID
destination_folder param as folder’s name
destination_folder param as folder’s path
destination_folder_path param as folder’s path

In this case, path can also be provided in one of the 3 ways described above (tuple, list, str).

Note

Using name to identify folder may take some significant time as under the hood it lists all of the available folders to compare names with and takes the first exact match it finds going level by level of folders. Please avoid using only name unless necessary.

Below are some live examples of how to use those parameters based on listing metrics and creating fact. Please see documentation of Connection class method or connect.py code snippet to see how to obtain conn variable.

folder param as instance of Folder class

from mstrio.project_objects import Folder
from mstrio.modeling.metric.metric import list_metrics

folder = Folder(connection=conn, id="1234QWER6789POIU")
metrics = list_metrics(connection=conn, folder=folder)

folder param as string ID or folder_id param as string ID

from mstrio.modeling.metric.metric import list_metrics

metrics = list_metrics(connection=conn, folder="1234QWER6789POIU")
# or
metrics = list_metrics(connection=conn, folder_id="1234QWER6789POIU")

folder param as folder’s name or folder_name param as folder’s name

from mstrio.modeling.metric.metric import list_metrics

metrics = list_metrics(connection=conn, folder="My Metrics")
# or
metrics = list_metrics(connection=conn, folder_name="My Metrics")

folder param as folder’s path or folder_path param as folder’s path

from mstrio.modeling.metric.metric import list_metrics

# as tuple
metrics = list_metrics(connection=conn, folder=("MicroStrategy Tutorial", "My Metrics"))
metrics = list_metrics(connection=conn, folder_path=("MicroStrategy Tutorial", "My Metrics"))

# as list
metrics = list_metrics(connection=conn, folder=["MicroStrategy Tutorial", "My Metrics"])
metrics = list_metrics(connection=conn, folder_path=["MicroStrategy Tutorial", "My Metrics"])

# as str
metrics = list_metrics(connection=conn, folder="MicroStrategy Tutorial/My Metrics")
metrics = list_metrics(connection=conn, folder_path="MicroStrategy Tutorial/My Metrics")

destination_folder param as instance of Folder class

from mstrio.project_objects import Folder
from mstrio.modeling.schema.fact.fact import Fact

folder = Folder(connection=conn, id="1234QWER6789POIU")
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder=folder,
)

destination_folder param as string ID

from mstrio.modeling.schema.fact.fact import Fact

fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder="1234QWER6789POIU",
)

destination_folder param as folder’s name

from mstrio.modeling.schema.fact.fact import Fact

fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder="My Facts",
)

destination_folder param as folder’s path or destination_folder_path param as folder’s path

from mstrio.modeling.schema.fact.fact import Fact

# as tuple
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder=("MicroStrategy Tutorial", "My Facts"),
)
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder_path=("MicroStrategy Tutorial", "My Facts"),
)

# as list
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder=["MicroStrategy Tutorial", "My Facts"],
)
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder_path=["MicroStrategy Tutorial", "My Facts"],
)

# as str
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder="MicroStrategy Tutorial/My Facts",
)
fact = Fact.create(
    connection=conn,
    name="My Fact",
    expressions=[...],
    destination_folder_path="MicroStrategy Tutorial/My Facts",
)

**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`

Usage Remarks¶

General¶

Calling mstrio-py Methods¶

Project as parameter to a method call¶

Folder as parameter to a method call¶

**filters parameters in listing methods¶

Providing type or subtype¶

mstrio-py

Navigation

Related Topics