Best practices

Using best practices when you customize MicroStrategy Web makes it easier to maintain your customizations when you upgrade to future releases. Recommended best practices include the following:

• Make sure that your customization is in the form of a plug-in.

  • A plug-in should contain delta files for all the changes that need to be made for the customization, as well as a readme that describes the customization, the files involved, and the steps needed to test it.
  • Plug-ins should be saved in the plugins folder located in the root directory of the MicroStrategy Web installation. At runtime, MicroStrategy Web uses these delta files to override out-of-the-box files.
  • A plug-in should conform to a specific structure that mimics the structure of hte out-of-the-box files that they override.
  • To preserve customizations during an upgrade, the current plugins folder should be copied to the upgraded installation of MicroStrategy Web.

• Take these actions before you create a customization:

  • Determine what you want the customization to do.

    When you specifically define what you are trying to accomplish, it makes it easier to create and test your customization.

  • Confirm that your purpose cannot be achieved with out-of-the-box features.

    If your purpose can be achieved using out-of-the-box features, it is almost always the best solution. It is faster, cheaper, and easier to maintain.

  • Document the purpose of the customization and include it within your plug-in as a readme file.
  • Give the plug-in for your customization a meaningful name.
• Take these actions after you create a customization:

  • Make sure you have made all changes within the plug-in.

    Do not modify out-of-the-box files. These changes are not preserved automatically during an upgrade.

  • In the readme for the plug-in, list the types of files that are used in the customization (that is, the types of files that are in the plug-in) and briefly describe what each file does. This is very helpful later if you are trying to determine whether an action can now be handled out-of-the-box or if you have problems with an upgrade. Save your readme file in the root folder of the plug-in.

    • Javascript files ( includes custom/new global.js, xPage.js, etc.)

    • .jsp/.ascx files (generally customized page source file)

      Check the corresponding out-of-the-box file and make sure that differences/changes are clear, so they can be redone from scratch after the upgrade.

    • XML files (generally custom configuration files)

    • CSS files

    • Java classes (includes custom transforms, addons, tasks, event handlers, etc.)