Alerts Manual

7/31/2019 Alerts Manual

1/76

V7.5

iDashboards Aler t s Manual

Ver s ion 7 .5


2/76


3/76

V7.5

iDashboards Alerts Manual

Version 7.5

No part of the computer software or this document may be reproduced or transmitted in any

form or by any means, electronic or mechanical, including photocopying, recording, or by any

information storage and retrieval system, without permission in writing from iDashboards. The

information in this document is subject to change without notice. If you find any problems with

this documentation, pleased report them in writing to [email protected]. iDashboards

does not warrant that this document is error free.

Copyright 2004 - 2011 iDashboards. All rights reserved.

Trademarks:

The iDashboards logo and tagline are trademarks of iDashboards.

All other products and company names referenced herein are the trademarks of their respective

owners.

This product includes software developed by the Apache Software Foundation.

Support information:

iDashboards700 Tower Drive, Suite 400

Troy, MI 48098

Phone: (248) 528-7160Fax: (248) 828-2770

Email:[email protected]

Web site:http://www.iDashboards.com
mailto:[email protected]:[email protected]:[email protected]:[email protected]://www.idashboards.com/http://www.idashboards.com/http://www.idashboards.com/mailto:[email protected]:[email protected]


4/76


5/76

iDashboards Alerts Manual i

Table of Contents

VERSION 7.5 ......................................................................................................................................... 31 INTRODUCTION ........................................................................................................................... 7

1.1 ABOUT THIS MANUAL................................................................................................................ 71.2 SYSTEM OVERVIEW.................................................................................................................. 71.3 WHAT IS AN ALERT? .............................................................................................................. 81.4 TERMINOLOGY USED IN THIS MANUAL....................................................................................... 8

2 INSTALLATION .......................................................................................................................... 112.1 SYSTEM REQUIREMENTS........................................................................................................ 112.2 INSTALLATION ROADMAP ........................................................................................................ 122.3 CREATING THE IVIZGROUP HOME DIRECTORY........................................................................... 122.4 CONFIGURING IVIZGROUP.PROPERTIES ................................................................................... 13

2.4.1 RUNTIME LOCATION OF IVIZGROUP.PROPERTIES .............................................................. 132.4.2 CONFIGURATION OVERVIEW............................................................................................ 142.4.3 TROUBLESHOOTING ....................................................................................................... 152.5 INSTALLING THE LICENSE FILE ................................................................................................ 16

2.6 DEPLOYING THE APPLICATION ................................................................................................ 162.6.1 CHOOSING A CONTEXT ROOT ......................................................................................... 17

2.7 LOGGING INTO THE ALERTS SERVER CONSOLE ....................................................................... 173 SYSTEM CONFIGURATION ...................................................................................................... 19

3.1 SYSTEM SETTINGS................................................................................................................. 193.2 MODIFYING A SYSTEM SETTING .............................................................................................. 203.3 ALERT SETTINGS ................................................................................................................... 21

3.3.1 SERVER STARTUP STATE ............................................................................................... 213.3.2 ALERT INSTANCE RETENTION (DAYS) .............................................................................. 213.3.3 BROWSER ALERT CHECK INTERVAL (MINUTES) ............................................................... 213.3.4 MAXIMUM DISPLAYED ALERT INSTANCES......................................................................... 213.4 LOG SETTINGS....................................................................................................................... 223.4.1 GENERAL LEVEL ............................................................................................................ 223.4.2 XMLLOGGING ENABLED................................................................................................ 233.4.3 HTTPREQUEST LOGGING ENABLED............................................................................... 233.4.4 MAX FILE SIZE ............................................................................................................... 233.4.5 MAX BACKUP FILES........................................................................................................ 23

3.5 DOWNLOADING LOG FILES...................................................................................................... 233.6 SENDING LOG FILES TO IDASHBOARDS TECHNICAL SUPPORT .................................................. 233.7 BROWSER ALERT CHECKS ENABLED....................................................................................... 24

4 MANAGING SEVERITY LEVELS ............................................................................................... 254.1 ADDING A SEVERITY LEVEL..................................................................................................... 264.2 MODIFYING A SEVERITY LEVEL ............................................................................................... 274.3 DELETING A SEVERITY LEVEL ................................................................................................. 28

5 NOTIFICATION EMAIL SETTINGS ............................................................................................ 295.1 EMAIL CONFIGURATION ROADMAP .......................................................................................... 295.2 CONFIGURING THE SMTPSETTINGS....................................................................................... 295.3 CONFIGURING THE NOTIFICATION EMAIL SETTINGS.................................................................. 315.4 CONFIGURING THE EMAIL TEMPLATES ..................................................................................... 33

5.4.1 TEMPLATE DIRECTORIES ................................................................................................ 33


6/76

ii Table of Contents

5.4.2 TEMPLATE FILES ........................................................................................................... 345.4.3 HTMLSUPPORTING FILES ............................................................................................. 35

5.5 MAIL MACROS ....................................................................................................................... 355.5.1 ALERT MACROS............................................................................................................. 365.5.2 CHART MACROS............................................................................................................ 365.5.3 EVENT MACROS ............................................................................................................ 375.5.4 ERROR MACROS ........................................................................................................... 375.5.5 MISCELLANEOUS MACROS ............................................................................................. 38

6 SERVER OPERATION ............................................................................................................... 396.1 PAUSING AND RESTARTING THE SERVER ................................................................................ 406.2 UNDERSTANDING SERVER EVENTS......................................................................................... 40

6.2.1 EVENT ID ...................................................................................................................... 406.2.2 LEVEL ........................................................................................................................... 416.2.3 TIMESTAMP ................................................................................................................... 416.2.4 SUBJECT....................................................................................................................... 416.2.5 MESSAGE...................................................................................................................... 41

6.3 REFRESHING THE EVENT LIST ................................................................................................ 416.4 FILTERING THE EVENT LIST .................................................................................................... 416.5 TROUBLESHOOTING ERROR EVENTS ...................................................................................... 426.6 EVENT RETENTION ................................................................................................................ 43

6.6.1 QUALIFIED EVENT RETENTION........................................................................................ 436.7 EMAIL EVENTS ...................................................................................................................... 44

7 ALERT ADMINISTRATION ........................................................................................................ 457.1 RETRIEVING AN ALERT........................................................................................................... 46

7.1.1 SEARCHING BY ALERT ID ............................................................................................... 467.1.2 SEARCHING BY CHART ID .............................................................................................. 477.1.3 BROWSING FOR AN ALERT.............................................................................................. 48

7.2 MODIFYING AN ALERT ............................................................................................................ 487.3 IMPORTING AND EXPORTING CHARTS WITH ALERTS................................................................. 48

8 USER APPLICATION: CREATING ALERTS IN CHARTS ...................................................... 498.1 CONFIGURING ALERTS........................................................................................................... 50

8.1.1 CONFIGURE ALERTS MENU OPTION................................................................................ 508.1.2 ALERT CONFIGURATION ................................................................................................. 528.1.3 ALERT NOTIFICATIONS................................................................................................... 64

8.2 CHARTS WITH ALERTS ........................................................................................................... 668.3 ALERT NOTIFICATION SETTINGS ............................................................................................. 67

APPENDIX A DEPLOYING THE ALERTS SERVER TO TOMCAT ............................................. 69 I. ALTERNATE INSTALLATION PROCESS ...................................................................................... 70

APPENDIX B LOG CONFIGURATION ......................................................................................... 71


7/76

iDashboards Alerts Manual 7

1 Introduction

1.1 About this ManualSome of the information required for installing and administering the Alerts Server (such as

installing JDBC drivers) can be found in the iDashboards Administrators Manual; therefore

this manual should be used in conjunction with that one. It is assumed that the reader is

already familiar with the iDashboards Server and its basic architecture, and is familiar with

