Designing templates with IBM Rational Team Concert as a data source

Report designers can use Document Studio to import data source schemas and build report templates.

Before you begin

Tip: The Rational® Publishing Engine installation includes a set of sample reports. Before you begin to publish documents, you can explore this example document generation scenario. See Creating the REST sample template.
Get familiar with the Rational Team Concert REST service and the various URLs needed to extract data from Rational Team Concert when you are using Rational Publishing Engine. See Reportable REST API wiki: Resources provided by Rational Team Concert.
The Rational Team Concert reportable REST API is different from many traditional domain APIs. Rather than providing resource URLs that point to specific items, such as a single work item or a single build result, the reportable REST API provides access to monolithic resources. Each monolithic resource is a container resource, which represents the result of a query for one or more elements.
  • foundation: Common artifacts such as project areas, team areas, contributors, iterations, and links.
  • workitem: Work item artifacts such as summaries, categories, severities, and priorities.
  • apt: Agile Planning artifacts such as team capacity, resource schedules, and absences.
  • generic: Generic artifacts.
  • build: Build artifacts such as build results, build result contributions, build definitions, and build engines.
  • scm: Source control artifacts such as streams and components, as well as stream sizing deltas.
These resources provide flexibility in filtering and querying when gathering data for a report. For example, a work item resource might contain one or more elements related to the work items, depending on the query or filter passed to the REST API.

About this task

Data is extracted by using the REST API. This interface is installed and implemented with the data source application and works independently of Rational Publishing Engine. For more information about the REST API for a data source, see the documentation for that data source.

Procedure

  1. Review Designing document templates for an overview of the template development process. Start planning the structure of your document and the data that might be included. For example, decide whether the final document will be generated from one template or from multiple template files that each contain reusable pieces of content.
  2. In the Document Studio application, create a document template.
  3. Add a data source schema to your document template. For Rational Team Concert, you can discover the data source schema by entering the base URL to the application.
    1. In Document Studio, click Data > Add Data Source Schema.
    2. In Schema type, select the type of the schema from the list. For Rational Team Concert, select REST.
    3. In Schema file field, paste in the URL you identified as the data source schema.
      • https://server:port/ccm/rpt/repository/foundation
      • https://server:port/ccm/rpt/repository/workitem
      • https://server:port/ccm/rpt/repository/apt
      • https://server:port/ccm/rpt/repository/generic
      • https://server:port/ccm/rpt/repository/scm
      • https://server:port/ccm/rpt/repository/build
    4. Append ?metadata=schema to the end of the URL.
      • Example: https://server:port/ccm/rpt/repository/workitem?metadata=schema
    5. In the Data Source ID field, type a name for the data source in the template. Click Next.
    6. If the resource is in a secured server, specify the User name.
    7. If the resource is in a secured server, specify the Password.
    8. Select the Authentication Type from the list. For Rational Team Concert, the authentication type is OAuth. If you do not select OAuth, each authentication type is tested until the correct type is found, which might increase document generation time.
    9. Click Finish. The data source schema you selected displays in the Data Source Schema view.
  4. Add elements to the template. Rational Publishing Engine has a comprehensive set of template elements that you can use to structure your document. You can drag elements into the template content editor. For example, you can add a Container element to hold several paragraphs. Each paragraph might be controlled by a test condition that associates it only with specific data. For more information, see Template elements in the Palette view and Adding elements to a template.
  5. Use queries, attributes, and variables to add data to a template. These items specify which pieces of information are generated in the report.
  6. Add formatting and styling to the elements to control how they display in the output.
  7. Create filters to narrow the data that is pulled into the report. You can use filters, which are detailed versions of the general data source URI, to point to specific subsets of data so that Rational Publishing Engine does not attempt to retrieve more information than necessary from the data source during report generation. These filters must be broad enough to retrieve all necessary data referenced by the template or the generated report cannot include complete data. Rational Team Concert supports Reportable Rest v1 data sources for use in native filters. See the Reportable REST API on Jazz.net for more information. Example:
    projectArea/name="Rational Publishing Engine"  and target/name="1.2.1"
    Resolved request:
    fields=workitem/workItem[projectArea/name="Rational Publishing Engine" and target.name="1.2.1"]/(@href|summary)
    Note: Not all fields can be used for native filtering.
  8. Create sorts to organize the data in your report.

Feedback