Setting up a Flex Environment for Building MicroStrategy Widgets

As of MicroStrategy 8.1, you can build custom widgets and visualizations using Adobe Flex.  Today, I’ll walk through the steps to setup the environment and some of the issues I’ve run into in the past (as well as some common issues other’s have run into).

Step 1: Obtaining the MicroStrategy Flex Plugin

This ships with the MicroStrategy SDK, so you’ll need to own a license for that.  The SDK is an option to install with the standard installation package if you’re licensed to use it.  You don’t need to install the MicroStrategy SDK locally, just somewhere that you can access the files.

Copy the following 2 files and keep them handy for later:


C:Program FilesMicroStrategySDKtoolsFlexVisualizationBuildercom.microstrategy.sdk.tools.visframe.visualizationbuilder.zip

C:Program FilesMicroStrategySDKDevelopmentKitsVisualizationSDKVisFramework.swc

I put this as Step 1, because if you don’t have access to this file or own an SDK license, there’s no need to continue.

Step 2: Downloading the correct version of Adobe Flex

MicroStrategy 8.1 – 9.0.2 only support Adobe Flex Builder 3.0.  Adobe released (and subsequently renamed) Flash Builder 4.0 in March of 2010 and seemed to immediately drop support for Flex 3.  It is actually quite a chore to locate the files to download, so here are the direct links for your convenience (they come with 60 day free trials):

Flex Builder 3.0
Windows: http://download.macromedia.com/pub/flex/flex_builder/FB3_win.exe
Mac: http://download.macromedia.com/pub/flex/flex_builder/FB3_mac.dmg

Flash Builder 4.0
Download link I had is now dead, so if anyone finds a new one, please drop it in the comments.
This seems to work for some people: http://trials.adobe.com/AdobeProducts/FLBR/4/win32/FlashBuilder_4_LS10.exe
You can also try to run the 4.0.1 updater which will downgrade the 4.5 version:
http://www.adobe.com/support/flex/downloads_updaters.html#flex4

Flex Builder is the IDE and ships with Flex SDK 3.0.  You’ll need to upgrade the Flex SDK to the appropriate version.  Each version of MicroStrategy requires a specific Flex SDK version.  Don’t worry though, through upgrades you can just recompile your code using the new versions of the Flex SDK without any codes changes.

9.0.2 requires Flex SDK 3.5
9.0.1 requires Flex SDK 3.2
9.2/9.2.1 requires Flex SDK 4.1
(other Flex SDK versions)

You can find the version of the SDK that you need by opening the VisFramework.swc file from Step 1 using an archive utility like WinRAR.  Extract the contents and view the catalog.xml file.  The first node will tell you what version of the Flex SDK that MicroStrategy used, and that is what you have to match.

Step 3: Setting Up Your Environment


Install Flex Builder 3.0 (you get a 60 day free trial) and extract your Flex SDK version to C:Program FilesAdobeFlex Builder 3sdks.

Extract the contents of com.microstrategy.sdk.tools.visframe.visualizationbuilder.zip from Step 1 into C:Program FilesAdobeFlex Builder 3plugins.
Important: Make sure that you extract the contents (not just place the zip file) and that the files are inside a folder called C:Program FilesAdobeFlex Builder 3pluginscom.microstrategy.sdk.tools.visframe.visualizationbuilder.

64bit Users
I work in a 64bit Windows Vista environment, and I had a lot of trouble getting Flex to run properly at first.  It would either not open or crash constantly.  After a few days of tweaking configuration files, I finally got it to run perfectly and I haven’t had any problems since.  I don’t know if these settings will work for everyone, but hopefully they’ll be a guideline.

Edit the file FlexBuilder.ini which is located in C:Program FilesAdobeFlex Builder and paste these contents:

-vmargs
-Xms512m
-Xmx1024m
-XX:MaxPermSize=96m
-XX:PermSize=96m
-Djava.net.preferIPv4Stack=true

Note: There are lots of other problems with Flex Builder in 64bit.  Check out the end of this post for some tips for getting around some of the other bugs.

Step 4: Configuring Your Environment


Launch Flex and create a new Flex Project.  Be sure to choose Web Application, but don’t have to set anything else up here.  Once your project folders are created, paste the VisFramework.swc file from Step 1 into the libs folder.  This is the core MicroStrategy framework that the widget will need for integration.

If everything was done right, you’ll see a MicroStrategy menu in the top section.  That’s a good sign, but not our destination.  First, go to Windows -> Preferences and you should see the option Visualization Builder at the bottom.  Select this option and fill out the form.  Configuring these settings will give you the ability to Deploy your widget directly to MicroStrategy automatically, but this isn’t actually a required step.  You can manually deploy your widget if you have problems with this screen (or don’t have deployment access), but I’ll talk about that in a different post.

Finally, open the mxml file that was created under the src folder and click on the MicroStrategy menu -> Overwrite With Default Template.  This will provide you with a starting shell to begin your coding.

Step 5: Compiling and Deploying

Once your masterpiece is complete, it’s time to deploy.  You’ll want to do a release build (as opposed to the debug builds you’ve been doing during development) as this will result in a smaller file size.  Under the Project menu, select Export Release Build.  This will create a bin-release folder under your project that contains some container files, but more importantly, YourWidget.swf.

From the MicroStrategy menu, select Deploy and the appropriate option for Widget / Visualization.  A Widget can only be used in Flash Mode on a Document, whereas a Visualization can be used directly in Reports or in DHTML mode in Documents.  The Deployment process will invoke TaskProc on the MicroStrategy Web server and configure MicroStrategy to accept your widget.

Copy YourWidget.swf from your bin-release folder into C:Program FilesMicroStrategyWeb ASPxswf (for Widgets) and/or C:Program FilesMicroStrategyWeb ASPxVisFramework (for Visualizations).

Restart your Web Server (just IIS) and your widget is now available to be used in MicroStrategy!

Exporting
If you want to be able to export your widget, you’ll need to do one more step.  First, download Adobe’s Local Content Updater utility and run it on a copy of YourWidget.swf:

LocalContentUpdater.exe -x YourWidget.swf

Now, copy this modified copy to your IServer machine and place it in C:Program FilesCommon FilesMicroStrategyVisFramework.  This requires an IServer restart to take effect.

Appendix: 64bit User Tips

Flex Builder 3 has some quirks with 64bit machines, to put it mildly.  I already highlighted the first one which was requiring some tweaks to the FlexBuilder.ini file.  The other place you will really struggle is in the menus.  There are lots of little bugs and issues in all of the menu and property windows.  The most common form of this is the blank property windows.  If this happens, there are two easy possible fixes.

1) Grab the little divider control between the vertical tab of options and the content of the menu that is blank.  Dragging it around to resize it will make some objects magically appear on the screen.  This works well in Project Properties.

2) Select a property category that you don’t want, and then close the property window.  Open it up again, and now going to your desired section will load properly.  This doesn’t always work, but it does seem to usually work to get to the MicroStrategy Visualization Builder menu (which has lots of issues).

Further Reading: A great blog post with some tips for wrangling Flex in a 64bit environment, including how to manually add new Flex SDKs, since I can never get the Add button to appear.

Conclusion

This tutorial will hopefully get your environment up and running with Flex Builder 3 and MicroStrategy.  Future tutorials will focus on various development topics and techniques.  Happy coding!

You may also like...