Creating a document-style report on Engineering Lifecycle Management data by using Engineering Publishing

You can use IBM Engineering Lifecycle Optimization - Publishing to design reports based on data from IBM Engineering Lifecycle Management applications, including requirements management, Engineering Workflow Management , and quality management repositories. Requirements management templates can be imported into the application for use in the Jazz web interface.

Before you begin

Engineering Publishing , is not included with Engineering Lifecycle Management; separate installation and license are required. Before you begin using Engineering Publishing to customize reports, a license key server must be set up with valid licenses for your use. Contact your server administrator to verify that this has been done and to determine the license server path that you must use to connect to the license server. If you do not already have Engineering Publishing installed, you or your administrator must install it and verify that you can connect to the licensing server.

Supporting tasks:

Procedure

Engineering Publishing provides the ability to author new document-style report templates. Reports based on change and configuration management and Engineering Test Management data can only be generated using Engineering Publishing. Templates created for requirements management can be uploaded so that requirements management users can generate document-style reports, based on the templates, from the Jazz web interface. A Engineering Publishing license is required to author templates, but it is not required to run them from the requirements management application.

The tasks required to create document-style reports are covered in the Engineering Publishing product documentation. This topic contains an overview of those tasks and links to the Engineering Publishing product documentation for detailed instructions.

To create reports with Engineering Publishing that use Engineering Lifecycle Management application data, complete the following steps depending on your role:

1: Connect to Engineering Publishing
2: Design report templates
3: Connect to the application data source
4: Add application-based data queries to the template
5: Create document specification
6: Generate report (optional)
7: Import the custom document-style report

Step 1: Connect to Engineering Publishing

If you do not already have Engineering Publishing installed, you or your administrator must install it and then connect to the licensing server. Authors can use the Engineering Publishing Document Studio to import application sources and build report templates. They can also can use the Engineering Publishing Launcher to build document specifications, which incorporate report templates, and generate reports.

Connecting to a license server

Step 2: Design report templates

Start Document Studio to build a report template design.

Create or import a template design. This design determines the layout of the report. Engineering Publishing comes with a set of guided tours and templates that you can explore.

Document Studio
Getting started with creating and customizing templates
Creating a document template
Configuring metadata in Engineering Publishing for document-style reports: Add type system model to a Engineering Publishing template that can be imported.

Step 3: Connect to the application data source

Determine the data source schema that you want to import. You can use the elements in the schema to add queries on application data to the template. These queries specify what pieces of information are ultimately generated in the report.

Review the available data schemas that you want to use in the report. Each of the products has a unique schema or set of schemas.
- IBM Engineering Requirements Management DOORS® Next schema information: Schema on Jazz®.net
- IBM Engineering Workflow Management schema information: Schema on Jazz.net
- IBM Engineering Test Management schema information: Schema on Jazz.net
  Engineering Test Management provides two different types of schemas:
  - Collection schema: This schema references the individual resource schema.
  - Individual resource schema: This schema contains the definitions for all the artifacts in the quality management repository.
Construct a URL that points to the data source schema. The following are examples of URLs that point to application resources. These examples could be modified to narrow the scope of the URL to point to a subset of the schema. See the supporting information links for details.
- Engineering Requirements Management DOORS Next data source schema URL:
  - Format:
```
https://server:port/rmContextRoot/publish/artifact?metadata=schema
```
  - Example:
```
https://localhost:9443/rm/publish/text?metadata=schema
```
  - Variables:
    - rmContextRoot: Context root of your requirements management application instance
    - artifact: Type of requirements artifact that you are querying (text, resources, etc.). See Supported Artifact Types on the Jazz.net wiki.
- Engineering Workflow Management data source schema URL:
  - Format:
```
https://server:port/ccmContextRoot/rpt/repository/resource?metadata=schema
```
  - Example:
```
https://localhost:9443/ccm/rpt/repository/workitem?metadata=schema
```
  - Variables:
    - rmContextRoot: Context root of your requirements management application instance
    - resource: Type of Engineering Workflow Management resource that you are querying (text, resources, etc.).
- Engineering Test Management data source schema URL:
  - Format:
```
https://host:port/qmcontextRoot/service/com.ibm.rqm.integration.service.IIntegrationService/schema/schema file name
```
  - Example - Collection schema:
```
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/schema/feed.xsd
```
  - Example - Individual resource schema:
```
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/schema/qm.xsd
```
  - Variables:
    - qmContextRoot: Context root of your Engineering Test Management application instance
    - schema file name: Name of the schema that you are querying (tasks.xsd, testscript.xsd, etc.). See Schema on Jazz.net for information on available schema files.
Add a new data source in Document Studio. To connect to the Engineering Workflow Management schema, you can use the following steps or you can use the Schema Discovery wizard (Data > Schema Discovery > REST Schema Discovery and enter the data source schema URL.
Note: The schema discovery wizard does not work with the application REST APIs for Engineering Requirements Management DOORS Next and Engineering Test Management, so you must add the schema directly using the following steps.
1. In the data source Schemas view, click Add new data source button.
2. For Engineering Workflow Management, select REST as the schema type and enter an ID. For Engineering Test Management or Engineering Requirements Management DOORS Next, select Generic XML for better performance.
3. Enter the URL that you constructed in step 2 to access Engineering Lifecycle Management application resources.
4. Enter appropriate credentials, which give you access to the application repository.
Dynamically configure your data source schema so it can be selected at run time. If you are planning to import and run the template from the Engineering Lifecycle Management user interface, you can decide to dynamically retrieve data from your application or a friend application at run time rather than when the template is being designed.
For each data source whose URL is dynamically configured by a data source configuration element in the template, add an additional data source schema to the template. The name of the schema must not begin with an underscore (_). This additional data source does not need to be referenced in the template.

Adding a data source schema

Step 4: Add application-based data queries to the template

Report designer: Use Document Studio to add data from the Engineering Workflow Management data sources to an existing report design template. The data queries that you add determine what pieces of data are generated in various parts of the report output. You must select data points in the data source Schemas view and add them in a hierarchical order to the template.

Step 5: Create document specification

Once you have finished creating the report template and populating it with application data points, you can generate a report in a variety of formats. When you generate a report, you must connect to the data source that contains the information on which you want to run the report. You do this by specifying a URI that points to the application repository that contains the relevant data. To connect to a Engineering Workflow Management data source, you can also use the Schema Discovery wizard.

You can use filters, which are more specific versions of the general data source URI, to point to specific subsets of data so that PUB does not attempt to retrieve more information than necessary from the application repository during report generation. These filters must be broad enough to retrieve all necessary data referenced by the template or the generated report will be incomplete.

Specify the templates to include in the report.
Specify the output format and location.
Determine the data source URI. You can point to a general data source, which retrieves all the related data within the repository, or you can optionally use filters, which are more specific URIs, specifying parameters, that retrieve a smaller set of data from the repository.
- Engineering Requirements Management DOORS Next URI
  - Access all objects in the database
    - Format:
```
https://server:port/rmContextRoot/publish/artifact/*
```
    - Example:
```
https://localhost:9443/rm/publish/text
```
  - Access all objects in a project:
    - Format:
```
https://server:port/rmContextRoot/publish/artifact?projectName=guid
```
    - Example:
```
https://localhost:9443/rm/publish/resources?projectName=JKESample
```
  - Access a specific object in the database:
    - Format:
```
https://server:port/rmContextRoot/publish/artifact?resourceURI=rrc1,rrc2,rrc3
```
    - Example:
```
https://localhost:9443/rm/publish/resources?resourceURI=_c1cm0L3VEeCPFbe791FOoQ
```
  - Variables:
    - rmContextRoot: Context root of your requirements management application instance
    - artifact: Type of requirements artifact that you are querying (text, resources, etc.). See Supported Artifact Types on the Jazz.net wiki.
    - guid: Unique ID for your requirements project. See Scope and Filtering Parameters on the Jazz.net wiki for information on the optional parameters.
    - rrc1,rrc2,rrc3: Unique (comma-separated) IDs for specific requirements objects
- Engineering Workflow Management URI
  Note: A typical data source URI for Engineering Workflow Management can be constructed by taking the data source schema URL, which was used to add the schema to the template, and removing the ?metadata=schema suffix.
  - Format:
```
https://host:port/ccmcontextRoot/rpt/repository/resource/filtering properties
```
  - Example - Access general resource:
```
https://localhost:9443/ccm/rpt/repository/workitem
```
  - Example - Access specific resource:
```
https://localhost:9443/ccm/rpt/repository/workitem?fields=workitem/workItem/id
```
    Returns the id field of all workItem elements
  - Example - Access specific resource:
```
https://localhost:9443/ccm/rpt/repository/workitem?fields=workitem/workItem/(id|summary)
```
    Return the id and the summary fields of all workItem elements
  - Variables:
    - ccmContextRoot: Context root of your Engineering Workflow Management application instance
    - resource: Type of artifact that you are querying (ex, foundation, scm, build, work item, apt).
    - (optional) filtering properties: Optional filtering parameters and flags. See Reportable REST API wiki: Field selection and filtering on the Jazz.net wiki for information on the optional parameters.
- Engineering Test Management URI
  - Format:
```
https://host:port/qmcontextRoot/service/com.ibm.rqm.integration.service.IIntegrationService/resources/project name/resource/filtering properties
```
  - Example:
```
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/project1/testcase?abbreviate=false
```
  - Variables:
    - qmContextRoot: Context root of your Engineering Test Management application instance
    - project name: Name of the Engineering Test Management project that you want to access. To see the list of your available project names, visit https://host:port/qmcontextRoot/service/com.ibm.rqm.integration.service.IIntegrationService/projects
    - resource: Type of artifact that you are querying (ex, test case, test plan, etc.). See Resource Objects and their Relationships on the Jazz.net wiki for information on the supported resource types.
    - (optional) filtering properties: Optional filtering properties and flags. See Advanced Functionality on the Jazz.net wiki for information on the optional parameters.
Enter the data source URI.
Optional: Enter login credentials to access the specified data source. If this document specification is going to be shared with other users, you might want to leave the credentials fields blank. If the credentials are not specified and a user attempts to run a report from the document specification, he is prompted for credentials. If credentials are specified and a user attempts to run the report, the saved credentials are used to access the repository even though they are not that user’s credentials.

Filter conditions supported by REST native filters

Step 6: Generate report (optional)

You can generate reports from document specifications. When you generate a report, you must be connected to the data source(s) that supplies the data for the report. For information on generating documents using PUB, see Generating a document with the document generation wizard.

Step 7: Import the custom document-style report

You can import this report into your change and configuration or requirements management application, and then users can generate document-style reports using the Create a Report wizard in the requirements management Jazz web interface. For more information see, Setting up document-style reports in Engineering Lifecycle Management from Engineering Publishing templates.