report creation guide

Reporting Suite

Report Creation Guide

2


Id:0900d805801dba06

The information in this document is subject to change without notice and describes only the product defined in the introduction of this documentation. This documentation is intended for the use of Nokia Siemens Networks customers only for the purposes of the agreement under which the document is submitted, and no part of it may be used, reproduced, modified or transmitted in any form or means without the prior written permission of Nokia Siemens Networks. The documentation has been prepared to be used by professional and properly trained personnel, and the customer assumes full responsibility when using it. Nokia Siemens Networks welcomes customer comments as part of the process of continuous development and improvement of the documentation.

The information or statements given in this documentation concerning the suitability, capacity, or performance of the mentioned hardware or software products are given "as is" and all liability arising in connection with such hardware or software products shall be defined conclusively and finally in a separate agreement between Nokia Siemens Networks and the customer. However, Nokia Siemens Networks has made all reasonable efforts to ensure that the instructions contained in the document are adequate and free of material errors and omissions. Nokia Siemens Networks will, if deemed necessary by Nokia Siemens Networks, explain issues which may not be covered by the document.

Nokia Siemens Networks will correct errors in this documentation as soon as possible. IN NO EVENT WILL Nokia Siemens Networks BE LIABLE FOR ERRORS IN THIS DOCUMENTA-TION OR FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SPECIAL, DIRECT, INDI-RECT, INCIDENTAL OR CONSEQUENTIAL OR ANY LOSSES, SUCH AS BUT NOT LIMITED TO LOSS OF PROFIT, REVENUE, BUSINESS INTERRUPTION, BUSINESS OPPORTUNITY OR DATA,THAT MAY ARISE FROM THE USE OF THIS DOCUMENT OR THE INFORMATION IN IT.

This documentation and the product it describes are considered protected by copyrights and other intellectual property rights according to the applicable laws.

The wave logo is a trademark of Nokia Siemens Networks Oy. Nokia is a registered trademark of Nokia Corporation. Siemens is a registered trademark of Siemens AG.

Other product names mentioned in this document may be trademarks of their respective owners, and they are mentioned for identification purposes only.

Copyright © Nokia Siemens Networks 2008/2/22. All rights reserved

f Important Notice on Product Safety Elevated voltages are inevitably present at specific points in this electrical equipment. Some of the parts may also have elevated operating temperatures.

Non-observance of these conditions and the safety instructions can result in personal injury or in property damage.

Therefore, only trained and qualified personnel may install and maintain the system.

The system complies with the standard EN 60950 / IEC 60950. All equipment connected has to comply with the applicable safety standards.

The same text in German:

Wichtiger Hinweis zur Produktsicherheit

In elektrischen Anlagen stehen zwangsläufig bestimmte Teile der Geräte unter Span-nung. Einige Teile können auch eine hohe Betriebstemperatur aufweisen.

Eine Nichtbeachtung dieser Situation und der Warnungshinweise kann zu Körperverlet-zungen und Sachschäden führen.

Deshalb wird vorausgesetzt, dass nur geschultes und qualifiziertes Personal die Anlagen installiert und wartet.

Das System entspricht den Anforderungen der EN 60950 / IEC 60950. Angeschlossene Geräte müssen die zutreffenden Sicherheitsbestimmungen erfüllen.

3


Id:0900d805801dba06

Table of ContentsThis document has 20 pages.

1 Reporting Suite Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.1 Reporting Suite Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 KPI Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1 Query Engine Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 Engine Execution Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 File Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.4 Basic Report Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4.1 Create a new report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4.2 Create a UI conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4.3 Add an entry to the navigation tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.5 Advanced Report Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.5.1 Create a new KPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.5.2 Create a new Counter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4


Id:0900d805801dba06

List of FiguresFigure 1 Reporting Suite Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Figure 2 KPI Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Figure 3 Engine execution example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Figure 4 File structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Figure 5 Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Figure 6 User interface configuration sub folder . . . . . . . . . . . . . . . . . . . . . . . . . . 14Figure 7 Node tag example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Figure 8 KPI definition example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Figure 9 kpi mark use example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Figure 10 kpi info use example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Figure 11 Counter example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Figure 12 Counter example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5


Id:0900d805801dba06

List of TablesTable 1 Element tags used in a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Table 2 kpi info sub tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Table 3 temp-table attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6


Id:0900d805801dba06

7

Report Creation Guide Reporting Suite Overview

Id:0900d805801dba01

