Quick Start¶

Quick Start Guide for mstrio-py, with example workflows.

Welcome to the mstrio-py Quick Start Guide! This guide will help you connect to the Strategy I-Server, manage SuperCubes, and create email subscriptions using the mstrio-py library. We’ll provide examples for both novice and experienced users.

Prerequisites¶

Before you start, please ensure that:

Either Python and mstrio-py are installed on your machine (see the Installation section for details), OR
You are working within the Strategy Workstation environment.

Connecting to the Strategy I-Server¶

Connecting Outside Workstation¶

To connect to the Strategy I-Server outside of the Workstation environment, you can use the following example:

# Import the necessary class from the mstrio library
from mstrio.connection import Connection

# Define your server connection details
BASE_URL = "https://your-microstrategy-server-url/MicroStrategyLibrary/api"
USERNAME = "your-username"
PASSWORD = "your-password"
PROJECT_NAME = "your-project-name"

# Create a connection to the Strategy environment
conn = Connection(
    base_url=BASE_URL,
    username=USERNAME,
    password=PASSWORD,
    project_name=PROJECT_NAME
)

# Check connection status
print("Connection established:", conn.status())

# Disconnect when done (optional)
conn.disconnect()

Replace the placeholders:

your-microstrategy-server-url: The URL to your Strategy server.
your-username: Your Strategy username.
your-password: Your Strategy password.
your-project-name: The name of the project you want to connect to.

Connecting Inside Workstation¶

If you are working within the Workstation environment, you can establish a connection using the workstation data object:

# Import the necessary class from the mstrio library
from mstrio.connection import get_connection

# Workstation data obtained from the Strategy Workstation environment is always available
# as `workstationData` inside Workstation Scripts Editor.
# Get the connection using `get_connection`
conn = get_connection(workstation_data=workstationData, project_name="your-project-name")

# Check connection status
print("Connection from Workstation delegated:", conn.status())

Replace the placeholders accordingly where needed.

Example Flow: Listing All SuperCubes¶

Once connected, you can list all SuperCubes available in your project:

# Import necessary classes
from mstrio.project_objects.datasets.super_cube import list_super_cubes

# List all SuperCubes
super_cubes = list_super_cubes(connection=conn)

print("Available SuperCubes:")
for super_cube in super_cubes:
    print("-", super_cube.name)

# Disconnect when done (optional)
conn.disconnect()

Example Flow: Creating an Email Subscription¶

To create an email subscription, you can use the following example:

# Import necessary classes
from mstrio.distribution_services.subscription.email_subscription import EmailSubscription

# Create an email subscription
email_sub = EmailSubscription.create(
    connection=conn,
    name="My Email Subscription",
    project_name="your-project-name",  # Replace with your project name
    recipients=["some-user-id"],
    email_subject="Sample Email Subject",
    email_message="This is a sample email message sent via subscription.",
    send_now=True,
)

print("Email Subscription Created:", email_sub.id)

# Disconnect when done (optional)
conn.disconnect()

Replace the placeholders where appropriate.

Utility Function: what_can_i_do_with¶

The what_can_i_do_with function is a helpful utility in the mstrio-py library designed to provide users with insights into the capabilities of a given object or callable, such as functions, classes, and methods. This function is particularly useful for exploring the properties and methods available on any object, helping users understand how to effectively utilize the library.

Purpose¶

The purpose of the what_can_i_do_with function is to:

Inform users about the functionalities and attributes of a specific callable or object.
Present a summary of available properties and methods that can be invoked, enhancing the usability of the library by reducing guesswork.

How to Use¶

To use the what_can_i_do_with function, simply pass in the callable or object you wish to inspect. Here are examples to demonstrate its application:

Inspecting a Class

You can use what_can_i_do_with on a class in the mstrio-py library to discover what functionalities it offers:

from mstrio import what_can_i_do_with
from mstrio.project_objects.datasets.super_cube import SuperCube

# Inspect the SuperCube class
what_can_i_do_with(SuperCube)

Inspecting an Instance

You can also pass an instance of a class to see its usable methods and properties:

# Initialize an instance of SuperCube
my_super_cube = SuperCube(connection=conn, name="My SuperCube")

# Use the utility to explore its capabilities
what_can_i_do_with(my_super_cube)

Key Points¶

The function logs detailed information about the class or method, including its name, available parameters, and its docstring.
It categorizes the output, making it clear which attributes are properties, methods, class methods, and static methods.
This utility promotes better practice by helping users to utilize the capabilities of the mstrio-py library effectively.

Getting Help¶

If you encounter any issues or have questions, consult the detailed documentation of mstrio-py or reach out to community forums for help.

That’s it! You’ve successfully connected to the Strategy I-Server, listed SuperCubes, and created an email subscription with mstrio-py. Enjoy exploring more functionality with Strategy and Python!