13 Working with Reports Extensibility

This chapter provides overview information about the Oracle Business Intelligence (BI) Publisher and reports extensibility for Oracle Communications Network Integrity.

This chapter contains the following sections:

• About BI Publisher

• Reports Provided with Network Integrity

• Network Integrity Report Building Blocks

• Developing BI Publisher Reports

• Using BI Publisher Features

• Installing and Integrating BI Publisher with Network Integrity

• Uploading and Exporting Reports

About BI Publisher

Oracle BI Publisher (formerly XML Publisher) is an enterprise reporting solution to design, use, author, manage, and deliver report documents in various formats. This tool provides the following services:

• Creating New Report

• Uploading Existing Report

• Organizing reports in folders

• Viewing a report in various formats like RTF, HTTP, PDF, XLS

• Scheduling a report for delivery to destination like Email id

• Internationalization of report

• Configuring various data sources like Oracle Business Intelligence Enterprise Edition (OBIEE), Web service, and database

This chapter does not describe all Oracle BI Publisher features. Customized, or more advanced reports can be created using BI Publisher. For more information about Oracle BI Publisher, see the Oracle Business Intelligence Publisher Installation documentation:

https://download.oracle.com/docs/cd/E12844_01/doc/bip.1013/e12690/toc.htm

About BI Publisher Desktop

BI Publisher Desktop is a plug-in for Microsoft Word that enables a user to create report templates and represent data from data sources. This plug-in provides various wizards to create tables, grouped tables, graphs, charts, and so on. It internally uses Microsoft Word's native features and the eXtensible Stylesheet Language (XSL) to implement these wizards.

Reports Provided with Network Integrity

Network Integrity includes the following BI Publisher reports:

• Scan History Report

• Discovery Scan Summary Report

• Device Discrepancy Detection Summary Report

• Device Discrepancy Detection Detail Report

• Discrepancy Corrective Action Report

Scan History Report

The Scan History Report shows the discovery and discrepancy summaries for each scan for each scan configuration falling within the specified start and end dates. This report is accompanied by the following graphs:

• Discovery Scan History: a graph showing a history of the run discovery scans.

• Discrepancy Scan History: a graph showing a history of the run discrepancy scans.

• Discrepancy Severity History: a graph showing a history of the discrepancies by severity.

The following fields are used to generate this report:

• Start Time: the date stamp indicating when a scan started.

• End Time: the date stamp indicating when a scan finished.

Discovery Scan Summary Report

The Discovery Scan Summary Report shows the summary of the latest scan for each scan configuration, per vendor and per device type. This report generates a pie-chart, illustrating the summary findings, for each scan configuration.

The following fields are used to generate this report:

• Vendor: the name of the vendor for the discovered device.

• Device Type: the type of device discovered.

Device Discrepancy Detection Summary Report

The Device Discrepancy Detection Summary Report shows the summary of the latest scan for each scan configuration. This report generates a pie-chart that shows the accuracy of the latest scans for each scan configuration.

The following fields are used to generate this report:

• Vendor: the name of the vendor for the discovered device.

• Device Type: the type of device discovered.

Device Discrepancy Detection Detail Report

The Device Discrepancy Detection Detail Report lists details of all discrepancies for the latest scan for each scan configuration.

The following fields are used to generate this report:

• Vendor: the name of the vendor for the discovered device.

• Root device name: the name of the root device in the scan result tree.

• Root device type: the type of the root device in the scan result tree.

• Owner: the user name of the owner of the discrepancy.

• Parent entity type: the type of the parent entity on which discrepancy occurred.

• Parent entity name: the name of the parent entity on which discrepancy occurred.

• Entity type: the type of the entity on which discrepancy occurred.

• Inventory value: the value of the field on the inventory side on which discrepancy occurred.

• Network value: the value of the field on the network side on which discrepancy occurred.

• Severity: the severity of the discrepancy (for example, major, critical, minor, warning).

• Discrepancy type: the type discrepancy (for example, entity+, entity-, attribute).

• Description: the description of the discrepancy.

• Status: the status of the discrepancy (for example, processed, failed, ignored).

• Scan name: the name of the scan in which the discrepancy is found.

Discrepancy Corrective Action Report

