Quick Start Guide to Using an Existing Task

If you would like to learn how to construct and test a URL that invokes a currently registered task, without first reading all of the explanatory information in the MSDL, follow the simple steps below. Little or no explanation is provided since the goal is simply to give you a quick start rather than providing a tutorial. While it is highly recommended that you have a good understanding of tasks before you use and build tasks in production, you can go back and read in more depth after you have seen how easy it is to invoke a task.

Brief instructions are provided below for discovering whether a task that you want to execute is available out-of-the-box and, if so, constructing a URL that invokes the task—complete with appropriate parameters—and testing it to see whether it runs successfully.

This Quick Start Guide explains how to get task information using the Task Viewer, which is the application used by developers. Refer to Consuming Tasks for general guidelines on how to invoke a task from a third-party application.

Once you have successfully built and tested your task URL, you take the syntax of the task call, incorporate it into your code, and dynamically populate the answers to the relevant parameters. In addition, you need to look at the return (task status) codes to determine whether the task call was successful.

Any out-of-the-box MicroStrategy task can be exposed through a Web Services container to make operations available in a WSDL (Web Services Description Language) and accessible by SOAP.  If you would like more information about MicroStrategy Web Services and using a registered task through SOAP, refer to the Web Services SDK section of the MSDL.

In this example, you want to use a task to execute a report.

1. Open the Task Admin application using the following URL. 

   J2EE environment:

   Copy

   http://webserver:port/MicroStrategy/servlet/taskViewer

   where webserver is the machine that hosts the MicroStrategy Web Server and port is the port number to which the MicroStrategy Web Server listens.

   .NET environment:

   Copy

   http://webserver/MicroStrategy/asp/taskViewer.aspx

   where webserver is the machine that hosts the MicroStrategy Web Server.

2. Click the Home tab.

   On the Home page, there is a list of all tasks that are registered with the Task Processor. When you review the list, you see a task called reportExecute, whose description is "This executes and transforms a Report with the style supplied by the caller". To use this task, you are required to supply the style name, and in addition you must also supply the report ID and the session state. For this example, you will use the report ID of the Category Sales Report in the MicroStrategy Tutorial project. In order to get the session state, you will first run the login task, which returns the session state.

3. Click the Builder tab.

   On the Builder page, do the following: 

   1. Choose the login task from the Task ID combo box, set the Task Envelope to "XML", and set the Task Content Type to "XML (Default)". For each required parameter, enter the value indicated in the table below and check the Include? check box. 

      Required parameter	Value to enter
      server	Name or IP address of the server where MicroStrategy is installed This value will be specific to your environment.
      project	Name of the MicroStrategy project in which the report being executed is located   In this example, you should enter MicroStrategy Tutorial as the project.
      userID	User name of an account with MicroStrategy access and appropriate permissions   This value will be specific to your environment.
      password	Password for the user name referenced by the userID parameter   This value will be specific to your environment.

      The value you select for the Task Envelope is used as the value of the taskEnv parameter in the task call. Every task call should include this parameter to explicitly specify how the contents generated by the task should be packaged.

   2. Click the Update URLbutton and theBuilderpage should look similar to the one shown below.

      

   3. Click the Invoke URL button. A new pane is displayed beneath the button, with contents like those shown below.

      
      

   4. Copy the session state—that is, all of the text between the opening <session-state> node and the closing </session-state> node and outlined in dark red in the illustration above— and save it on the Clipboard. 

4. Still on the Builder page, do the following: 

   1. Choose the reportExecute task from the Task ID combo box, leaving the Task Envelope set to "XML" and the Task Content Typeset to "xml[Default]". For each parameter listed in the table below, enter the value provided or referenced and check the Include? check box. 

      Required parameter	Value to enter
      styleName	ReportDataVisualizationXMLStyle
      sessionState	Paste the value of the session state that you copied to the Clipboard in the last step
      reportID	CEF3C2B64463B7202F49AF81FCA9BE35

   2. Click the Update URL button and the Builder page should look similar to the one shown below.

      
      

   3. Click the Invoke URL button. A pane is displayed below with contents like those shown below. Status code "200" indicates that the task was successful.