Microstrategy, personalizar ejecutaciones de informes/documentos y responder prompts vía API URL

Microstrategy nos permite vincular documentos entre sí, de manera que desde un documento podemos navegar a otro. Dependiendo de nuestras necesidades, es posible que no nos baste con las acciones por defecto que nos ofrece Microstrategy para este fin, por este motivo os voy hablar sobre las llamadas API URL que nos permite crear links personalizados a otros informes, documento, páginas, exportaciones… desde objetos como las etiquetas de texto o las imágenes:

Link, API URL

 

Antes de empezar, os listo algunos de los parámetros más importantes que podemos utilizar para construir nuestras llamadas URL :
Fuente:
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.

 

También es interesante listar las macros más comunes que podemos utilizar:

{&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.

Con la introducción anterior de las macros más habituales y de los parámetros más usados para construir invocaciones API URL, podemos determinar que la sentencia mínima para poder invocar un documento desde otro es la siguiente:
mstrWeb?port=0&evt=2048001&src=mstrWeb.2048001&documentID=ID_DOCUMENTO*
* (Podemos consultar el ID de cualquier objeto Microstrategy haciendo Clic Derecho sobre él y pulsando “PROPIEDADES”)

Vemos que se estamos utilizando el evento 2048001. Os voy a listar los principales eventos que se usan en 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

Estas URL como las anteriores podemos ir “customizandolas” a nuestra medida, según el fin que busquemos y las posibilidades son infinitas. Podemos ir concatenando infinidad de instrucciones usando el carácter “&”.
¿Qué pasaría si el documento/informes que queremos invocar tiene prompts? A continuación os muestro algunos de los parámetros e instrucciones para la respuesta de prompts vía API URL:
— &valuePromptAnswers (parámetros por valor)
— &objectsPromptAnswers (selección de objetos)
— &elementsPromptAnswers (selección de elementos de atributo)
Procedemos a analizar cada uno de ellos.
Para no sobrecargar de código redundante en las siguientes URL vamos a omitir la parte común con la que ha de empezar la URL:
mstrWeb?port=0&evt=2048001&src=mstrWeb.2048001&documentID= ID_DOCUMENTO& …

Value Prompts
Para hablar de este tema más detalladamente, en primer lugar, vamos a suponer que tenemos un documento destino con una serie de prompts por valor y queremos invocarlo desde un documento origen. Prompts documento destino (ejemplo) Mes y Región:

Desde el documento origen podemos realizar la llamada al documento destino en cuestión, contestando a los prompts en la URL, siguiendo el orden con el que nos lo solicita el documento/informe separados por ^ y precedidos del parámetro valuePromptAnswers.

Por ejemplo:
…&valuePromptAnswers=2003^Northeast

Podemos responder a estos prompts dinámicamente según el valor que tomen los atributos e indicadores en el contenedor en que se encuentre la invocación al documento destino, por ejemplo:
…&valuePromptAnswers={ATRIBUTO_1@ID}^{[ATRIBUTO_2]@[DESC]}

Si el documento origen desde el que se realiza la llamada al link ya tiene prompts, podemos utilizar alguno o todos ellos en la llamada al siguiente documento, por ejemplo:
…&valuePromptAnswers ={&Prompt1&}^{&Prompt2&}^{&Prompt3&}

Alternativamente, podemos anidar todos los prompts ya contestados en el documento origen para la llamada al siguiente documento:
…&promptsAnswerXML={&PROMPTXML}

A nivel de debug, podemos usar la variable {&PROMPTDETAILS} en una etiqueta dentro del documento para ver los prompts que hemos ido arrastrando entre documentos.
Todas las opciones son combinables, con esto me refiero a que podemos tener un escenario en que esta URL sea válida:
…&promptsAnswerXML={&PROMPTXML}&valuePromptAnswers={&Prompt1&}}^{[ATRIBUTO_2]@[DESC]} ^Northeast

