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

Create a resource by importing a Engineering Publishing template.

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.
     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.

     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.

     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.

     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.

     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.

After you import a PUB template into a report resource, enter the report parameters.

• 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.

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

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.
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 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 IBM Engineering Workflow Management and IBM Engineering Test Management, see 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.

• 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.