py-mstr Documentation - Read the Docs py-mstr supports Elements Prompt Answers (the most common type) and Value Prompt Answers. Element Prompt Answers: This is the most common type

py-mstr DocumentationRelease 0.1

InfoScout and Jocelyn Neff

Jul 12, 2017

Contents

1 py_mstr 1

2 Tutorial 5

3 Executing a Report 73.1 Report Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Installation 9

5 Contribute 11

6 License 13

Python Module Index 15

i

ii

CHAPTER 1

py_mstr

class py_mstr.Attribute(guid, name)Bases: object

Object encapsulating an attribute on MicroStrategy

An attribute can take many values, all of which are elements of that attribute. An attribute is defined by its nameand its guid. Its __metaclass__ is Singleton.

Parameters

• guid (str) – guid for this attribute

• name (str) – the name of this attribute

guidstr – attribute guid

namestr – attribute name

class py_mstr.Metric(guid, name)Bases: object

Object encapsulating a metric on MicroStrategy

A metric represents computation on attributes. A metric is defined by its name and its guid. Its __metaclass__is Singleton.

Parameters

• guid (str) – guid for this metric

• name (str) – the name of this metric

guidstr – guid for this metric

namestr – the name of this metric

1

py-mstr Documentation, Release 0.1

class py_mstr.MstrClient(base_url, username, password, project_source, project_name)Bases: object

Class encapsulating base logic for the MicroStrategy Task Proc API

__del__()Logs the user out of the session.

get_attribute(attribute_id)Returns the attribute object for the given attribute id.

Parameters attribute_id (str) – the attribute guid

Returns Attribute object for this guid

Return type Attribute

Raises MstrClientException – if no attribute id is supplied

get_folder_contents(folder_id=None)Returns a dictionary with folder name, GUID, and description.

Parameters folder_id (str) – guid of folder to list contents. If not supplied, returns con-tents of root folder

Returns

list of dictionaries with keys id, name, description, and type as keys

Return type list

get_report(report_id)Returns a report object.

Parameters report_id (str) – report guid for the report

list_elements(attribute_id)Returns the elements associated with the given attribute id.

Note that if the call fails (i.e. MicroStrategy returns an out of memory stack trace) the returned list is empty

Parameters attribute_id (str) – the attribute guid

Returns a list of strings containing the names for attribute values

Return type list

exception py_mstr.MstrClientException(msg)Bases: exceptions.Exception

Class used to raise errors in the MstrClient class

exception py_mstr.MstrReportException(msg)Bases: exceptions.Exception

Class used to raise errors in the MstrReport class

class py_mstr.Prompt(guid, prompt_str, required, attribute=None)Bases: object

Object encapsulating a prompt on MicroStrategy

A prompt object has a guid and string and is or is not required. A prompt also potentially has an Attributeassociated with it if it is an element prompt.

Parameters

• guid (str) – guid for the prompt

2 Chapter 1. py_mstr


• prompt_str (str) – string for the prompt that is displayed when the user uses the webinterface

• required (bool) – indicates whether or not the prompt is required

• attribute (Attribute) – Attribute object associated with the prompt if it is an elementprompt

guidstr – guid for the prompt

prompt_strstr – string for the prompt that is displayed when the user uses the web interface

requiredbool – indicates whether or not the prompt is required

attributeAttribute – Attribute object associated with the prompt if it is an element prompt

class py_mstr.Report(mstr_client, report_id)Bases: object

Encapsulates a report in MicroStrategy

The most common use case will be to execute a report.

Parameters

• mstr_client (MstrClient) – client to be used to make requests

• report_id (str) – report guid

execute(start_row=0, start_col=0, max_rows=100000, max_cols=255,value_prompt_answers=None, element_prompt_answers=None)

Execute a report.

Executes a report with the specified parameters. Default values are chosen so that most likely all rowsand columns will be retrieved in one call. However, a client could use pagination by cycling through callsof execute and changing the min and max rows. Pagination is usefull when there is a risk of the amountof data causing the MicroStrategy API to run out of memory. The report supports any combination ofoptional/required value prompt answers and element prompt answers.

Parameters

• start_row (int) – first row number to be returned

• start_col (int) – first column number to be returned

