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.

15 Replies to “MicroStrategy Task API”

  1. Very nice write up. Is it possible to use TaskAPI and pull data out of a Microstrategy Cube in, say, JSON format? I assume it would be possible using your examples above, but one would need to create a report off the MSTR cube rather than hitting it directly. Thanks kindly for your reply.

    1. Creating a report off of the cube is incidental once the cube is created. So, my best guess is no, you can’t get JSON or XML from the cube directly but the report will be a thin mask to the cube. I can’t think of a use case that would necessitate using a cube object versus a report object. With that said, I suppose I can’t definitively answer this until I’ve see the dataservice task actually fail. I’ll test it and let you know.

      1. Thanks for the followup. I do agree it will probably be best just to use the TaskAPI to pull from a report sitting on a cube, but if you test it will be interesting to hear of your findings. Thanks kindly.

  2. Hi,

    do you know if it is possible to use windows authentication with TaskAdmin? I haven’t seen an example for it anywhere.

    It’s a great blog by the way!

    Thanks,
    Bejamin

    1. I didn’t think about this when I was playing with it. It’s a good point, and I suppose the sequence has to use the getSession call, and once you have that you can refer to the session ID to do everything you need.

  3. Hey Chris. One more question on this. Have you found that you need to get and pass a Session variable? I don’t see it in your documentation or code, but when trying to capture data output using Task Administrator itself it appears as though it is required. Thanks

  4. Hi,
    I’m trying to view the output of a MicroStrategy report with JSON format by means of TaskAdmin. I get the next output:
    (function(){
    var dt = {
    status: 200,
    content: {‘id’:’DCDF65494E55CA0621A1B8973EA62B18′,’st’:’0′,’status’:’1′}
    };

    try{
    ;
    }catch(e){}
    })();

    However, I’d like to get the report content directly, so I think TaskAPI is my solution.
    The problem consists on the URL http://localhost/MicroStrategy/taskAPI not exists (localhost=myserver). ¿Is correct the URL? ¿where is located taskAPI?
    Thanks in advance.
    Mar.

    1. You need to have a functioning web server (running the 9.3 software) in order to be able to call the dataService task. Localhost is the name of the local environment — the example I gave is running the entire MicroStrategy application stack on my environment. In the example posted, I created my own .jsp file called taskAPI — normally calls to the task API are made directly via the taskAdmin or taskProc calls within the web server.

  5. I want to consume Task API event – retrieveChildren but it requires userGroupId as a mandatory parameter. Can you please let me know from where I can get these value?

    1. The userGroupID is going to be the Object ID of the user group that the user belongs to. So to find this, log in as an administrator, go to Administration –> User Manager –> and right-click on a user group. Go to properties and you will see an ID listed. This is how you anchor your reference to the user group.

  6. Hi,

    How to pass a parameter to the URL link which has the XML file generated from Microstrategy report(task proc). I need this information because I want to consumume this data as a source for a mobile application.

Leave a Reply

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

*