Using Word Stylesheets with DNG templates
Using Word stylesheets with your template allows you to keep a consistent look&feel and simplify the design and maintenance of the RPE templates.
To use Word stylesheets with the templates deployed in DNG you need to:
- use the same name for the stylesheet and the dta file. Use doc extension for the stylesheet
- copy the stylesheet in <Server Installation>\server\conf\rm\reporting\initialization\templates\word
- reinitialize the DNG publish service by making a request to https://clmserver:port/rm/publish/initialize
You do not need to add an entry in DNG’s MANIFEST.MF but you need to have the entry for the template. See the Configuration Files for Reporting Wizard wiki for more information on what each property means.
Name: testTemplateWithMacro Location: templates/rrdg/testTemplateWithMacro.dta Label: Test Template with Macro Description: Test Template with Macro Content-Type: application/octet-stream Is-Report: true Context: view, collection
DNG can run Word macros once the document generation is complete if the following preconditions are met:
- Word is installed on the DNG server.
- the Word stylesheet associated with your template contains the macros you want to run
- the RPE template is configured to specify which macro to run
- Word is configured to allow running macros
Before we proceed I want to note one limitation I observed with this capability: you cannot specify at run time the macro to run and DNG will always run the macro hard coded in the template variable’s default value.
For the normal end user this makes a lot of sense since he/she would not know what are the supported macros and if/when they should be run so this is a decision best left to the template designer.
Edit the Word stylesheet
The first step is to edit your stylesheet to add the macro (s). Alt+F11 is the default shortcut to open the Visual Basic editor in Microsoft Word.
NOTE: RPE does not support running multiple macros. If you need to run multiple macros you just need to create an entry point macro which invokes all the required ones and call that macro from RPE/DNG.
Make sure you add your macros in the stylesheet file and not in normal.dot or any of the other projects that might be open. Double click the “ThisDocument” entry from the outline to see the macros from your file.
Edit the RPE template
The next step is to edit your template to “tell” DNG which macro you want to have executed at the end of the document generation.
NOTE: remember to run Document Studio as administrator if you want to edit the template directly in the DNG server installation. See Editing templates in protected system areas for more details.
This information on the macro to run is passed to DNG via an external variable defined in the template, variable that has the isMacroname parameter in its description.
The important things to observe about this variable:
- it is external variable
- the name is prefixed with “_” which will hide it from the report wizard.
- the description is in the form of <label> ( isMacroname:true)
- The isMacroname is the important bit as it tells DNG that this variable holds the name of the macro to be run at the end of docgen
- the label is what DNG would show in the report wizard if the variable name would not start with “_”
- the default value contains the name of the macro that will be executed.
Step #2 is done as the DNG Report Wizard will ignore any value passed in the Report Wizard for this field so showing it will only confuse user. See the limitation described at the beginning of this section.
NOTE: You can experiment by removing the “_” from the name and passing various values in the Report Wizard and you will see that it’s still the macro specify by the ‘default value’ that is run.
NOTE: if you do not specify a default value for the variable no macro will be run even if you make the variable visible and specify the name in the Report Wizard
Run the template in the Report Wizard
With the doc and dta file in place and assuming DNG publish service has been reinitialized you can run the template via the DNG’s Report Wizard. Since the macro variable is hidden you must see nothing in the Report Wizard related to macros.
You might however get a glimpse of Microsoft Word starting up and running the macro just before the process completes and if everything worked then you should see the results of the macro in the document downloaded from DNG.
Observe the results
The addDate macro I used adds the current date&time as the last line in the document. You can also observe the, intentionally excessive, styling of the output inherited from the stylesheet.
Troubleshooting the macros
You can verify if the macro run successfully or find additional information about errors in the the rrdg.log.
- CRRPE3097I The document template is processed. If there are no more templates to process, output files are being written. - CRRPE3134I The command cscript "C:\Program Files\IBM\JazzTeamServer\server\tomcat\temp\rrc_reports\rrdg\1_1_20120423\utils\word\runmacro.vbs" "C:\Program Files\IBM\JazzTeamServer\server\tomcat\temp\rrc_reports\1a41ac3b-0bda-48e8-a354-10049d7f5c17.doc" addDate is running to process the Microsoft Word macro. - Microsoft (R) Windows Script Host Version 5.8 - Copyright (C) Microsoft Corporation. All rights reserved.
For more troubleshooting tips see Troubleshooting DNG document generation with RRDG