Project Documentation

Documentation isn’t the most exciting thing to work on, but fortunately, MicroStrategy provides a tool that does some of the leg work for you.  This free tool is included in Desktop and produces a nicely formatted, web browsable output that can be shared with users.  In addition to discussing how to access and create this documentation report, I’ll also outline a really simple Web Customization you can apply that will integrate it into your Web environment for direct, quick access.



Generating Project Documentation
You can access the Project Documentation wizard via Desktop by opening any Project and choosing “Project Documentation” from the Tools menu.  (Note, that you need to have the “Use Project Documentation” privilege under Desktop Designer).
Choose the projects you want to include, and click Next.
Choose the types of objects you want to include.  I normally choose the first 3 since I don’t use MDX Cubes and I don’t want to share configuration options with end users.
You have the option of how verbose you want the documentation to be, but I usually choose everything.  Better to have too much information than not enough, but you can tweak individual things that you may or may not want to include.
The default export options are probably what you want, with one exception.  It’s better to change the Images option to be “Relative to the destination folder”.  This will make it easier to copy the folder to a web server for web based consumption instead of relying on local files that may not exist on a user’s machine.
Once you’re finished, click Next and Finish to begin processing.  The process isn’t fast, and if you have lots of objects and lots of projects, it can take a very long time.  It’s best to set this up on a machine that you can leave along for awhile if you suspect you’ve got a lot.
Deploying to Web
You’ll want to make it accessible to users, and since it’s already in HTML format, what better way than hosting it on a web server.  You may as well just use the same web server you use for MicroStrategy.  Here are the steps to deploying it using IIS7.
Step 1 – Copy the folder that you generated into your C:Program FilesMicroStrategy folder.  This way, your documentation is covered under the same directory security as the rest of your MicroStrategy application.
Also, make a note of the file name in the root ProjDoc folder, because we’ll need that for Step 2.
In my example, the file name is MicroStrategyAnalyticsModules(20120415112450).html
Step 2 – Open IIS Manager (under Control Panel -> Administrative Tools), expand your Sites and MicroStrategy folder, single click on the ProjDoc folder and double click on Default Document.
Then click the Add… link in the top right and enter the full name of the html file (don’t forget the extension).
Now users can access the Project Documentation by going to http://yourwebserver/MicroStrategy/ProjDoc
Integrating Directly with MicroStrategy Web
Now that we’ve generated the documentation and deployed it to an easy to find location, there’s one more thing to do to make it truly integrated: Add a context menu link to reports in Web.
In the above screenshot, you can see the new custom “View Documentation” link that is added to all objects in Web.  Clicking on it takes you directly to that object’s entry in the Project Documentation that we’re hosting:
To build this, it will require a small Java Addon.  Here’s the code:
package com.custom.microstrategy;
import com.microstrategy.web.app.transforms.TransformContext;
import com.microstrategy.web.app.transforms.FolderViewTransform;
import com.microstrategy.web.objects.WebObjectInfo;
import com.microstrategy.web.app.gui.ContextMenuItem;
import com.microstrategy.web.app.gui.ContextMenu.DefaultContextMenuItemBuilder;
import com.microstrategy.web.app.Shortcut;

public class ProjDoc extends DefaultContextMenuItemBuilder {
    public ProjDoc(Shortcut definition) {
        super(definition);
    }

    public ContextMenuItem createItem(TransformContext context) {
        ContextMenuItem  __result = super.createItem(context);
        if (context instanceof FolderViewTransform.Context) {
            FolderViewTransform.Context ftcontext = (FolderViewTransform.Context) context;
            WebObjectInfo object = ftcontext.getWebObjectInfo();
            if(object!=null) {
                __result.setJSCode("window.location='http://localhost/microstrategy/projdoc/MicroStrategy%20Tutorial%20(20120415112450)/" + ftcontext.getWebObjectInfo().getParent().getID() + "_1.html#" + object.getID() + "';");
            }>
        }
        return __result;
    }
}

Basically, this is just a small addon that generates the Context Menu Item that we’ll click on.  The link is going to redirect the page to our Project Documentation.  The format for the URL is <FolderID>_1.html#<ObjectID>.

Note: You’ll notice that the folder that contains all of the html files in the ProjDoc folder has a timestamp in it’s name.  This folder name is deeply linked in hundreds (or even thousands) of html files that the Project Documentation wizard generated.  Unfortunately, it looks like you can’t remove that timestamp during the generation process and I’m not sure how to make it a configurable option since it’ll change each time you refresh the files.  The only option I can think of is to create a second virtual directory for that specific folder and link directly to the html files through there.  That way, when you refresh your ProjDoc files, you only have to modify the IIS Virtual Directory.  Otherwise, you’ll have to recompile the java class in order to change the URL.  If anyone has a better solution to that, please share in the comments!

Next, create a file called folderContextMenus.xml with the content:
<shortcut-list-set name="folderContextMenus">
  <shortcut-list name="default">
    <shortcut desc="-" name="group3"/>
    <shortcut builder-class-name="com.custom.microstrategy.ProjDoc" desc="View Documentation" name="viewProjDoc"/>
  </shortcut-list>
</shortcut-list-set>
You can download the plugin here which contains the java file and a compile batch file.  To compile it, you’ll need Desktop installed locally on the machine and the JDK installed (first download set on that page).

You may also like...