Making document-style reports available to viewers

Create a resource by importing a Rational® Publishing Engine template. Then, create a report from the resource where you can set values for the report parameters in the template.

Before you begin

Configure the metadata for the variables and data source schemas in your Rational Publishing Engine template.

About this task

For templates to be used in the Change and configuration management (CCM) application or in the Quality management (QM) application, this task is completed in three steps:
  1. Create a report resource containing the Rational Publishing Engine template
  2. Create a report from the report resource
  3. Specify the parameters for the report
Restriction: For templates to be used in the Requirements management (RM) application, you must complete the steps in manually import the custom document-style report templates.

Importing custom document-style report templates for change and configuration or quality management

1. Creating a resource

Create a resource by importing a Rational Publishing Engine template.

Procedure

In either the web client or the Eclipse client, create a report resource that contains a Rational Publishing Engine template and its associated files:

  • To import a template in the web client:
    1. In the main menu, click Reports > Report Resources.
    2. Click Create Resource.
    3. Enter a name for the report resource.
    4. Optional: Edit the description.
    5. In the Identifier field, specify the ID for the report resource.
      Learn more about how are identifiers used
      When you add a report resource or define one in a process template, there is an Identifer field. In certain cases, where reports are referenced by other artifacts, the report resource identifier is important. Example:
      • In the dashboard, the Trend Report viewlets search for reports with particular identifiers. If they are found, the dashboard viewlet displays and is usable.
      • In the Iteration Plan editor, the Charts tab looks first for a report template with the identifier apt.WorkItems. If that identifier is not found, the identifier workitems.OpenWorkItemsByType is used.
      • The dashboard viewlets offer drill-in support from the viewlet to a full-scale report. These references are by ID.
      • Some reports provide drill-in capabilities from one report to another. These references are by ID. For example, you can drill in from Work Items by Team Area to Work Items by Owner, or from Build Health to Build Result.

      If you are just deploying a report for stand-alone use (no dashboard or other report is referencing it), you can use whatever ID you want, or none at all.

    6. In the Contents area, click Browse and select a Rational Publishing Engine template (.dta).
    7. If there is an associated document specification file or style sheet that the template requires, in the Files area, click the New File icon to select the documents.
      Document specification files (.dsx)
      • A document specification is not required for every template. If you are including a document specification only to provide data source URLs or variable values, you can configure those items in your Rational solution for CLM application instead of in a document specification. A .dsx file is required when using a style sheet for Microsoft Word output and can also be used for PDF output.
      • Important: If you do include a document specification, verify that the HTML output type is configured in it. You must have HTML output available to generate the report in the Rational solution for CLM application. To export the report from the Rational solution for CLM application into Microsoft Word or PDF output, you must also specify those output types in the document specification.
      • In the .dsx file, the path to the template is not required, but the template field is required.
      • In the .dsx file, the data source URL should be left blank.
      Style sheet files (.css, .dot)
      • If a style sheet is specified for an output type in the document specification, you must also add that style sheet to the resource.
      • In the document specification, when you configure the style sheet for the output, ensure that the value of the stylesheet property is the name of the file only. Do not include a filepath.
      • The template file for Microsoft Word document generation must be renamed to template.dot before uploading it to the report resource in Quality Management.
      • The template file for Microsoft Word document generation must be renamed to template.dot before uploading it to the report resource in Quality Management.
      To edit the stylesheet property in the document specification
      1. Open the document specification in the Launcher application.
      2. Right-click the output type.
      3. Click Configure stylesheet.
      4. Select a style sheet.
      5. Remove the path to the style sheet so that only the name of the file displays.
        • Incorrect: C:\stylesheets\template.dot
        • Correct: template.dot
      6. Click OK and save the changes.

      Repeat to add each associated file.

    8. Optional: To make this report accessible by all members of the project or team area, in the Project/Team Area section, select the Shared check box.
    9. Optional: In the Caching area, select Supports data caching.
    10. Optional: To set the report as default in the planning editor, in the Planning area, select Set as Default Report.
    11. Click Save. The report resource is now updated with the new report design file.
  • To import a template in the Eclipse client:
    1. In the Team Artifacts view, expand a Project Area and Reports.
    2. Right-click Report Resources and click New > Report Resource.
    3. Enter a name for the report resource.
    4. Optional: Edit the description.
    5. In the Identifier field, specify the ID for the report resource.
      Learn more about how are identifiers used
      When you add a report resource or define one in a process template, there is an Identifer field. In certain cases, where reports are referenced by other artifacts, the report resource identifier is important. Example:
      • In the dashboard, the Trend Report viewlets search for reports with particular identifiers. If they are found, the dashboard viewlet displays and is usable.
      • In the Iteration Plan editor, the Charts tab looks first for a report template with the identifier apt.WorkItems. If that identifier is not found, the identifier workitems.OpenWorkItemsByType is used.
      • The dashboard viewlets offer drill-in support from the viewlet to a full-scale report. These references are by ID.
      • Some reports provide drill-in capabilities from one report to another. These references are by ID. For example, you can drill in from Work Items by Team Area to Work Items by Owner, or from Build Health to Build Result.

      If you are just deploying a report for stand-alone use (no dashboard or other report is referencing it), you can use whatever ID you want, or none at all.

    6. Optional: To make this report accessible by all members of the project or team area, in the Project/Team Area section, select the Shared check box.
    7. In the Contents area, click Browse and select a Rational Publishing Engine template (.dta).
    8. Optional: In the Caching area, select Supports data caching.
    9. If there is an associated document specification file or style sheet that the template requires, in the Files area, click Add to select a document.
      Document specification files (.dsx)
      • A document specification is not required for every template. If you are including a document specification only to provide data source URLs or variable values, you can configure those items in your Rational solution for CLM application instead of in a document specification. A .dsx file is required when using a style sheet for Microsoft Word output and can also be used for PDF output.
      • Important: If you do include a document specification, verify that the HTML output type is configured in it. You must have HTML output available to generate the report in the Rational solution for CLM application. To export the report from the Rational solution for CLM application into Microsoft Word or PDF output, you must also specify those output types in the document specification.
      • In the .dsx file, the path to the template is not required, but the template field is required.
      • In the .dsx file, the data source URL should be left blank.
      Style sheet files (.css, .dot)
      • If a style sheet is specified for an output type in the document specification, you must also add that style sheet to the resource.
      • In the document specification, when you configure the style sheet for the output, ensure that the value of the stylesheet property is the name of the file only. Do not include a filepath.
      • The template file for Microsoft Word document generation must be renamed to template.dot before uploading it to the report resource in Quality Management.
      • The template file for Microsoft Word document generation must be renamed to template.dot before uploading it to the report resource in Quality Management.
      To edit the stylesheet property in the document specification
      1. Open the document specification in the Launcher application.
      2. Right-click the output type.
      3. Click Configure stylesheet.
      4. Select a style sheet.
      5. Remove the path to the style sheet so that only the name of the file displays.
        • Incorrect: C:\stylesheets\template.dot
        • Correct: template.dot
      6. Click OK and save the changes.

      Repeat to add each associated file.

    10. Optional: To set the report as default in the planning editor, in the Planning area, select Set as Default Report.
    11. Click OK. The report resource is now updated with the new report design file.

