MicroStrategy ONE

Passing Prompt Answers Using the URL API

You can use the URL API to pass certain types of prompt answers to the page being executed.

The separate sections below each provide a table of the parameters in a typical URL illustrating a specific type or number of prompts and/or a corresponding sample URL. To provide a more visual explanation, the following simple example uses actual sample prompts and prompt values to illustrate how to pass prompts in a URL. While this simple example uses value prompts and the value prompt answer parameter, the process described is the same for all types of prompts.

Simple illustrated example of passing value prompts in a URL

In this simple example, let's assume that you have a report with three value prompts—employee pay rate, employee name, and employee ID, in that order. The order can be seen in the prompt page for the report, as shown below.

Let's further assume that your answers to these prompts are the values shown below. 

Prompt Name Prompt Description Prompt Value

EmployeeID

Employee ID

25354

EmployeeName

Employee name

Sam Hill

PayRate

Employee pay rate

30

To pass these three answers as part of the URL, you first construct an answer string which includes the values shown above (in the order they appear on the prompt page), with "%5e" (a percent encoded caret character) as the separator. Using the specific prompts and values in this example, you would take the three values "30, Sam Hill, and  25354" (that is, PayRate, EmployeeName, and EmployeeID, in that order) and construct a string with "%5e" as the separator between the three values: "30%5eSam Hill%5e2535". Once you have constructed the answer string, you would set it as the value of the valuePromptAnswers parameter: "valuePromptAnswers=30%5eSam Hill%5e2535".

The caret ("^") is not a valid URL character and must be percent encoded if you follow the recommendations of the IETF. This is one of the "unsafe" characters defined in RFC1738 (which was updated by RFC3986). Previously, the caret character would not cause a problem, but many browsers will no longer allow its use.

Now you are ready to create the URL that runs a specific prompted report and automatically provides your answers to the prompts. With the parameters placed on separate lines for better understanding, the URL you create would look like the one shown below. Prompt answers are shown on the last line.

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=4CF6D88A4588097466A4B7B8851A161F
&reportViewMode=1
&valuePromptAnswers=30%5eSam Hill%5e25354

When you use this URL, the report identified by the reportID parameter is executed and automatically supplied with the prompt answers provided by the valuePromptAnswers parameter.

Answering all prompts  (promptsAnswerXML parameter)

A typical URL that passes the answers to all prompts required to run a report would have the parameters in the following table.

Parameter Description

evt

"4001" - runReport

Executes the report specified by either the reportID or reportName parameter

src

The page component that should handle the action and the event

reportID

The Global Unique Identifier (GUID) of the report to be executed

reportName

The name of the report to be executed

reportViewMode

Grid mode (1) or graph mode (2) or both (3)

execFlags*

Flags to be used while executing a report

resultFlags*

Flags to be used while retrieving the report results

promptsAnswerXML

XML with the answer to all prompts

promptAnswerMode*

Value that indicates how prompts should be answered. The following values are available from EnumWebPromptAnswerMode:

DO_NOT_PASS_PROMPT_ANSWERS = 0
This mode does not pass prompt answers.

ALL_PROMPTS_USE_DEFAULT_ANSWER = 1
This mode closes all prompt using the default answers.

OPTIONAL_PROMPTS_USE_EMPTY_ANSWER = 2
This mode closes all optional prompt using the empty answers.

USE_SOURCE_ANSWERS_FOR_PROMPT_IN_PROMP = 4
This mode uses the answers provided by the user for all prompts.

* optional parameters

A corresponding sample URL is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&promptsAnswerXML=<rsl><pa pt="4" pin="0" did="9948DC5C47AEB84A18B1BFA7F9459028" tp="10"> BB:8D679D4A11D3E4981000E787EC6DE8A4:1:2:0:2:1:3:20044:2004 Q4 pa></rsl>

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&promptsAnswerXML=<rsl><pa pt="4" pin="0" did="9948DC5C47AEB84A18B1BFA7F9459028" tp="10"> BB:8D679D4A11D3E4981000E787EC6DE8A4:1:2:0:2:1:3:20044:2004 Q4 pa></rsl>

Generating the XML to answer all prompts (including nested prompts)

The promptsAnswerXML URL parameter passes a block of MicroStrategy-specific XML that contains all of the information needed to answer prompts. While it is not recommended, it is possible to use this parameter to automatically answer nested prompts in a URL. To do this, you capture the XML generated by MicroStrategy and then use it as the value of the promptsAnswerXML parameter in the URL.