1 Reporting Suite OverviewThe purpose of Reporting Suite is to deliver content that can be used immediately by operators to analyze the performance and capacity of their networks. The bulk of the RS content is reports and Key Performance Indicator (KPI) definitions for the Performance

The content of Reporting Suite is primarily based on Nokia Siemens Networks KPI and report definitions which are designated by Performance Management Working Groups (PMWG). The RS content can be customized to match specific customer needs.

Reporting Suite provides information for several user groups in an operator's organisa-tion. Detailed KPI matrices support optimization and troubleshooting tasks, and are available in all report components.

Reporting Suite considers two main user roles. A report user that collects data with the RS reports to analyze network performance, and a report developer that defines new reports and KPIs or customizes existing reports.

From a report user point of view RS is a web based application with a look and feel con-sistent with NetAct , which enables the user to:

– Browse and run reports– Read and analyze the report data– Export reports results– Access documentation

In addition to this a report developer would be able to:

– Define KPIs and reports by editing XML files– Deploy the defined content as files on tier 3– Customize the RS navigation tree to activate content

1.1 Reporting Suite ComponentsReporting Suite (RS) is available for NetAct Regional Cluster and Global Reporter.

Reporting Suite is a web application that runs on tier 2 in the NetAct system, the KPI, the reports and configuration data, are stored as files on tier 3.

Management domain.

8


Id:0900d805801dba01

Reporting Suite Overview

Figure 1 Reporting Suite Components

There are three fundamental components on Reporting Suites:

– KPI & Report definitionsXML files, with the actual content of the package.

– Query Engine (QE)A data extraction engine, based on report definitions.

– Adaptation SupportDefines how the QE must handle data from a given network technology (like BSS)

Multi Vendor reporting is supported via the Adaptation Support for each technology.

9

Report Creation Guide KPI Library

Id:0900d805801dba02

2 KPI LibraryThe Reporting Suite content files structure separates counter, KPI and report informa-tion in separate libraries. All content definitions are stored in XML folders. Each sup-ported technology has its own folder under which counters, KPIs and reports sub folders are defined.

KPIs are kept in separate files, one file per KPI, this offers an easily maintainable KPI Library.

Customers are welcome to add their own counters and KPI definitions.

Figure 2 KPI Library

2.1 Query Engine PrinciplesThe core task of the reporting engine is to transform raw counters into KPIs. This provides efficient analysis of the network performance and capacity.

This is accomplished by providing the engine with the definitions of the KPIs and reports. When defining KPIs and reports there are a number of principles that should be taken into consideration

Key priorities for the engine and the KPI definition format:

– Generic KPI definitions: • Reports are needed on many different object and time aggregation levels • Open possibilities for advanced User Interface (UI) operations such as drill down

and KPI analysis– Focus on reuse:

• KPIs are typically required in different contexts, which typically means that a KPI appears in multiple reports

only once– Focus on documentation:

• The KPI definition and the related documentation, should be kept in close prox-imity to ensure consistency

– Clarity and Transparency • Keep it simple

– Performance

2.2 Engine Execution ExampleKPI Step

When the aggregation has finished the results are joined together. On the result of this join the KPI formulas are applied.

• To avoid errors and ensure maintainability it is important that a KPI is defined

10


Id:0900d805801dba02

KPI Library

Aggregation Step

The different measurements used by the reports are handled one by one. The data in the tables are aggregated to the report level. The selection of the reports is done in the User Interface.

The engine will choose to do the aggregation of the different tables in one or multiple steps to optimize performance.

Figure 3 Engine execution example

2.3 File StructureIn tier 3 the XML files are placed in the custom directory. Inside this directory there are sub folders defined for each supported technology.

For each technology the counters, KPIs and reports are divided in to sub folders (see Figure 4).

11


Id:0900d805801dba02

Figure 4 File structure

This type of structure provides:

– Faster corrections and updates to KPIs and reports– Customization or addition of reports directly by operators staff– Report customization services by Nokia Siemens Networks engineers

2.4 Basic Report CreationTo create a new report follow the steps described below:

1 Create a new report, using a KPI from the existing KPI Library (see 2.4.1)

2 Create a new User Interface configuration file (see 2.4.2)

3 Add a new entry to the navigation tree (see 2.4.3)

2.4.1 Create a new reportThe Figure 5 is an example of a complete report using one KPI.

12


Id:0900d805801dba02

KPI Library

Figure 5 Report Example

New report files are stored in the report subdirectory of the adaptation, see 2.3 File Structure.

The report structure has the following elements:

Element Tag Description

<conf_file> Root tag of the report, mandatory in every report.

<header> Defines the report title. It is displayed in the user interface. The <header> must be kept below 40 characters.

<help-text> Longer descriptive text about the report, this information is dis-played in the online help. CDATA is used to get HTML formatting of the output.

g This tag is optional.

<report-description>

Brief description of the report, it is recommended to be short and informative. This description is displayed in the report output table when the report is generated.

g This tag is optional.

Table 1 Element tags used in a report

13


Id:0900d805801dba02

<kpi_ref> This tag is used to make a reference entry in the report XML to existing KPI’s in the library. The existing KPI libraries are divided into different adaptations.

Example:

<kpi_ref ref="custom/bss/kpis/c090_qos.xml#NBR_

OF_TBF_ALLOCATIONS"/>

The KPI library used in this example is /c090_qos.xml.

Multiple KPI’s may be defined within a file. The hashmark (#) iden-tifies the KPI to use.

<column order>

Specifies the order in which the KPIs are displayed on the web page. For each KPI reference in the report a tag with the same name as the KPI is used.

KPIs can be grouped under different headers in the result output. If the user wants to use grouping it must be defined in the <column order> tag.

If several KPIs are part of the same group, the group attribute must be defined for each KPI.

<master_temp_table_names>

For a given report the used temp tables can be found by searching the temp_table_ref and temp_table tags in the KPIs included in the report.

creator must decide which of the temp table names are used as masters, otherwise is used the first temp table in the report. Usually the temp table name (temp_table) and alias (alias_name) are the same. In this example the temp table with the alias qos is defined as master temp table.

If a report contains more than one temp table, a master temp table must be defined. The sequence of the temp table names in comma separated list determines the priority in which the temp tables are selected for use.

<kpi name> Name of the KPI.


Table 1 Element tags used in a report (Cont.)

The temp table names are given by the attribute name. The report

14


Id:0900d805801dba02

KPI Library

2.4.2 Create a UI confIn the directory structure under the folder conf there is a sub folder ui_conf where all the delivered user interface configuration files are stored.

The User Interface configuration file, defines the databases that can be accessed, and the reports that are available in the user interface. The ui conf file is used by the naviga-tion tree in the user interface.

Figure 6 User interface configuration sub folder

<formula> By looking to the <formula> tag in a KPI definition the user is able to identify the temp table alias used in the included counter(s). In the following example the KPI uses a counter NBR_OF_TBF_ALLOCATIONS that is defined in the temp table with the alias qos.


Table 1 Element tags used in a report (Cont.)

15


Id:0900d805801dba02

Below is an example of a simple UI configuration file, where it is defined one database and one report.

The tag <dbpool> refers to a database pool. The attribute name defines the display name in the user interface. The tag <report> defines the filename of the report to be included.

2.4.3 Add an entry to the navigation treeIn order to get your own nodes into the navigation tree, remove the hashmark from the following line in custom.properties:

#com.nokia.oss.qengine.customNavLocation=cus-tom/bss/ui_conf/custom_bss_nav.xml

The custom.properties file is located at: custom/conf/

The file custom_bss_nav.xml located in the folder custom/bss/ui_conf defines custom nodes in the navigation tree.

The created report can be added to an existing UI configuration file, or a new one can be created. New UI configuration files must be placed in the folder custom/bss/ui_conf (see Figure 6). If a new UI configuration file is created a new entry must be added in the custom_bss_nav.xml file.

There can be several <node> tags in the NavTree xml file, each node tag represents a link in the navigation tree.

Figure 7 Node tag example

The node tag has two additional tags <navTreeEntry> and <url>.

Within the navTreeEntry tag an <id> tag must be defined. The id tag is an unique iden-tification of the navigation tree link. The link name and the id tag entry have the same name.

The url tag defines the actual link to the report. In the example (see Figure 7) the url points to the UI conf file (koala_mvi_ui_conf.xml).

g If the new report is added to an existing UI conf file, it is not necessary to update the navigation tree.

<ui-conf>

<dbpool name=”pmwPool”>pmwPool</dbpool>

<report>exampleReport.xml</report>

</ui-conf>

16


Id:0900d805801dba02

KPI Library

2.5 Advanced Report Creation1 Create a new KPI, see 2.5.1

2 Create a new Counter, see 2.5.2

2.5.1 Create a new KPIAll KPI files are placed under the kpis folder in the /custom/”adaptation”/kpis folder.

A KPI file consists of:

– Temp table references– KPI definitions

The figure below is an example of a KPI definition.

Figure 8 KPI definition example

The temp table reference is created with the tag <temp_table_ref>. Which has the attribute src. The src attribute is used to identify the referenced table.

Example:

It is possible to add new counter aggregations to the referenced temp table.

Every KPI added to a KPI file is created within the <kpi> tag, this tag has the attribute name. The attribute name is the KPI id, the defined KPIs uses an official Nokia Siemens Networks naming convention.

g Max length of the KPI name is 30 characters, it is recommended to use lower case only and spaces are not allowed.

Example:

<kpi name=”sms_5”>

...

</kpi>

<conf_file>

<temp_table_ref src=”custom/bss/counters/resacc.xml”/>.

...

</conf_file>

17


Id:0900d805801dba02

The KPI formula must be defined within the <formula> tag. This is the actual formula used in the SQL query. Any functions of Oracle SQL can be used. A KPI can refer to counters defined in a temp_table or included temp_table_ref elements in the file containing the KPI.

The kpi_alias is a short descriptive name of the KPI. It is used in the report output header. It should be kept under 40 characters, spaces between words are encouraged as it improves the visual appearance of the final report.

Example:

<kpi_alias>SMS SDCCH establishment attempts</kpi_alias>

The <kpi_format> tag must follow the web script conventions, like float:2 and float:1.

The <kpi_mark> tag allows the user to color the background of the table output, there are four colors available (red, green, yellow or orange).

The example shown below marks all cells, within a KPI column, that have a value less than 80 with red. It also colors the cells with values greater or equal than 80 and less or equal than 95, with yellow.

Figure 9 kpi mark use example

Because it is a markup, according to Web script Framework the CDATA tag must be used to enclose the <markup> tag.

The <type> tag, attribute color defines what color to use.

18


Id:0900d805801dba02

KPI Library

The tag <term> has an attribute test which defines the condition for the markup, it also has the attribute value that defines the value for the condition check. There are six dif-ferent conditions that can be checked:

It is possible to combine different conditions, this is done with the <and> tag. Inside the <and> tag multiple <term> tags can be defined.

The <kpi_info> tag is defined within the <kpi> tag. The help information about the KPI is stored inside the <kpi_info> tag. The user can define five sub tags inside the <kpi_info>, see the following table.

Figure 10 kpi info use example

lt Less than

gt Greater than

ne Not equal

eq Equal

le Less than or equal

ge Greater than or equal

Tag Description

title Same as kpi_alias (see alias) or a longer and more descriptive title. If left empty, the kpi_alias is used as replacement.

use This is the main field for documenting the KPI, with a description and explanation.

formula Used for documentation in web pages. For formatted output it is allowed to use html formatting, the text and tags must be enclosed in a CDATA section. To preserve indentation it is possible to use the <pre> tag.

g If the user is using encapsulation by <pre> ... </pre>, all spaces count, so heading spaces must be avoided.

unit Defines the unit used in the KPI. This tag must be in brackets, like [%].

tables Defines the measurements used by this KPI.

Table 2 kpi info sub tags

19


Id:0900d805801dba02

2.5.2 Create a new CounterCounters are grouped together in counter files. Customer specific counters are stored in the /custom/”adaptation”/counters directory.

Every counter file contains a temp-table definition. The temp-table definition is defined by the <temp_table> tag. This tag has four attributes as described in the following table:

Each counter is created with the <counter> tag, and has one attribute, alias. The alias is the name used by the KPI to reference the counter.

The table name is given in the tag <table_name>, the exact table name to be used in the measurement can be found in the Reporting Suite documentation.

In the tag <alias_name> an alias for the temp table is created. This is used in the KPI definitions to refer to the temp table entry.

Figure 11 Counter example

If an <info> tag with sub-tags is added to the counter file, this file becomes indepen-dent and can be executed as a report file. This is a very useful for debugging purposes.

The Figure 12 is an example, where this is done. Instead of creating a KPI that uses the counter and a report file that includes that KPI, the counter can be tested directly, by adding the <info> tag to the counter file.

Attribute Description

meas_level The base level of the measurement, like PLM/BSC. The measu_level that is used in the measurement can be found in the Reporting Suite documentation.

name Used as ID of the temp-table. It defines the temp-table name when the QE is executed.

master If set to true this temp table is used as driver for the OUTER JOIN.

pragma Gives an instruction to the query engine to identify how the SQL is gen-erated.

Table 3 temp-table attributes

20


Id:0900d805801dba02

KPI Library

Figure 12 Counter example 2

report creation guide

Documents