2. Creating a report from the report resource

After you import a Rational Publishing Engine template into a report resource, enter the report parameters.

Procedure

  • To create a report from a resource in the web client:
    1. Click Reports > Create report from resource
    2. Enter a name for the report.
    3. Optional: Enter a description for the report.
    4. Select a folder to store your report in.
    5. Select the resource that you created in the previous task.
    6. Click Save.
  • To create a report from a resource in the Eclipse client:
    1. Right-click Reports and select New > Report.
    2. Select the resource that you created in the previous task. The report is added to My Reports.
    3. Expand My Reports.
    4. Optional: To edit the name and properties of the report, right-click the report and select Properties.

3. Specifying parameters to view the report

After you create a report from the report resource, you can enter the parameters for the report and run it.

Procedure

  1. Run the report:
    • Web client: Click the name of the report.
    • Eclipse client: Double-click the report or right-click the report and click Open.
  2. Click the Edit parameters icon Edit parameters icon.
  3. To specify values for each parameter:
    • You can select or enter a value where appropriate.
    • For parameters with a browse option, you can click Browse to open a window and select from a list of possible values. If the Browse window has a filter option, enter the filter text and click Filter to display only the values that match the filter.
      How do I design a Rational Publishing Engine template element so that the Browse button appears to select a value?
      You must set the configuration metadata for a data source schema or a variable in your template. For more information with specific examples for Rational Team Concert™ and Rational Quality Manager, see Module 1 in the Managing data with the configuration layer tutorial in the Rational Publishing Engine information center.
    • For a parameter that represents a data source whose URL is set in the template by using a data source configuration element, enter the value for the parameter as the URL of the target application. Examples:
      • https://server:port/ccm
      • https://server:port/qm
  4. Click Run.

