Microstrategy, customize executions (documents/reports) and answer prompts via API URL

MicroStrategy allows us to link documents to other documents/reports and create a navigation between them. Depending on our needs, the default way of Microstrategy to make links couldn´t be enough for our purposes, for this reason I will talk about API URL, which allow us to create custom links to other reports, documents, pages, exports … from objects such as text labels or images:

Link, API URL

 

First, I show you some of the most important parameters we can use to build the URL calls:
Source:
https://lw.microstrategy.com/msdz/MSDL/931/docs/mergedProjects/websdk/topics/scenarios/
MicroStrategy_URL_Parameters.htm

evt The event or action that you want your MicroStrategy Web product to perform. A comprehensive list of event names and IDs can be found in events.xml, as well as the Event Handlers Reference. See Using the URL API to Access a MicroStrategy Web Page topic for instructions on how to access both out-of-the-box and custom MicroStrategy Web pages using the evt and src parameters.
src The MicroStrategy Web application component that you wish to perform the handling of the specified event. See Using the URL API to Access a MicroStrategy Web Page topic for instructions on how to access both out-of-the-box and custom MicroStrategy Web pages using the evt and src parameters.
reportID The global unique identifier (GUID) of a MicroStrategy report.
reportName The name of a MicroStrategy report.
documentID The global unique identifier (GUID) of a MicroStrategy document or HTML document.
documentName The name of a MicroStrategy document or HTML document.
folderID The global unique identifier (GUID) of a MicroStrategy folder.
objectID The global unique identifier (GUID) of a MicroStrategy object. The objectID is generally used in URLs where the event request can apply to multiple types of objects.
objectType Specifies the type of object the objectID represents. The objectType is represented by a value from EnumDSSXMLObjectType.
target Specifies the page to be opened when the evt parameter is set to the “Open Page” event id (“3004”)
hiddensections A comma-separated list of the page sections that should be hidden. For example, if you add hiddensections=header,path. to the URL, neither the header section nor the navigation bar would be displayed on the page returned by the request.
ConnMode The authentication mode used for connecting to Intelligence Server.
server The name or IP address of the machine that hosts the Intelligence Server to which to the MicroStrategy Web product connects.
project The name of the MicroStrategy project (reporting or analytical application).
uid The MicroStrategy login name to be used to authenticate with Intelligence Server.
pwd The password for the corresponding uid (login name) submitted.
usrSmgr The session state. See Authentication Using the URL API for instructions on how to use this parameter.
promptsAnswerXML An XML representation of a collection of prompt answers. Passing this parameter with any number of common events automatically applies the supplied prompt answers to as many of the prompts as are found in the particular report, document, or HTML document.
originMonthsageID An existing report, document, or HTML document instance. This parameter is used by the resulting report, document, or HTML document to extract the prompt answers from the specified instance and use them as prompt answers to any corresponding prompts in the requested report, document, or HTML document.
elementsPromptAnswers A convenience parameter that allows you to answer single or multiple element prompts by supplying individual prompt answers in the form of AttributeID;AttributeElementID^DisplayName. When there are multiple prompt answers, each individual answer is separated by a “,” (comma) separator character. In addition, you can include multiple elements to answer the same element prompt by separating each AttributeElementID^DisplayName combination (for the same AttributeID) with the “;” separator character. For example, the following parameter value represents two element prompt answers, the first of which has three different elements to answer the prompt and the second of which has only one element to answer the prompt: AttrID1;AttrElemID1a^DisplayName1a;AttrElemID1b^DisplayName1b; AttrElemID1c^DisplayName1c, AttrID2;AttrElem2^DisplayName2.
objectsPromptAnswers A convenience parameter that allows you to answer single or multiple object prompts by supplying individual answers in the form of objectID~type~name. When there are multiple prompt answers, each individual answer is separated by a “^” (caret) separator character. In addition, you can include multiple objects to answer the same object prompt by separating each objectID~type~name combination with the “%1B” separator character. For example, the following parameter value represents two object prompt answers, which each include two objects (of the same type) to answer the prompt: objectID1a~type1~name1a%BobjectID1b~type1~name1b^objectID2a ~type2~name2a%1BobjectID2b~type2~name2b.The name for an object prompt is optional, but without it, the object name does not show up in the prompt details pane in the report page.Because object prompt answers do not have an identifier that allows them to be matched with the actual prompts, the order of the prompt answers is very important. It determines the order in which prompts are answered. If you want to skip an object prompt answer when there are multiple object prompts, simply use the “^” (caret) delimiter character, without anything else, to signify an unfurnished prompt answer. An unfurnished prompt answer for the first prompt would be represented by a single caret character (“^”), while an unfurnished prompt answer for subsequent prompts would be represented by two caret characters (“^^”)—one delimiting the previous furnished prompt answer and one delimiting the unfurnished prompt answer.The prompt answers, and their order, in this parameter pertain only to object prompts. So, for example, if the first object prompt for a report is preceded by an element prompt, you would not signify an unfurnished answer to this element prompt; instead, the first prompt answer would be the one for the first object prompt.
valuePromptAnswers A convenience parameter that allows you to answer single or multiple value prompts by supplying answers in the form of a string value. When there are multiple prompt answers, each individual answer is separated by a “^” (caret) separator character. For example, the following parameter value represents two value prompt answers: Northwest^2005. Because value prompt answers do not have an identifier that allows them to be matched with the actual prompts, the order of the prompt answers is very important. It determines the order in which prompts are answered. If you want to skip an object prompt answer when there are multiple object prompts, simply use the “^” (caret) delimiter character, without anything else, to signify an unfurnished prompt answer. An unfurnished prompt answer for the first prompt would be represented by a single caret character (“^”), while an unfurnished prompt answer for subsequent prompts would be represented by two caret characters (“^^”)— one delimiting the previous furnished prompt answer and one delimiting the unfurnished prompt answer. The prompt answers, and their order, in this parameter pertain only to value prompts. So, for example, if the first value prompt for a report is preceded by an element prompt, you would not signify an unfurnished answer to this element prompt; instead, the first prompt answer would be the one for the first value prompt.
promptAnswerMode This parameter specifies how the answering of the prompts will be handled. It takes the following values. 1 – Answers all required prompts and optional prompts with default answers. Required prompts without any default answers remain open while optional prompts without default defaults answers are closed with an empty answer. 2 – Closes all optional prompts with an empty answer.

 

