Setting up document-style reports in ELM from Engineering Publishing templates

Create a resource by importing a IBM® Engineering Lifecycle Optimization - Publishing (PUB) 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 Engineering Publishing 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 PUB 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 Engineering Publishing template.

Procedure

In either the web client or the Eclipse client, create a report resource that contains a Engineering Publishing 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.
      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.

      The only requirement for the identifier is that it be unique within the project area (i.e., you can't have two report resources in the same project with the same identifier).

      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 Engineering Publishing 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 IBM Engineering Lifecycle Management (ELM) 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 ELM application. To export the report from the ELM 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.
      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.
      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.

      The only requirement for the identifier is that it be unique within the project area (i.e., you can't have two report resources in the same project with the same identifier).

      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 Engineering Publishing 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 IBM Engineering Lifecycle Management (ELM) 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 ELM application. To export the report from the ELM 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.
      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 PUB 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.
      You must set the configuration metadata for a data source schema or a variable in your template. For more information with specific examples for IBM Engineering Workflow Management and IBM Engineering Test Management, see Module 1 in the Managing data with the configuration layer tutorial.
    • 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 ELM 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 PUB or Microsoft Word template by using the appropriate tool. For PUB templates, you must have a licensed copy of the PUB Document Studio tool.
See Creating a document-style report on ELM data by using Engineering Publishing.

Procedure

  1. Add any new Microsoft Word or PUB 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 PUB and the Microsoft Word template. For Microsoft Word templates, you can use Microsoft Word or a similar compatible tool. For Engineering Document Generation (EDG) 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 PUB 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 Yes 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.


video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki