The document describes how to use Rational Publishing Engine (RPE) to extract data from a Rational DOORS module and linked modules to generate an output document. It provides steps to: 1) Iterate through objects in a DOORS module and display attributes. 2) Configure an RPE data source to extract data from linked modules. 3) Filter and extract children objects from the linked modules. 4) Use schema discovery to add new attributes and update the schema. 5) Create templates, queries, containers and other elements to display the extracted DOORS data in paragraphs, tables and other structures in the output document.

1. Using Rational Publishing Engine to extract data from Rational DOORS Dan Ani Reporting Arena Team Leader www.reportingarena.com

2. 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.

3. 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.

4. Introduction The goal of this tutorial is to present the basic steps that a user has to perform in order to extract data from a specific DOORS Module, and to follow links to get information from all linked modules. Also in this tutorial the user can find information about DOORS Schema Discovery process, advance filtering using Javascript, fancy Table formatting and some valuable information about defining and using variables in Master Pages.

5. Prerequisites Microsoft Windows XP/Vista/7 Rational Publishing Engine 1.1.1.2 or later Rational DOORS 9.1 or later ( 9.1 is the older version supported by RPE ) Microsoft Word 2003/2007 (to visualize the output document) Basic knowledge of using Rational Publishing Engine Basic knowledge of using Rational DOORS

6. Use Case 1/3 Output Document Description I’m looking to extract all objects from a DOORS Module, for each object to display the Object Text, and Object Heading attributes (if they are not empty). Then I’m looking through all linked objects and I want to get all children of that linked object (if any). The information from the linked module will be display into a Table, and will contain 3 attributes: Absolute Number, Created On and Object Text. Also a Master Page will be created, and in the Header I will display the current chapter, representing the headings from the main module. The template will contain some additional structures like: Table of Contents and Table of Tables and it will have a title page section.

7. Use Case 2/3 Step to obtain the desired Output Document 1. Iterate through all the module objects, and display the Object Text and Object Heading attributes, if they are not empty. [add DOORS schema, create Paragraphs, Containers, set queries, use conditions] 2. Use and configure a Data Source Configuration element to extract data from the linked module [use the Target Full Name attribute of the Module/Object/Link element to reconfigure the DOORS Data Source of the linked module ] 3.Extract all the children of the linked object [use a special filter using Javascript to select only those objects from the linked modules that are children of the linked object] 4. Use schema discovery process to add a new object attribute to the schema [add the Created On attribute to DOORS Schema, using Schema Discovery process]

8. Use Case 3/3 5. Create a Table element to display 3 attributes for the objects from the linked module [create a Table element, drag specific attributes, use specific conditions and formatting to display the Table in a fancy manner] 6. Create a Master Page with Header and Footer [in Header display the current chapter (current level 1 heading from the main module), and in the Footer display the page number sequence] 7. Add additional template structures like: Table of Contents and Table of Tables 8. Create the first page [add document title, author, and specific first page formatting] 9. Document Specification will be configured to extract the desired data and to generate the output document for Microsoft Word. [use the System Requirements module, from the demo DOORS project with minor modifications]

9. Desired Output Document Header section: on left side: static text on right side: current chapter Font-family: Arial 10 Main Module Objects (Object Heading and Object Text) Linked Object (use left indentation: 50) Linked Object Children display a Table with 3 columns header (background-color: #C0C0C0) use left indent: 50 Footer section Page Number / Total Pages Number font family: Arial 10

10. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

11. Add a DOORS Data Source 1/2 The first step is to open the Rational Publishing Engine in Studio perspective. Go to File menu, and select New->Document Template To extract information from DOORS we need to have in our template a proper Data Source schema. Add a DOORS Data Source schema using the Data Source Schemas entry from the Outline view. Right click, and select Insert->Data Source Schema…

12. Add a DOORS Data Source 2/2 In the Add Data Source Schema wizard, on the second page, select the default DOORS schema, using schema type DOORS , and as Data Source ID type : “MAIN_MODULE” Click Finish to insert the DOORS Data Source Schema into the template.

13. Set Module/Object Query Create a Container: Select the Container element in the Palette view and click in the desired location in the Template Content Editor. Set the Module/Object query [$1] to the Container: Drag the desired query from the Data Source Schemas view and drop it on the Container. NOTE: It’s recommended to use the Container element when you want to iterate a collection of elements. The Container element will not add extra empty Paragraphs.

14. Display Object attributes Create two Paragraphs and add them to the Container. Expand the Object element from the DOORS Data Source schema; drag Object Heading attribute into the first Paragraph, and Object Text into the second Paragraph. In this moment in our template we iterate through all module objects, and display for each object two attributes, each one in a separate Paragraph.

15. Display only non empty attributes 1/3 In order to only display non empty attributes, we will create two conditions, one for each Paragraph. To filter the non empty Object Heading attributes, select the first Paragraph, right click and select Data->Edit Condition… The Set Condition for Current Element editor will open.

16. Display only non empty attributes 2/3 There are two ways to create script conditions using this editor: 1) Use embedded operations (right part) to create simple conditions. 2) Drag the operands from the left side and create complex conditions using javascript language. NOTE: Each time it’s recommended to test your condition using the Test Script Expression Dialog, by pressing the Test button.

17. Display only non empty attributes 3/3 To filter Object Heading attributes the condition will be: Object_Heading != “” The process to create the condition for the second attribute will be similar The script expression is: Object_Text != “” NOTE: For safety, save the document template from time to time.

18. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

19. Insert Data Source Configuration element 1/4 To get data from a linked module we need to obtain the necessary information to configure that DOORS Data Source. Create a new Container and set the Module/Object/Link query [$2] on it. This query should be in the context of $1. We want to follow only the In Links , so we need to use a native filter . Select the newly created Container, and go to Properties view, Data->Filter property and open the Filter Editor . Choose the Native Filter tab, and insert the “Link direction in” text. NOTE: Read more about DOORS native filters on RPE Help

20. Insert Data Source Configuration element 2/4 Create a new Container into the last one. Set the Module/Object/Link/Linked Object query [$3] on this Container. Set this query in the context of $2 query. Insert a Data Source Configuration element at the same level with the last created Container In order to configure this last element we have to add a new DOORS Data Source schema into the template. Insert a new DOORS Data Source schema, and set its name to be: LINKED_MODULE Now in the template we will have two DOORS Data Sources. One for the Main Module, and one for the Linked Module

21. Insert Data Source Configuration element 3/4 Go to Outline view. Expand Data Source Schemas node, select LINKED_MODULE Data Source Schema and drag it into the Data Source Configuration element from the template. Drag Data Source Schema into the Data Source Configuration element

22. Insert Data Source Configuration element 4/4 All we have to do now, is to properly configure this second DOORS Data Source. A DOORS Data Source can be configured either using Module URI or Module ID properties. In our case, we will configure the DOORS Data Source using the Module URI. Steps to configure: Select the Data Source Configuration element Go to Properties view and select the Formatting->dynamic configuration->URI property. Open the Set URI value dialog, using the Browse button Select the Source Full Name attribute of $2 – Module/Object/Link query This attribute contains the URI of the Linked Module Press OK button, and we have a properly configured DOORS Data Source

23. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

24. Insert all necessary queries to extract the linked object children Create a new Container, below the Data Source Configuration element. Drag from LINKED_MODULE Data Source, Module/Object query [$4], and drop it to the Container. In this Container create a new Container element. This Container will be used to filter only the children of the linked object from the linked module. Set the name of this Container: LINKED_OBJECT_CHILDREN Create a new Paragraph inside the last created Container, and drag the Object Heading attribute. The attribute is in the context of $4 query from the LINKED_MODULE Data Source. NOTE: Use the Zoom Editor if you want to zoom on a specific element from the template.

25. Use internal variables and conditions to filter only the children objects 1/4 Create an internal variable named _ linked_object_heading to store the value of Heading Number attribute of the linked object Go to Outline View Select Variables node Use contextual menu on this node, and select Insert->New Variable … Variable name should be unique Insert a variable description (for external variables) NOTE: Set appropriates names to variables. As a best practice, internal variables should start with _ Set a default value for current variable Select variable type

26. Use internal variables and conditions to filter only the children objects 2/4 Steps to perform the filter: Use the Container with $3 query on it to assign variables. Use Assign Variable mechanism to store the Heading Number value of the linked object Use contextual menu from the Container, and select Data->Edit Assignments option. The Assignments Editor will open. Add _linked_object_heading variable Switch to Data Expression tab and select the Heading Number attribute of the $3 query.

27. Use internal variables and conditions to filter only the children objects 3/4 When we pass through all the linked module objects, we will select only those objects (children) that have the Heading Number attribute starting with the value of _ linked_object_heading. Create a condition on LINKED_OBJECT_CHILDREN Container, and use the value of the internal variable. Use the drag & drop features of the editor to create the condition. All the script expressions are javascript expressions.

28. Use internal variables and conditions to filter only the children objects 4/4 Add another condition to display Object Heading attribute just when this is not empty The script expression will be: Object_Heading!=“” In this moment the template content should look like this:

29. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

30. Use DOORS Schema Discovery to add a new object attribute 1/2 For each child object we want to display a Table with 3 Cells. In each Cell a different attribute will be displayed. The 3 attributes are: Absolute Number , Object Text and Created On . If the first two attributes are already in the default DOORS schema, for the third attribute [ Created On ] , we have to use the DOORS Schema Discovery process to improve (update) the schema. In the Outline view, select the LINKED_MODULE Data Source, use the contextual menu and select Edit Using Schema Discovery…. DOORS Schema Discovery Wizard will start.

31. Use DOORS Schema Discovery to add a new object attribute 2/2 Select the DOORS connection type (using existing DOORS instance/ new DOORS instance) Select a module (in this tutorial the System requirements module, from the rpe_demo project is used) Select the Current baseline Check the Created On – object attribute Go to the end of the wizard and press Finish. The old DOORS schema will be replaced by the new updated one.

32. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

33. Create a Table to display child object attributes 1/2 To display these attributes, create a Table element, with 2 Rows and 3 Cells. The first Row will be the Table Header, and the second one the Table Content. Insert this Table into the LINKED_OBJECT_CHILDREN Container, below the Paragraph. Now in the LINKED_MODULE schema we have all the requested attributes: Absolute Number, Object Text and Created On

34. Create a Table to display child object attributes 2/2 Table Header – all Cells contain only static text In the second Row – Table Content First Cell: Absolute Number attribute Second Cell: Created On attribute Third Cell: Object Text attribute

35. Display Table only if objects have text We have to create a condition, to filter only those objects with Object Text attribute non empty. Add a condition on Table element. Using the Set Condition for Current Element editor from the right side, create the condition: Object_Text!=“”

36. Add condition to display the Table Header only once Create a condition to determine if the Table Header (first Row) was already printed. If so, we will not display this Row again. Create an internal variable _firstRowWasPrinted . This variable value will be false only the first time when the Table is displayed. Create a Container below Data Source Configuration element. Use this Container to assign the _firstRowWasPrinted value to false Create a special Container inside de Table element and drag the first Row into this Container. On this Container we will add our condition, to check if the Row was already printed. Create another Container element below the special Container, and use it to assign the _firstRowWasPrinted variable to true

37. Advanced Table formatting 1/3 Create a new style for Header Cells Go to Outline view, right click on Styles node, and select Insert->New Style… option. New Style Wizard will open Set the style name: CellHeaderStyle In the Select Style Properties page, select the Cell element, and add it to the result list. Go to the last page and press Finish . The style will be added into the Styles node .

38. Advanced Table formatting 2/3 Configure CellHeaderStyle style Select the style in the Outline view Go to Properties view Set cell->font->bold to true Set cell->color->cell background color to C0C0C0 Drag the newly created style from the Outline view on each Cell from the first Row (Header) Set Cell dimensions on both Rows: First Cell: 100 Second Cell: 100

39. Advanced Table formatting 3/3 Select Table element Set Formatting->Specific->auto fit to autofit to window Set Formatting->Specific->resize to fit contents to false Indent all child content In LINKED_OBJECT_CHILDREN Container select the Paragraph, and in the Properties view, set Formatting->Indentation->left indent to 50 In the same Container select Table element, and set Formatting->positioning->left indent to 50

40. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

41. Create Master Page 1/7 Create a Master Page (ContentMP) To create a new Master Page in RPE go to Outline view, select Master Pages node, and choose Insert->New Master Page… Use this Master Page to present the content Master Page Name – should be unique Optional: A short description of this Master Page Master Page Orientation Size empty – default paper size (In Word A4) NOTE: In a template could be more than 1 Master Page elements. For each Master Page a new editor will be created

42. Create Master Page 2/7 Define Header section 1. Create a Table having one Row with two Cells 2. Create in the first Cell a Text element with static content (“ Reporting Arena” ). 3. In the second Cell create a Text (with no value for the moment) 3.1 The second Cell will contain the current heading of level 1 from DOORS Main Module Level 1 Heading

43. Create Master Page 3/7 Define Header section 4. Create an internal variable (_currentHeading) and store the value of current Object Heading of level 1 into this variable. 5. Double click on the Text from the second Cell, use the Data Expression tab, and select _currentHeading variable. NOTE: The only way to add dynamic content into the Header or Footer sections it’s to use variables.

44. Create Master Page 4/7 Define Header section 6. Go back to Template Editor to assign the proper value for the _currentHeading variable 7. Create a Container as a first element of the main Container. 8. Use this Container to assign the value of _currentHeading variable 9. Use contextual menu, select Assign Variables and Script Expression tab 10. Use level attribute and Object_Heading attribute to construct the expression

45. Create Master Page 5/7 Format Header section table auto fit – autofit to window resize to fit contents - false cell width – 200 Table cell borders cell alignment – center right resize to fit contents - false

46. Create Master Page 6/7 Define Footer section Create a Paragraph into the Footer In order to display in Footer Page page nr. Of total pages number structure we have to do: Create a Text having “Page “ text as content Create Page Number element Create a Text having the content the text “ of ” Create Total Pages Number element

47. Create Master Page 7/7 Set font style in Header and Footer Select Header element, and in Properties view go to Formatting->font node set font size to 10 set font family to Arial 2. Add the same formatting information to Footer element.

48. Use Master Page Drag the Master Page element from the Outline and drop it in the area of the Paragraph containing the attribute Module/Object/Object Heading . To view a different chapter in Master Page, we have to force the Master Page to change, each time when a Object Heading of level 1 is displayed. Select the Paragraph with the Master Page, and in the Properties view go to Formatting->common->force page change. Create a script expression, to change the page when the object level is “1”

49. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

50. Add Table of Contents Create ToC Create a Container as the first template element. Create a Paragraph element into this Container Create a Text having as content the text “Table of Contents” into the Paragraph set Paragraph property font-size : “24” 4. Create a Table of Contents element below the Paragraph NOTE: After document generation is finished on WORD, in case you are not using some special macros, to see the Table of Contents , select all the content, right click, and choose “Update Field”.

51. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

52. Add Title Page Create a Container before ToC Container. Set the name to be: “Title Page” To have the Title Page on a separate page, create a Page Break element between the title Container and the ToC Container. Create 3 Paragraphs into the Title Page Container In the first one create a Text having the static text “Extract all System Requirements” as content. In the second one display the author name For this we have to create an external variable (author), to set at runtime the name of the author. 6. In the third one, use a script expression to display current Date.

53. Format Title Page First Paragraph set “Title” style (drag from Styles node) set spacing->before spacing : “200” Second Paragraph set spacing->before spacing : “50” set alignment->paragraph alignment : “right” Third Paragraph set alignment->paragraph alignment : “right”

54. Final Template 1/2 Intro Part

55. Final Template 2/2 Content Part

56. Checkpoint 1. Iterate through all the module objects and display some attributes 2. Use a Data Source Configuration element to extract data from the linked module 3. Extract all the children of the linked object 4. Use Schema Discovery process to update schema 5. Display the children objects attributes into a Table 6. Create a Master Page with Header and Footer 7. Add ToC and ToT elements 8. Title page 9. Configure Document Specification

57. Running the report Select the Launcher Perspective to be able to: Configure the Data Sources Configure the Microsoft Word Output The Microsoft Word Output Main Module – DOORS Data Source Author name – external variable RPE Template

58. Configure Data Sources 1/4 This tutorial uses DOORS rpe_demo project as data content. Please download and restore this project into your DOORS database. Inside this project there are 2 DOORS Formal Modules. One is the System requirements and the other one is the module containing all the linked objects ( Car user reqst ). In real word scenarios it could be more then 1 linked modules.

59. Configure Data Sources 2/4 Select the MAIN_MODULE Source , open contextual menu and Configure Data Source… Use Data Source Selection Wizard to select the System requirements module

60. Configure Data Sources 3/4 Use a running DOORS instance When a DOORS Data Source is present in a document template, there are two ways to configure that Data Source: using a running DOORS instance or using a new DOORS instance. In the first scenario (using existing DOORS instance) all we have to provide is the module URI, baseline and view [optional] and to set the property new_instance to false

61. Configure Data Sources 4/4 Use a new DOORS instance The DOORS connection information, such as the username, password, and the properties, doors_home, doors_param and new_instance need to be provided if we want to use a new DOORS Instance to extract data. In this scenario, the property new_instance should be set to “true”. In both scenarios, the LINKED_MODULE Data Source will not be configured, because this Data Source is a dynamic Data Source and will be configured/re-configured during the generation process.

62. 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.

63. Results 1/2 Title Page Table of Contents

64. Results 2/2 Content Page Main Module Object Linked Object Table with all linked object children Footer Section (page number / total pages number) Header: Chapter Name

65. More Information RPE Online Help http://publib.boulder.ibm.com/infocenter/rsdp/v1r0m0/index.jsp?topic=/com.ibm.help.download.tpe.doc/topics/publishingengine_version1_1.html 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 Rational DOORS http://www-947.ibm.com/support/entry/portal/ Overview/Software/Rational/Rational_DOORS

66. 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