It is also interesting list the most common macros you can use:

{&PAGE} Display the current page.
{&NPAGES} Display the total number of pages.
{&DATETIME} Display the current date and time.
{&USER} Display the user name that is executing the Report Services Document.
{&DOCUMENT} Display the document name.
{&DOCUMENTID} Display the document ID.
{&DESCRIPTION} Display the document description.
{&PROJECT} Display the project name.
{&EXECUTIONTIME} Display the execution time.
{&SERVERNAME} Display the Intelligence Server name
{&REPORT:FILTERDETAILS} Display the filter details of that report.
{&REPORT:PROMPTDETAILS} Display the prompt details of that report.
{&REPORT:REPORTDETAILS} Display the report details.
{&NOTES} Display the Report Services Document notes.
{&Prompt1&} Display the answer of the first prompt.
{&WEBSERVER} Display the Web server URL.
{&TITLE} Display the Report Services Document inbox title.
{&PROMPTXML} Display the prompt answers XML.
{&DOCUMENTMESSAGEID} Display the message ID of the Report Services Document.
{&REPORT:GUID} Display the GUID of that particular report.
{&ATTRIBUTE@ELEMENTID} Display the Element ID of that attribute.
{&ATTRIBUTE@GUID} Display the GUID of that particular attribute.

Considering the previous introduction of macros and parameters, we can determine that the minimum sentence to invoke a document from another is:

mstrWeb?port=0&evt=2048001&src=mstrWeb.2048001&documentID=DOCUMENT_ID*

* (We can see the ID of any Microstrategy object by right- clicking on it and go to “PROPERTIES”)

As you can see, we are using the event 2048001 because is the event to execute a document.
Here you have a list of events that are usually used in Microstrategy:
• evt=2048001 Execute a document
• evt=4001 Execute a report , URL: mstrWeb?evt=4001&src=mstrWeb.4001&reportID= ID
• evt=2001 Explore a folder, URL: mstrWeb?evt=2001&src=mstrWeb.2001&folderID= ID
• evt=3034 Subscribe to a report, document, or HTML document
• evt=3036 Send a report, document, or HTML document via e-mail on a schedule ( Narrowcast Server)
• evt=3062 Export a report to PDF
• evt=3067 Export a report or HTML document (Includes Excel, Plain Text, and HTML exporting)
• evt=3069 Export a document to PDF
• evt=4033 Execute a report by supplying a template and a filter
• evt=32001 Execute an HTML document

We can customize these URLs as well as we need according to our objective. We can concatenate such parameters as we need using the character “&

And, what would happen if the target document/report, which we want to invoke, have prompts? At the following lines, I will show you some of the parameters and instructions for response prompts via API URL:

  • &valuePromptAnswers (value prompt)
  • &objectsPromptAnswers (object prompt)
  • &elementsPromptAnswers (element prompt)

 

We proceed to analyse each of them. In order to not overload the text with redundant code, in the following examples of URLs we will omit the common part which the URL need to start:

mstrWeb?port=0&evt=2048001&src=mstrWeb.2048001&documentID= DOCUMENT_ID& … :

