Using a Customized Version of MicroStrategy Web Help

MicroStrategy Web Help can be accessed in a number of ways—using a Help link in the toolbar, a Help icon, or a Help link in a drop-down menu. When you click a Help link or icon, either the top-level page of the MicroStrategy Web Help is displayed or, if you are on a particular page, the MicroStrategy Web Help topic for that page opens.

By default, the Help links and icon launch help files that are installed on a MicroStrategy-hosted server. When you replace the out-of-the-box MicroStrategy Web Help files with a customized version, you need to store your custom help files in a location that is accessible by your users and create a plug-in that causes the Help links and icon to point to that location. You save the plug-in in the plugins folder inside the MicroStrategy Web installation on your local machine.

In addition to generating a customized version of help, you can also rebrand the look and feel of your help. Refer to the MicroStrategy Web product help for an explanation of how to white-label your help.

MicroStrategy Web Help is generated using an authoring tool called Madcap® Flare®. To customize the out-of-the-box MicroStrategy Web Help, you need access to Madcap Flare's proprietary files along with the source files that contain the content for MicroStrategy Web Help. Using Madcap Flare's terminology, this combination of proprietary files and source HTML files is called a Flare project. To make changes to a MicroStrategy Web Help project, you need a Madcap Flare license and you should be familiar with using Madcap Flare.

For a successful implementation of custom help, refer to the following guidelines for customizing MicroStrategy Web Help. Doing so will save time and money, and simplify future upgrades.

• You can change the titles of MicroStrategy Web Help topics, but you should not change the actual file names. If you do change file names, the context sensitive help links on each page will no longer work. 
• If your System Administrators and regular users use only the English locale, you can place the custom Web Help files only in the Lang_1033 subfolder and avoid creating other language sub-folders. However, the disadvantage to this approach is that if any of your MicroStrategy Web users change the Web locale to a language other than English, they will not be able to access the MicroStrategy Web Help.

Use the following files to customize MicroStrategy Web Help: 

• Flare source files for MicroStrategy Web Help for each supported language you want to customize

  MicroStrategy Web Help is available in English and is translated into additional languages, including Chinese, French, German, Italian, Japanese, Korean, Portuguese (Brazil), and Spanish. You can customize MicroStrategy Web Help in any  translated language. 

  The Flare source file for MicroStrategy Web (DWW.flprj) includes help for multiple products. Use the MSTRWeb target to generate MicroStrategy Web Help only.

• Generated output files for Web Admin Help and the Functions Reference, in English

  Custom help must include both the Web Admin Help files and the Functions Reference because all links to the server-side out-of-the-box help are overridden and go to your custom help location.

To replace out-of-the-box MicroStrategy Web Help with your own customized version of this help, follow the steps below. Details for each step follow.

1. Place the Functions Reference and Web Admin help on your server
2. Download the MicroStrategy Web Help project source files for the languages you want to customize
3. Customize and generate the MicroStrategy Web Help projects and copy them to your custom help location
4. Create a plug-in that points the MicroStrategy Web Help links to your custom help files

Once this is completed, when you click any Help link or icon on a MicroStrategy Web page or MicroStrategy Administrator page, your custom help opens.

1. Place the Functions Reference and Web Admin help on your server

   1. Download the FunctionsRefOutputHelpFiles_English.zip file.
   2. Download the WebAdminOutputHelpFiles_English.zip file.
   3. Create a top-level producthelp folder in the location where you are hosting your help files. See the folder structure for clarification.
   4. Create a version folder (2021) below the producthelp folder. This folder is named 2021, 2022, and so on, depending on the help version you are using.
   5. Under the version folder (2021), create WebAdmin and FunctionsRef folders.
   6. Extract the contents of FunctionsRefOutputHelpFiles_English.zip in the FunctionsRef folder.

   7. Under the WebAdmin folder, create the following folder structure: WebHelp/Lang_1033. The Lang_1033 folder will contain all of the MicroStrategy Web Admin Help files in English. See the folder structure for clarification.

   8. Extract the contents of WebAdminOutputHelpFiles_English.zip in the WebAdmin/WebHelp/Lang_1033 folder.

   9. For your custom help to work correctly in MicroStrategy Web, you must save your custom help files using the specific directory structure, within the producthelp folder, as shown below. Remember the version folder (2021) may be different if you are using another version. If you are only using English, any language folders other than Lang_1033 are unnecessary.

      

2. Download the MicroStrategy Web Help project source files for the languages you want to customize

   1. Download the MicroStrategy Web Help .zip files for the languages that you want to create custom help files for:

      • Download the English help files
      • Download the translated help files
        • Chinese
        • French
        • German
        • Italian
        • Japanese
        • Korean
        • Portuguese (Brazil)
        • Spanish

   2. Extract the contents of the .zip files to your local machine. Each .zip file contains the Flare source files for MicroStrategy Web Help in that language. 

3. Customize and generate the MicroStrategy Web Help projects and copy them to your custom help location

   1. Using your copy of Flare, create a project using the source files for the MicroStrategy Web Help project that you downloaded and expanded.

   2. Customize this help project.

   3. Generate the final output with Flare.

      The Flare source file for MicroStrategy Web (DWW.flprj) includes help for multiple products. Use the MSTRWeb target to generate MicroStrategy Web Help only.

   4. Copy the generated output of your custom help projects to the location where you are hosting your custom help files.

      Copy the generated help for each language to its own language sub-folder under MSTRWeb/WebHelp. The naming convention for the language sub-folders is Lang_<localeID>. For example, generated French help files would be placed under WebUser/WebHelp/Lang_1036 and generated English help files under WebUser/WebHelp/Lang_1033. See the folder structure for clarification.

      The locale IDs for the translated help files are provided below:

      Chinese	2052
      English	1033
      French	1036
      German	1031
      Italian	1040
      Japanese	1041
      Korean	1042
      Portugese (Brazil)	1046
      Spanish	3082

4. Create a plug-in that points the MicroStrategy Web Help links to your custom help files

   Use the Web Customization Editor provided with the MicroStrategy SDK to create a plug-in for your custom help files: 

   1. Launch the Web Customization Editor. 

   2. Create a new plug-in by clicking on the Select Plug-in icon on the Application Settings tab. Give it a meaningful name, such as CustomHelp.

      
      

   3. In Eclipse, navigate to Window > Preferences > MicroStrategy. On the Preferences page:

      • Select the Show Advanced Option checkbox.
      • Select the Check All radio button to enable all the advanced options.

      • Click OK.

        
        

   4. In the Web Customization Editor, expand MicroStrategy Web Configuration inside the Application Settings view.
   5. Expand Web Configuration Settings > System Defaults.
   6. Double-click helpUrl to open the System Default Settings page.
      • For Scope, select system.

      • For Value, enter the base url where your custom help files are hosted. For example, set it to https://www.yourSite.com/producthelp/2021/, instead of the original value, https://www2.microstrategy.com/producthelp/2021/.

        

   7. Save your changes. This creates a sys_defaults.xml file in the Web-INF/xml folder of your plug-in. This XML file contains the following:

      <prs>

        <pr n="helpUrl" scp="server" v="http://www.yourSite.com/producthelp/2021/"/>

      </prs>
      
      

   8. Restart your web application server to apply your changes. Open MicroStrategy Web to view the customization.