También podéis coger como parámetro, el valor de algún selector que tengáis en vuestro documento. Para ello, tenéis que analizar el código de la página, buscando el ID correspondiente al selector del que queréis coger el valor y referiros a él con el parámetro {&CurrentSelectionElementID:ID_ELEMENTO&} , así podéis incluirlo como respuesta de un prompt. Tenéis información más detallada en la TN39871

 

Element Prompts

Ahora vamos a suponer que el documento destino, al que queremos invocar, tiene una selección de elementos de atributo, por ejemplo, en la que se pide escoger uno o varios meses del año (Enero, Febrero, Marzo…).
La sentencia para este tipo de llamadas sería:
— …&elementsPromptAnswers=ID_ATRIBUTO;ID_ATRIBUTO:Enero
— …&elementsPromptAnswers=ID_ATRIBUTO;ID_ATRIBUTO:Enero;ID_ATRIBUTO:Febrero
— …&elementsPromptAnswers=ID_ATRIBUTO;ID_ATRIBUTO:Enero^Febrero

Donde para obtener el ID del objeto MES de dos maneras:
— refiriéndonos a él dinámicamente como expresaba en la tabla de macros anterior {&ATTRIBUTE@GUID} en la que se correspondería con {&Mes@GUID}
— de la forma clásica (clic derecho en el atributo en cuestión y en propiedades copiar el código de su ID).

Object Prompts

Es menos común usar API URL para resolver prompts de selección de objetos no obstante también es posible hacerlo. Vamos a suponer que tenemos un prompt de selección de objetos de tipo atributo (Mes, Nombre, Edad)
La sentencia para este tipo de llamadas sería:
…&objectsPromptAnswers=ObjectGUID~ObjectTypeID~ObjectName
En nuestro caso, el ID del tipo atributo es el 12 (podéis ver los códigos ID de los tipos de datos en la tabla de este otro post):
…&objectsPromptAnswers=ID_ATRIBUTO~12~Mes
…&objectsPromptAnswers={&MES@GUID} ~12~Mes

Para seleccionar Mes y Edad (separador %1B) en el mismo prompt:
…&objectsPromptAnswers=ID_ATRIBUTO_MES~12~Mes%1BID_ATRIBUTO_EDAD~12~Mes
…&objectsPromptAnswers={&Mes@GUID}~12~Mes%1B{&Edad@GUID}~12~Mes

Si tuviéramos 2 prompts, por ejemplo otro de selección de Indicador (id de tipo objeto 4)
…&objectsPromptAnswers={&Mes@GUID}~12~Mes%1B{&Edad@GUID}~12~Mes^ID_METRICA~4~Nombre_Indicador

Otros parámetros útiles anidables en URL

Podemos forzar a que los nuevos documentos se muestren con las secciones que no nos interesen ocultas. Para ocultar secciones en un documento, no tenemos más que anidar en nuestra URL el parámetro &hiddensections seguido de las partes que queramos ocultar. Por ejemplo, nuestra URL podría ser:
mstrWeb?evt=2048001&src=mstrWeb.2048001&documentID=DOCUMENT_ID…
…&hiddensections=header,footer,path,dockLeft,dockTop

Si tenemos conflicto por usar comas en nuestra URL podemos sustituirlo por su símbolo ASCII en código hexadecimal (%2C)
…&hiddensections=header%2Cfooter%2Cpath%2CdockLeft%2CdockTop

Con una variable podemos fijar el modo de visualización de los informes:
— …&reportViewMode=1 (grid)
— …& reportViewMode=2 (graph)
— …& reportViewMode=3 (grid/graph)

O podemos definir la forma en que se va ejecutar un documento:
— …&currentViewMedia=1 Express
— …&currentViewMedia=2 Interactivo
— …&currentViewMedia=4 Editable
— …&currentViewMedia=8 Flash
— …&currentViewMedia=16 Exportar a Excel
— …&currentViewMedia=32 Exportar a PDF

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *