Handling issues and conflicts when you upgrade

Even if you follow best practices, you may still encounter issues when you upgrade to a newer version of MicroStrategy Web. If you experience problems, do the following:

• See if someone else has already solved this issue.

  First, search the MicroStrategy Community to see if the issue you are experiencing is related to any known issues. There may already be a solution to your problem.

• Look for the file that is causing the problem.

  Try to narrow down the cause of the problem. Look at each type of file in a customization; some types of files are more likely than others to cause problems. By a process of elimination, you should be able to find the problem and fix it.

  • Javascript files

    • Customized or new Javascript files don't usually need changes, unless they are customizing or extending the Mojo framework which is subject to updates from version to version.

      Mojo Javascript objects are not part of the Web SDK. Changes or customizations to these objects come at your own risk.

    • Common Javascript files include global.js, xPage.js, and custom visualizations.

  • .jsp/.ascx files

    • Customized .jsp/.ascx files usually need to be recreated using fresh copy.

    • The most common .jsp/.ascx files are customized page sources.

    • Check the OOTB corresponding file and ensure diff/changes are clear, so they can be redone from scratch-post upgrade.

  • XML files

    • XML files don't usually need changes. However, if you have customized XML layout files in <PluginName>\WEB-INF\xml\layouts, you need to get the latest version of the files and re-implement the changes in the layout file. These files are not deltas, they are copied to the plugin in their entirety just like the .jsp and .ascx files.

    • XML files are generally configuration files.

  • CSS files

    • CSS files don't usually need changes, though CSS rules may conflict with new UI improvements.

    • CSS files are style files.

  • Java classes

    • Java classes may need to be recompiled with newerJava libraries after upgrade.

    • Common Java classes used in customizations include transforms, addons, custom tasks, and event handlers.

• Review the APIs that use have used in the customization

  The MicroStrategy SDK also provides a set of APIs you can use as building blocks to integrate advanced functionality into your applications. You can use these building blocks to create your own custom classes and JAR files. These classes are backwards-compatible, so your custom classes should work when you upgrade. You should recompile these classes so that if any of them are deprecated, the code can be updated to use new methods and to avoid possible problems in a future release.

  With each release, some of the API entities such as classes, interfaces, fields, and constructors are deprecated. This can happen because the entities are replaced by other entities that perform the tasks. It is useful to check the deprecated APIs listed in the API Reference and update any API entities from the list that you have used in your customizations in previous versions. This is important because deprecated APIs eventually get deleted in higher versions, and if you continue using deprecated APIs you run the risk of encountering compilation problems when a given API entity has been deleted. Although deprecated entities for MicroStrategy 8.x should still work, MicroStrategy recommends you migrate your customizations from deprecated entities to the new entities at your earliest convenience.

  There are two ways to learn about deprecated APIs:

  1. Review the API Reference and click Deprecated. This displays a list of all deprecated API entities such as classes, interfaces, fields, and constructors. Each entity is listed along with instructions about the replacement entity and how to use it. You can then inspect your code to work on any deprecated API that you use. 

  2. Compile your code using the "-deprecation" flag. The Java compiler finds only those deprecated entities that you use. If you are running the compiler from within an IDE, be sure the flag for displaying the deprecated API is not set to Ignore.

  Be aware of the following restrictions:

  • Old JARs and JavaScript files may conflict with new MicroStrategy versions and should not be mixed between versions.
    
  • Old CSS files may not produce functional or meaningful HTML output in the context of the new Web framework.