What to do next

To export this report into another file type, click the Export icon Export icon.
  • If you are not able to view the report in the Rational solution for CLM application, verify that the HTML output is configured in your document specification.
  • If you are not able to export the report into Microsoft Word or PDF output, verify that the Microsoft Word or PDF output is configured in your document specification.

Manually importing custom document-style report templates for requirements management

If you are using the Requirements management application, you must manually import customized document-style report templates by uploading files to the Jazz Team Server.

Before you begin

To add or modify a template, complete the following steps:
  1. On the server, open the following directory: https://server:9443/application context root/reporting/initialization/templates

    For example, the full path might be C:\IBM\JazzTeamServer\server\conf\rm\reporting\initialization\templates\word for a Microsoft Word template.

  2. Open the appropriate subdirectory, and make the necessary changes to either the Rational Publishing Engine or Microsoft Word template by using the appropriate tool. For Rational Publishing Engine templates, you must have a licensed copy of the Rational Publishing Engine Document Studio tool.
See Creating a document-style report in Rational Publishing Engine using Collaborative Lifecycle Management application data.

Procedure

  1. Add any new Microsoft Word or Rational Publishing Engine templates to the appropriate subdirectory.
  2. If the report template uses a custom style sheet for the Microsoft Word output, you must upload both the Rational Publishing Engine and the Microsoft Word template. For Microsoft Word templates, you can use Microsoft Word or a similar compatible tool. For Rational Reporting for Document Generation (RRDG) to function correctly, you must save Microsoft Word templates in the Word 2003 format.
  3. The \META-INF\MANIFEST.MF file contains information that is used to populate the reporting wizard with the appropriate Rational Publishing Engine templates. If new templates are added, an entry must be added to this file. The new entry is similar to the following text: 
    Name: audithistory
Location: templates/rrdg/audithistory.dta
Label: Audit History
Description: Change history log
Content-Type: application/octet-stream
Is-Report: true
    The following table provides further information about the properties of a manifest entry:
    Table 1. Manifest entry properties
    Name Required Description
    Name Yes The name of the report template. The name must be unique in this file.
    Location Yes The directory path to access the report.
    Label No Textual label for the report template. This label is the title of the report template that is shown in the requirements management Reports wizard.
    Description No* Optional description for the report template.
    Content-Type Yes The content type that is used when you are uploading a report template.
    Is-Report No Determines whether the report template is available for selection in the requirements management Reports wizard. If present and set to "true", the template displays in the Select a Document-Style Report Type page of the wizard.
    Context No States in which context the report is displayed. Set to view, module, collection or review. For example, if you want to create a report that is only displayed in the module context, set the context to module.
    Important: You must have an empty line at the end of the MANIFEST.MF file
  4. After the changes are made, reinitialize the publish service on the server. To reinitialize,
    1. Open https://server:9443/application context root/admin in a browser.
    2. Click Debug.
    3. Under Services, click Publish Services.
    4. Click Initialize Service.
    Remember: You need Jazz Admin privileges to reinitialize the publish service.
    If the reinitialization is completed successfully, the following message is displayed: Publish Service initialized successfully.

Results

If you completed this procedure successfully and set the Is-Report property to true in the manifest file, the new template displays in the Select the Document-Style Report Type window of the Create a Document-Style Report wizard.

The Document-Style Report Type window displays a list of available templates.

Related information:
Updating Rational Publishing Engine template configuration files

video icon Watch videos

CLM playlist
Jazz.net channel
User Education channel

learn icon Learn more

CLM learning circle
Agile learning circle
Learning circles

ask icon Ask questions

Jazz.net forum
developerWorks forums

support icon Get support

Support Portal
Deployment wiki
Support blog