Refreshing a Document Automatically

This customization scenario shows how to automatically refresh a document by specifying the ID for a document and the time interval for refreshing. This customization is useful in cases where the data warehouse is frequently updated and you want to provide the most updated information in the document to the users.

This customization is accomplished by creating a properties file that lists the particular document or documents that need be automatically refreshed. Next, you create an add-on that checks for the document-to-refresh web feature. If this web feature finds the document ID (in the properties file) for the document that is clicked for execution, it executes a JavaScript for refreshing the document based on a set time interval (30 seconds). You can customize this scenario further by updating the properties file to list the document IDs of your choice and the JavaScript to specify a different time interval for refreshing.

The advantage of using an add-on is that the document ID is checked—and the document is refreshed if there is a match— each time the Document Execution page is loaded (because an add-on is executed every time a page is loaded).

This customization can be accomplished using either of the following methods:

• Deploying the plug-in provided with MicroStrategy SDK 

• Using the Web Customization Editor to create a plug-in

Deploying the plug-in provided with MicroStrategy SDK

MicroStrategy SDK provides a plug-in (ZIP file) that can simply be extracted to thepluginsfolder to view the customization in MicroStrategy Web. The following steps guide you in locating the plug-in and deploying it. 

1. Access the plug-in: JSP version or ASP .NET version. 

2. Extract the plug-in to the plugins subfolder inside the MicroStrategy Web installation folder.   

3. Launch MicroStrategy Web to view the customization.

Using the Web Customization Editor to create a plug-in

MicroStrategy SDK provides a Web Customization Editor that can be used to create a customization plug-in. The following steps guide you in creating the plug-in and deploying it. 

1. Launch the Web Customization Editor. 

2. Create a new plug-in and give it a meaningful name. For example: RefreshingDocumentAutomatically. 

3. Exit the Web Customization Editor. 

4. Create a properties file, DocumentID.properties,  that lists the document IDs of all the documents that need to be automatically refreshed and place it inside the WEB-INF/classes folder of this customization plug-in. For example: plugins\RefreshingDocumentAutomatically\WEB-INF\classes. The sample, DocumentID.properties,(located in the CustomizationPlugins\AdvancedScenarios\RefreshingDocumentAutomatically\RefreshingDocumentAutomatically\WEB-INF\classes folder of the MicroStrategy SDK installation for J2EE or located in the CustomizationPlugins\AdvancedScenarios\RefreshingDocumentAutomatically_ASP\RefreshingDocumentAutomatically\WEB-INF\classes folder of the MicroStrategy SDK installation for .NET) contains the document IDs for documents Balanced Scorecard, Category Sales and Profit Performance and Enterprise Performance Management Dashboard available in the MicroStrategy Tutorial as shown below.

   Copy

   #Balanced Scorecard
   1=18D8D2824E43A33D039C698AB4975706
    
   #Category Sales and Profit Performance
   2=3BFF3D80439FE79883E3F7986798F120
    
   #Enterprise Performance Management Dashboard
   3=374377BE47BA3CE179B10AAF592782E7

   Once the customization plug-in is created, DocumentID.properties can be accessed through the Web Customization Editor by clicking Application Settings->Property Files->WEB-INF->classes. To add or remove document IDs from this property file to maintain a list of documents that need to be automatically refreshed, see Editing a Property File or Adding a New Property to a Property File.

5. Use the Eclipse IDE to create an interface class called EnumRefreshWebFeatures. The sample, EnumRefreshWebFeatures.java, contains the entire code for this custom interface class. 

6. Compile EnumRefreshWebFeatures.java and place the class file inside the classes folder of this customization plug-in adhering to the package structure. For example: plugins\RefreshingDocumentAutomatically\WEB-INF\classes\com\microstrategy\sdk\samples\rw\refresh.
   

7. Use the Eclipse IDE to create a class for custom Web features. The sample, RefreshWebFeatures.java, contains the entire code for this custom class. 