the repository database, etc. If not, please review the iDashboards Administrators Manual.

1.2 System OverviewiDashboards Alerts is a separate server from the iDashboards Server. Like the iDashboards

Server, the Alerts Server is J2EE web application, packaged in a WAR file. It is entirely

separate from the iDashboards Server web application. It can be deployed in the same

application server as the iDashboards Server, or in a different one running on the same or

different machine.

Figure 1-1 provides an overview of the Alerts Servers deployment environment. The Alerts

Server connects to the iDashboards repository database, which it reads and updates during

its operation. It also connects to the external data sources configured by the iDashboards

Server, for the purpose of reading and examining chart data.

An external SMTP service, such as UNIX Sendmail or Microsoft Exchange Server, is used

for sending notification emails. This component is optional, however; the Alerts Server can

operate without sending notification emails.


8/76

8 Chapter 1: Introduction

Figure 1-1

1.3 What is an Alert?The term alert can have different meanings in different contexts. At a general level, an

alert is a mechanism that notifies iDashboards users that certain conditions exist within chart

data. The term alert is sometimes used to refer to the notification itself, i.e. the item

appearing in a users alerts dashboard. It is also used to describe the configuration stored

in the repository that defines the conditions for an alert, its name and the message that is

displayed to users when the conditions are met.

1.4 Terminology Used in This ManualIn this section some of the terms used in this manual are defined.

Alert Unless its context suggests otherwise, the term alert, as used in this manual, will

refer to the configuration of an alert the conditions, name, severity level, message text,

etc. that is stored in the iDashboards repository database.

DataWarehouseData MartRDBMS

iDashboards

Repository

(RDBMS)

Browser (IE, Firefox)

HTML/JavascriptPages

Alerts Server Console

J2EE Application Server(Tomcat, Weblogic, WebSphere,

JBoss, etc.)

iDashboardsAlerts Server

(J2EE Web Application)

HTML/XML

over HTTP

Client SideServer Side

External Data Sources

JDBC

JDBC

JDBC JDBC

External User

Authentication Service

(MS Active Directory,

Novell eDirectory, etc.)

LDAPSMTP

Service

SMTP


9/76


Check An alert is checked by the alerts server according to a predefined schedule. This

means that the alerts server loads the data of the chart for which the alert was configured,

and evaluates it according to the alerts rules.

Fire If, during an alert check, the alert's rules are satisfied by the chart data, then the alert

is said to fire.

Instance When an alert fires, an instance of the alert is created. It is this instance that

appears in the alerts dashboard of the Flash-based iDashboards User Application.


10/76

10 Chapter 1: Introduction

This page intentionally left blank.


11/76


2 Installation

The iDashboards Alerts Server is a J2EE1 web application, which can be deployed to

virtually any J2EE compliant application server.2 A J2EE web application is packaged in a

WAR3 file with a .war filename extension. A WAR file is simply a compressed file in thecommon zip format, with a specific internal structure. A WAR file contains most or all of

the resources used by a J2EE web application, such as HTML files, image files, and Java

binary code. The Alerts Server WAR file is named idbalerts.war.

The iDashboards Alerts Server is an add-on to iDashboards. As such, it can function

effectively only in conjunction with an installation of iDashboards. The installation

process described in this document assumes that iDashboards has already been fully

installed; therefore, the steps for creating the repository database tables are omitted

from this document.

2.1 System Requirements Operating System - Microsoft Windows 2000 or higher, or any version of UNIX or

Linux for which a Java Virtual Machine is available.

Application Server - Any J2EE-compliant application server that supports at least

the Servlet 2.3 API and the JSP (Java Server Pages) 1.2 API. Any J2EE application

server released since 2003 should suffice. The Apache Tomcat application server,

which is bundled with iDashboards, is highly recommended.

Java - A Java Development Kit (JDK), version 1.5 or later, depending on the

requirements of the application server, must be installed on the server. A JDK

includes a Java Virtual Machine (JVM) to run the application server, and a Java

compiler, which is used to compile JSP pages. If the bundled version of Apache

Tomcat is used as the application server, then a Java Runtime Environment (smaller

than the JDK) version 1.5 or later can be used.

JDBC Drivers - JDBC (Java Database Connectivity) drivers for the repository

database, and any database used as the data source for a dashboard. JDBC drivers

are usually bundled with a database, or they can be downloaded for free from the

vendors website.

1http://support.idashboards.com/links/j2eereference

2The iDashboards Alerts Server must be deployed to an application server that supports at least the Servlet 2.3

and JSP 1.2 specifications, and runs on a version 1.5 or later Java Virtual Machine. Most application servers

released since 2003 should meet these requirements.

3WAR stands for Web ARchive.


12/76

12 Chapter 2: Installation

Browser - Internet Explorer 5.5 or above, Firefox or any other comparable browser

is required to access the Alerts Server console.

2.2 Installation RoadmapThe exact procedure for installing the iDashboards Alerts Server will vary from one

installation to the next, since a wide variety of application servers may be used. If it isbeing deployed to the same application server that is hosting iDashboards, then

section 2.3, 2.4, and 2.5 below may be skipped. Otherwise, the basic installation steps

are:

Create the ivizgroup home directory This is a directory where the Alerts Server

stores needed information. See section 2.3,Creating the ivizgroup home directory,

for more information.

Configure the ivizgroup.properties file This is a text file read by the Alerts

Server that contains information needed to connect to the repository database. See

section 2.4,Configuring ivizgroup.properties, for further information.

Install the iDashboards license file This file, named idashboards.lic, is provided

separately from the installation CD. It is read by the Alerts Server and must be

present for it to operate properly. See section 2.5,Installing the License File, for

more details.

Deploy the idbalerts.war file to the application server See section 2.6,

Deploying the Application for more information.

2.3 Creating the ivizgroup home directory

NOTE: If the Alerts Server is being deployed to the application server whereiDashboards has already been installed, this step may be skipped. The Alerts Server

will use the sameivizgroup home directory as iDashboards.

The ivizgroup home directory (also referred to as a folder) is where various files, such as

the license and configuration files, needed by the iDashboards Alerts Server and the main

iDashboards application are kept. In order for iDashboards to function properly, this

directory must exist and be readable.

The ivizgroup home directory must be manually created as part of the Alerts Server

installation if the alerts server in on a separate server than the main iDashboards

application. The default location is in the home directory of the user account under which

the iDashboards application server is running, and the default name is ivizgroup (all

lowercase). So for example, on a Windows system where the application server is running

as the Windows user tomcat, the ivizgroup home directory would be C:\Documents and

Settings\tomcat\ivizgroup.


13/76


The default location of the ivizgroup home directory can be overridden by setting a Java

system property4 called ivizgroup.home to the path of the ivizgroup home directory.

NOTE:Throughout the remainder of this document, will be used to

indicate the ivizgroup home directory.

After the location of the ivizgroup home directory has been established and created, threesubdirectories must be created within it:

1. \config This directory is where iDashboards configuration

files are kept.

2. \drivers JAR files containing JDBC drivers (explained in the

iDashboards Administrators Manual) can be stored in this directory, making them

available to the Alerts Server at runtime.

3. \logs This directory is where Alerts Servers log files are

written.

2.4 Configuring ivizgroup.propertiesNOTE: If the Alerts Server is being deployed to the application server where

iDashboards has already been installed, this step may be skipped. The Alerts Server

will use the same ivizgroup.properties file as iDashboards.

The ivizgroup.properties file is a plain text file read by the Alerts Server application. It

contains the information the Alerts Server needs to connect to the repository database and

the settings that control runtime logging.

2.4.1 Runtime location of ivizgroup.properties

By default, the Alerts Server will look for the ivizgroup.properties file in the \config directory. Both the name and the location of ivizgroup.properties can be

overridden, however, by setting a Java system property called ivizgroup.properties to the

path and filename of the alternate file.

The ivizgroup.properties file is in Java properties format, which has the following

characteristics:

1. Blank lines, and lines whose first non-whitespace character is # or ! are ignored.

(Lines beginning with # or ! can be used for comments.)

2. Other lines should adhere to the format:

name=value

4A Java system property is set on the command line that is used to start a Java Virtual Machine. For many J2EE

application servers, this command line will be contained within a startup script. A system property is set with

the switch -Dname=value, so for example, an alternate ivizgroup home directory might be set with the switch

-Divizgroup.home=C:\ivizgroup.


14/76


where name is the name (unique within the file) of a particular property, and valueis the value assigned to that property. Property names and values are both case-sensitive.

3. Although the Java properties format allows for leading and trailing whitespace in

property names and values (when properly escaped), neither property names norvalues in ivizgroup.properties should contain leading or trailing whitespace.

A template ivizgroup.properties file is located in the config directory of the installation CD.

The names of the properties needed by iDashboards are included in the supplied file, along

with instructional comments.

2.4.2 Configuration overview

The Alerts Server actually uses a pool of at least three connections to the repository

database. There are two possible ways the Alerts Server gets access to a pool of repository

database connections:

1. Server-Managed Connection Pool The Alerts Server uses a connection pool

created and managed by the J2EE application server. (This may be referred to as a

DataSource in the servers documentation.) This option is for advanced users.

2. iDashboards-Managed Connection Pool The Alerts Server creates and

manages its own connection pool. This is the recommended option for most users.

2.4.2.1 Using a server-managed connection pool

If a server-managed connection pool is used, it must be accessible through the application

servers naming and directory service, which can also be referred to as the servers JNDI

(Java Naming and Directory Interface) service. Such a connection pool is given a JNDIName, which web applications can use to access it. To use a server-managed connection

pool, only a single setting is needed in ivizgroup.properties:

db.jndiName=

An example entry might look like:

db.jndiName=idbRepository

2.4.2.2 Using an iDashboards-managed connection pool

It is important to note that the presence or absence of the db.jndiName property in

ivizgroup.properties determines whether or not the Alerts Server will use a server-managed

connection pool. If such an entry is present, iDashboards will always try to look up and

use a connection pool by that name, and it will fail if one is not available. If iDashboards is

to create and use its own connection pool, then the db.jndiName setting must be

removed or commented out of ivizgroup.properties.

To make the Alerts Server create and manage its own pool of connections to the repository

database, four settings are needed in ivizgroup.properties:


15/76


db.user=

db.password=

db.driverClass=

db.url=

Additonally, three optional properties may be specified:

db.maxConnections=

db.validateConnections=

db.password.encrypted=

The db.user and db.password properties are the credentials used to connect to the

repository database. As mentioned in the iDashboards Administrators Manual, the

database user account that the Alerts Server connects with must have SELECT, INSERT,

UPDATE and DELETE privileges on the repository tables.

The db.driverClass and the db.url properties depend on the type of database and the

JDBC drivers used to connect to it. The documentation for the JDBC drivers should be

consulted when entering values for these properties. For information on JDBC drivers, seeAppendix A of the iDashboards Administrator's Manual.

The db.maxConnections property indicates the maximum number of connections that will

be created by an iDashboards-managed connection pool. If this property is missing or

blank, a default value of 20 will be used. Connections will only be created and added to the

pool on an as-needed basis, so the maximum number of connections may never be reached

unless the Alerts Server console is being simultaneously accessed by many users.

The db.validateConnections property indicates whether or not connections should be

tested when they are returned to the connection pool after use. If true, then a test query will

be run on each connection when it is returned to the connection pool, and if it fails, theconnection will be considered dead and removed from the connection pool. Since there is

a small performance cost associated with testing connections, this property should be set to

true only in cases where the repository database may go temporarily offline while the Alerts

Server remains online.

The db.password.encrypted property is set to true to indicate that the password set with

the db.password property has been encrypted with the idb_encrypt tool. This is a

command line tool shipped with iDashboards that can encrypt a password, so it can be

included in the ivizgroup.properties file without being revealed to unauthorized persons who

may have access to the file. If the value for db.password.encrypted is anything other than

true (case-insensitive), then the password is assumed to be in cleartext. For information onencrypting passwords with idb_encrypt, see the iDashboards Administrator's Manual.

2.4.3 Troubleshooting

The first step in troubleshooting problems with ivizgroup.properties is to make sure that

iDashboards is able to locate it at runtime. Although you wont be able to login and use

iDashboards until ivizgroup.properties has been properly configured, you will be able to view

the Alerts Server consoles login screen, which, if the suggested defaults have been used,


16/76


should be at http:///idbalerts.5 The path to the ivizgroup.properties file is also

displayed on this screen, along with a Reload link that will reread the contents of the file.

The Reload link should only be used while troubleshooting problems with the

ivizgroup.properties file or connecting to the repository database. Once a connection to the

repository database has been established, hitting the Reload link will have no effect on the

current connection, and any changes to the connection properties will require a server

restart to take effect.

2.5 Installing the License FileNOTE: If the Alerts Server is being deployed to the application server where

iDashboards has already been installed, this step may be skipped. The Alerts Server

will use the license file from the same location as iDashboards.

In order for iDashboards to function properly, the iDashboards license file, named

idashboards.lic, should be copied to the directory. The default

location of the license file, however, can be overridden. iDashboards looks for the licensefile in the following locations, in the order listed, and the first one it finds will be the one

used:

1. It will search the application servers Java classpath6 for a file named

idashboards.lic.

2. It will check for a Java system property called idashboards.license, which, if

present, must be set to the full path (including filename) of the idashboards.lic file.

3. It will check in the directory for a file called idashboards.lic.

4. It will check in the current working directory of the J2EE application server for a filenamed idashboards.lic.

After iDashboards has located and read the license file, its location will be displayed near

the bottom of the iDashboards administrative login screen.

2.6 Deploying the ApplicationThe idbalerts.war file is located in the bin directory on the installation CD. The procedure

used to deploy the WAR file depends on the type of J2EE application server used. Since

the Alerts Server can be installed on a variety of different application servers, it would be

impossible to document here the exact steps required for each one. Deployment of a WAR

file is usually a straightforward process, however, which should be thoroughly explained inthe application servers documentation. The process may involve copying the WAR file to a

5The URL for the administration login screen may vary according to how your application is deployed. See

section 2.6,Deploying the Application for more information.

6An explanation of the Java classpath is beyond the scope of this document, and installing the idashboards.lic

file in the Java classpath is not recommended.


17/76


specific directory and restarting the server, or uploading the WAR file to the application

server through a web interface. Some manual editing of server configuration files may be

required.

Note:If the bundled version of Apache Tomcat is being used as the application server, the

deployment process is documented inAppendix A of this manual.

2.6.1 Choosing a Context Root

Regardless of the application server used to host the Alerts Server, it must be assigned a

context root within the servers URL space. Conceptually, the context root can be thought

of as a subdirectory beneath the servers root URL, which forms the root of the web

applications URL space. This allows multiple web applications from different sources to be

deployed to the same application server without URL conflicts.

It is recommended that /idbalerts be used as the context root for the iDashboards web

application. Since the Alerts Server WAR file is named idbalerts.war, some application

servers (such as Tomcat) will automatically default its context root to /idbalerts, so

choosing that can simplify the deployment process.

2.7 Logging into the Alerts Server ConsoleAfter the alerts server has been deployed to the application server, the Alerts Server

console can be logged into through a Web browser. If the application server is running on

intranet.mycompany.com, and /idbalerts was used as the context root, the URL for the

Alerts Server console login screen (shown in Figure 2-1) would be:

http://intranet.mycompany.com/idbalerts

If the application server is listening for connections on a port other than 80, the port number

must be included in the URL For example, the default port used by Apache Tomcat is 8080,which would make the URL:

http://intranet.mycompany.com:8080/idbalerts

Any iDashboards user account with the admin role can log into the Alerts Server console.


18/76


Figure 2-1


19/76


3 System Configuration

Various aspects of the Alerts Server can be controlled through the system configuration

screens of the Alerts Server console. Some of these aspects, such as severity levels, are

discussed in detail in other chapters of this manual; those that do not merit an entire chapterare discussed here.

The system configuration screens are accessed by clicking SYSTEM on the application

menu, as shown in Figure 3-1.

Figure 3-1

3.1 System SettingsSystem settings are global settings used to control the Alerts Servers behavior. They are

managed through the System Settings screen, which is the first screen displayed when

SYSTEM is clicked on the application menu. The System Settings screen can also be

accessed by clicking the System Settings tab that appears on the other systemconfiguration screens.

System settings are grouped according to their function into setting categories. A dropdown

list of the available setting categories appears near the top of the System Settings screen.

When a category is selected, a list of the system settings for that category appears on the

System Settings screen as shown in Figure 3-2.


20/76

20 Chapter 3: System Configuration

Figure 3-2

3.2 Modifying a System SettingThe three categories of system settings are:

1. Alerts

2. Notification Email Settings (covered in Chapter 5,Notification Email Settings)

3. SMTP Settings (covered in Chapter 5,Notification Email Settings)

To modify a system setting, click its Edit icon ( ). A form similar to the one shown in

Figure 3-3 will appear through which the setting can be edited. For most system settings,

the value must be entered into a textbox, while for others, the value can be selected from a

dropdown list. The edit form for a system setting will include a description of that setting and

its valid values.

After a system setting has been modified, click the Save button to save the changes, or

Cancel to discard the changes and return to the system settings screen.


21/76


Figure 3-3

3.3 Alert SettingsNotification email settings and SMTP settings are discussed in other chapters of this

manual. The settings in the Alerts category are discussed below.

3.3.1 Server Startup State

This setting determines the initial state of the server upon startup. The two possible values

are:

1. Running (default) The Alert Monitor Thread will be started, and the server will check foralerts according to its schedule.

2. Paused The Alert Monitor Thread will be in the paused state when the server starts up. Itwill need to be started manually through the STATUS screen of the Alerts Admin application.

3.3.2 Alert Instance Retention (Days)

This setting indicates the number of days an alert instance will be kept before it "ages out" of

the alert queue and is deleted from the repository database. Allowable values are from 1 to

9999. If the setting is left blank, then alert instances will remain in the queue indefinitely.

Note:This setting will not remove or alter alert configurations. The default is null.

3.3.3 Browser Alert Check Interval (Minutes)

This setting indicates the interval, in minutes, in which a users Alerts dashboard will check

for new alert instances. Allowable values are from 1 to 60. The default is 1 minute.

3.3.4 Maximum Displayed Alert Instances

This setting indicates the maximum number of alert instances that will be displayed in a

user's Alerts dashboard. If the number of alert instances for a user exceeds this maximum,

the newest ones will be given priority. Allowable values are from 20 to 200.The default is 50

instances.


22/76


3.4 Log SettingsLog settings are managed through the Log Settings screen. The Log Settings screen can

be accessed by clicking the System Logs tab on any of the system configuration screens

where it appears (see Figure 3-4).

Figure 3-4

When the iDashboards server is started, the initial log settings are read from theivizgroup.properties file, and if they are not present, the defaults shown in Figure 3-4 are

used. Once the server has been started, the settings can be changed through the Log

Settings screen, however, changes made will not persist beyond a server restart. Under

normal operating circumstances, the settings shown in Figure 3-4 should be used.

Changes made to log settings are not applied until the Apply button has been clicked. The

available settings are:

3.4.1 General Level

This setting determines the types of log messages that will be written to the log file. Each

level can be thought of as a threshold, with Debug being the lowest and Error the highest.When a level is selected, all messages categorized at that level and abovewill be written to

the log. The available levels are as follows:

Debug This is the most verbose setting, and could impact system performance ona busy server. Debug log messages are generally only useful to an iDashboardssupport representative, so this level should only be used when troubleshootingproblems.


23/76


Info (default) This is a far less verbose level than Debug, which writes informationabout the operating environment to the log when the iDashboards server is started.It is the recommended level for normal operations.

Warn In addition to error messages, this level will write warning messages aboutserver events that are noteworthy but not critical.

Error This is the least verbose log level. It will only write messages to the logwhen a critical error occurs.

3.4.2 XML Logging Enabled

When this checkbox is checked, XML that passes between the Alerts Server Console

screens and the server is written to the log file. It causes very verbose output which is only

useful to an iDashboards support representative, so it should remain unchecked except for

troubleshooting purposes. The default is unchecked.

3.4.3 HTTP Request Logging Enabled

When this checkbox is checked, information about the HTTP requests that are sent to the

Alerts Server from the Alerts Server Console screens is logged. As is the case with XML

logging, it causes very verbose output which is only useful to an iDashboards support

representative, so it should remain unchecked except for troubleshooting purposes. The

default is unchecked.

3.4.4 Max File Size

This is the maximum size to which a log file will be allowed to grow before it is overwritten by

a new one or archived. The default is 10Mb.

3.4.5 Max Backup Files

This setting indicates the maximum number of archived log files that will be kept. When an

active log file, named idbalerts.log grows to its maximum allowed size, it will be renamedwith to idbalerts.log.1 and a new idbalerts.log file will be started. If there is already a file

named idbalerts.log.1 in the logs directory, it will be renamed idbalerts.log.2, and so on, up

to the maximum number of archived log files. When the maximum number has been

reached, the oldest archived log file will be discarded. The default is 10.

3.5 Downloading Log FilesThe active log file (idbalerts.log) and any existing archived log files (idbalerts.log.1,

idbalerts.log.2, etc.) can be downloaded through the Log Settings screen. To do so, select

the desired files from the list at the right of the screen and click the Download button.

The selected files will be bundled into a ZIP file by the server and downloaded.

3.6 Sending Log Files to iDashboards Technical SupportWhen working with iDashboards technical support to troubleshoot problems with the Alerts

Server, it is useful to provide the Alerts Servers log file(s) to the support representative.

Problems can be diagnosed and corrected more expeditiously if these steps are followed

prior to contacting iDashboards technical support:


24/76


1. Set the General Level to Debug, and enable XML logging and HTTP Request

Logging.

2. Recreate the error condition through the User Application or the appropriate

Administrator Application screen.

3. Download the idbalerts.log file, and the idbalerts.log.1 file if it exists, as described insection 3.5,Downloading Log Files.

4. Email the ZIP file containing the log file(s), along with a description of the problem

(and steps to recreate it if possible) [email protected].

3.7 Browser Alert Checks EnabledThis setting can be found in the iDashboards Administrator Application, under the SYSTEM

tab. Note that this is different from the Alerts Administrator Application that has been

discussed so far in this chapter. This setting determines whether or not browsers will

contact the iDashboards server periodically to check for new alerts. The default setting is

TRUE; however it can be set to false when the Alerts server is offline for an extended period

of time, to reduce the load on the iDashboards server. This setting is sent to a user's

browser upon login, so changing it will have no effect on active login sessions.

Figure 3-5
mailto:[email protected]:[email protected]:[email protected]:[email protected]


25/76


4 Managing Severity Levels

Every alert has a severity level associated with it, which indicates whether the news brought

by the alert is good or bad, and to what degree it is good or bad. A severity level is

represented by an integer value from 0 to 999. Although the meaning associated with aseverity level is determined by the administrator who configures it, the suggested convention

is that lower numbers (0-499) should be used to indicate bad news the lower the number,

the worse the news and higher numbers (500-999) indicating good news the higher the

number, the better the news.

In addition to its integer value, a severity has two other important attributes:

The severity name a short name, for example Crisis or Monthly Sales GoalsReached.

The severity color a color that is displayed on alert notifications.The name and color associated with a severity level can be changed, but its integer value

cannot.

In its default configuration, the Alerts Server provides four built-in severity levels:

Level Name Color

300 Crisis Red

400 Caution Yellow

600 Good Blue

700 Excellent Green

Figure 4-1

These levels cannot be deleted; however their names and colors can be changed.

In addition to the default severity levels, an administrator can add new ones and delete

existing (non-built-in) ones.

Severity levels are managed through the Severity Levels screen. To access the Severity

Levels screen, select SYSTEM from the application menu, as shown in Figure 4-2, and then

click the Severity Levels tab as shown in Figure 4-3.


26/76

26 Chapter 4: Managing Severity Levels

Figure 4-2

Figure 4-3

4.1 Adding a Severity LevelTo add a severity level click the Add New button on the Severity Levels screen. This will

open the Severity Level edit screen, shown in Figure 4-4. Enter an integer value from 0 to

999 for the severity level, and a name consisting of from one to 50 characters.

The severity color is defined as a mixture of red, green and blue component colors. Enter

an integer value from zero to 255 for each component color, or click and drag on the colors

slider bar to set its value. The severity color will be displayed in the preview box to the right

of the slider bars.

The red, green, and blue values that make up a color are often referred to collectively as the

colors RGB value. RGB values are often expressed as three concatenated 2-digit

hexadecimal numbers, representing the red, green and blue values respectively. For

example, a color with the red, green and blue values of 255 (FF in hexadecimal), 127 (7F in

hexadecimal) and 0 (00 in hexadecimal) would be expressed as FF7F00 in hex RGB format.


27/76


In HTML, a hex RGB value is usually preceded by a pound sign (#), for example #FF7F00

.

After the Severity Level Edit screen has been completed, click the Save button to save the

new severity level, or the Cancel button to dismiss the screen without saving it.

Figure 4-4

4.2 Modifying a Severity Level

To modify a severity level, click its Edit icon ( ) on the Severity Levels screen. This will

open the Severity Level Edit screen, through which the severity levels attributes (other than

its integer value) can be modified.

To save the changes, click the Save button, or click the Cancel button to discard the

changes and dismiss the screen. Clicking the Reset button will discard the changes, but

keep the Severity Level Edit screen displayed.

Note:Any changes made to a severity level will be visible on any alerts that have a severity

level, and all instances of those alerts.


28/76

28 Chapter 4: Managing Severity Levels

4.3 Deleting a Severity LevelSeverity levels can be deleted, provided that: a.) they are not one of the four built-in severity

levels shown in Figure 4-1, and b.) no existing alerts are using them as their severity level.

The numbers of alerts that are using each severity level are shown in the Alerts column on

the Severity Levels screen.

To delete a severity level, click its Delete icon ( ) on the Severity Levels screen. If it is not

a built-in severity level, and there are no alerts using it, it will be deleted immediately

(without confirmation); otherwise, the operation will fail with a warning message.


29/76


5 Notification Email Settings

The iDashboards Alerts Server is capable of sending emails in response to certain events.

The three types of emails sent are:

Alert Notifications An alert can be configured so that an email is sent to itsrecipients when the alert is fired.

Server Event Notifications These emails are sent to a predefined list of emailaddresses (which presumably belong to server administrators) when certain routine(non-error) server events occur, such as the startup or shutdown of the server.

Server Error Notifications These emails are sent when certain types of errorsoccur on the server, such as a database error during an alert check. They are sentto the same email addresses that receive server event notifications.

5.1 Email Configuration RoadmapFor the alerts server to send email notifications, it must first be properly configured. The

overall steps to accomplish this are:

Configure the SMTP (Simple Mail Transfer Protocol) Settings Notification

emails are sent through an external SMTP service, such as UNIX Sendmail or

Microsoft Exchange Server. The Alerts Server must be configured with enough

information to connect to, and if necessary, authenticate itself to the SMTP service.

Configure the Notification Email Settings These settings include information

such as the name and email address used in the from header of outgoing emails,

the list of email addresses that will receive server event notifications, and theinformation that is included in the subject lines of notification emails.

Configure the Email Templates This is an optional step that provides a great deal

of control over the information included in the bodies of notification emails. Using

email templates, notification emails can be sent in both HTML format (including

images) and plain text. If this step is omitted, emails will be sent as plain text and

include only a minimal amount of default information.

The following sections describe the above steps in greater detail.

5.2 Configuring the SMTP SettingsAs mentioned previously, the iDashboards Alerts Server uses an external SMTP service to

send emails. The settings needed to connect to the SMTP service are entered through the

system settings screen. To access this screen, select SYSTEM from the application menu

as shown in Figure 5-1:


30/76

30 Chapter 5: Notification Email Settings

Figure 5-1

On the system settings screen, select SMTP Settings from the Setting Category dropdown

as shown in Figure 5-2:

Figure 5-2

On the SMTP Settings screen (see Figure 5-3), enter the following settings:

SMTP Host This is the hostname or IP address of the machine on which the SMTPservice is running.

SMTP Port This is the number of the TCP/IP port on which the SMTP service islistening. (The standard SMTP port number is 25.)

SMTP Service Requires Authentication Set this to Yes if the SMTP servicerequires authentication or incoming connections, or to No if it does not.

SMTP Service User If the SMTP service requires authentication, this setting must

contain the username of the user that will be used to connect to it, otherwise itshould be left blank.

SMTP Service Password If the SMTP service requires authentication, this settingmust contain the password that will be used to connect to it, otherwise it should beleft blank.


31/76


SMTP Encryption This setting determines the type of encryption (if any) used tosecure the connection with the remote mail server. The options are None, SSL(Secure Socket Layer) and TLS (Transport Layer Security).

Figure 5-3

5.3 Configuring the Notification Email Settings

The settings for notification emails are entered through the System Settings screen. Toconfigure the settings select Notification Email Settings from the Setting Category dropdown

(see Figure 5-4):

Figure 5-4

On the Notification Email Settings screen (see Figure 5-5), enter the following settings:


32/76


Notification Email Enabled If this setting is No, then all email notifications, for

alerts and server event notifications, will be disabled. If it is Yes, then the settings in

the SMTP Settings category must be properly configured to connect to the SMTP

Service.

Notification Email "From" Address This setting must be a valid email addressthat will appear in the "From" header of notification email messages, for example

"[email protected]". This setting is required if email notifications are enabled.

Notification Email "From" Name This optional setting is the name that will appear

before the email address in the "From" header of notification email messages, for

example "iDashboards Alerts".

Alert Notification Subject This optional setting is a string that will be used to build

the subject line for alert notification emails. Mail macros can be used in this setting;

See Section 5.5,Mail Macros for information on mail macros.

Server Events Notification Threshold This setting determines what types of

server events will generate emails to the addresses listed in the Server Events

Notification List setting. The higher in the list a selection is, the fewer notification

emails will be sent. Selecting "Disabled" will turn off all email notification of server

events.

Since a selection represents a threshold, each selection implicitly includes the ones

above it.

Server Events Notification List This setting is a list of email addresses that will

receive notifications of server events, both error and non-error. Each email address

should be on a separate line. Email addresses may be in plain format, for example:

[email protected]

or in any RFC822-compliant format, for example:

"Jane C. Smith"

The combined length for all email addresses, including end-of-line characters, must

not exceed 500 characters.

Server Event Subject This optional setting is a string that will be used to build thesubject line for non-errorserver event notification emails. Mail macros can be used

in this setting; See Section 5.5,Mail Macros for information on mail macros.

Server Error Subject This optional setting is a string that will be used to build the

subject line for error-levelserver event notification emails. Mail macros can be used

in this setting; See Section 5.5,Mail Macros for information on mail macros.


33/76


Figure 5-5

5.4 Configuring the Email TemplatesEmail templates are text files that can be used to control the content and layout of

notification emails. Through the use of email templates, notification emails can be sent in

HTML format (with images), plain text, or a combination of both.

5.4.1 Template DirectoriesWhen the alerts server sends a notification email it will look in the template directory

corresponding to the type of notification it is sending, and if the directory exists and contains

a template file, it will use that template file to construct the email.

Template directories are located within the directory /templates/idbalerts. The name of a template directory determines the type of

notification email it is associated with. The three possible template directories are:

/templates/idbalerts/alerts This directory holds the

template files for alert notification emails-the emails sent to an alerts recipients when

the alert fires.

/templates/idbalerts/events The template files in this

directory are used for the emails sent to notify administrators of normal (non-error)

server events, such as server startup and shutdown.


34/76


/templates/idbalerts/errors The template files in this

directory are used for the emails sent to notify administrators of errors that occur on

the server.

The template directories are not created as part of the regular install process; rather they

must be created manually on the server. The location of the directory is displayed on the home screen of the Alerts Server Console:

Figure 5-6

5.4.2 Template Files

Once the template directories have been created, the template files can be prepared and

placed inside them. One or both of the following files may be used:

template.txt This is the template file used for plain text email messages. It should

contain the text of the corresponding notification email in plain-text format, including

line breaks where appropriate.

template.html This is the template file used for HTML email messages. It should

contain the text of the corresponding notification email in HTML format.

It is the presence or absence of these template files that determines what type of email issent:

If neither template file is present, emails will be sent in plain-text format using the

default content.

If only template.txt is present in a template directory, emails will be sent in plain-text

format, using content defined in template.txt.

If only template.html is present in a template directory, then emails will be sent only

in HTML format, using content defined in template.html.

If both template.txt and template.html are present in a template directory, emails will

be sent as multipart/alternative MIME messages that include both the plain text and

HTML messages, and mail readers can choose which to display based on their

capabilities.

Sample template files are included on the distribution CD-ROM, in the file templates.zip,

which is located in the templates directory. To install these sample templates, unzip the


35/76


templates.zip file in the directory, making sure that the directory

structure inside the templates.zip file is preserved.

Information specific to a particular alert, event or error can be included in a notification email

through the use of mail macros, which are explained in Section 5.5,Mail Macros.

5.4.3 HTML Supporting Files

As previously mentioned, HTML messages may include images, as well as other supporting

files such as cascading stylesheets. To include these within an HTML message, place them

into the appropriate template directory, and they will be included with the notification email

as attachments. The following table lists the types of files that may be included:

Filename Extension(s) MIME type File Type

.gif image/gif Image

.jpg, .jpeg image/jpeg Image

.png image/x-png Image

.css text/css Cascading Stylesheet

Figure 5-7

Within an HTML template, URLs that reference attachments should consist of the bare

filename of the attachment, for example:

div.banner {background-image:url(banner.gif); background-repeat:no-repeat;}

HTML messages may also display images that are not attached to the message, but rather

loaded from a remote server, for example:

It should be noted that many email readers restrict the display of images in HTML messages

as a security precaution.

5.5 Mail MacrosMail macros are used to include information about a particular alert or event in a notification

email pertaining to that alert or event. A mail macro is a special string of characters thatbegins with ${ followed by a specific keyword, and ends with }. An example of a mail

macro is:

${ALERT_NAME}

When the alerts server sends a notification email based on a template file, it will first scan

the contents of the template file for mail macros, and replace each one it finds with what is


36/76


referred to as its expanded value. In the case of the ${ALERT_NAME} macro, the

expanded value would be the name of the alert to which the notification email pertains.

The subject lines of notification emails, as configured in the System Settings screen, are

also scanned for the presence of mail macros, and any that are found are expanded

appropriately.

Not every macro has an expanded value for every type of email. For instance, the

${ALERT_NAME} macro would not be available in an email notifying an administrator that

the server is shutting down, since no specific alert would be associated with that event.

When a macro has no actual expanded value, it is replaced with a zero-length string.

Mail macros are case-insensitive, so ${alert_name} would be equivalent to

${ALERT_NAME} in template files or subject lines. The suggested convention, however, is

to use all uppercase letters for mail macros to make them more visible.

In the remainder of this section, the various mail macros that may be used in template files

are described.

5.5.1 Alert Macros

Alert macros can be used to include information about an alert in its notification emails. This

information is also available in error notification emails, when an error is related to a

particular alert; therefore alert macros should also be used in error notification templates.

${ALERT_ID} Alert ID.

${ALERT_NAME} Alert name.

${ALERT_MESSAGE} Alert message.

${ALERT_DESCR} Alert description.

${SCHEDULED_CHECK_TIME} The time at which the alert was scheduled to be checked.

${ACTUAL_CHECK_TIME} The time at which the alert was actually checked.

${ALERT_VISIBILITY} The alerts visibility (Public for non-private alerts, or Privatefor private alerts.)

${SEVERITY} The alerts severity level (the numeric value.)

${SEVERITY_NAME} The name given to the alerts severity level.

${SEVERITY_RGB} The severity color, in HEX RGB format, suitable for use inHTML emails. An example would be FF0000.

${SEVERITY_RGB_INVERT} The bit-wise inverse of the alert's severity color, in HEX RGB

format. In many cases, this is suitable for use as a foregroundor background color in contrast with the severity color.

5.5.2 Chart Macros

Chart macros can be used to include information about an alerts associated chart in its

notification emails. This information is also available in error notification emails, when an

error is related to a particular alert.

${CHART_ID} Chart ID.


37/76


${CHART_TITLE} Chart title.

${CHART_NAME} Chart name (what is displayed for the chart in the Chart Opendialog.)

${CHART_CATEGORY} Name of the chart's category.

5.5.3 Event Macros

Event macros can be used in any email sent by the iDashboards Alerts Server to notify

administrators of a server event, either a normal event (such as the server starting) or an

error event.

${EVENT_ID} This is the ID used to identify this type of event. This valueappears in the Event ID column on the Server Status screen.

${EVENT_SUBJECT} A short phrase describing the type of event. This appears in theSubject column of the Server Status screen.

${EVENT_MESSAGE} A message specific to this individual event. This appears in theMessage column of the Server Events screen.

${EVENT_LEVEL} The "Level" of the event, either INFO, WARNING or ERROR.${EVENT_QUEUE_ID} This is a string consisting of the Event ID, possibly followed by

additional characters that more specifically identify the type ofevent. This string is used internally by iDashboards and isgenerally not useful to administrators or end users.

${EVENT_MAX_EMAILS} This is the maximum number of emails that will be sent forevents with a particular Event Queue ID. A value of 0 or belowindicates there is no limit, and an email will be sent for eachoccurrence of the event with the given Event Queue ID. This isused to prevent an administrator from receiving numerousidentical emails related to a server error that occurs over andover again.

${EVENT_TIMESTAMP} This is the date and time when the event occurred.

5.5.4 Error Macros

Error macros can be used in any error notification email.

${ERROR_MESSAGE} This is the error message constructed by the iDashboardsAlerts server.

${EXCEPTION_NAME} If the error was the result of a Java "exception", this is the nameof the exception class. This information is useful toiDashboards support personnel when troubleshooting a servererror.

${EXCEPTION_MESSAGE} This is the error message provided by the Java exception, if one

exists.${EXCEPTION_STACKTRACE } This is the "stacktrace" of the Java exception, which shows the

exact point in the server code where the error occurred. Thisinformation is useful to iDashboards support personnel whentroubleshooting a server error. If this macro is included in anHTML template file. It should be placed between tags to make it more readable.


38/76


5.5.5 Miscellaneous Macros

These macros can be used in any email sent by the iDashboards Alerts Server.

