Rational Publishing Engine and Rational RequisitePro

Using Rational Publishing Engine to extract data from Rational RequisitePro Calin Rusu Reporting Arena Team Member www.reportingarena.com

About the author Reporting Arena is part of Global E-Business Solution Group, an IBM Business Partner that became IBM Software Services Business Partner for Rational Tools in 2010. Reporting Arena is formed by a large part of the team that developed IBM Rational Publishing Engine, team that also developed and maintained Telelogic DocExpress. The team has been active in the document generation world for the past 8 years gathering invaluable expertise in the real-world document generation needs.

Services At Reporting Arena, we specialize in providing enterprise-grade services for publishing needs, by setting up a correct documentation process and adopt it to your organization specific needs. Template Design and Optimization With many years of first-hand experience in the document generation world, including the development of Rational Publishing Engine, and long exposure to many data source repositories and real-world documentation needs we are in a good position to handle complex scenarios including the creation of cross-products documents. Custom Solutions Rational Publishing Engine is a great solution for document generation needs but there are tasks that require additional capabilities that might not be immediately available in RPE. We provide custom solutions that enable Rational Publishing Engine to fully meet your requirements. Migration from other document generation technologies Rational Publishing Engine supersedes IBM Rational SoDA and IBM Telelogic DocExpress. Reusing the SoDA and DocExpress templates will not only prevent from wasting the resources spend to create these assets but will also reduce the time needed to create and validate matching RPE assets.

Introduction The goal of this tutorial is to introduce the basics of using Rational Publishing Engine to extract data from Rational RequisitePro and create output documents to present in a friendly way the extracted data. Using Rational Publishing Engine, a Template will be created for extracting all the Software Requirements of a RequisitePro project and other related information.

Prerequisites Microsoft Windows XP/Vista/7 Rational Publishing Engine 1.1.1.2 or later Rational RequisitePro 7.1 including Learning Project – Traditional Some additional elements were inserted in the Learning Project – Traditional to emphasis recursion and image extracting RPE features additional descendant requirement for the current existing requirements image attribute of type URL Link – to store the URL to the image file Rational Publishing Engine Data Services for RequisitePro Microsoft Word 2003/2007 (to visualize the output document) Basic knowledge of using RPE Basic knowledge of using RequisitePro

Use Case 1/5 Output Document Description The output document will contain the list of SR Requirements and the related PR Requirements of a specific RequisitePro project. The output document will also present the relations between the SR Requirements . The attributes FullTag , Text , Status will be extracted for each SR Requirement . If a SR Requirement will contain a URL link to an image file, the image will be displayed in the output document. The FullTag attribute will be displayed for each PR Requirement . Output document additional information The title page will present the name of the RequisitePro project. The output document will contain a Table of Contents. The name of the RequisitePro project will be presented in the header section of the output document.

Use Case 2/5 Desired output document title page Text centered in vertical and horizontal plan

Use Case 3/5 Heading 1 Heading 2 Heading 3 Indentation Figure Caption Desired output document Sample page

Use Case 4/5 To obtain the desired output document the following steps will be performed: 1. Data Sources Schema Three Data Source Schemas will be retrieved from RequisitePro using REST Schema Discovery: Data Source Schema for Software Requirements Used to extract the SR Requirements Data Source Schema for Product Requirements Used to extract the PR Requirements Data Source Schema for Project Used to extract information about the Project 2. Software Requirements query and attributes All Software Requirements of Level 0 will be extracted. A set of attributes (FullTag, Text, Status and an Image, if available) will be displayed for each Software Requirement . A Figure Caption of which text will be retrieved from a Data Source attribute will be displayed for the Image.

Use Case 5/5 3. Descendant Software Requirements query All descendant Software Requirements will be extracted using recursion. The FullTag attribute will be displayed in the output documents for each descendant Software Requirement 4. Traceability: Product Requirements query The Product Requirements that have traceability links to Software Requirements will be extracted using the Data Source Schemas for Product Requirements . 5. Styles and Formatting properties Styles and formatting properties will be used to provide a nice look for the output document. 6. Master Page A Master Page will be created and used. 7. Title page A title page will be created to present the Project name. 8. Configure Document Specification Document Specification will be configured to extract the desired data and to generate the output document for Microsoft Word.

