Post on 05-Apr-2018
transcript
7/31/2019 Alerts Manual
1/76
V7.5
iDashboards Aler t s Manual
Ver s ion 7 .5
7/31/2019 Alerts Manual
2/76
7/31/2019 Alerts Manual
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 support@iDashboards.com. 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:support@iDashboards.com
Web site:http://www.iDashboards.com
mailto:support@iDashboards.commailto:support@iDashboards.commailto:support@iDashboards.commailto:support@iDashboards.comhttp://www.idashboards.com/http://www.idashboards.com/http://www.idashboards.com/mailto:support@iDashboards.commailto:support@iDashboards.com7/31/2019 Alerts Manual
4/76
7/31/2019 Alerts Manual
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
7/31/2019 Alerts Manual
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/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
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
7/31/2019 Alerts Manual
9/76
iDashboards Alerts Manual 9
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.
7/31/2019 Alerts Manual
10/76
10 Chapter 1: Introduction
This page intentionally left blank.
7/31/2019 Alerts Manual
11/76
iDashboards Alerts Manual 11
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
13/76
iDashboards Alerts Manual 13
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.
7/31/2019 Alerts Manual
14/76
14 Chapter 2: Installation
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:
7/31/2019 Alerts Manual
15/76
iDashboards Alerts Manual 15
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,
7/31/2019 Alerts Manual
16/76
16 Chapter 2: Installation
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.
7/31/2019 Alerts Manual
17/76
iDashboards Alerts Manual 17
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.
7/31/2019 Alerts Manual
18/76
18 Chapter 2: Installation
Figure 2-1
7/31/2019 Alerts Manual
19/76
iDashboards Alerts Manual 19
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
21/76
iDashboards Alerts Manual 21
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.
7/31/2019 Alerts Manual
22/76
22 Chapter 3: System Configuration
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.
7/31/2019 Alerts Manual
23/76
iDashboards Alerts Manual 23
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:
7/31/2019 Alerts Manual
24/76
24 Chapter 3: System Configuration
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) tosupport@idashboards.com.
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:support@idashboards.commailto:support@idashboards.commailto:support@idashboards.commailto:support@idashboards.com7/31/2019 Alerts Manual
25/76
iDashboards Alerts Manual 25
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
27/76
iDashboards Alerts Manual 27
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
29/76
iDashboards Alerts Manual 29
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:
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
31/76
iDashboards Alerts Manual 31
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:
7/31/2019 Alerts Manual
32/76
32 Chapter 5: Notification Email Settings
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
"alerts@mycompany.com". 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:
jsmith@company.com
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.
7/31/2019 Alerts Manual
33/76
iDashboards Alerts Manual 33
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.
7/31/2019 Alerts Manual
34/76
34 Chapter 5: Notification Email Settings
/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
7/31/2019 Alerts Manual
35/76
iDashboards Alerts Manual 35
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
7/31/2019 Alerts Manual
36/76
36 Chapter 5: Notification Email Settings
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.
7/31/2019 Alerts Manual
37/76
iDashboards Alerts Manual 37
${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.
7/31/2019 Alerts Manual
38/76
38 Chapter 5: Notification Email Settings
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 ${".
7/31/2019 Alerts Manual
39/76
iDashboards Alerts Manual 39
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
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
41/76
iDashboards Alerts Manual 41
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
7/31/2019 Alerts Manual
42/76
42 Chapter 6: Server Operation
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 tosupport@idashboards.comto
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:support@idashboards.commailto:support@idashboards.commailto:support@idashboards.commailto:support@idashboards.com7/31/2019 Alerts Manual
43/76
iDashboards Alerts Manual 43
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
7/31/2019 Alerts Manual
44/76
44 Chapter 6: Server Operation
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).
7/31/2019 Alerts Manual
45/76
iDashboards Alerts Manual 45
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
7/31/2019 Alerts Manual
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
7/31/2019 Alerts Manual
47/76
iDashboards Alerts Manual 47
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.
7/31/2019 Alerts Manual
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
7/31/2019 Alerts Manual
49/76
iDashboards Alerts Manual 49
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
51/76
iDashboards Alerts Manual 51
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.
7/31/2019 Alerts Manual
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.
7/31/2019 Alerts Manual
53/76
7/31/2019 Alerts