Value Prompts

To discuss this issue in more detail, first, let’s assume that we have a target with a series of value prompts and we need to build a URL to call it from a source document. For example, prompts of the target document Month and Region:

We can build a URL to navigate from a source document to other target. We need to answer the prompts in the URL with the same order as the target document asks us. We use the parameter “valuePromptAnswers” and the character “^” to separate values For example:

…&valuePromptAnswers=2003^Northeast

We can answer these prompts dynamically based on the value taken by the attributes and indicators in the container which the link is, For example:

mstrWeb?evt=2048001&src=mstrWeb.2048001&documentID=DOCUMENT_ID&valuePromptAnswers={ATRIBUTO_1@ID}^{[ATRIBUTO_2]@[DESC]}

If the source document (where the link is) has prompts, we can use some or all of them in the call to the next document, For example:

…&valuePromptAnswers ={&Prompt1&}^{&Prompt2&}^{&Prompt3&}

Alternatively, we can nest all prompts answered in the source document, in the call to the following document:

…&promptsAnswerXML={&PROMPTXML}

At debug level, we can use the variable {&PROMPT DETAILS} on a label inside the document to see the prompts that we have been dragging between documents.

All this options are combinable, I mean that we can have a scenario which this URL is valid:

…&promptsAnswerXML={&PROMPTXML}&valuePromptAnswers={&Prompt1&}}^{[ATRIBUTO_2]@[DESC]} ^Northeast

Other option is use the value of an attribute selector as a prompt answer. For this objective, we need to analyse the page code (internet browser) looking for the corresponding ID of the selector you want to get the value and referring it with the parameter: {&CurrentSelectionElementID:ELEMENT_ID&} so you can include it in response to a prompt. You have more detailed information on the TN39871
Element prompts

Now we go to suppose that we have a target document with element prompt like the attribute Month (January, February, March…). The syntax of the URL would be:

  • …&elementsPromptAnswers=ATTRIBUTE_ID;ATTRIBUTE_ID:January
  • …&elementsPromptAnswers=ATTRIBUTE_ID;ATTRIBUTE_ID:January;ATTRIBUTE_ID:February
  • …&elementsPromptAnswers=ATTRIBUTE_ID;ATTRIBUTE_ID:January^February

Here we have two ways to get the ID of the object MONTH:

  • referring to it dynamically, as I expressed in the previous macro table {&ATTRIBUTE@GUID} , in this case: {&Month@GUID}
  • classic way (right click in the attribute and look for the ID in the properties tab.

Object prompts

Now, we go to suppose that we have a target document which have objects prompts, for example attributes (Month, Name, and Age)

The syntax of the URL would be:

…&objectsPromptAnswers=ObjectGUID~ObjectTypeID~ObjectName
In our case, the object type ID is 12 (you can check the different values of objects types ID in this post):

…&objectsPromptAnswers=ATTRIBUTE_ID~12~Month …&objectsPromptAnswers={&MONTH@GUID} ~12~Month

 

If we want to select Month and Age (separator %1B) in the same prompt:

…&objectsPromptAnswers=ATTRIBUTE_ID_MONTH~12~Month%1BATTRIBUTE_ID_AGE~12~Month …&objectsPromptAnswers={&Month@GUID}~12~Month%1B{&Age@GUID}~12~Month

 

IF we have 2 different prompts, for example, other prompt to select a metric (object type ID 4)

…&objectsPromptAnswers={&Month@GUID}~12~Month%1B{&Age@GUID}~12~Month^METRIC_ID~4~MetricName

 

Other useful parameters for you URLs

We can force to hide the sections which we will not need in our documents:

To hide sections in a document, we have only to nest the parameter &hiddensections in our URL followed by the parties we want to hide. For example, our URL could be:

mstrWeb?evt=2048001&src=mstrWeb.2048001&documentID=DOCUMENT_ID…
&hiddensections=header,footer,path,dockLeft,dockTop

If we find conflict using commas in our URL we can replace it for the equivalent hexadecimal ASCII code symbol (%2C)

hiddensections=header%2Cfooter%2Cpath%2CdockLeft%2CdockTop

With the parameter &reportViewMode we can set the report visualization mode:

  • …&reportViewMode=1 (grid)
  • …& reportViewMode=2 (graph)
  • …& reportViewMode=3 (grid/graph)

With the parameter &currentViewMedia we can define the document execution mode:

  • …&currentViewMedia=1 Express
  • …&currentViewMedia=2 Interactive
  • …&currentViewMedia=4 Editable
  • …&currentViewMedia=8 Flash
  • …&currentViewMedia=16 Export to Excel
  • …&currentViewMedia=32 Export to PDF

Leave a Reply

Your email address will not be published. Required fields are marked *