The Discrepancy Corrective Action Report shows corrective actions against specified discrepancies for the latest scan for each scan configuration. Discrepancies that have not been actioned are not considered in this report.

The following fields are used to generate this report:

• Submitted By: the user who submitted the discrepancy for correction.

• Action: the action taken against the discrepancy.

• Discrepancy Status: Status of the discrepancy.

• Owner: the user name of the owner of the discrepancy.

• Priority: the priority of the discrepancy.

• Failure Reason: the reason for failure for the corrected discrepancy.

• Discrepancy Type: the type discrepancy (for example, entity+, entity-, attribute)

• Entity Type: the type of the entity on which discrepancy occurred.

• Inventory Value: the value of the field on the inventory side on which discrepancy occurred.

• Network Value: the value of the field on the network side on which discrepancy occurred.

Network Integrity Report Building Blocks

Network Integrity uses BI Publisher to generate reports. These reports use Rich Text Format (RTF) templates and a report Definition Extensible Markup Language (XML) file (.xdo) that tracks the various data sources, parameters, values, rendering options, and report properties that BI publisher uses to populate the RTF reports.

RTF Templates

The RTF template defines the layout and display for report data. The BI Publisher server uses the templates to format the data from various data sources. These formats include tables, charts, graphs, and so on.

A user can use general word processing features and BI Publisher's simplified tags for XSL expressions. The template parser inside the server processes the RTF document and converts it to XLS formatting objects (XSL-FO), useful for rendering the final formatted report in PDF, RTF, or HTML formats.

Report Definition Files

The reports Definition file (.xdo) contains all the configurations pertaining to a report and all the layout definitions that refer to the various templates used by the report.

Data Source Query Tools

The data source tools use various protocols such as SQL, Web service, and XML files that can get data from data sources for use in a report. Network Integrity typically uses SQL queries pertaining to Network Integrity schemas and retrieves query results from a Network Integrity database through Java database connectivity (JDBC).

See Network Integrity Information Model Reference for more information about how entities and parameters relate to the Network Integrity database.

Parameters

Parameters capture values at run-time and use these values to filter or manipulate data. Parameter definitions includes data type, default value, parameter type, display label, and list of values.

List of Values

The Menu parameter type uses the list of values definitions that BI Publisher render as a dropdown in a report. The dropdown menu is populated with values defined in the list of values. This definition can be a pre-defined hard coded list or it can be the result of an SQL query.

Rendering Options

You can render reports using formats like PDF, RTF, HTML, EXCEL, and so on. You can choose the render option for the reports they create.

Report Properties

The following list provides details on various report property functions:

• Run report online: Enable this property to view a report online. You can only schedule and view reports in history after BI Publisher runs the scheduled report.

• Show Controls: Enable this property to see the parameters and other View report screen controls like View, Send, Schedule, Analyzer, and so on.

• Show Report Links: Enable this property to see a link menu in the view report screen that contains different menu items that provide HTTP links for a report. You can bookmark these links.

• Auto Run: Enable this property to cause a report to run automatically when a user attempts to view it. If this property is not enabled, the user must click View in the view screen of the report.

• Enable document cache: Enable this property to provide a cache in the report document. This property is appropriate for reports that connect to live databases that are frequently updated.

Developing BI Publisher Reports

This section explains how to develop a custom report by creating an example report called Discrepancy Severity History Report.

Report Requirements

The Discrepancy Severity History Report requires the following

• Display the following fields:

  • Scan Name

  • Discrepancy Scan Start & End time

  • Counts of Critical, Major, Minor, Warning discrepancy types

• Filter on discrepancy start date.

• Group data by scan name.

• Create a bar chart for all discrepancy severity types.

Knowledge of the Network Integrity data model is necessary to write the SQL queries needed for the Discrepancy Severity History Report (see Network Integrity Models). This information is provided in the following sections.

Configuring a Data Source Tutorial

The following steps provide a tutorial for configuring a data source:

1. Log on to BI Publisher as an Administrator.

2. Click the Admin tab.

3. Click JDBC Connection under the Data Sources section

4. Click demo to edit the connection details for this data source.

5. In the Update Data Source screen, enter the following details:

   1. For Connection String, enter:

      jdbc:oracle:thin:@Host_name:Port:SID

      For example, a sample connection string may look like jdbc:oracle:thin:@myhost:1521:orcl

   2. For the User Name, enter:

      oe

   3. For the Password, enter:

      oe

   4. For the Database Driver Class enter the default:

      oracle.jdbc.driver.OracleDriver

6. Click Test Connection.

7. Click Apply to save the connection details after confirmation that the connection is successfully established.

Creating a Report Tutorial

The following steps provide a tutorial for creating a report:

1. Log on to BI Publisher as an Administrator.

2. Click the Reports tab.

3. Click the MyFolders link.

4. Click Create a new folder link in the Folder and Report Tasks tab.

5. Enter the following folder name:

   Test

6. Click Create to create the folder.

7. Click the new Test folder.

8. Click Create a new Report.

9. Enter the following report name:

   Discrepancy Severity History Report

10. Click Create to create the report.

11. Click Edit link below the report name.

12. Select Parameter.

13. Click New button.

14. Enter the following values to create a parameter called p_StartDate.

    1. For Identifier, enter:

       p_StartDate@

    2. For the Parameter Type, select Date.

    3. For the Display Label, enter:

       Discrepancy Begin Date Range Start

    4. For the Date Format String enter:

       MM-dd-yyyy

15. Repeat steps 12 to 14 to create a parameter called p_EndDate. Label the Identifier as p_EndDate and the Display Label as Discrepancy Start Date Range End.

16. Select Data Model.

17. Click New.

18. Enter the following values to create a data set called MyDataSet.

    1. For Name enter:

       MyDataSet

    2. For Type, select SQL Query.

    3. For Data Source select demo from the dropdown menu.

    4. For the SQL Query text box enter the following SQL query as required by the Network Integrity model to display the field described in "Report Requirements":

       select  dc1.NAME as SCANCONFIGNAME,
               case when dsr.DISCREPDETECTBEGINTIME is null then null else to_char(dsr.DISCREPDETECTBEGINTIME,'YYYY-MM-DD HH12:MI:SS TZR AM') end STARTTIME,
                 nvl(to_char(dsr.DISCREPDETECTENDTIME, 'YYYY-MM-DD HH12:MI:SS TZR AM'),' ') as DISCREPDETECTENDTIME,
       CASE WHEN DISCREPDETECTBEGINTIME IS NULL THEN NULL ELSE nvl(ddc.NUMBERCRITICAL,0) END C,
               CASE WHEN DISCREPDETECTBEGINTIME IS NULL THEN NULL ELSE nvl(ddc.NUMBERMAJOR,0) END M,
               CASE WHEN DISCREPDETECTBEGINTIME IS NULL THEN NULL ELSE nvl(ddc.NUMBERMINOR,0) END mi,
               CASE WHEN DISCREPDETECTBEGINTIME IS NULL THEN NULL ELSE nvl(ddc.NUMBERWARNING,0) END w,
               
       from 
               DISCONFIG dc left outer join DISCONFIG dc1 on dc.scanconfig= dc1.entityid
               left outer join DISSCANRUN dsr on dc.ENTITYID=dsr.CONFIG
               left outer join DISDISCREPANCYCOUNTS ddc on dsr.DISCREPANCYCOUNTS=ddc.ENTITYID
        
       where   
       dc.scanconfig is not null and
       (:p_StartDate is null or trunc(dsr.DISCREPDETECTBEGINTIME, 'DDD') >= :p_StartDate) and
       (:p_EndDate is null or trunc(dsr.DISCREPDETECTBEGINTIME, 'DDD') <= :p_EndDate)
       

19. Save the data set. The XML source data can now be viewed in a report.

Building an RTF Template Tutorial

The following steps provide a tutorial for building an RTF template:

1. Using Microsoft Word, create an RTFF file called DiscrepancySeverityHistory.rtf.

2. Open the Microsoft Word file.

3. From the AddIns menu, select BI Publisher.

4. Log on to BI Publisher as an Administrator. The Login Wizard immediately opens to a screen showing the DiscrepancySeverityHistory.rtf report selected.

5. Click the Open Report button.

6. Enter the following text as the title of the report (see Figure 13-1):

   Discrepancy Severity History Report

7. Enter the following text as a description of the report (see Figure 13-1):

   The report shows historical discrepancies severity summaries for scans.

8. Enter the following code in the field after the description (see Figure 13-1). This code is a declaration of the parameter strings already defined in "Creating a Report Tutorial":

   <?param@begin:p_Start;'None'?>
   <?param@begin:p_End;'None'?>
   

9. Below the declaration, insert a table with two columns (see Figure 13-1).

10. Enter the table column titles as FilterName and FilterValue and enter StartDate and EndDate in first column of both the rows (see Figure 13-1).

11. Insert the following code into the second and third rows of the second column respectively (see Figure 13-1).

    <?$p_Start?> 
    <?$p_End?> 
    

    Figure 13-1 Report Example

    
    

12. Select Oracle BI Publisher then Insert then Table wizard.

13. Select the Table option.

14. Click Next.

15. Select the data set that you defined in "Creating a Report Tutorial".

16. Select the field to display on the report and arrange them in an appropriate order.

17. Click Next.

18. Select Scanconfigname from the Group By dropdown menu and to be grouped by horizontally.

19. Click Next.

20. Select any field from the Sort By dropdown menus. This step is optional.

21. Label each field as required.

22. Click Finish.

23. Place the cursor below the table within the groupby clause.

24. Select Oracle BI Publisher then Insert then Chart.

25. From the Data explorer tab, drag the STARTTIME field into the text box adjacent to Labels.

26. Drag the C, M, Mi, W fields into the text boxes adjacent to Values.

27. From the Type dropdown menu, select Line Graph.

28. From the Style dropdown menu, select Confetti.

29. Select the Group Data check mark.

30. Select the Chart is inside group check mark.

31. Change the items as required in the Properties list. The values are True or False.

32. Click OK to insert the chart into the Microsoft Word document.

33. Select Oracle BI Publisher menu then Upload Template As to upload the template to the BI Publisher server.

34. Enter a name for the new template, for example, SevHistoryReportTemplate.

35. Click OK.

36. Navigate to the BI Publisher server where the template is now located.

37. Click View to see the reports.

Using Microsoft Word Native Features and XSL

RTF templates can use standard word processing features of Microsoft Word like tables, formatting, styles, and so on. The BI Publisher Desktop plug-in also provides additional wizards for use in Microsoft Word. These wizards internally generate XSL equivalent code which is interpreted by BI Publisher server while rendering the template.

Using BI Publisher Features

Oracle BI Publisher provides the following important features:

• Scheduling Reports

• Localizing Reports

Scheduling Reports

To schedule reports, use the following tasks:

• Enabling BI Publisher Scheduler Tutorial

• Using BI Publisher to Schedule Reports Tutorial

Enabling BI Publisher Scheduler Tutorial

BI Publisher requires a database to create a scheduling schema and a database user to use the scheduling schema.

To create an database user for scheduler schema and grant required permissions to that user, use the following steps:

1. Use the following SQL example to create a database user:

   SQL> CREATE USER bipubsched
      2  IDENTIFIED BY welcome
      3  DEFAULT TABLESPACE USERS
      4  TEMPORARY TABLESPACE TEMP
      5  QUOTA 20G ON USERS
      6  QUOTA 1M ON TEMP;
     
   User created. 
    
    SQL> GRANT CREATE SESSION TO bipuser; -- or "GRANT CONNECT TO bipuser;"
    
    Grant succeeded. 
    
    SQL> grant create table to bipublisher; 
    
    Grant succeeded.
   

2. Log on to BI Publisher as an Administrator.

3. Select Admin.

4. Under System Maintenance, select Scheduler Configuration.

5. Enter the following values:

   1. For Database Connection Type dropdown menu, select jdbc.

   2. For Database Type dropdown menu, select Oracle 10g.

   3. For Connection String, enter jdbc:oracle:thin:@10.177.219.0:1521:ORCL.

   4. For Username, enter bipudsched.

   5. Enter a Password.

   6. For Database Driver Class, enter oracle.jdbc.OracleDriver.

6. Click Text Connections to verify if the connection is successful.

7. If the connection was successful, click Install Schema to install the schema in the database.

8. Restart BI Publisher to apply the change. You can schedule reports after the server restarts.

Using BI Publisher to Schedule Reports Tutorial

To schedule reports, use the follow procedure:

1. In BI Publisher, navigate to the folder you stored your reports.

2. Click Schedule below the report you want to schedule.

3. In the Schedule Reports screen, enter values as required.

   Tip:

   Before you can configure Email destinations, ensure that the mail server has been configured. This can be done from the Admin tab on the main menu in the Delivery section.

4. Click Submit to schedule the report. When the scheduled report has been run, the report is stored in the History.

Localizing Reports

The localization of a report is achieved by translating the templates used for that report and adding those templates to the report Definition in BI Publisher. There are two options for adding translated templates to a report Definition.

Localized Template Option

In this option, there is one RTF template for one locale supported for the report. There are n RTF templates for n locales supported. Figure 13-2 illustrated that there is an RTF template with French locale and the data is in an XML file. BI Publisher uses both and renders the report in French text.

Figure 13-2 Localized Template

Naming convention for the report template is TemplateName_<language code>_<TERRITORY CODE>.rtf.

This RTF template must be uploaded to BI Publisher to include this in the report Definition.

XLIFF File Option

In this option, there is one RTF template for one locale supported for the report. There are n RTF templates for n locales supported. illustrated that there is an RTF template with French locale and the data is in an XML file. BI Publisher uses both and renders the report in French text.

In this option, there one RTF template but n XML localization interchange file format (XLIFF) files for n locales supported. Figure 13-3 illustrates that BI Publisher receives data in XML, base template, and an XLF file with translated text strings to render the report in French text.

Figure 13-3 XLIFF Localized Template

Naming convention for the report template is TemplateName_<language code>_<TERRITORY CODE>.rtf.

Upload all supported n XLF files and corresponding n locales to the BI Publisher report to include these into the report Definition.

Installing and Integrating BI Publisher with Network Integrity

BI Publisher can be installed as a standalone application or as a web application deployed in the same application server where the Network Integrity is deployed.

BI Publisher is partially integrated with Network Integrity which supports various BI Publisher application links in the Network Integrity Links tab. The BI Publisher application can be launched from Network Integrity using the BI Publisher link.

Installing BI Publisher in Standalone Mode

The following link provides the steps to install BI Publisher in standalone mode:

https://download.oracle.com/docs/cd/E12844_01/doc/bip.1013/e12690/T434820T487782.htm

Deploying BI Publisher

To deploy BI Publisher as an Enterprise ARchive (EAR) in a WebLogic application server where Network Integrity is running, use the following steps:

1. Download the BI Publisher zip file.

2. Unzip the zip file.

3. Navigate to the RH_Linux/Oracle_Business_Intelligence_Publisher_Standalone/manual/generic directory where the xmlpserver war and ear files are located.

4. Explode the war file to create an xmlpserver directory with all the war files present within using the following command:

   jar -xvf xmlpserver.war

5. Deploy the xmlpserver folder onto WebLogic as an application.

6. Copy all the files under RH_Linux/Oracle_Business_Intelligence_Publisher_Standalone/manual/generic directory into (for example) ~/BIP or /home/<username>/BIP

7. Search the xmlp-server-config.xml file in the Network Integrity domain of WebLogic.

8. Insert the following in the file:

   path="/home/<username>/BI

9. Save the file.

10. Copy font files from RH_Linux/Oracle_Business_Intelligence_Publisher_Standalone/manual//fonts and put them in JAVA_HOME/jre/lib/fonts. This is the JDK that the Network Integrity installer uses.

11. Restart the application server.

12. Launch BI publisher. For example:

    http://localhost:7101/xmlpserver
    

13. Login as administrator.

Integrating BI Publisher with Network Integrity using WebLogic Enterprise Manager

Complete one of the following prerequisites before attempting this procedure:

• Installing BI Publisher in Standalone Mode

• Deploying BI Publisher

To integrate BI Publisher with Network Integrity using the WebLogic Enterprise Manager, use the following steps:

1. Launch WebLogic enterprise manager. For example

   http://10.177.219.11:7101/em
   

2. Log on to Enterprise Manager using the username and password used to log on to WebLogic Admin Console

3. Click the WebLogic Domain folder link in the left side navigation panel.

4. Expand the Weblogic Domain folder to display the domains.

5. Select the domain where the Network Integrity application is installed.

6. Select System Mbean Browser from the dropdown menu. The System Mbean Browser shows all the Mbeans deployed in WebLogic server.

7. Select the NIRegionLinksService Network Integrity Mbean to view its properties.

8. Enter BI Publisher link against any URL property (for example, URL06).

9. Enter the display string of the URL against URLName06. This link appears in the Links tab of the Network Integrity UI the next time the UI refreshes.

Integrating BI Publisher with Network Integrity using JConsole

Complete one of the following prerequisites before attempting this procedure:

• Installing BI Publisher in Standalone Mode

• Deploying BI Publisher

To integrate BI Publisher with Network Integrity using the JConsole:

1. Use the following command to launch JConsole in Windows.

   %JAVA_HOME%/bin/jconsole -J-Djava.class.path=%JAVA_HOME%\lib\jconsole.jar;%JAVA_HOME%\lib\tools.jar;%WLS_HOME%\server\lib\wljmxclient.jar -J-Djmx.remote.protocol.provider.pkgs=wlserver.management.remote
   

2. Use the following command to launch JConsole in Linux.

   jconsole -J-Djava.class.path=$JAVA_HOME/lib/jconsole.jar:$JAVA_HOME/lib/tools.jar:$WLS_HOME/server/lib/wlserver.jar -J-Djmx.remote.protocol.provider.pkgs=wlserver.management.remote
   

3. In the JConsole New Connection screen, select the Remote Process option.

4. In the Remote Process text box, enter service:jmx:t3://10.147.240.137:7007/jndi/wlserver.management.mbeanservers.runtime

   The host name corresponds to the IP address of the host where Network Integrity is installed.

   The port number is the port on which the managed server is running. For example, 7003.

5. Enter the same username and password used for accessing the WebLogic admin console and click connect.

6. Navigate to oracle.communications.integrity then NIRegionalLinksService then oracle.comminications.integrity then Attributes. NIRegionalLinkService is the Mbean placeholder for BI Publisher link.

7. Set URL06 with the BI PublisherWebLogic URL.

8. Set URLName06 with the corresponding display title. Now the Network Integrity shows BI Publisher link that points to the BI Publisher URL in the Links tab after next page refresh.

Integrating BI Publisher with the Network Integrity Installer

Complete one of the following prerequisites before attempting this procedure:

• Installing BI Publisher in Standalone Mode

• Deploying BI Publisher

To integrate BI Publisher with Network Integrity using the Network Integrity Installer:

1. Log on to Network Integrity.

2. Navigate to the Network Integrity Installer screen.

3. Navigate to the System Wide Shortcut links (Optional) screen.

4. Enter a name for the link to BI Publisher in the Name text box (for example, BI Publisher).

5. Enter the URL for the link to BI Publisher in the Link text box.

6. Click Next and follow the Wizard instructions.

Uploading and Exporting Reports

Oracle BI Publisher provides the following methods to upload and export reports:

• Exporting a Report

• Uploading a Report

Exporting a Report

To export a BI Publisher report, use the following steps:

1. Log on to BI Publisher as administrator.

2. Click the Admin tab.

3. In the System Maintenance section, click Report Repository.

4. Change the Path if required.

5. Copy the path and paste it into the Explorer Address bar, or an equivalent software.

6. Navigate to User folders.

7. Select the user name associated to the report you want to export. There are n folders for n reports in that user folder. These reports can be zipped and stored in any location for future use.

Uploading a Report

To upload a BI Publisher report, use the following steps:

1. Log on to BI Publisher as administrator.

2. Click the Reports tab.

3. Click My Folders.

4. Click Create a new folder.

5. Click Create.

6. Click the newly created folder link.

7. Click Upload a Report.

8. Save the reports downloaded from secondary memory or from location where they were stored.

9. Unzip each of the zip files into individual folders.

10. Click browse and navigate to the unzipped folder.

11. Select the file with.xdo extension.

12. Click upload button. The report is created in you folder now.

13. Click the report – ”Edit” link and click the ”Layouts” link in the left side navigation.

14. Click browse and upload all the RTF files in the unzipped folder.

15. Click Save link in the left navigation.

16. Repeat steps 10 to 15 for all additional unzipped report folders.