${SERVER_NAME} The hostname of the machine on which the iDashboards AlertsServer is running.

${TEMPLATE_DIRECTORY} The path to the directory where the template file used toconstruct the notification email is located.

${DOLLAR} This macro always expands to a dollar sign. It can be usedwhen an email needs to contain the literal string ${".


39/76


6 Server Operation

Within the regular iDashboards Server, nothing much happens unless a user or

administrator does something in a browser that causes a request to be sent to the server.

Otherwise, it sits idle, waiting for user input.

The Alerts Server is different. Even when there are no administrators logged in, the server

can be busy, checking alerts, creating alert instances, sending notification emails, etc. If an

error occurs on the regular iDashboards Server, it is usually in response to some user

action, and is immediately noticed by the user. Within the Alerts Server, however, an error

can occur at any time and go unnoticed, and as a result, alerts might fail to fire when they

should.

The Alerts Server provides a window through which its inner workings can be observed.

This window is the Server Status screen of the Alerts Server console. To access it, click

Server Status in the application menu, as shown in Figure 6-1. This screen will show a listof server events (see Figure 6-2).

Figure 6-1

Figure 6-2


40/76

40 Chapter 6: Server Operation

6.1 Pausing and Restarting the ServerAt any given moment, the Alerts Server will be in one of two possible states:

Running In this state, the Alerts Server is performing all of its normal activities,

such as alert checks, sending notification emails, etc.

Paused In this state, the Alerts Server does not perform activities such as alert

checks or sending notification emails, however, the Alerts Server console is still fully

functional.

In its default configuration, the Alerts Server enters the running state when it is started.7

When it is in the running state, the Server Status screen will display the line, Current State:

RUNNING, and the rightmost button (referred to herein as the toggle button) will be labeled

Pause Server. A running server can be paused by clicking the toggle button.

When the Alerts Server is in the paused state, the Server Status screen will display Current

Status: PAUSED and the label on the toggle button will say Start Server. It can be placed

back into the running state by clicking the toggle button.

Normally, the Alerts Server should be left in the running state. The paused state is generally

only useful when performing troubleshooting or certain configuration changes.

6.2 Understanding Server EventsThe most prominent feature of the Server Status screen (shown in Figure 6-2) is the list of

server events. A server event can be any type of noteworthy occurrence, such as the server

being paused or a database error. A server event has the following attributes:

6.2.1 Event ID

Each server event is assigned a code referred to as the event ID, which identifies the typeof event that it is. And event ID consists of an event category, such as MONITOR, and a

number, separated by a hyphen.

The event category is used to identify approximately where in the system the event

occurred. For example, the MONITOR category is for events that occur on the monitor

thread, which is the main thread that runs continually inside the server, checking alerts and

performing other tasks.

The number portion of the event ID uniquely identifies the type of event within an event

category. For example, MONITOR-7 is the event ID used to indicate that a routine alert

check occurred.

7The initial state can also be set to paused through the Server Startup State system setting. See section 3.3,

Alert Settings, for more information.


41/76


6.2.2 Level

Each server event has one of the following three levels:

INFO This level is used for routine events. INFO-level events are displayed in

green text in the event list.

WARNING This level is for events that occur during normal operation, but should

be noted by a server administrator. WARNING-level events are displayed in the

yellow text in the event list.

ERROR This level is used for abnormal, unexpected events such as a database

error that occurs during an alert check. ERROR-level events are displayed in red

text in the event list.

6.2.3 Timestamp

The event timestamp is the date and time at which the event occurred.

6.2.4 SubjectThe event subject is a short phrase describing the event.

6.2.5 Message

The event message is a short sentence that contains information about the event.

6.3 Refreshing the Event ListTo refresh the event list and display the events that have occurred since the screen was

loaded or was last refreshed, click the button labeled Refresh.

The event list can also be made to automatically refresh at a specific interval, by selecting

the interval from the dropdown labeled Autorefresh Rate.

The freshness of the event list is indicated by the timestamp labeled Last Refresh. This

timestamp represents the servers system time when the event list was last refreshed.

6.4 Filtering the Event ListThe event list can be filtered to only display events of certain, selected levels. This is

accomplished by checking or unchecking the checkboxes for the different event levels that

appear just above the event list, as shown in Figure 6-3.

Figure 6-3


42/76


6.5 Troubleshooting Error EventsIn some cases, an ERROR-level event displayed in the event list may contain hyperlinks to

other screens that display additional information about the error or the alert it is associated

with.

For example, if the events level code, ERROR, is followed by (!) (Figure 6-4) theexclamation mark can be clicked on to display the Java stacktrace that was generated by

the error.

Figure 6-4

Although stacktraces appear undecipherable to almost anyone other than Java developers,

they usually provide clues as to the cause of an error. For example, the stacktrace shown in

Figure 6-5 says Connection timed out, indicating that the Alerts Server was unable toconnect to the SMTP service to send notification emails.

A stacktrace can also be copied and pasted into an email [email protected]

assist iDashboards support staff in troubleshooting errors.

Figure 6-5

When an error is associated with a specific alert, the event message in the event list may be

followed by (View Alert)., as shown in Figure 6-6. This is a hyperlink that can be clicked to

open the administrative screen for the errant alert, through which the alert can be

temporarily disabled or permanently deleted.

Figure 6-6
mailto:[email protected]:[email protected]:[email protected]:[email protected]


43/76


6.6 Event RetentionDuring normal operation, the Alerts Server is frequently recording new events in the event

list. Because of this, one would expect that over time, the event list would grow extremely

large, yet it does not. This is because only a certain number of events with a given event ID

are retained in the event list. This number is referred to as the retention depth for that

event ID. When the number of events with a particular event ID exceeds the retention depthfor that ID, the oldest ones are removed from the list and discarded, keeping the entire event

list at a manageable size.

The retention depth for an event ID is normally not of concern to an Alerts Server

administrator. It can be viewed, however, by holding the mouse cursor over the event ID in

the events list. This will produce a tool tip, similar to the one shown in Figure 6-7, displaying

the retention depth for the event ID.

Figure 6-7

6.6.1 Qualified Event Retention

For some error events, the retention depth is not applied to the event ID alone, but rather to

the event ID combined with some hidden qualifying information. For example, if the error

event is related to a particular alert, that alerts ID number might be used as the qualifying

information. So, if the event ID is MONITOR-9 and the alert ID is 714, the hidden,

qualified event ID to which the retention depth would apply would effectively (if not

actually) be MONITOR-9-714. And if the retention depth for MONITOR-9 events is 1, that

really means that one MONITOR-9 event related to alert #714will be retained in the list, but

at the same time a MONITOR-9 related to alert #905 might be retained in the list as well.

This keeps important events from being pushed out of the event list before they can be

viewed by an administrator.

If a retention depth applies to a qualified event ID as described above, it will be followed by

an asterisk (*) in the event ID tool tip, as shown in Figure 6-8.

Figure 6-8


44/76


6.7 Email EventsCertain event types are designated as email events. When an email event occurs, a

notification email will be sent to the designated Alerts Server administrators, provided that:

1. The Alerts Server is properly configured to send event notification emails.

2. The level of the event (INFO, WARNING, or ERROR) is at or above the configured

threshold at which the event notification emails are sent.

To determine whether or not an event in the list is an email event, hold the mouse cursor

over its event ID until the tool tip appears. It will include the line Email: true for email

events (Figure 6-8), and Email: false for non-email events (Figure 6-7).


45/76


7 Alert Administration

Alerts are normally created and maintained through the iDashboards User Application as

described in Chapter 8,User Application: Creating Alerts in Charts. The Alerts Server

console, however, provides screens through which limited modifications can be made toexisting alerts, specifically:

Alerts can be enabled or disabled. When disabled, an alert is not checked by the

Alerts Server.

Email notifications can be enabled or disabled for individual alerts.

Alerts can be deleted.

Administrative access to alerts is independent of the iDashboards security framework. An

administrator can perform the above modifications on any alert in the system, regardless ofthe category to which the alerts chart belongs, or whether the alert is public or private.

The alert administration screens are accessed by clicking ALERTS in the application menu,

as shown in Figure 7-1. This will display the Alerts Search screen, shown in Figure 7-2.

Figure 7-1

Figure 7-2


46/76

46 Chapter 7: Alert Administration

7.1 Retrieving an AlertBefore an alert can be modified, it must first be retrieved from the repository. If the alert's ID

number is known, it can be retrieved directly. If the ID number of the alerts associated chart

is known, the alert can be selected from a list of alerts associated with that chart. If neither

the alert ID nor chart ID is known, then the alert can be browsed for.

7.1.1 Searching by Alert ID

The alert ID is the number that uniquely identifies an alert in the iDashboards repository. In

the iDashboards User Application, the alert ID is visible on both the summary panel of the

alert configuration dialog (Figure 7-3), and in the alert panel of the alerts dashboard (Figure

7-4) when an instance of the alert is being viewed. To retrieve an alert with its alert ID, enter

the ID in the appropriate text box on the Alerts Search screen and click the button labeled

"Search by Alert ID". If the alert with the given ID exists in the repository, it will be displayed

on the Alert Administration screen, shown in Figure 7-7.

Figure 7-3

Figure 7-4


47/76


7.1.2 Searching by Chart ID

The Chart ID is the number that uniquely identifies a chart in the iDashboards repository. In

the iDashboards User Application, it is visible near the top of the Chart Properties window,

under the Features tab for a given chart (see Figure 7-5). Enter the Chart ID in the

appropriate text box on the Alerts Search screen and click the button labeled "Search by

Chart ID". If the chart exists and has one or more alerts configured, the Chart Alerts screenwill be displayed, showing a list of all the alerts configured for that chart, as shown in Figure

7-6.

Figure 7-5

Figure 7-6

When an alert appears on the Chart Alerts screen, it can be displayed in the Alert

Administration screen by clicking its Edit icon ( ). An alert can also be deleted from the

Chart Alerts screen by clicking its Delete icon ( ) and then clicking the OK button on the

confirmation dialog that appears.

NOTE:The Alert ID and the Chart ID can also be included in an alert notification email. See

Section5.5,Mail Macrosfor more information.


48/76

48 Chapter 7: Alert Administration

7.1.3 Browsing for an Alert

To browse for an alert, click the button labeled Browse Categories on the Alerts Search

screen. This will display a list of categories in the iDashboards system that has charts with

alerts, along with the total number of alerts for each category. Clicking the View Charts

link for a category will display a list of the charts within that category that have alerts, along

with the number of alerts for each chart. Clicking the View Alerts link for a chart in the listwill display the Chart Alerts screen (Figure 7-6) for that chart.

7.2 Modifying an AlertAdministrative modifications can be made to an alert through the Alert Administration

screen, shown in Figure 7-7. To enable or disable the alert or its email notifications, check

or uncheck the checkboxes labeled "Enabled" or "Email" appropriately, and click the Save

button. To delete the alert, and all of its active instances, click the button labeled "Delete

Alert" and click the OK button on the confirmation dialog that appears.

Figure 7-7

7.3 Importing and Exporting Charts with AlertsCharts and dashboards can be exported from one iDashboards repository and imported into

another iDashboards repository. This process is only performed through the iDashboards

Administrator Application and is detailed in the iDashboards Administrators Manual.

Charts that contain alerts will retain their alerts when exported if the alerts are not private.

Private alerts will not be exported. Also, specific group notifications will not be preserved as

iDashboards will not reconcile groups. The user will have to edit the alert after it has been

imported and decide which groups will be notified


49/76


8 User Application: Creating Alerts in

Charts

To recap, Alerts are functionality in iDashboards that notify you when certain conditions

arise in your data. You utilize the alerting capabilities to set the conditions to monitor for,

and it notifies you when they occur.

iDashboards Alerts provides the following capabilities:

Near/Real-time monitoring of changing data values.

Highly flexible monitoring criteria, based on easily-defined rules.

Robust scheduling for monitoring by month, day, hour and minute.

Seamless integration into the dashboard/chart framework.

Flexible notification options, sending on-screen and email messages to individuals orgroups.

You can add an alert to any chart that has dynamic data connectivity and does not have a

filtering constraint. Every alert includes:

One or more rules, describing the data values to watch for.

A schedule, describing when to check the data values, and how often.

A list of groups, defining the userswho will be notified when the rules are satisfied.

An alert category, or severity, defining the urgency of the alerts conditions.

There are two parts to iDashboards Alerts: the Configure a Chart Alert window and the

Active Alert Notification window. The first allows you to define the rules and schedule the

conditions you need to monitor. The second notifies you when those conditions are met.

When you create an alert on a chart, iDashboards follows the alerts schedule. At the

selected dates and times, it checks your data against the alerts rules. If the rules are

satisfied, the alert triggers, and iDashboards notifies you (or any other users you choose)

with an on-screen message and an optional email message.

To manage the on-screen notifications, iDashboards uses a special alerts dashboard. It

looks similar to the dashboards youre used to seeing, but instead of charts, it displays a list

of all the alert notifications youve received. In the alerts dashboard, you can sort, select

and delete notifications; expand them for more information; and even display the charts that

triggered them.

The following sections describe how to configure alerts, and how to handle alert

notifications.


50/76

50 Chapter 8: User Application: Creating Alerts in Charts

8.1 Configuring AlertsEvery alert is associated with a single chart, but not all charts can have alerts. For instance,

a chart with static data has no need for an alert, as its data never changes. If you try to

create an alert on a chart with static data, an error message will display (see Figure 8-1).

Figure 8-1

Alerts have the same requirements for access, creation and modification as charts. In

general, if you can modify a chart, then you can also create alerts on it or edit its existing

ones. Further, even if you do not have Save access on a charts category, you can still

create an alert on the chart, although it must be a private alert. That is, it can notify only you

and not any other user(s) who have access to the same chart.

8.1.1 Configure Alerts Menu Option

To see or edit a charts alerts, or to create a new one, select Configure Alerts from the

Chart Menu or the charts right-click menu (see Figure 8-2 and Figure 8-3). The Alertsdialog will open, and display the names of all the alerts associated with this chart (see

Figure 8-4). From this dialog, you can create a new alert, or edit or delete an existing one.


51/76


Figure 8-2

Figure 8-3

Figure 8-4

Note:Some of the alerts listed in this dialog may be marked with a stylized letter P.

These are private alerts, meaning that when their conditions are satisfied, they notify only

you. You can make any alert private. Any chart in your Personal category can have only

private alerts. There are a few other criteria regarding private alerts, described in Section

8.1.3,Alert Notifications.


52/76

52 Chapter 8: User Application: Creating Alerts in Charts

If you select an existing alert and click the Delete button, youll be warned that deleted

alerts cannot be retrieved (see Figure 8-5). If you choose to continue, the selected alert will

be deleted.

Figure 8-5

When you click on the New button, or select an alert and click the Edit button, the

Configure a Chart Alert dialog opens. This is where you set up an alert to meet your

requirements, and is described in the following sections.

8.1.2 Alert Configuration

The Configure a Chart Alert dialog box gives you access to all aspects of a single alert

(see Figure 8-6). Depending on the alert, the dialog will have three or four main editing

tabs, and one summary tab. The four editing tabs are Properties, Rules, Schedule, and

Users. (If the alert is necessarily a private alertfor example, if it is on a chart in your

Personal categorythen the Users tab is not present.) The Summary tab is always

available to provide a textual description of the alerts current definition.


53/76

7/31/2019 Alerts

Alerts Manual

Documents

Transcript of Alerts Manual