
README_excelTemplates.txt

Summary
-------

This file describes how to use the Excel reporting templates for
HP OpenView / Network Node Manager.

The Excel report templates are installed in the directory

  $OV_CONF/analysis/excelTemplates/NNM

To use the templates, the various *.xlt need to be copied to the system
where Excel is installed.  These files should go in the Microsoft Office
Templates directory, such as

  C:\Program Files\Microsoft\Office\Templates

The simplest method to do this is to copy all of the directories to the
target system:

  NNM_Alarms         -->   ...\Office\Templates\NNM_Alarms
  NNM_Availability   -->   ...\Office\Templates\NNM_Availability
  NNM_Inventory      -->   ...\Office\Templates\NNM_Inventory

The templates will then be accessible from Excel's File:New... menu.  Upon
creating a new file from a template, you will be prompted to locate the
accompanying NNMReports add-in for Excel, called NNMReports.xla.  Locate the
file in the dialog and Open it.

The report template will prompt you to enter parameters to control how the
report is generated.  Enter a title and the name of the NNM web server, plus
the appropriate report interval.  After the report is generated, you will have
a new Excel Workbook with the report data.

If the generated report is empty, perhaps the NNM Data Warehouse from which
the data is obtained is itself empty.  The NNM operational data must be
exported into the Data Warehouse so that reports can be generated.  This
is accomplished from within ovw via these menu items:

    Tools:Data Warehouse->Export Topology
    Tools:Data Warehouse->Export Events
    Tools:Data Warehouse->Export Trend Data



HOW TO USE THE TEMPLATES
------------------------

The excelTemplates directory contains a number of Excel template files
(*.xlt) which are used to generate reports based on the data contained in
the Data Warehouse of a system where NNM is running.  This directory is
typically

    C:\OpenView\conf\analysis\excelTemplates\NNM  (Windows NT)
    /etc/opt/OV/share/conf/analysis/excelTemplates/NNM  (HP-UX, Solaris)

To make use of the Excel templates, the template files must be accessible
via Excel.  It is recommended that these templates be copied to the
Microsoft Office/Excel Template directory ( directory named "Templates" under
the Office/Excel installation directory ).  For example, if Excel97 is
installed under

    C:\Program Files\Microsoft\Office

there should be a Templates directory called

    C:\Program Files\Microsoft\Office\Templates

Excel will look in this Templates directory (and all subdirectories) for
all template (*.xlt) files.  The Excel report template directories should be
copied as follows:

  NNM_Alarms         -->   <template dir>\Office\Templates\NNM_Alarms
  NNM_Availability   -->   <template dir>\Office\Templates\NNM_Availability
  NNM_Inventory      -->   <template dir>\Office\Templates\NNM_Inventory

where <template dir> is the Office Templates directory.

Once these files have been copied into the Templates directory, they become
available via the New... menu command on the File menu in Excel.  The New...
command shows all of the Excel templates that are available, organized by 
the name of the subdirectory in which they were placed.  Selecting one
of these templates will cause a new copy of the template workbook to be
created.  NOTE: Don't open the template files directly using the Open...
command, as this will cause the original report template files to be
modified.

The first time any of the Excel report template are used, the user is
required to let Excel know where the NNMReports add-in file is located.  This
Excel add-in contains functionality required by all of the report templates,
and must be accessible in order to generate reports from the templates.
The add-in file is call NNMReports.xla, and it is installed in the same
directory as the template files, for example:

    C:\OpenView\conf\analysis\excelTemplates\NNM\NNMReports.xla

Once the user has located and opened the NNMReports.xla file, Excel remembers
its location so that it is immediately accessible for any future use.

When the template is opened, a dialog box will be displayed prompting the
user to enter some parameters needed to generate the report.  This dialog
is called the Report Generation Wizard, and it contains the following fields:

    o  Report Title - The string to be displayed in the generated report
       as the title for the report.

    o  HTTP Server - This specifies the server name or address for connecting
       to the NNM embedded web server on the management station.  If the
       management station is a Windows NT system, the server name by itself
       is sufficient.  If the management stations is a HP-UX or Solaris system,
       the user will need to also enter the port number for the web server,
       which is usually 8880.

    o  Report Interval - This selection determines the starting and ending
       times for the interval for which to generate a report.  For some
       reports, it also determine whether to report on detailed data or
       summarized/aggregated data.  Changing this selection automatically
       fills in the From and Until fields with default values.

    o  From and Until - These fields can be modified from the defaults to
       specify a custom report interval.  These entries must be valid dates
       and/or times.

After all of these fields have been properly filled and the user presses Ok,
the process of generating the report begins.  Report generation involves
making a number of queries to the Data Warehouse on the management station
(via the specified HTTP server), and formatting the resulting data into the
Excel workbook.  In most cases, the resulting report will consist of a number
of worksheets, one for the overall summary, plus several detail reports.
The report workbook can be saved and modified using any Excel functionality.



HOW THE TEMPLATES WORK
----------------------

The generation of the reports is driven by macros written in Visual Basic for
Applications, which are embedded as part of each report template.  The 
templates also make use of VB macros contained in the NNMReports add-in.

The major piece of generating a report is getting the report data from the
data warehouse.  Excel supports external data queries via ODBC and HTTP(web).
Connecting to a database using ODBC requires that the database reside on the
same system that is running Excel.  Using HTTP to perform the query allows
the report to be generated from any remote PC.

The HTTP web queries to the management station rely on a CGI program included
as part of Network Node Manager, ovwebdata.  Ovwebdata invokes in turn ovdwquery,
the standard Data Warehouse query tool.  Ovwebdata passes the SQL to be invoked
as standard input to ovdwquery, and ovdwquery writes the result of the query back
to its standard output.  This output is read by ovwebdata and sent back to the
web client (Excel) as the result of the CGI.  Excel has built-in functionality 
to perform these web queries, but the NNMReports add-in extends the functionality
and makes it transparent to the end user.