Use the following procedure to obtain the XML for the promptsAnswerXML parameter for a specific prompted report:

  1. Add the prompted report to a Report Services document. 

  2. In the body of the Report Services document, add the following auto-text:  {&PROMPTXML}. This auto-text will generate the XML needed to complete the URL API call.


  3. Run the Report Services document and answer the prompts with the answers that you want to be passed in the URL. 

  4. When the document is executed, the XML needed to complete the URL API call will be displayed. Copy this XML and use it as the value of the promptsAnswerXML in the URL.


For a code sample that illustrates how to pass prompt answers programmatically, see Capturing the Prompt Answers Supplied by the User at Runtime.

Answering element list prompts (elementsPromptAnswersparameter)

A typical URL that passes the answers to element list prompts required to execute a document would have the parameters in the following table.

Parameter Description

evt

"2048001" -  executeRWDocument

Executes the document specified by the documentID parameter

src

The page component that should handle the action and the event

documentID

The Global Unique Identifier (GUID) of the document to be executed

currentViewMedia

Interactive DHTML view mode (2) or Flash view mode (8) or Export to Excel (16) or Export to PDF (32)

execFlags*

Flags to be used while executing a report

resultFlags*

Flags to be used while retrieving the report results

elementsPromptAnswers

Specifies the answer to a single element prompt or multiple element prompts. Each individual prompt answer is in the form of AttributeID;ElementID%5eDisplayName, where ElementID consists of two identifiers, AttributeID:value, and value can be either the element ID or description. The DisplayName for an element prompt is optional, but without it, the element name does not show up in the prompt details pane in the report page.

When there are multiple element prompts, each prompt answer (or group of prompt answers) is separated by a "," (comma) separator character.

When there are multiple answers to the same element prompt, each prompt answer is separated by a ";" (semi-colon) separator character.

When the DisplayName for an element prompt is included, it must be separated from the AttributeID:value by "%5e", the encoded value of the caret character ("^").

The caret ("^") is not a valid URL character and must be percent encoded if you follow the recommendations of the IETF. This is one of the "unsafe" characters defined in RFC1738 (which was updated by RFC3986). Previously, the caret character would not cause a problem, but many browsers will no longer allow its use.

The following example represents a URL that answers two element prompts. The URL provides three different elements to answer the first prompt and only one element to answer the second prompt:

AttrID1;ElemID1a%5eDisplayName1a;ElemID1b%5eDisplayName1b;ElemID1c%5eDisplayName1c,AttrID2;ElemID2%5eDisplayName2

To pass the prompt answer for an unanswered optional element prompt, you simply specify the AttributeID for the unanswered prompt, followed by a semi-colon, but do not  include the ElementID.

To pass the prompt answer for an element prompt when the attribute has a compound ID, you separate each ElementID with a colon.

Because element prompt answers are matched with prompts using the AttributeID, the order of the prompt answers does not determine the order in which prompts are answered.

promptAnswerMode*

Value that indicates how prompts should be answered. The following values are available from EnumWebPromptAnswerMode:

DO_NOT_PASS_PROMPT_ANSWERS = 0
This mode does not pass prompt answers.

ALL_PROMPTS_USE_DEFAULT_ANSWER = 1
This mode closes all prompt using the default answers.

OPTIONAL_PROMPTS_USE_EMPTY_ANSWER = 2
This mode closes all optional prompt using the empty answers.

USE_SOURCE_ANSWERS_FOR_PROMPT_IN_PROMP = 4
This mode uses the answers provided by the user for all prompts.

* optional parameters

The attribute element ID in the code samples below should be retrieved programmatically and not constructed manually because its structure is subject to change.

A corresponding sample URL that passes the answer to a specific attribute element prompt is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
evt=2048001
&src=mstrWeb.2048001
&documentID=B9800BBC42B65FD064717BB94AF0B44B
&currentViewMedia=2
&elementsPromptAnswers=54BABC8311D59D57C000B28A4CC5F24F;54BABC8311D59D57C000B28A4CC5F24F:3%5eConnecticut

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
evt=2048001
&src=Main.aspx.2048001
&documentID=B9800BBC42B65FD064717BB94AF0B44B
&currentViewMedia=2
&elementsPromptAnswers=54BABC8311D59D57C000B28A4CC5F24F;54BABC8311D59D57C000B28A4CC5F24F:3%5eConnecticut

Passing prompt answers for an unanswered optional element prompt