• max_rows (int) – maximum number of rows to return

• max_cols (int) – maximum number of columns to return

• value_prompt_answers (list) – list of (Prompts, strings) in order. If a value is tobe left blank, the second argument in the tuple should be the empty string

• element_prompt_answers – (dict) element prompt answers represented as a dictio-nary of Prompt objects (with attr field specified) mapping to a list of attribute values topass

Raises MstrReportException – if there was an error executing the report.

get_attributes()Returns the attribute objects for the columns of this report.

If a report has not been executed, there exists an api call to retrieve just the attribute objects in a Report.

3


Returns list of Attribute objects

Return type list

get_headers()Returns the column headers for the report. A report must have been executed before calling this method

Returns a list of Attribute/Metric objects

Return type list

get_metrics()Returns the metric objects for the columns of this report.

A report must have already been executed for this method to run.

Returns list of Attribute objects

Return type list

Raises MstrReportException – if execute has not been called on this report

get_prompts()

Returns the prompts associated with this report. If there are no prompts, this method raises an error.

Returns a list of Prompt objects

Return type list

Raises MstrReportException – if a msgID could not be retrieved likely implying there areno prompts for this report.

get_values()Returns the rows for a prompt that has been executed.

A report must have been executed for this method to run.

Returns list of lists containing tuples of the (Attribute/Metric, value) pair, where the At-tribute/Metric is the object for the column header, and the value is that cell’s value

Return type list

Raises MstrReportException – if execute has not been called on this report

class py_mstr.SingletonBases: type

Singleton parent class to preserve memory.

Objects are considered to be the same, and thus a new object does not need to be instantiated, if an object withthat guid already exists.

__call__(*args, **kwargs)Called when a new Singleton object is created.

Singleton class checks to see if there is already a copy of the object in the class instances, and if so returnsthat object. Otherwise, it creates a new object of that subclass type.

Features:

• Browse folders

• View Attribute and Metric objects

• Execute a Report with or without Prompt objects

4 Chapter 1. py_mstr

CHAPTER 2

Tutorial

Here is a sample use case of the api:

from py_mstr import MstrClient

BASE_URL = 'http://insights.infoscout.co/MicroStrategy/asp/TaskProc.aspx?"'USERNAME = 'johndoe'PASSWORD = 'password'PROJECT_SOURCE = 'ip-0AB4D138'PROJECT_NAME = 'MicroStrategy Tutorial Project'

client = MstrClient(base_url=BASE_URL, username=MSTR_USERNAME,password=MSTR_PASSWORD, project_source=MSTR_PROJECT_SOURCE, project_name=MSTR_

→˓PROJECT_NAME)

View folder contents. Specify a folder guid to view the contents of a specific folder. Otherwise, the contents of thebase folder of the PROJECT_NAME will be returned:

base_folder_contents = client.get_folder_contents()print 'There are %s folders in the base folder' % len(base_folder_contents)

folder_contents = client.get_folder_contents(folder_id='parent_folder_guid')for f in folder_contents:

print 'Folder: name - %s description - %s guid - %s type - %s' % (f['name'], f[→˓'description'], f['id'], f['type'])

Get the corresponding Attribute object from an attribute_id. See Attribute section for details:

attr = client.get_attribute('attribute_guid')print attr

List the values an attribute_id can take. Note that this call is prone to failure by the MicroStrategy Task Api. Ifan attribute id has a very large number of values, a java stack trace is returned. py-mstr currently responds to this caseby returning an empty list:

5


elements = client.list_elements(attr.guid)for e in elements:

print element

Get a Report and execute.:

report = client.get_report('report_guid')report.execute()headers = report.get_headers()for header in headers:

print header

# metrics and attributes are together the headersmetrics = report.get_metrics()attributes = report.get_attributes()

# row is a list of tuples for each columnfor row in report.get_values():

# the tuples for each column represent the header ``Attribute`` or# ``Metric`` and the valuefor attr, val in row:

print val

6 Chapter 2. Tutorial

CHAPTER 3

Executing a Report

Report Prompts

Currently, py-mstr supports Elements Prompt Answers (the most common type) and Value Prompt Answers.

Element Prompt Answers:

