Designing templates with Rational ClearQuest 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 ClearQuest® REST service and the various URLs needed to extract data from Rational ClearQuest using Rational Publishing Engine. See About the Rational ClearQuest information center.

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 ClearQuest, you can discover the data source schema by entering the base URL to the application.
    1. Open the schema discovery wizard that applies to your version of Rational ClearQuest
      • For early versions of Rational ClearQuest that use REST v1, click Data > Schema Discovery > REST Schema Discovery.
      • For later versions of Rational ClearQuest that use REST v2, click Data > Schema Discovery > REST v2 Schema Discovery.
    2. Specify the Base URL for the resource.
      • For REST v1 versions of Rational ClearQuest, Rational Publishing Engine uses Rational Data Services to discover schema and query data. The base URL to the Data Services is: https://server:port/DataServices/ClearQuest
      • For REST v2 versions of Rational ClearQuest, started from a ServiceProvider URL. Users can obtain the ServiceProvider URL by visiting Rational ClearQuest REST v2 ServiceCatalog URL, like https://server:port/context/oslc. Set HTTP headers OSLC-Core-Version to 2.0 and accept to application/rdf+xml. From the returned result, you can find the ServiceProvider URL rdf:about.
        If you are using the REST v2 APIs to generate the document, you must provide a data source schema URL to the service provider rather than to the root entry. Example:
        • Incorrect: https://server:port/cqweb/oslc
        • Correct: https://server:port/cqweb/oslc/repo/repository/db/schema_repository/
    3. Select an Authentication Type from the list. If you do not select a type, each type is tested until the correct type is found, which might increase document generation time.
    4. If the resource is in a secured server, specify the User name.
    5. If the resource is in a secured server, specify the Password.
    6. Click Next. The base URL you entered is automatically appended with ?metadata=schema. Example: https://server:port/service/cq/records/defects?metadata=schema
    7. 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.

    The Rational ClearQuest adapter supports native filtering from Reportable Rest v1 data sources. In Reportable Rest v1 native filters, you are only required to enter the text between the brackets []. The rest of the filter is generated by Rational Publishing Engine. See Reportable Rest v1 for more information.

    Rational ClearQuest version 8 without the adapter supports native filtering from Reportable Rest v2 data sources. For more information, see Rational ClearQuest OSLC CM REST API .

    Sample variable filter:
    cq:Product{cq:Product="${productName}") 
    Sample resolved filter where the productName is Rational Publishing Engine:
    cq:Product{cq:Product="Rational Publishing Engine")
    Note:
    • Requests are made to a data source only when required. For example, you can use conditions to have an element display in the output only when it contains data. The condition on a container element might be variable == "true". If this condition is not met and no data meets the variable condition, no requests are made to the data source.
    • You can calculate native filters before making the request. The native filter is calculated at the point where the query is encountered and uses the variable values at that point. So you can perform calculations in the template, which impacts the native filters.
  8. Create sorts to organize the data in your report.

Feedback