A sample URL that answers an unanswered optional element prompt is shown below. The URL executes a document with an optional element prompt. It specifies the AttributeID in the URL, followed by a semicolon.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.2048001
&evt=2048001
&documentID=B9800BBC42B65FD064717BB94AF0B44B
&currentViewMedia=2
&elementsPromptAnswers=54BABC8311D59D57C000B28A4CC5F24F;

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.2048001
&evt=2048001
&documentID=B9800BBC42B65FD064717BB94AF0B44B
&currentViewMedia=2
&elementsPromptAnswers=54BABC8311D59D57C000B28A4CC5F24F;

Because the value passed in the URL for an unanswered optional element prompt does not include an AttributeElementID, it does not filter the results.

Passing prompt answers for an element prompt when the attribute has a compound ID

A sample URL that answers an element prompt when the attribute has a compound ID is shown below. This URL executes a report with one prompt. In the report, the attribute with the compound key is Distribution Center.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=58981E80412090A924C6528D14182897
&elementsPromptAnswers=8D679D5211D3E4981000E787EC6DE8A4;8D679D5211D3E4981000E787EC6DE8A4:1:2%5eSeattle

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.4001
&evt=4001
&reportID=58981E80412090A924C6528D14182897
&elementsPromptAnswers=8D679D5211D3E4981000E787EC6DE8A4;8D679D5211D3E4981000E787EC6DE8A4:1:2%5eSeattle

Answering value prompts (valuePromptAnswers)

A typical URL that passes the answers to value prompts required to run a report would have the parameters in the following table.

Parameter Description

evt

"4001" - runReport

Executes the report specified by either the reportID or reportName parameter

src

The page component that should handle the action and the event

reportID

The Global Unique Identifier (GUID) of the report to be executed

reportName

The name of the report to be executed

reportViewMode

Grid mode (1) or graph mode (2) or both (3)

execFlags*

Flags to be used while executing a report

resultFlags*

Flags to be used while retrieving the report results

valuePromptAnswers

Specifies the answer to a single value prompt or multiple value prompts in the form of a string value.  When there are multiple value prompt answers, each individual answer is separated by "%5e", a percent encoded caret ("^") character.

The caret ("^") is not a valid URL character and must be percent encoded if you follow the recommendations of the IETF. This is one of the "unsafe" characters defined in RFC1738 (which was updated by RFC3986). Previously, the caret character would not cause a problem, but many browsers will no longer allow its use.

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 percent encoded caret character ("%5e"), without anything else, to signify an unfurnished prompt answer. An unfurnished prompt answer for the first prompt would be represented by a single percent encoded caret character ("%5e"), while an unfurnished prompt answer for subsequent prompts would be represented by two percent encoded caret characters ("%5e%5e")—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 notsignify an unfurnished answer to this element prompt; instead, the first prompt answer would be the one for the first value prompt.

Because of the convention for signifying unanswered prompts, you are not able to answer a value prompt with an empty string through the URL.

promptAnswerMode*

Value that indicates how prompts should be answered. The following values are available from EnumWebPromptAnswerMode:

DO_NOT_PASS_PROMPT_ANSWERS = 0
This mode does not pass prompt answers.

ALL_PROMPTS_USE_DEFAULT_ANSWER = 1
This mode closes all prompt using the default answers.

OPTIONAL_PROMPTS_USE_EMPTY_ANSWER = 2
This mode closes all optional prompt using the empty answers.

USE_SOURCE_ANSWERS_FOR_PROMPT_IN_PROMP = 4
This mode uses the answers provided by the user for all prompts.

* optional parameters

A corresponding sample URL is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=4CF6D88A4588097466A4B7B8851A161F
&reportViewMode=1
&valuePromptAnswers=South%5e1/1/2003

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.asp.4001
&evt=4001
&reportID=4CF6D88A4588097466A4B7B8851A161F
&reportViewMode=1
&valuePromptAnswers=South%5e1/1/2003

Answering object prompts (objectsPromptAnswersparameter)

A typical URL that passes the answers to object prompts required to run a report would have the parameters in the following table.

Parameter Description

evt

"4001" - runReport

Executes the report specified by either the reportID or reportName argument

src

The page component that should handle the action and the event

reportID

The Global Unique Identifier (GUID) of the report to be executed

reportName

The name of the report to be executed

reportViewMode

Grid mode (1) or graph mode (2) or both (3)

execFlags*

Flags to be used while executing a report

resultFlags*

Flags to be used while retrieving the report results

objectsPromptAnswers

Specifies the answer to a single object prompt or multiple object prompts, with each individual prompt answer in the form of objectID~type~name. When there are multiple object prompt answers, each individual answer is separated by "%5e", a percent encoded caret ("^") character.