Checkpoint 1. Data Sources Schemas 2. Software Requirements query and attributes 3. Descendant Software Requirements query 4. Traceability: Product Requirements query 5. Styles and Formatting properties 6. Master Page 7. Title page 8. Configure Document Specification

SRRequirements Schema Discovery 1/10 Getting the Data Source Schema using the REST Schema Discovery wizard Select from Menu Data -> Schema Discovery -> REST Schema Discovery … The REST Resource Discovery wizard will start. This wizard will provide guidance for choosing the correct schema.

SRRequirements Schema Discovery 2/10 Specify Credentials The Name (name of the schema) and the Base URL are mandatory information. In this tutorial, “giediprime” is the name of the machine providing data services for RequisitePro. Specify Data Source Schema name Specify Data Source Schema description Insert Base URL of resource

SRRequirements Schema Discovery 3/10 Check the href in the Adaptor folder and click Next . The href represents the URL of the Resource to be discovered.

SRRequirements Schema Discovery 4/10 Each wizard page will ask to select an href value.

SRRequirements Schema Discovery 5/10 Check the href in the Project folder and click Next .

SRRequirements Schema Discovery 6/10 In this tutorial the Learning Project - Traditional will be used

SRRequirements Schema Discovery 7/10 Check the href in the Resource folder and click Next .

SRRequirements Schema Discovery 8/10 The Requirements represents the interesting data for this tutorial. Click Next .

SRRequirements Schema Discovery 9/10 Check the href in the RequirementsCollection folder and click Next .

SRRequirements Schema Discovery 10/10 Select the SR and press Finish to get the schema for SRRequirements . Schema will be downloaded and added to Template .

PRRequirements Schema Discovery 1/2 The process is similar like getting the schema for SRRequirement . Difference: insert the PRRequirements in the Name field.

PRRequirements Schema Discovery 2/2 Difference: the final href . Select PR and press Finish . Schema will be downloaded and added to Template .

Project Schema Discovery 1/2 The process is similar like getting the schema for SRRequirement . Difference: the name of the schema: Project.

Project Schema Discovery 2/2 Difference: the final href . Select Learning Project – Traditional and press Finish . Schema will be downloaded and added to Template.

Data Source Schemas All three Data Source Schemas are added to the Data Source Schema view and in Outline view.

Checkpoint 1. Data Sources Schema 2. Software Requirements query and attributes 3. Descendant Software Requirements query 4. Traceability: Product Requirements query 5. Styles and Formatting properties 6. Master Page 7. Title page 8. Configure Document Specification

SRRequirements query Set the Paragraph name as SRRequirements : select the Paragraph; in the Properties view, expand the Metadata tree item, set the value of the name property. Best Practice: The Template elements name should suggest what is intended to be displayed in the output document. Create a Paragraph: Select the Paragraph in the Palette and click in the desired location in the Template Content. Set the SRRequirement query to the Paragraph: Select the SRRequirements tab of the Data Source Schema v iew; Drag the desired query from the Data Source Schemas view and drop it on the Paragraph.

SRRequirements query attributes 1/5 Use the FullTag and Text attributes of the SRRequirement query from the Data Source Schema view in the SRRequirement attributes Paragraph: Drag the attribute from the Data Source Schemas view and drop it to the desired location. Create a new Paragraph in the SRRequirements Paragraph. Set the name of the newly created Paragraph to SRRequirement attributes .

SRRequirements query attributes 2/5 When the attribute is dropped, the Select Context dialog will open to select the way the attribute will be used. Select Use as value . Select the $1 – Project/Requirements/SRRequirement context. Perform the same operation for all the attributes.

SRRequirements query attributes 3/5 Create a Paragraph named Status below the SRRequirement attributes Paragraph. Create a Text in the Status Paragraph that will be used as a label for Status data attribute. Use the Status attribute of the SRRequirement query: insert it after the newly created Text.

SRRequirements query attributes 4/5 Set the content of the Text used as a label: Double click on the Text. The Set Content for Current Element dialog opens: Select Simple Value tab and write “Status”. Click Ok.

SRRequirements query attributes 5/5 The content is set to the Text.

Preview the Output Document Configure the Data sources. run the report to preview the output document. Please see Step No. 8. The output document contains the SRRequirement of all levels. A query filter is needed to get only the SRRequirements of Level 0. A Native Filter can be used in this situation.

SRRequirements query filter Select the SRRequirements Paragraph. In the Properties view, expand Data item. Select the Filter and click on “Browse” button. The Filter Editor dialog is open. Select the Native Filter tab. Set the Native Filter expression: “Level = 0”, where Level is an attribute of the query Project/Requirement/SRRequirement Click Ok. The Filter is set.

SRRequirements Image attribute Create a Container in the SRRequirements Paragraph. Set Image as the name of the Container. Create an Image in the Image Container. Set the Image Content : Double click on the Image, the Set Value for Image Element dialog will open. Select Data Expression tab to have access to the Data Source attributes. Select Image attribute of the query Project/Requirements/SRRequirement . Click Ok.

Adding a Figure Caption Create a Paragraph in the Image Container, below the Image. Create a Figure Caption in the Paragraph. Set the content of the Figure Caption: Double click on the Figure Caption, the Set Field Label Value for Image Element dialog will open. Select Data Expression tab to have access to Data Source attributes. Select FullTag attribute of the query Project/Requirements/SRRequirement . Click Ok.

SRRequirements condition A condition is needed to display the Image only when a valid link to an image exists. Click on the Image Container. Select Data -> Edit Condition… in the contextual menu. The Set Condition for Current Element dialog opens. Select the Image attribute of the query for the Left operand. Select “Not equal to” for the Operator. Let the Right Operand empty. Click Add button. The condition Image != “” is added. Click Ok.

Preview the Output Document Note the Image and below the Image the Figure Caption having the text “SR1”.

Descendant SRRequirements 1/3 The following query part containing 3 segments, Children/Relationship/Requirement , is recursively present in the Data Source Schema. In red is the first appearance of this query part. In green is the second appearance of this query part.

Descendant SRRequirements 2/3 Create a Container in the SRRequirements Paragraph below Image Container; Set name Descendants to Container; Create a Paragraph in Descendants Container. Name the Paragraph Descendant attributes . Set the query Project/Requirements/SRRequirement/Children/Relationship/Requirement to the Descendants Container using the available $1 context: this query will be executed in the context of the $1 query : Project/Requirements/SRRequirement . Use the FullTag attribute of this query, by dragging and dropping it in the Descendant attributes Paragraph.

Descendant SRRequirements 3/3 Recursive Level = 4 How deep the query will go. Recursive Segments = 3 How many segments from query will be used to construct the recursive query. In this case the recursive query part contains segments: Children/Relationship/Requirement Set the Recursion Parameters: Select the Descendants Container. In the Properties view, note the two properties used for Recursion Recursive Level Recursive Segments Set proper values for recursion properties

Preview the Output Document Note the SR of levels 1,2, 3 and 4 are present in the output document.

Traceability Set the Project/Requirements/SRRequirement/TracesFrom/Relationship/RelatedRequirement query to the Related Requirements Container. Use the existing $1 context for the query. Create a Container in the SRRequirements Paragraph. Name the Container Related Requirements .

Traceability Data Sources 1/2 The query Project/Requirements/SRRequirement/TracesFrom/Relationship/RelatedRequirement has a smaller set of attributes than the query Project/Requirements/PRRequirement. In the project used for this tutorial, all the traceability relations ( TracesFrom ) for the SRRequirements come from the PRRequirements . Based on this fact, the PRRequirements Data Source Schema will be used to extract attributes from the related requirements.

Traceability Data Sources 2/2 Differences PRRequirements schema has more attributes for a requirement.

PRRequirement query and attributes 1/4 Create a Container named PRRequirements in the Related Requirements Container. Set the Project/Requirements/PRRequirement query of the PRRequirements Data Source Schema to the PRRequirements Container. Create a Paragraph named PRRequirement attributes in the PRRequirements Container. Use the FullTag attribute of Project/Requirements/PRRequirement query in the PRRequirement attributes Paragraph.

PRRequirement query and attributes 2/4 A Filter is required for the Project/Requirements/PRRequirement query to extract only the related PRRequirements for each SRRequirement . The UniqueID attribute is used in this regard. Create a variable named relatedRequirementID_ : In the Data menu , select New Variable , the New Variable dialog will open. Set the name of the variable. Let the default value internal for Access , because the variable will be used only for calculation in the Template .

PRRequirement query and attributes 3/4 Use Assignment feature to assign to relatedRequirementID_ variable the value of the UniqueID attribute of the query Project/Requirements/SRRequirement/TracesFrom/Relationship/RelatedRequirement . Select the Related Requirements Container, and select Edit Assignments… from the contextual menu. Click Add in the Assignments Editor dialog. Select the relatedRequirementID_ variable and click Ok. The Set Assignments for Current Element dialog will open. Select the UniqueID data item of the Project/Requirements/SRRequirement/TracesFrom/Relationship/RelatedRequirement query. This value will be used to retrieve only relevant PRRequirements .

PRRequirement query and attributes 4/4 Add a Filter for Project/Requirements/PRRequirement query to extract only the related PRRequirements . Select the PRRequirements Container. In the Properties view, In the Data item, open the Filter Editor by clicking on the “Browse” button for the Filter property. A Scripted Filter will be used. Select Variable relatedRequirementID_ Equals operator Select UniqueID attribute of query Project/Requirements/PRRequirement Click Add

Preview the Output Document Note the FullTag value of the PRRequirements

Checkpoint 1. Data Sources Schema 2. Software Requirements query and attributes 3. Descendant Software Requirements 4. Traceability: Product Requirements query 5. Styles and Formatting properties 6. Master Page 7. Title page 8. Configure Document Specification

Improve output document appearance 1/5 Bold can be applied using contextual menu, shortcut keys, or from the Properties view. Create a Text after the FullTag attribute as a separator between the FullTag attribute and Text attribute, and set its content to three empty spaces. Use the Heading 1 Style for the SRRequirements attributes Paragraph: Select the Paragraph; Open contextual menu; Select Style -> Heading Styles -> 1 .

Improve output document appearance 2/5 Create a Container above the Descendants Container. Name it Descendants Title . Create a Paragraph in the Descendants Title Container. Create a Text in the Paragraph. Set Text content “Descendant Requirements”. Move the Descendants Container in the Descendants Title Container below the Paragraph. The condition HasChildren == “true” will be set for the Descendants Title Container to assure that the Container content will be inserted only when descendant requirements exists.

Improve output document appearance 3/5 Create a Container below the Related Requirements Container. Name the Container Traceability . Create a Paragraph in the Traceability Container and create a Text in the Paragraph. Set the Text content to “TracesFrom Requirements”. Move the Related Requirements Container in the Traceability Container below the Paragraph. The condition HasTracesFrom == “true” is set to the Traceability Container to assure that the Container content will be inserted only when traceability requirements exists.

Improve output document appearance 4/5 Heading Style 2 Heading Style 3 Bold and Italic Set styles and formatting properties like in the picture above. Set left indent property of the Descendant attributes Paragraph to a script value having the expression: “parseInt(Level) * 20” to indent the text based of the Requirement Level, where Level is an attribute of the query Project/Requirement/SRRequirement/Children/Relationship/Requirement, Heading Style 2

Improve output document appearance 5/5 To center the Image: Select the Image. In the Properties view set value center for the image alignment property. To center the Figure Caption: Select the Paragraph having as child the Figure Caption; In the Properties view set value center for the paragraph alignment property.

Create Master Page 1/8 To create a Master Page, select the Master Pages item in the Outline , right click to open the contextual menu. Select Insert -> New Master Page … The New Master Page dialog opens. Insert the name of the Master Page. Click Ok. The MPRequirements Master Page is created. The Header and Footer are automatically created for the Master Page.

Create Master Page 2/8 A new tab Master Page: MPRequirements is created in the editor. A new child node Master Page : MRRequirements is created in Outline .

Create Master Page 3/8 Header Create a Table having one Row with two Cells. Create two Paragraphs in the first Cell. Create two Text elements, one in each Paragraph and set theirs content. Create a Text in the second Cell. Footer Create a Paragraph. Create a Text, a Page Number, another Text and a Total Pages Number in the Paragraph. Set the content of the two Text elements.

Create Master Page 4/8 Select the Table from the Header. In the Properties view: Set autofit to window value for the table auto fit property. Set false value for the resize to fit contents property. Select the first Cell of the Table. In the Properties view: Set top left value for the cell alignment property. Set 325 value for the cell width property. Header

Create Master Page 5/8 Footer Select the Paragraph from the Footer. In the Properties view: Set value center for the paragraph alignment property.

Create Master Page 6/8 Data Source Query cannot be used in the Master Pages . It is possible to use an internal variable of which value can be assigned to a specific attribute of a query. The assignment must take place before the variable will be used in Master Page. Create an internal variable named projectName_ . Switch to Master Page editor tab. Drag the projectName_ variable from Outline and drop it in the Text from the second Cell of the Table from Header.

Create Master Page 7/8 Switch back to the Template Content editor tab. Drag the Master Page from Outline and drop it in the area of the SRRequirements Paragraph. Note: the Master Page icon in the Paragraph. Another way of using the Master Page: Select the Paragraph. Using contextual menu, from the Master Page submenu select the suitable Master Page.

Create Master Page 8/8 Select the Template Content tab. Create a Container above the SRRequirements Paragraph in the Template content. Set its name to Project Info . Select the Project Data Source Schema . Set the query Project to the Project Info Container. This query will be the first to be executed. Add an Assignment to the Project Info Container, for the projectName_ variable. Set the value of the Assignment as Name attribute of the Project query.

Create a Title Page Create a Paragraph below the Project Info Container. Name it Title . Set “Title” Style for it. Create a Paragraph inside the Title Paragraph. Set the name of the Paragraph to Generic . In the Properties view, set the value 300 for the before spacing property to place the Generic Paragraph in the middle of the page in the vertical plan. Create a Text inside the Generic Paragraph and set its content to “Software Requirements”. Create another Paragraph below the Generic Paragraph. Set its name to Project name . Drag the projectName_ variable from the Outline and drop it in the Project name Paragraph. Create a Page Break below the Project Paragraph. Create Table of Content below the Page Break. .

Checkpoint 1. Data Sources Schema 2. Software Requirements query and attributes 3. Descendant Software Requirements 4. Traceability: Product Requirements query 5. Styles and Formatting 6. Master Page 7. Title page 8. Configure Document Specification

Running the report Select the Launcher Perspective to be able to: Configure the Data Sources Configure the Microsoft Word Output The Microsoft Word Output Project Data Source SRRequirements Data Source PRRequirements Data Source

Configure Data Sources Select Discover and the REST Resource Discovery wizard will start. The same steps must be performed as for the getting the Data Source Schemas to obtain the proper URL for all three Data Sources. Select the Project Data Source , open contextual menu and Configure Data Source… The Configure REST Data Source dialog will open.

Configure Word Output Select the Output -> Target: Word . Open contextual menu and select Configure Output… The Configure Word Output dialog will open. Select the path of the Word Output Document. Select a Stylesheet : “rpe.dot” Stylesheet Word file comes with the RPE installation. Select a macro : peUpdateFields to update Table of Contents.

Results 1/2 Title Page Table of Contents

Results 2/2 Heading 1 Heading 2 Heading 3 Indentation Figure Caption

More Information RPE Online Help http://publib.boulder.ibm.com/infocenter/rpehelp/v1r1m1/index.jsp RPE Developer Works Forum http:// www.ibm.com/developerworks/forums/forum.jspa?forumID =1512 RPE Community Wiki http:// www.ibm.com/developerworks/wikis/display/rpe/Home RequisitePro http://www-01.ibm.com/software/awdtools/reqpro/support/ RPE Data Services http://publib.builder.ibm.com/infocenter/rpehelp/v1r1m1/topic/com.ibm.rational.pe.install.doc/topics/c_dataservices_deployment.html

Media Channels Reporting Arena on YouTube http://www.youtube.com/ReportingArena Reporting Arena on Twitter http://www.twitter.com/ReportingArena Reporting Arena on Facebook http://www.facebook.com/Reporting-Arena Reporting Arena on LinkedIn http:// www.ibm.com/developerworks/wikis/display/rpe/Home

Rational Publishing Engine and Rational RequisitePro

More Related Content

What's hot

Viewers also liked

Similar to Rational Publishing Engine and Rational RequisitePro

Recently uploaded

Rational Publishing Engine and Rational RequisitePro