This is the most common type of prompt. Typically, the MicroStrategy web interface displays it in ashopping cart style where you select from a list of elements for an Attribute.

Value Prompt Answers:

These prompts are where the user types a value into a text box, or chooses a date from a calendar view.Filters are also answered this way. Note that order matters because the answers are passed in a list, andthe prompts appear in the same order as they do in the web interface.

Refer to http://www.bryanbrandow.com/2011/08/answering-prompts-via-url-api.html for more information about an-swering prompts via the api.

The user must understand what types of prompts make up the report they wish to execute, so that there is a correctmatching of Prompt objects to values. Prompts will be returned in the order that they are listed in the web interface,making it easier to expect what prompts belong with what values:

prompts = report.get_prompts()

for prompt in prompts:if prompt.attribute:

print 'Prompt is an Elements Prompt Answer'else:

print 'Prompt is a Value Prompt Answer'

value_answers = [(prompts[0], 'v1'), (prompts[2], 'v2')]# You can pass multiple answers to one element prompt by including all values# in the list for the promptelement_answers = {prompts[1]: ['v3', 'v4']}

7

http://www.bryanbrandow.com/2011/08/answering-prompts-via-url-api.html


You can pass no value for an optional parameter. The empty string for Value Prompt Answers signfies there should beno answer supplied.:

value_answers = [(prompts[0], ''), (prompts[2], 'v2')]

For Element Prompt Answers, you pass an empty list as the value for the prompt key.:

element_answers = {prompts[1]: []}

Pagination

The default number of rows to be returned is 100,000. This number should be a default parameter that retrieves allrows in the report, because currently the maximum number of rows in a MicroStrategy report is ~60K. Note, however,that when there are a large number of columns in the row that it would be prudent to consider pagination, otherwisethe api may return a Java out of memory stack trace.

Here is an example paging through rows rather than returning all rows in one call.:

min_row = 0max_rows_returned = MAX_ROWS / 10for i in range(10):

report.execute(start_row=min_row, max_rows=max_rows_returned)values = acv_report.get_values()# values will be null if there are no rows leftif not values:

breakfor row in values:

for attr, val in row:print val

min_row = (i + 1) * max_rows_returnedreturn result

8 Chapter 3. Executing a Report

CHAPTER 4

Installation

Install py-mstr through pip.:

pip install py-mstr

9


10 Chapter 4. Installation

CHAPTER 5

Contribute

• Source Code: https://github.com/infoscout/py-mstr

11

https://github.com/infoscout/py-mstr


12 Chapter 5. Contribute

CHAPTER 6

License

py-mstr is licensed under the MIT license.

13


14 Chapter 6. License

Python Module Index

ppy_mstr, 1

15


16 Python Module Index

Index

Symbols__call__() (py_mstr.Singleton method), 4__del__() (py_mstr.MstrClient method), 2

AAttribute (class in py_mstr), 1attribute (py_mstr.Prompt attribute), 3

Eexecute() (py_mstr.Report method), 3

Gget_attribute() (py_mstr.MstrClient method), 2get_attributes() (py_mstr.Report method), 3get_folder_contents() (py_mstr.MstrClient method), 2get_headers() (py_mstr.Report method), 4get_metrics() (py_mstr.Report method), 4get_prompts() (py_mstr.Report method), 4get_report() (py_mstr.MstrClient method), 2get_values() (py_mstr.Report method), 4guid (py_mstr.Attribute attribute), 1guid (py_mstr.Metric attribute), 1guid (py_mstr.Prompt attribute), 3

Llist_elements() (py_mstr.MstrClient method), 2

MMetric (class in py_mstr), 1MstrClient (class in py_mstr), 1MstrClientException, 2MstrReportException, 2

Nname (py_mstr.Attribute attribute), 1name (py_mstr.Metric attribute), 1

PPrompt (class in py_mstr), 2

prompt_str (py_mstr.Prompt attribute), 3py_mstr (module), 1

RReport (class in py_mstr), 3required (py_mstr.Prompt attribute), 3

SSingleton (class in py_mstr), 4

17

py-mstr Documentation - Read the Docs py-mstr supports Elements Prompt Answers (the most common type) and Value Prompt Answers. Element Prompt Answers: This is the most common type

Documents