The caret ("^") is not a valid URL character and must be percent encoded if you follow the recommendations of the IETF. This is one of the "unsafe" characters defined in RFC1738 (which was updated by RFC3986). Previously, the caret character would not cause a problem, but many browsers will no longer allow its use.

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 to answer the prompt: objectID1a~type1a~name1a%1BobjectID1b~type1b~name1b^objectID2a~type2a~name2a%1BobjectID2b~type2b~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 percent encoded caret character ("%5e"), without anything else, to signify an unfurnished prompt answer. An unfurnished prompt answer for the first prompt would be represented by a single percent encoded caret character ("%5e"), while an unfurnished prompt answer for subsequent prompts would be represented by two percent encoded caret characters ("%5e%5e")—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 notsignify an unfurnished answer to this element prompt; instead, the first prompt answer would be the one for the first object prompt.

promptAnswerMode*

Value that indicates how prompts should be answered. The following values are available from EnumWebPromptAnswerMode:

DO_NOT_PASS_PROMPT_ANSWERS = 0
This mode does not pass prompt answers.

ALL_PROMPTS_USE_DEFAULT_ANSWER = 1
This mode closes all prompt using the default answers.

OPTIONAL_PROMPTS_USE_EMPTY_ANSWER = 2
This mode closes all optional prompt using the empty answers.

USE_SOURCE_ANSWERS_FOR_PROMPT_IN_PROMP = 4
This mode uses the answers provided by the user for all prompts.

* optional parameters

Answering a single object prompt

A sample URL that answers a single object prompt is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=4C051DB611D3E877C000B3B2D86C964F~4~Profit

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=4C051DB611D3E877C000B3B2D86C964F~4~Profit

Answering multiple object prompts

A sample URL that answers multiple object prompts is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&src=mstrWeb.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=
4C05177011D3E877C000B3B2D86C964F~4~Revenue
%5e
8D679D3711D3E4981000E787EC6DE8A4~12~Category

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=
4C05177011D3E877C000B3B2D86C964F~4~Revenue
%5e
8D679D3711D3E4981000E787EC6DE8A4~12~CategoryPassing multiple objects to one prompt

Passing multiple objects to one prompt

A sample URL that passes multiple objects to one prompt is shown below.

J2EE environment:

Copy 
http://webserver/MicroStrategy/servlet/mstrWeb?
&&src=mstrWeb.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=
4C05177011D3E877C000B3B2D86C964F~4~Revenue
%1B
4C051DB611D3E877C000B3B2D86C964F~4~Profit
%5e
8D679D3711D3E4981000E787EC6DE8A4~12~Category

.NET environment:

Copy 
http://webserver/MicroStrategy/asp/Main.aspx?
&src=Main.aspx.4001
&evt=4001
&reportID=EB3CD5D14F4C8C77782AC0882C986B8D
&reportViewMode=1
&objectsPromptAnswers=
4C05177011D3E877C000B3B2D86C964F~4~Revenue
%1B
4C051DB611D3E877C000B3B2D86C964F~4~Profit
%5e
8D679D3711D3E4981000E787EC6DE8A4~12~Category

Answering all optional prompts with empty answers

You can use the following parameter in the mobile URL to pass empty answers for all optional prompts. You set the value of the promptAnswerMode parameter to 2 for OPTIONAL_PROMPTS_USE_EMPTY_ANSWER.

This parameter closes all optional prompts with empty answers; you cannot selectively choose to close individual optional prompts.

Parameter Value

promptAnswerMode

Value that indicates how prompts should be answered. The following values are available from EnumWebPromptAnswerMode:

DO_NOT_PASS_PROMPT_ANSWERS = 0
This mode does not pass prompt answers.

ALL_PROMPTS_USE_DEFAULT_ANSWER = 1
This mode closes all prompts using the default answers.

OPTIONAL_PROMPTS_USE_EMPTY_ANSWER = 2
This mode closes all optional prompts using the empty answers.

USE_SOURCE_ANSWERS_FOR_PROMPT_IN_PROMP = 4
This mode uses the answers provided by the user for all prompts.

A sample URL that answers all optional prompts with empty answers for an email subscription is shown below.

J2EE environment:

Copy 
mstrWeb?evt=3036&src=mstrWeb.3036&objectID=0DBAEAEE11E894CBB9810080EF9578D4&viewMode=1&objectType=3&evt=8026&src=mstrWeb.subFrame.pcb.8026&promptAnswerMode=2&evtorder=3036%2c8026&8026=1&3036=1

See also: