BMC Remedy Action Request System Using a BIRT Editor to Create or Modify Web Reports

Transcription

1 White Paper BMC Remedy Action Request System Using a BIRT Editor to Create or Modify Web Reports September

2 Contacting BMC Software You can access the BMC Software website at From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities. United States and Canada Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX USA Outside United States and Canada Telephone or Telephone (01) Fax (01) Fax If you have comments or suggestions about this documentation, contact Information Development by at Copyright 2012 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. IBM, DB2, and AIX are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Linux is the registered trademark of Linus Torvalds. UNIX is the registered trademark of The Open Group in the US and other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation. Restricted Rights Legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section , DFARS , DFARS , DFARS , and DFARS , as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX , USA. Any contract notices should be sent to this address.

3 Customer Support You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or . To expedite your inquiry, please see Before Contacting BMC Software. Support Website You can obtain technical support from BMC Software 24 hours a day, 7 days a week at From this website, you can Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including addresses, fax numbers, and telephone numbers. Support by telephone or In the United States and Canada, if you need technical support and do not have access to the Web, call or send an message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance. Before Contacting BMC Software Have the following information available so that Customer Support can begin working on your issue immediately: Product information Product name Product version (release number) License number and password (trial or permanent) Operating system and environment information Machine type Operating system type, version, and service pack System hardware configuration Serial numbers Related software (database, application, and communication) including type, version, and service pack or maintenance level Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) Product error messages Messages from the operating system, such as file system full Messages from related software

4

5 White Paper Using a BIRT Editor to Create or Modify Web Reports This white paper explains how to use BIRT TM reporting tools with BMC Remedy Action Request System Web reports. BIRT is an open source, Eclipse-based reporting system. Using Web reports and the BIRT Report Designer, you can: Create reports based on BMC Remedy AR System data in the BIRT Report Designer, and then deploy those reports to the AR System server using the Report form. Modify out-of-the-box Web reports in the BIRT Report Designer, and deploy those reports to the AR System server using the Report form. IMPORTANT This white paper is intended for administrators with expertise using BMC Remedy AR System Web reports and the BIRT Report Designer. This white paper is only intended to document what is specific or different to modify reports for BMC Remedy AR System. For information and tutorials about using the BIRT Report Designer, choose Help > Help Contents in the BIRT Report Designer. For additional information about the BIRT Report Designer, see For information about Web reports, see the BMC Remedy Mid Tier Guide. This white paper guides you through the following process: Step 1 Install the BIRT Report Designer to work with Web reports Step 2 Enable BIRT to access your BMC Remedy AR System data by setting resource and templates preferences in the BIRT Report Designer Step 3 Create or modify reports with the BIRT Report Designer Step 4 Deploy BIRT reports to the AR System server using the Report form Using a BIRT Editor to Create or Modify Web Reports 5

6 White Paper This white paper discusses the following sections: Installing the BIRT Report Designer to work with AR System Web reports (page 6) Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences (page 7) Creating a new report with the BIRT Report Designer (page 10) Modifying an out-of-the-box Web report with the BIRT Report Designer (page 18) Deploying BIRT reports to the AR System server using the Report form (page 23) Examples for modifying reports with the BIRT Report Designer (page 27) Installing the BIRT Report Designer to work with AR System Web reports Before you can modify or create reports using the BIRT Report Designer, you must perform the following high-level steps: Step 1 Download version the BIRT Report Designer. Step 2 Copy three BMC Remedy AR System plug-ins into their proper location. Step 3 Specify the BIRT library and template location in the BIRT Report Designer. NOTE For information about system requirements for the BIRT Report Designer, see the Eclipse documentation. To download and open the BIRT Report Designer 1 Download the BIRT Report Designer zip file: R-R1-2_5_ /birt-rcp-report-designer-2_5_1.zip NOTE The BIRT Report Designer is a 32-bit application, and requires a 32-bit Java installation. 2 Extract the BIRT Report Designer zip file to a destination directory (BIRTInstallDir). 3 To open the BIRT Report Designer application, click the BIRT.exe executable file. 6 Using a BIRT Editor to Create or Modify Web Reports

7 Using a BIRT Editor to Create or Modify Web Reports To copy BMC Remedy AR System plug-ins for use with BIRT 1 Go to BIRTInstallDir, and create in it a plugins subdirectory. 2 Copy and paste the following plug-ins from your BMC Remedy AR Server Mid Tier plugins directory (MidTierInstallDir/WEB-INF/platform/plugins) to BIRTInstallDir/plugins: com.bmc.arsys.oda.designtime_7.6.4.nnnnnnnn.jar com.bmc.arsys.oda.runtime_7.6.4.nnnnnnnn.jar com.bmc.arsys.studio.api_7.6.4.nnnnnnnn.jar 3 In the BIRTInstallDir directory, launch BIRT.exe. The BIRT Report Designer application opens. Now, proceed to Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences on page 7. Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences Before you can create new BIRT reports or export and import.rptdesign files, you must first download and extract resource and template zip files from the AR System Resource Definitions form, and then configure resource and template preferences in the BIRT Report Designer. The Resource library files contain resource files for localized labels that you use for new labels to add to a report. The BIRT library files contain the BIRT library (for example, stylesheets) and out-ofthe-box templates that you can use as you modify out-of-the-box reports or when you create new BIRT reports. To specify the BIRT library and template location in the BIRT Report Designer 1 To open the AR System Resource Definitions form, type the following URL into your browser: System Resource Definitions 2 In the Type field, select BIRT Library, and then click Search. Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences 7

8 White Paper Figure 1-1: AR System Resource Definitions form 3 In the search results, select BIRT Resource File. 4 In the Resource section, select the Resources.zip file, and click Save to Disk. Figure 1-2: AR System Resource Definitions form 5 Go to BIRTInstallDir, and create a Library subdirectory. 6 Copy the Resources.zip file to the BIRTInstallDir/Library directory. 7 In the search results, select BIRT Report Library. 8 In the Resource section, select the BIRT_Library.zip file, and click Save to Disk. 8 Using a BIRT Editor to Create or Modify Web Reports

9 Using a BIRT Editor to Create or Modify Web Reports 9 Copy the BIRT_Library.zip file to the BIRTInstallDir/Library directory. 10 Create a Resources subdirectory in the BIRTInstallDir/Library directory. 11 Extract the BIRT_Library.zip file into the BIRTInstallDir/Library/Resources directory. This creates the BIRTInstallDir/Library/Resources/Images and BIRTInstallDir/ Library/Resources/Templates directories. This also places the DateParameter.js and bmc_library.rptlibrary files in the BIRTInstallDir/Library/Resources directory. 12 Extract the Resources.zip file into the BIRTInstallDir/Library/Resources directory. This creates the BIRTInstallDir/Library/Resources/Resources directory with *.properties files as content. 13 Open the BIRTInstallDir/Library/Resources directory, and copy its path. For example: BIRTInstallDir/Library/Resources 14 In the BIRT Report Designer, choose Windows > Preferences. 15 In the Preferences box, choose Report Design > Resources, and copy the path for the Resources directory into the Resources folder field, and then click OK. Figure 1-3: Resource panel for Preferences in the BIRT Report Designer 16 Open the BIRTInstallDir/Library/Resources/Templates directory, and copy its path. 17 In the BIRT Report Designer, choose Windows > Preferences. Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences 9

10 White Paper 18 In the Preferences box, choose Report Design > Templates, and copy the path for the Templates directory into the Template folder field, and then click OK. Figure 1-4: Template panel for Preferences in the BIRT Report Designer You can now do the following tasks: Creating a new report with the BIRT Report Designer on page 10 Modifying an out-of-the-box Web report with the BIRT Report Designer on page 18 Creating a new report with the BIRT Report Designer After installing BIRT, you can start creating new reports in the BIRT Report Designer. Perform the following workflow to create a new report in the BIRT Report Designer: Create a new report file in the BIRT Report Designer (page 11) Add a data source for the new report (page 11) Add a data set for the new report (page 13) Preview and save the new report (page 17) 10 Using a BIRT Editor to Create or Modify Web Reports

11 Using a BIRT Editor to Create or Modify Web Reports To create a new report with the BIRT Report Designer 1 In the BIRT Report Designer, choose File > New > New Report. 2 Enter a file name. Use the default file location or browse to a different file location. a If you want to use a blank report template, click Finish. b If you want to select a report template, click Next, select a report template, then click Finish. The new report appears in the Layout editor pane of the BIRT Report Designer. Figure 1-5: New report in the BIRT Report Designer To enable data access for a BIRT report by creating a data source Before creating new BIRT reports, you must build a BIRT data source to connect a BIRT report to a data source, such as an AR System database. A BIRT data source allows you to access data for a BIRT report. 1 In the BIRT Report Designer, go to the Data Explorer tab, right-click Data Sources, and select New Data Source from the submenu. Creating a new report with the BIRT Report Designer 11

12 White Paper Figure 1-6: Data Explorer pane NOTE If the Data Explorer tab is not open, choose Window > Show View > Data Explorer. 2 In the New Data Source box, make sure Create from a data source type in the follow list (default) and BMC Remedy AR System ODA Data Source (default) are selected, and then click Next. Figure 1-7: New Data Source box 12 Using a BIRT Editor to Create or Modify Web Reports

13 Using a BIRT Editor to Create or Modify Web Reports NOTE If BMC Remedy AR System ODA Data Source does not appear as a selection in the New Data Source box, make sure the correct BMC Remedy AR System plugin files were copied to the BIRT install directory. For more information, see To copy BMC Remedy AR System plug-ins for use with BIRT on page 7. 3 In the New BMC Remedy AR System Designtime Data Source Profile box, enter the User Name and Server for the AR System server data source. Figure 1-8: New BMC Remedy AR System Designtime Data Source Profile 4 Click Test Connection. a If the Ping succeeded! message appears, continue to the next step. b If the Ping failed! error message appears, review the details, correct the data source information, and then test the connection again until you are successful. 5 Click Finish, and then click OK to close the box. To define the data available in a report by creating a data set After creating a new report, you must build a data set to configure the data to extract from data source. The data set defines all data that is available to the report. For example, the data set configuration determines which fields are displayed in the report. NOTE You must create a BIRT data source before you build a data set. For details, see To enable data access for a BIRT report by creating a data source on page 11. Creating a new report with the BIRT Report Designer 13

14 White Paper 1 In the BIRT Report Designer, go to the Data Explorer tab, right-click Data Sets, and select New Data Set from the submenu. 2 Configure the New Data Set box by doing the following tasks: a Enter the Data Set Name. For example, Incident Data Set. b Under the Data Source node, select the data source, and then click Next. For example, select a data source previously created for this report. Figure 1-9: New Data Set box 3 Configure the Query box by doing the following tasks: a Select a form from the Form list. 14 Using a BIRT Editor to Create or Modify Web Reports

15 Using a BIRT Editor to Create or Modify Web Reports Figure 1-10: Query box b Click Add. The Available Fields box displays all fields in the selected form. Creating a new report with the BIRT Report Designer 15

16 White Paper Figure 1-11: Available fields box c Select the fields you want to include in the report, and then click OK. You can select multiple fields by holding down Shift or Ctrl keys. d In the Qualification field, enter the criteria to be used for the query, click Verify, and then click Finish. Enter the qualification using the format 'field' operator "Parameter". For example, 'Status'!="Closed" for the incidents that are not closed. e Click Finish. NOTE BMC recommends using query for a data set instead of filters. Data set filters are applied to the entire result set, and can impair performance. Use the qualification in the query configuration to filter data. 4 If you want to change a column label in a report (for example, change the Short Description column heading to Description), configure the Output Columns box by doing the following tasks: For example, you can change the Short Description column heading to Description. a Select the output column you want to edit. b In the Display Name field, change the column label. 16 Using a BIRT Editor to Create or Modify Web Reports

17 Using a BIRT Editor to Create or Modify Web Reports Figure 1-12: Edit Output Columns box c Click OK. NOTE For a description of the parameters that can be configured in the Data Set editor, see the BIRT online help. To preview and save a new BIRT report 1 In the Edit Data Set box, preview the data for the new report by clicking Preview Results in the left navigation area, and then click OK. The data that fills in the criteria of the data set appears in the right pane of the Edit Data Set box. Figure 1-13: Preview Results in Edit Data Set Creating a new report with the BIRT Report Designer 17

18 White Paper 2 Save the new BIRT report by choosing File > Save As, and then enter a meaningful file name in the File name field. 3 Click Finish. NOTE To deploy the newly created BIRT report to the AR System server using the Report form, see To import the.rptdesign file from the BIRT Report Designer to the Report form on page 21 and Deploying BIRT reports to the AR System server using the Report form on page 23. Modifying an out-of-the-box Web report with the BIRT Report Designer This section explains how you can export the.rptdesign file of a Web report from the Report form, modify the report in the BIRT Report Designer, and then import the modified.rptdesign file back to the AR System server using the Report form. IMPORTANT Before modifying an out-of-the-box Web report with BIRT, BMC recommends saving a copy of the report definition file (.rptdesign file) and its corresponding record in the Report form. To make sure that future upgrades do not overwrite your modified Web report, set Status to Pending or Inactive. You can also import your original exported Web report (.rptdesign file) to a different AR System server. For details, see Importing a Web report to a different AR System server on page 22. To export a.rptdesign file from the Report form to the BIRT Report Designer 1 To open the Report form, type the following URL into your browser: 2 Search for an out-of-the-box Web report that you want to edit, and select the report from the search results. 3 In the Instance ID field, copy the Instance ID value of the report you want to edit. 18 Using a BIRT Editor to Create or Modify Web Reports

19 Using a BIRT Editor to Create or Modify Web Reports Figure 1-14: Copying the Instance ID in the Report form 4 Open the Report Definition form, paste the Instance ID you copied in the previous step from the Report form into the Report Definition GUID field, and then click Search. 5 In the search result, right-click the attached.rptdesign file, and then click Save. 6 Save the.rptdesign file to a folder where you store reports. Modifying an out-of-the-box Web report with the BIRT Report Designer 19

20 White Paper Figure 1-15: Saving the report file in the Report Definition form To modify an imported report in the BIRT Report Designer NOTE Make sure the Report Definition GUID does not change during editing. If the GUID of the report definition changes, the GUID will not be associated with the correct report. 1 In the BIRT report tool, choose File > Open File, and open the.rptdesign file you exported from the Report form. 2 Edit the report using the BIRT Report Designer, and then Save the edited file. NOTE For details about modifying reports with the BIRT Report Designer, such as adding a row or column, see the BIRT Report Designer help. Modifying reports with BIRT Report Designer is discussed further in Examples for modifying reports with the BIRT Report Designer on page Using a BIRT Editor to Create or Modify Web Reports

21 Using a BIRT Editor to Create or Modify Web Reports To import the.rptdesign file from the BIRT Report Designer to the Report form 1 In the Report Console, open the Report form, and search for the same Web report you retrieved in step 3 on page In the Report Definition File area, right-click the.rptdesign file, and click Add. Figure 1-16: Adding a file in the Report form 3 In the Confirm Save Request window, click Yes. Figure 1-17: Confirm Save Request window 4 In the Add Attachment window, click Choose File, then browse and select the.rptdesign file you edited in the BIRT Report Designer, and click OK. Modifying an out-of-the-box Web report with the BIRT Report Designer 21

22 White Paper Figure 1-18: Add Attachment window Modifying an out-of-the-box ITSM report Modifying an out-of-the-box ITSM application report is similar to modifying a Web report. For example, an existing Print Incident report can be modified to add an additional Work Detail field by doing the following procedure. To modify an out-of-the-box ITSM application report 1 Follow the same procedure as Modifying an out-of-the-box Web report with the BIRT Report Designer on page 18, with the following exceptions: a When you search for an out-of-the-box report in the Report form, select the Print Incident report. b In the BIRT Report Designer, open the Print Incident report. c Right-click the data set, choose Edit > Query > Add, and select Work Detail in the Available Fields box. d Import the report back into an AR System server. Importing a Web report to a different AR System server This section explains how to export a Web report and then import it to a different AR System server. NOTE BMC recommends the process in this section instead of the one detailed in Modifying an out-of-the-box Web report with the BIRT Report Designer on page Using a BIRT Editor to Create or Modify Web Reports

23 Using a BIRT Editor to Create or Modify Web Reports To import a Web report to a different AR System server 1 In the Report form, select the Web report that you want to export. 2 Export the Web report to an.arx file. The report attachment will be part of this.arx file. 3 Import the.arx file to the target AR System server using the BMC Remedy Data Import Tool. To make sure that duplicate report entries are not created in the target AR System, import the report file using the following fields as key fields: Report Set Name, Locale, and Report Type. This is a concern when a report has been modified and a fixed report is being moved. Deploying BIRT reports to the AR System server using the Report form The reports you create or modify in the BIRT Report Designer must have a record in the Report form in order to be available in the Report Console. Creating a record for your report in the Report form includes: Storing the.rptdesign file Configuring how the report is filtered by the Category menu in the Report Console Before you start, determine where in the Category menu hierarchy you want the report to appear. As shown in Figure 1-19, this affects how you complete the Category 1 (for example, Incident), Category 2 (for example, Open Incidents), and Category 3 (for example, Count by Assignee Group) fields in step 3 on page 24. You can complete up to three Category fields, or you can create your own categories, using the Category fields. Figure 1-19: Category menu in the Report Console Deploying BIRT reports to the AR System server using the Report form 23

24 White Paper To deploy a report to the AR System server using the Report form 1 To open the Report form, type the following URL into your browser: 2 In the Report form, click New Request to create a record for the report. 3 Complete the required fields of the form and the Category fields. Enter unique, meaningful names for the Report Name and Report Set Name. Figure 1-20: New request in Report form 4 Attach the report definition file for the report to the request by doing the following: a Click Add. b Attach the.rptdesign file for the report. c Click OK. Figure 1-21: Attaching the.rptdesign file to a new request in Report form 24 Using a BIRT Editor to Create or Modify Web Reports

25 Using a BIRT Editor to Create or Modify Web Reports 5 Click Save, and then search for the report you just saved. 6 Copy the Instance ID of the report. Figure 1-22: Instance ID of the report in the Report form 7 To open the Report Definition form, type the following URL into your browser: Definition 8 In the Report Definition form, paste the Instance ID you copied for the report in the Report form into the Report Definition GUID field. Figure 1-23: Report Definition GUID field in the Report Definition form 9 Click Search. The search results show the report design file for the report you are deploying to the AR System server using the Report form. Deploying BIRT reports to the AR System server using the Report form 25

26 White Paper Figure 1-24: Report Definition form with file attachments 10 Go to the Report Console, and refresh the browser. 11 In the Category menu, locate the report you deployed. Figure 1-25: Category menu in the Report Console 12 Click the report to open it, and run the report. Figure 1-26: Deployed report in the Report Console 26 Using a BIRT Editor to Create or Modify Web Reports

27 Using a BIRT Editor to Create or Modify Web Reports Examples for modifying reports with the BIRT Report Designer This section provides example scenarios for modifying reports in the BIRT Report Designer. NOTE The procedures in this section are also discussed in the BIRT Report Designer online help. This section discusses the following topics: Applying styles to customize report appearance (page 27) Sorting and grouping results by a parameter to organize random results (page 31) Adding a column to report results (page 36) Adding a parameter to filter report results (page 37) Editing a Parameter box field to filter report results (page 39) Using subreports to link reports together (page 42) Using dynamic drill down reports to provide a series of detailed reports (page 44) Converting a currency type with a computed column (page 52) Displaying Status History data in the body of a report (page 54) Grouping results in multiple groups by using grids (page 54) Using a stacked bar chart to compare different series of results (page 60) Applying styles to customize report appearance This example explains how to customize the appearance of a new report by doing the following tasks: Modify the style elements of the report Edit the table header of the report To apply table styles to a report 1 Open the file of a report in the BIRT Report Designer by choosing File > Open File, and then selecting the file. The report opens in the Layout tab of the layout editor. 2 In the Data Explorer tab, right-click a data set under the Data Sets node, and drag and drop it into the layout editor. Examples for modifying reports with the BIRT Report Designer 27

28 White Paper Figure 1-27: Data set element dragged into layout editor in the BIRT Report Designer Data set in Data Explorer tab Same data set dragged into layout editor After you drop the data set into the layout editor, the table is automatically created with the fields you selected for the data set. Figure 1-28: Table for an unformatted report 3 In the bottom left corner of the table, click the Table icon. The icons for other parts of table appear on the left, such as Table-Header, Table-Detail, and Table-Footer. 28 Using a BIRT Editor to Create or Modify Web Reports

29 Using a BIRT Editor to Create or Modify Web Reports Figure 1-29: Table icon and table element icons 4 Right-click the icon of the report element to which you want to apply a style, then choose Style > Apply Style, and select a style appropriate for the report element. For example, apply the bmcreporttheme:tableheader theme to the Table-Header. Figure 1-30: Selecting a style 5 Save the report. 6 Preview the report by choosing Run > View Report > In Web Viewer. Examples for modifying reports with the BIRT Report Designer 29

30 White Paper Figure 1-31: Previewing a report To rename the report header 1 In the Layout tab of the layout editor, right-click the report header, then choose Edit. Figure 1-32: Layout editor 2 Type the updated title of the report. Figure 1-33: Layout editor 30 Using a BIRT Editor to Create or Modify Web Reports

31 Using a BIRT Editor to Create or Modify Web Reports 3 Click Save. Sorting and grouping results by a parameter to organize random results To sort results by a parameter If the results of a report are random, this procedure helps you sort or reorder the data by a parameter. Using the parameters used in the previous example, this example sorts the results in the far left column by Status. 1 With the report open in the Layout tab of the layout editor, go to the Data Explorer tab and double-click a data set under the Data Sets node. 2 In the Edit Data Set box, click the Sorting tab. Figure 1-34: Edit Data Set - Sorting tab Sorting tab 3 Click Add to open the Available Fields box. Figure 1-35: Available fields box Examples for modifying reports with the BIRT Report Designer 31

32 White Paper 4 In the Available Fields box, select the fields you want to sort by in the report, and then click OK. For example, select the Status and Assignee Groups fields. 5 Preview the report to make sure the report is sorted by the parameter you added to the Sorting tab. a Save the report. b Run the report. c Close the report after reviewing its content. If the report is not sorted as expected, review step 2 through step 4. In the following figure, the report is sorted by the Status parameter. Figure 1-36: Example: report sorted by a Status parameter To group results by a parameter This example shows how to group sorted results by a parameter. 1 Go to the Layout tab of the layout editor, select the Table icon of the table, rightclick the table header row, and select Insert Group in the submenu. Figure 1-37: Layout editor 32 Using a BIRT Editor to Create or Modify Web Reports

33 Using a BIRT Editor to Create or Modify Web Reports 2 In the New Group box, in the Group On list, select the parameter with which you want to group the results, and then click OK. In Figure 1-38, the Status parameter is selected in the Group On list so that the results are grouped by status. Figure 1-38: New Group box 3 Preview the report to make sure the results are grouped by the parameter you configured in the New Group box. To preview the report (Save, Run, and Close), repeat the procedures in step 5 on page 32. If the report is not grouped as expected, review step 2. In Figure 1-39, the report is grouped and sorted by the Status parameter. The first Assigned row has no data, then the next Assigned rows contain records. Then the first In Progress row has no data, then the following In Progress rows contain records. Figure 1-39: Report sorted by a parameter Examples for modifying reports with the BIRT Report Designer 33

34 White Paper 4 To apply a style to the group header, go back to the report file in the Layout tab, and right-click the group header row. Figure 1-40: Group header row in report Layout tab 5 Choose Style > Apply Style > bmcreporttheme:groupheader1. 6 Preview the report (Save, Run, and Close) to check the group header style. In Figure 1-41, the style selected resulted in a bold group heading. Figure 1-41: Report with stylized group header To aggregate results by a parameter You can configure your report results to display aggregated data. In other words, instead of displaying simple values, you can perform calculations on sets of values. This example shows you how to configure a report that counts the number of incidents. 34 Using a BIRT Editor to Create or Modify Web Reports

35 Using a BIRT Editor to Create or Modify Web Reports 1 In the Layout tab of the layout editor, select the Table icon, right-click a cell in a Table Group-Header row, and choose Insert > Aggregation. Figure 1-42: Inserting an aggregation 2 In the Aggregation Builder box, configure a report row by doing the following tasks: a In the Function list, select COUNT. b In the Expression list, select Incident Number. c Click OK. Figure 1-43: Aggregation Builder box Examples for modifying reports with the BIRT Report Designer 35

36 White Paper 3 Preview the report (Save, Run, Close). To preview the report, repeat the procedures in step 5 on page 32. This report groups results by the parameter you configured in the New Group box in, and displays the number of incidents in the Table Group Header row for incidents with Assigned and In Progress. Figure 1-44: Report displaying number of incidents and sorted by group Adding a column to report results This section explains how to add a column to filter report results. To add a column 1 In the BIRT Report Designer, go to the Layout pane of a report. 2 Click a column above its table header to select the entire column in a table. Figure 1-45: Highlighting a column in the Layout pane 3 Right-click in the selected column and choose Insert > Column to the Right (or Left). 4 Go to Data Explorer tab and drag a data set into the new column (for example, Data Explorer tab > Data Sets > HPD_Help_Desk > Incident Number). 5 Add a label for Incident Number at the top of the column. 36 Using a BIRT Editor to Create or Modify Web Reports

37 Using a BIRT Editor to Create or Modify Web Reports 6 Preview the report (Save, Run, Close). To preview the report, repeat the procedures in step 5 on page 32. Figure 1-46: Report displaying new column Adding a parameter to filter report results This section explains how to use the BIRT Report Designer to create a parameter that you can use to filter your report results. In this example, the License type field is added to the Parameter box for reports that return People records. To add a parameter 1 In the BIRT Report Designer, go to the Outline tab and right-click Report Parameters. 2 Select New Parameter from the submenu. 3 In the Name field, type a name for the new parameter. 4 In the Data type field, select String. 5 In the Display type field, select Combo box. 6 In the List of value area, select Static, then click New. 7 In the New Selection Choice box, type Fixed in the Value field, click OK. Examples for modifying reports with the BIRT Report Designer 37

38 White Paper Figure 1-47: New Parameter box 8 Click OK to close the New Parameter box. 9 To create binding between the data set and the new parameter, go to the Data Explorer tab, right-click the appropriate data set, click Edit, click Parameters, and click New. 10 In the New Parameter box, configure the new parameter by doing the following tasks: a In the Name field, type the name of the new parameter in the data set. NOTE Select one of the following two options as the Default Value field (see step c on page 39) can only be edited if you do not edit the Linked to Report Parameter field. b In the Linked To Report Parameter field, select the name of the new parameter you created in step 3 on page Using a BIRT Editor to Create or Modify Web Reports

39 Using a BIRT Editor to Create or Modify Web Reports Figure 1-48: New Parameter box for Editing a Data Set c In the Default Value field, edit the qualification query of the data set based on the report parameter that you linked to in step b on page 38. For example, enter the following in the Expression Builder: 'License Type' = [param:dslicensetype] where dslicensetype is the data set parameter which refers to the report parameter. 11 Preview the report (Save, Run, Close). To preview the report, repeat the procedures in step 5 on page 32. The Parameter box of the report appears and specifies a fixed License type parameter. The report shows People records having a fixed License type. Editing a Parameter box field to filter report results You can edit an existing field in the Parameter box to narrow your report results. When you run most out-of-the-box reports in BMC Remedy AR System or BMC Remedy IT Service Management Suite, the Parameter box appears and requests information to narrow the report results. For example, the Parameter box can request the Start Date and End Date for reports with a date range. Examples for modifying reports with the BIRT Report Designer 39

40 White Paper Figure 1-49: Parameter box To edit the Parameter box fields 1 Search for an out-of-the-box Web report that contains date-related fields that you want to edit, and save its.rptdesign file to a folder where you store reports. For details, see To export a.rptdesign file from the Report form to the BIRT Report Designer on page 18. a In the Report form, search for a report with the words Date and Range in its title by entering % Date Range in the Report Name field. Figure 1-50: Report Name field in the Report form b Select a report. For example, the Expiring Contracts by Date Range report. 40 Using a BIRT Editor to Create or Modify Web Reports

41 Using a BIRT Editor to Create or Modify Web Reports Figure 1-51: Search results in the Report form 2 In the BIRT Report Designer, choose File > Open File, and open the.rptdesign file you exported from the Report form. 3 Go to the Data Explorer tab, click the Report Parameters node. Figure 1-52: Report parameters 4 To edit a report parameter, right-click the report parameter you want to edit, and select Edit from the submenu. NOTE For details on editing parameters, see the BIRT Report Designer online help. For example, if you want to edit the Start Date field, right-click Start Date. 5 If you want to see how a parameter is filtered for a data set, go to the Data Explorer tab, right-click the data set you want to examine, click Edit, then click Filters. Examples for modifying reports with the BIRT Report Designer 41

42 White Paper NOTE For details on editing a filter condition, see the BIRT Report Designer online help. Using subreports to link reports together Subreports, which are reports that are linked and appear inside another report, can provide detailed information about a customer beyond the data provided in a parent report. For example: If a customer listing provides a customer ID, that customer ID can be input into a subreport that displays details about each customer. An ID value is often the common data between two data sets. If a parent report displays only the amount spent (or other customer data), a subreport can provide customer details (such as address). A subreport can show a combined parent report and subreport. Testing each subreport before building the next subreport can help minimize difficulties that can arise with subreports. NOTE The example in this section provides high-level instructions. Subreports are discussed in detail in the BIRT Report Designer online help. To create a subreport 1 Design the structure of a report and its subreports. This includes details of required data sets and how they are related, and can be a simple relationship diagram of forms. 2 Create a data source and a required number of data sets. For an example, consider a parent "People" report that can have an added subreport, which shows roles attached to a particular people record. The relationship structure is: CTM:People (Person ID) > CTM:SupportGroupFuncRoleLookUp (Person ID) This structure has two data sets that are required to develop the subreport. The two required data sets are CTM:People and CTM:SupportGroupFuncRoleLookUp. 3 Create the required data sets as follows: a Create a data set for the parent record (CTM:People). b Create a data set for the child records (CTM:SupportGroupFuncRoleLookUp). c In the Parameter tab of data set creation for child record, create a parameter for the parent key based on which will pull child records. For example, the key will be Person ID. Do not link the parameter to any report parameter. 42 Using a BIRT Editor to Create or Modify Web Reports

43 Using a BIRT Editor to Create or Modify Web Reports Figure 1-53: Parameter tab in the BIRT Report Designer 4 Click Query and modify the query as follows to pull child records having a key value the same as parent record: "Person ID" = [param:dspersonid] 5 Insert a second table element inside the new detail row of table. The child table must have the child record data set associated to it. Figure 1-54: Second table element inside a table detail row 6 Go to the Binding tab the new child table. 7 Bind the key field of the parent data set to the parameter of the child data set parameter. Examples for modifying reports with the BIRT Report Designer 43

44 White Paper Figure 1-55: Binding tab of the child table 8 Click Data Set Parameter Binding. 9 Bind the parent key value to the child. Figure 1-56: Data Set Parameter 10 Preview the report (Save, Run, Close). To preview the report, repeat the procedures in step 5 on page 32. Using dynamic drill down reports to provide a series of detailed reports This section provides high-level information about dynamic drill down reports. NOTE Adding interactive features, such as hyperlinks, to charts is discussed in detail in the BIRT Report Designer online help. 44 Using a BIRT Editor to Create or Modify Web Reports

45 Using a BIRT Editor to Create or Modify Web Reports Drill down reports are summary reports which can be drilled through to get related detail data in other reports at a granular level. The first report presented in a series of drill down reports provides only required or necessary data, and then the user decides whether they want further details. By adding hyperlinks, you make drill down reports interactive for your user. For example, a report first might show only a pie chart, which summarizes the report results. When a user clicks a slice of the pie chart, a detailed report opens for that particular slice of data. The following scenario looks at the report development of the All incidents by Status and assigned Group drill down report in ITSM. To create a drill down report This procedure provides high-level steps to create a drill down report. This procedure features the example All incidents by Status and assigned Group report. 1 Gather and analyze data to decide how to divide information into multiple stages. For example, the example report has a high number of incidents based on their status. The incidents have a particular status and are assigned to groups. There are also records for the incidents. A particular record in an incident form can provide details of that incident. Therefore, the design of this drill down report needs the following levels: Figure 1-57: Drill down report design example In this example: - A pie chart shows Incident Count categories based on Status Examples for modifying reports with the BIRT Report Designer 45

46 White Paper - A bar chart shows the Incident Count by Assigned Group for the Status slice selected in the pie chart - A detailed incident report based on the Assigned Group bar selected in the bar chart 2 Create a data source and data set required for a report (for example, HPD: Help Desk). 3 Insert a table in the report layout area. 4 Bind the data set property of the table. 5 Insert the required fields in the details section (for example, Incident Number, Assignee, Customer Name, and so on). 6 Insert groups in the table by right-clicking in the detail row of the table and selecting Insert Group. Insert the first group based on Status, and the second group based on Assigned Group. 7 Insert a chart in the table by right-clicking in a table header and choose Insert > Chart. Insert a pie chart showing the number of Incidents categorized based on Incident Status. Figure 1-58: Drill down report pie chart example 8 In the Status group header (header of first group) of the table, insert a bar chart, which will show the number of Incidents categorized based on Assigned Group. 46 Using a BIRT Editor to Create or Modify Web Reports

47 Using a BIRT Editor to Create or Modify Web Reports Figure 1-59: Drill down report inserting a bar chart 9 In the second group header, choose Insert > Grid to display details of Incident Count, Assigned Group, and Status. Figure 1-60: Drill down report inserting a grid 10 In the first group header, right-click and select Properties, select Bookmark in the Property Editor, then enter the following in the Bookmark box: row["status"] Figure 1-61: Bookmark box on Properties tab Examples for modifying reports with the BIRT Report Designer 47

48 White Paper This starts the process of adding drill down functionality by hyperlinking to the table. When clicking on a particular slice of the Status pie chart, the bar chart should appear and show details based on the Assigned Group of that Status. 11 To set the bookmark with a hyperlink to the pie chart, right-click the pie chart created in step 7 on page 46, and choose Format Chart > Series > Value Series > Interactivity, then click Add in the Series Interactivity box. Figure 1-62: Editing the pie chart Value series Interactivity 12 In the Hyperlink Editor box, type the name of the hyperlink in the Name field, and then click Edit base URL. 13 In the Hyperlink Options box, select Internal Bookmark, and then select the bookmark created in step 10 on page Using a BIRT Editor to Create or Modify Web Reports

49 Using a BIRT Editor to Create or Modify Web Reports Figure 1-63: Hyperlink Options box This adds the functionality for clicking a particular slice of a pie chart, then navigating to a bar chart that shows the incident count of a selected Status based on the Assigned Group. 14 Create a hyperlink for a bar chart by repeating the process from step 10 on page 47 through step 13 on page 48. To create a drill down report that links to an incident record This example shows how to enable a user with a list of incident records in a report to click on a particular Incident Number to open the form (for example, HPD:Help Desk) which includes the incident details. This allows the user to easily access and modify an incident record starting a report. 1 Add a new report parameter, select Hidden in the New Parameter box, and click OK. This new parameter will be used in script to fetch the mid tier URL. Examples for modifying reports with the BIRT Report Designer 49

50 White Paper Figure 1-64: Adding new parameter 2 Select a data set. In this example, select the HPD:Help Desk data set. 3 Go to the Script tab of the report, and select the BeforeOpen event in the Script list. The script fetches the MidTier URL at runtime and sets it to the hidden parameter created in step 1 on page 49. Figure 1-65: Script tab of the report The script is as follows: 50 Using a BIRT Editor to Create or Modify Web Reports

51 Using a BIRT Editor to Create or Modify Web Reports var request = reportcontext.gethttpservletrequest(); var urlvalue = null; if (request!= null) { var session = request.getsession(); if (session!= null) { urlvalue = session.getattribute("midtierurl"); } } if (urlvalue!= null) { params["midtierurl"].value = urlvalue; } else { params["midtierurl"].value = null; } 4 Go to Layout tab of the report, and select Incident Number, which was inserted in the table details section in step 5 on page Select the Hyperlink properties tab, and click Edit. Figure 1-66: Layout tab and Hyperlink property tab 6 In the Hyperlink Options box, select URL as the hyperlink type, and enter the following value: params["midtierurl"].value + row["entry ID"] choose Target = "Blank" 7 Save the report. 8 Preview the results by running the report on the mid tier, and clicking an Incident Number. The selected incident opens in the Help Desk form. Examples for modifying reports with the BIRT Report Designer 51

52 White Paper Converting a currency type with a computed column You can convert a particular currency field to the type entered by your user by creating a Computed Column in a data set. The Open Data Access (ODA) framework in BIRT converts the Currency Field in BMC Remedy AR System to the following fields: <Field Name>.OBJECT <Field Name>.VALUE <Field Name>.TYPE OBJECT is of type String and has currency value as well as currency type. To convert a currency field to the user entered currency type 1 With a report open in the Layout tab of the layout editor, go to the Data Explorer tab and double-click a data set under the Data Sets node. 2 In the Edit Data Set box, click Computed Columns. Figure 1-67: Edit Data Set - Computed Columns 3 Click New. 4 In the Column Name field, type a name for the computed column. 5 In the Data Type field, select Decimal. 6 In the Expression field, type the expression. For example: if (row["associated Cost.OBJECT"].toFunctionalValue(params["Currency Type"].value) 52 Using a BIRT Editor to Create or Modify Web Reports

53 Using a BIRT Editor to Create or Modify Web Reports Figure 1-68: New Computed Column The following is an example of entering an expression in the Expression Builder. Figure 1-69: Expression Builder for a computed column The function on the currency field object named tofunctionalvalue requires input as the expected currency type, which is obtained from the user parameter. The function returns Decimal currency value converted to a given currency type. 7 Click OK, then click Preview Results. Preview Results in Figure 1-70 shows the currency field converted into the.object,.value, and.type columns. Examples for modifying reports with the BIRT Report Designer 53

54 White Paper Figure 1-70: Preview Results for currency conversion Displaying Status History data in the body of a report Out-of-the-box Web reports do not support the Status History field. The Status History field is supported by AR System reports. In other words, Status History data can be displayed in the body of an AR System report. All core forms across the BMC Remedy IT Service Management suite are auditable for core fields. To include Status History data in a report, you can potentially use the data from the Audit form by either: Using subreports if using the BIRT Report Designer. See Using subreports to link reports together on page 42. Creating a join form to create a Web report. See the BMC Remedy Mid Tier Guide. Grouping results in multiple groups by using grids This example show how to create a report that shows grouped results, with those grouped results being further broken down into another level of groups. The first report shown in step 13 on page 58 of this example shows the results grouped by their Assigned Group (for example, A SupGrp) and then grouped by their Status (for example, Assigned, In Progress, and Pending). The second report shown in step 20 on page 59 of this example shows a deeper level of grouping, with the results grouped by their Assigned Group, then grouped by each Assignee within each Assigned Group, and then grouped by their Status. 54 Using a BIRT Editor to Create or Modify Web Reports

55 Using a BIRT Editor to Create or Modify Web Reports To add multiple groups by using grids 1 View the report in the Layout tab of the layout editor. This report starts with the Assigned Groups field in the left column. You can merge table group header cells and add a label to the left of the data set field as shown. Figure 1-71: Viewing the report in the Layout tab 2 Save and run the report to preview it. Figure 1-72: Report preview 3 In the Layout pane, add a column for the Incident Number to the right of the Assignee column. For details on adding a column, see Adding a column to report results on page 36. Figure 1-73: Adding a second column Examples for modifying reports with the BIRT Report Designer 55

56 White Paper 4 Add another column for the Submit Date to the right of the Incident Number column. 5 Save and run the report to preview it. The report shows columns for the Assigned Groups, Incident Number, and Submit Date. Figure 1-74: Report preview after adding two columns 6 In the Layout pane, right-click in the Table Group Header row, and choose Insert Group > Below. Figure 1-75: Inserting a group 7 In the New Group box, select Status in the Group On list, then click OK. The Status group is added to the table. 56 Using a BIRT Editor to Create or Modify Web Reports

57 Using a BIRT Editor to Create or Modify Web Reports Figure 1-76: Status group in the Layout tab 8 Right-click the Status group, and select a Group Header style for it. Figure 1-77: Selecting a style for the Status group 9 Apply a style to the other group headers and other rows in the table. 10 For formatting, merge the Status table group header cells and add a label to the left of the data set field. Figure 1-78: Merging and labelling the Status table group header 11 Right-click in the Status group header row, and choose Insert > Grid. 12 In the Insert Grid box, set the grid size as 2 columns and 1 row. Examples for modifying reports with the BIRT Report Designer 57

58 White Paper Figure 1-79: Inserting grid in Status group row 13 Save and run the report to preview it. The report shows the results grouped by their Assigned Group (for example, A Test Support, ABC Group) and then grouped by their Status (for example, Assigned and In Progress). Figure 1-80: Report preview showing grouping by Assigned Group and then Status 58 Using a BIRT Editor to Create or Modify Web Reports

59 Using a BIRT Editor to Create or Modify Web Reports To take the grouping to another level, this example now adds the Assignee group within the Assigned Group group. 14 Right-click in the Status table group header, and choose Insert Group > Above. 15 In the New Group box, set the grid size as 2 columns and 1 row 16 New Group box, select Assignee in the Group On list, then click OK. The Assignee group is added to the table. Figure 1-81: Assignee group added in Layout pane 17 For formatting, merge the Assigned table group header cells and add a label to the left of the data set field. Figure 1-82: Merging and labelling the Assigned table group header 18 Right-click in the Assigned group header row, and choose Insert > Grid. 19 In the Insert Grid box, set the grid size as 2 columns and 1 row. 20 Save and run the report to preview it. The report shows the results grouped by their Assigned Group (for example, A SupGrp), then grouped by Assignee (for example, A1 User), and then grouped by their Status (for example, Assigned and In Progress). Examples for modifying reports with the BIRT Report Designer 59

60 White Paper Figure 1-83: Report preview showing grouping by Assigned Group, then grouped by Assignee, and then Status Using a stacked bar chart to compare different series of results This procedure provides high-level steps to create a stacked bar chart report. A stacked bar chart compares the results for different sets of results. This example is for a stacked bar chart for all assignees in an incident group. The details of creating a bar chart are provided in the BIRT online help. 1 In BIRT Report Designer, create a basic new report. For details, see the BIRT online help. 2 Configure the data set for the report by adding the Status, Assignee Groups, Assignee, and Incident Number fields in the Query tab. 3 In the Layout pane, right-click in the report layout and choose Insert > Chart. 4 On the Select Chart Type tab of the New Chart box, select Bar as the Chart type, and Stacked Bar chart as the Subtype. 5 On the Select Data tab of the New Chart box: a Select Use Data from, and select Data Set from the list. 60 Using a BIRT Editor to Create or Modify Web Reports

61 Using a BIRT Editor to Create or Modify Web Reports Figure 1-84: Select Data tab for a stacked bar chart b Under In the Value (Y) Series, configure at least two series of data for Status using the Expression Builder. Optionally, configure the Aggregate Expression field to Count. Figure 1-85: Expression Builder for configuring a Value Series Examples for modifying reports with the BIRT Report Designer 61