Designing templates with Rational DOORS 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 Rational DOORS® sample template.
Examine the Rational DOORS module that you intend to use and its contents. To locate the information center for your version of Rational DOORS, see About the Rational DOORS information center.

You can use the combination of module properties, object attributes, and views that are stored in the modules. Review the available views in a module for computed columns including traceability views, or perhaps Layout DXL columns. These views do not correspond to Rational DOORS attributes, but might be something that you would like to include in the report.

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. Identify a data source schema from your data source. There are two ways to add a data source: through the DOORS Schema Discovery wizard or the Data Source Schema wizard. To add a data source using the Data Source Schema wizard:
    1. In Document Studio, click Data > Add Data Source Schema.
    2. In the Predefined field, select the Doors database schema.
    3. In Type, select the type of the schema from the list. For Rational DOORS , select DOORS.
    4. Edit the Schema field if needed or click Browse to select the path for the schema file.
    5. If the resource is in a secured server, specify the User name.
    6. If the resource is in a secured server, specify the Password.
    7. Select the Authentication Type from the list. For Rational DOORS , the authentication type is OAuth-OSLC. If you do not select OAuth-OSLC, each authentication type is tested until the correct type is found, which might increase document generation time.

    To add a data source using the DOORS Schema Discovery wizard:

    1. In Document Studio, click Data > Schema Discovery > DOORS Schema Discovery.
    2. Specify the connection details:
      • To use a running instance of Rational DOORS, select Use running DOORS instance.
      • To run Rational DOORS in the background, select Run a new background DOORS process. Specify the user name, password, database, and path to doors.exe.
    3. Select a view:
      • Database view
      • Project view
    4. Click Next.
    5. Select the attribute type:
      • To add attributes to the main objects, Module/Object schema elements, select Module and objects attributes.
      • To add attributes for linked objects, Module/Object/Link/Linked schema element, select Attributes of linked objects.
    6. In the DOORS Module Selection window, select a module from the Rational DOORS database structure and click Next.
    7. In the DOORS Baseline window, select a baseline for the module. The baseline that you select determines which attribute set to use.
    8. In the DOORS Attributes window, the following attribute information is displayed:
      • Attribute name: Lists attributes available in the selected baseline.
      • Scope: Displays the scope of the attribute as a module or an object.
      • Elevation name: The elevated name of the attribute is the name used in script expressions. A valid name is generated from the Rational DOORS attribute name to prevent entering an invalid value. An elevated attribute allows direct access to that attribute value from a Module/Object context. Non-elevated attribute values are available only from a Module/Object/Attribute context.

      Select a check box to specify an attribute or Select All to select all attributes. The Deselect All clears all attributes. Click Next.

    9. In the DOORS Views and Columns window, select the view. Then select the check box for a column name to select the column or Select All to select all column names. Click Next.
      Note: An elevation name of the column displays in the Elevation Name column. You can elevate columns from any number of views. You can elevate the attributes later while designing the template. Attributes add declarative information to elements beyond the usual predefined keywords. User-defined Rational DOORS attributes are only accessible through the Attribute nodes in the standard Rational DOORS schema file. To use these attributes, the attribute values can be elevated as XML attributes by using the XML schema discovery wizard. An attribute might have a single occurrence, for example, Module Name, and the Last Modified On property. Attributes might apply to an object, but have multiple occurrences, such as the Object Heading and Object Text.
    10. In the Select Schema Options window, enter the details for the following fields:
      • Select Schema Location: Click Browse to select the location to save the data source schema.
      • Data Source Schema ID: Enter the ID for the data source schema.
      • Select the Add Data Source Schema to the current Template check box to add this schema to the open template. Click Next.
      • Save the schemas to reuse them in other templates without running the Schema Discovery Wizard again.
    11. Review the information in the summary window and click Finish.
  4. Work with attributes. You can discover which object attributes are present in the Rational DOORS Module, and then assess whether they must appear in your Rational Publishing Engine report. Use the Edit > Attributes menu selection to access the list of attributes included in the module.
  5. 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.
    Container elements
    You can use container elements instead of tables for Rational DOORS Analyst diagrams that are contained in a 1x1 table.
    Image elements
    Images are extracted from a Rational DOORS module with the values for the attribute. You cannot query for the images only.
    To configure the size of the extracted images, specify the image max width and the image max height properties. These properties can be specified in two places:
    • Element format information defines the size for the images contained in that template element. Available for text template elements only.
    • Document specification metadata defines the size for the images in all templates. The element format values override these global values.
    Table elements
    You might not be able to reproduce a Rational DOORS table in Rational Publishing Engine exactly as it looks like in Rational DOORS; you can use available Rational DOORS table attributes and generate a new table.
    Use Rational DOORS schema wizard to extract information about the Rational DOORS tables. Example: TableCellWidthWidth of Cell in screen pixels. There are 2 ways to extract column information from Rational DOORS:
    • Using module/object/column to get the column names and values in an object query. This is useful when the Rational DOORS data is iterated by object.
    • Using module/view/column to get the column names from the Rational DOORS view used for document generation. Iterating by View is useful when the columns defined in the current view, and their properties, are needed. You can use Rational Publishing Engine sample templates to test these methods.
      Note: To access column data use module/object/column/(@Column Text) in the query.

    If you have cells in Rational DOORS tables that span multiple rows, Rational Publishing Engine generates the first cell and the remaining cells in the span are removed.

    See Adding a table element for more information about tables.

  6. Use queries, attributes, and variables to add data to a template. These items specify which pieces of information are generated in the report. Queries in IBM® Rational DOORS start with the root element (module), continues with its child element (Object), then with the child attribute of the object. For example, Module/Object/Attribute/Name. See Rational DOORS schema for more information.
  7. Add formatting and styling to the elements to control how they display in the output.
  8. 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. You can define native filters on link queries. See Example: Rational DOORS native filters for more information.
  9. Create sorts to organize the data in your report. For Rational DOORS, native sort text must be in the format of the Rational DOORS sort. See Example: Native sorts in Rational DOORS for more information.

What to do next

If you preview data from the Document Studio application, the default baseline and view are used to retrieve the data.

Feedback