8. Compile RefreshWebFeatures.java and place the class file inside the classes folder of this customization plug-in adhering to the package structure. For example: plugins\RefreshingDocumentAutomatically\WEB-INF\classes\com\microstrategy\sdk\samples\rw\refresh. 

9. If the Web Customization Editor is closed, launch it again and access your plug-in. 

10. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations. 

11. Click on Pages to expand the list of pages used in MicroStrategy Web. 

12. Right-click rwd (Report Writing Documents) and select Create New Add-on. This launches the Add-on Creation wizard.

    1. Click Browse to select the source folder for the project. 

    2. Enter com.microstrategy.sdk.samples.rw.refresh in the Package text field. 

    3. Enter RefreshFeatureAddon in the Name text field. 

    4. Enter Addon for refreshing a document automatically in the Add-on Description text field. 

    5. Click Next. 

    6. Click Finish. RefreshFeatureAddon.java opens in the editor. The sample, RefreshFeatureAddon.java, contains the entire code for this custom add-on. 

13. Save your changes. 

14. Double-click rwd (Report Writing Documents) and click the Events and JavaScript tab at the bottom in the right frame. 

15. Click Add Script in the JavaScript panel. This launches the JavaScript Wizard. 

    1. Enter onLoad2 in the Script Name text field. 

    2. Enter onload in the Event Name text field. 

    3. In the JavaScript code text field, enter if (typeof(microstrategy.getViewerBone()) != 'undefined')setTimeout('microstrategy.getViewerBone().commands.exec(\'refresh\');',30000);.:

       The refresh time interval is specified in milliseconds. To change it from 30 seconds to 20 seconds, update the value in the code from 30000 to 20000. 

    4. Check the box for Enable this component only when certain features are available to a user. 

    5. Select rwb from the drop-down menu for Select the web bean to be associated with this JavaScript. 

    6. Click Next. 

    7. Select document-to-refresh and click >>. 

    8. Click Next. 

    9. Click Finish. The custom JavaScript onLoad2 gets added to the list of JavaScripts in the JavaScript panel. 

16. Save your changes. 

17. Navigate back to Pages and double-click oivm (Optimized Interactive View Mode) to open it in the editor. 

18. Click the Add-on Properties tab at the bottom in the right frame. 

19. Click Add in the Add-ons section. This launches the Add-on Creation Wizard (Add). 

20. Click Modify and type RefreshFeatureAddon in the text field. 

21. Select RefreshFeatureAddon from the results window and click OK. 

22. Click Next. 

23. Click Finish to close the Add-on Creation Wizard. 

24. Click the Events and JavaScript tab at the bottom in the right frame. 

25. Click Add Script in the JavaScript panel. This launches the JavaScript Wizard. 

    1. Enter onLoad1 in the Script Name text field. 

    2. Enter onload in the Event Name text field. 

    3. In the JavaScript code text field, enter if(typeof(mstrmojo) != 'undefined') { setTimeout('mstrmojo.all.' + mstrApp.docId + '.refresh()',30000);}.:

       The refresh time interval is specified in milliseconds. To change it from 30 seconds to 20 seconds, update the value in the code from 30000 to 20000. 

    4. Check the box for Enable this component only when certain features are available to a user. 

    5. Select rwb from the drop-down menu for Select the web bean to be associated with this JavaScript. 

    6. Click Next. 

    7. Select document-to-refresh and click >>. 

    8. Click Next. 

    9. Click Finish. The custom JavaScript onLoad1 gets added to the list of JavaScripts in the JavaScript panel. 

26. Save your changes. 

27. Exit the Web Customization Editor. 

28. Launch MicroStrategy Web to view the customization.

See Also

• Customizing MicroStrategy Web:  User Privileges and Web Features 

• Advanced Customization Topics:  Web Features 

• Advanced Customization Topics:  Add-ons