MicroStrategy Task API

MicroStrategy’s Task API is an advanced topic within the MicroStrategy framework, but in short, it is a protocol that can allow for programmatic access to MicroStrategy in a lightweight manner.  The Task API differs from the URL API, which is a very cheap and easy way to call reports and affect what renders and what features are turned on or off.  Bryan Brandow has a very good explanation on his blog.  Rather than carry all of the overhead and expense of pass a full URL, with the user name and password embedded in the URL, the Task API can pass instructions to MicroStrategy and return the smallest possible result set.

My interest in the Task API came from a need to trim MicroStrategy functionality down to its lightest possible format. I needed to pass instructions to MicroStrategy either through SOAP or HTTP and get a small XML or JSON file back. MicroStrategy’s SDK provides the bulk of what is needed to set up the Task API (i.e., where the .war file is if you want to deploy on Tomcat). The base URL for the API with a Tomcat web server is:

http://localhost:8080/MicroStrategy/servlet/taskAdmin?

In release 9.2.1 the Task API included a new feature called reportDataService. The beauty of this task is that it handles the login, execution, and then logout of a user. This kind of drive-by execution in one call greatly simplifies getting data from MicroStrategy quickly. My example does not pass prompt parameters, but it could. To keep it simple I created a three row, four column static report in MicroStrategy Desktop.

With the TaskAPI framework set up, and the report created (right-click on it to get the Report ID), I could now create a simple .jsp page that called the report. My final output looks like this (some liberties taken with a .css file, and a superfluous call to a jquery library and voila!):

Since I used HTTP to make the call to MicroStrategy I had to wrap and capture the output so that I could see the output. Even though the Task API has an interface to do this on the taskAmin –> Builder page, I wanted my own wrapper so that I could do some things with the output.

First, I need to bring in a handful of java libraries to handle some of the HTTP passing and data parsing:

1
2
3
<%@ page import="java.util.*" %>
<%@ page import="java.net.*" %>
<%@ page import="java.io.*" %>

Here are the fundamental snippets:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
String sUserName = request.getParameter("userName");
String sPassword = request.getParameter("password");
String sReportID = request.getParameter("reportID");

URL uUrl1 = new URL("http://localhost:8080/MicroStrategy/servlet/taskProc?"
    + "taskId=reportDataService&taskEnv=xml&taskContentType=html"
    + "&server=SERVER2008&project=MicroStrategy+Tutorial"
    + "&userid=" + sUserName
    + "&password=" + sPassword
    + "&reportID=" + sReportID
    + "&styleName=CustomXMLReportStyle");

String sUrl1 = uUrl1.toString();
String sOutputLine = "";   

sOutputLine = GetContent(sUrl1).toString() ;

This handles the construction of the URL from the form. The getContent() function does the work:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
StringBuffer GetContent(String sUrl1) throws Exception
{
    URL uURL1 = new URL(sUrl1);
    BufferedReader oReader = new BufferedReader( new InputStreamReader( uURL1.openStream()));

    StringBuffer sResult = new StringBuffer("") ;
    String sInputLine = null ;
   
    while ((sInputLine = oReader.readLine()) != null)
        sResult.append(sInputLine);
    oReader.close();
   
    return(sResult) ;
}

The output in this example will be XML with some HTML wrapping.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
value="<taskResponse statusCode="200">
<?xml version="1.0" encoding="utf-8"?>
<mstr-report>
<information>
<report-name>taskProcReport1</report-name>
<report-id>82A8F038455A7B637C4504B72B39CFDF</report-id>
<report-desc></report-desc>
<number-of-rows>3</number-of-rows>
<number-of-cols>4</number-of-cols>
<message-id>5F5F2E7742C556A4D1B093BD76C3DBAC</message-id>
<state-id>0</state-id>
<block-begin>1</block-begin>
<block-count>-1</block-count>
</information>

<report-data>
   <titles>
      <col index="1">Category</col>
      <col index="2">Promotion Type</col>
      <col index="3">Gross Revenue</col>
      <col index="4">Cost</col>
      <col index="5">Profit</col>
      <col index="6">Profit Margin</col>
   </titles>
   <rows>
   <row index="1">
      <col index="1">Books</col>
      <col index="2">No Promotion</col>
      <col index="3">$893,845</col>
      <col index="4">$679,891</col>
      <col index="5">$213,954</col>
      <col index="6">23.94%</col>
   </row>
   <row index="2">
      <col index="1">Seasonal Sale</col>
      <col index="2">$237,616</col>
      <col index="3">$180,750</col>
      <col index="4">$27,377</col>
      <col index="5">13.15%</col>
   </row>
   <row index="3">
      <col index="1">Special Sale</col>
      <col index="2">$24,655</col>
      <col index="3">$18,756</col>
      <col index="4">$968</col>
      <col index="5">4.91%</col>
   </row>
   </rows>
</report-data>
</mstr-report>
</taskResponse>

There are several use cases for this level of simple query-response execution, and an external data API to extend an existing MicroStrategy environment for data consumption seems like the easiest to comprehend. Although MicroStrategy has portlets available, the Task API let’s developers go one level deeper into the platform. When the result is only XML or JSON, the consuming application can do whatever it wants with the chunk that is returned.