6eadminguide_6.2.pdf
DESCRIPTION
TelAlert 6e Administrator GuideTRANSCRIPT
TelAlert 6e™
Administrator Guide
Version 6.2.0
Copyrights
Copyright © 2005 - 2009, 2010 MIR3, Inc.
TelAlert 6e™ Administrator Guide
This document is copyrighted and all rights are reserved. The distribution and sale of this product
are intended for the use of the original purchaser only per the terms of the Agreement.
This document may not, in whole or part, be copied, photocopied, reproduced, translated, reduced,
or transferred to any electronic medium or machine-readable form without prior written consent in
writing from MIR3, Inc.
MIR3, TelAlert, IN, inEnterprise, inEnterprisePRO, inAlertCenter, inAlertCenterPRO, inCampusAlert
inGovAlert, inGovAlertPRO, inSalesTalk, inTechCenter, inTechCenterPRO, inWebServices, inConnect,
inConsole and Enterprise Access Control are trademarks of MIR3, Inc. All other product and
company names are marks of their respective holders.
This document is the property of MIR3, Inc. and may not be distributed in any manner except with
the express written permission of MIR3, Inc.
Software Version: TelAlert 6e v6.2.0
Document Revision: 5.0
MIR3, Inc.
3398 Carmel Mountain Road
San Diego, CA 92121
Phone: 858.724.1200
Fax: 858.724.1201
Email: [email protected]
http://www.mir3.com
Preface
The TelAlert 6e™ Version 6.2 Administrator Guide describes how to use the TelAlert 6e™ software.
It can run on all major platforms (Sun Solaris, Windows, HP-UX and Linux), and use all major
relational databases (Oracle, Microsoft SQL Server, and MySQL). The information in this document
is accurate regardless of the platform or database used to support the TelAlert 6e system.
This Guide does not include instructions about how to install, configure or integrate the
TelAlert 6e™ system with third-party data sources.
Table of Contents
Introduction ................................................................................... 1
1.1 Overview .......................................................................................... 1
1.2 Guide Introduction .............................................................................. 1
1.2.1 Contents ....................................................................................... 1
1.2.2 Audience ....................................................................................... 1
1.2.3 Related Technical Documentation ...................................................... 2
1.3 Product Support Contact Information ...................................................... 2
1.4 TelAlert™ Solutions from MIR3 ............................................................... 2
1.5 Guide Conventions .............................................................................. 3
1.5.1 Screen Captures ............................................................................. 5
1.5.2 File Locations ................................................................................. 5
1.6 Structure of the Administrator Guide ...................................................... 5
1.6.1 Chapter 1: Introduction ................................................................... 5
1.6.2 Chapter 2: What is TelAlert 6e .......................................................... 5
1.6.3 Chapter 3: Technical Overview .......................................................... 5
1.6.4 Chapter 4: Implementation Planning .................................................. 5
1.6.5 Chapter 5: Configuration Basics ........................................................ 5
1.6.6 Chapter 6: The Role of Ports in TelAlert .............................................. 6
1.6.7 Chapter 7: Dialing the Telephone....................................................... 6
1.6.8 Chapter 8: Configuring for Paging Notification ...................................... 6
1.6.9 Chapter 9: Configuring for Text to Speech (TTS) Notification .................. 6
1.6.10 Chapter 10: Configuring for Other Notification Media ........................... 7
1.6.11 Chapter 11: Applying Filtering Techniques ......................................... 7
1.6.12 Chapter 12: Setting Up and Applying Schedules .................................. 7
1.6.13 Chapter 13: Representing Users ...................................................... 7
1.6.14 Chapter 14: Enabling Responses ...................................................... 7
1.6.15 Chapter 15: Broadcasting to Groups and Creating Escalations ............... 8
1.6.16 Chapter 16: Processing Events ........................................................ 8
1.6.17 Chapter 17: Miscellaneous Administrative Tasks ................................. 8
1.6.18 Chapter 18: TelAlert Monitor ........................................................... 8
1.6.19 Chapter 19: Security Features ......................................................... 8
1.6.20 Chapter 20: Integrating XML Output ................................................. 8
What is TelAlert 6e? ....................................................................... 9
2.1 Overview .......................................................................................... 9
2.2 What is TelAlert 6e? ............................................................................ 9
2.2.1 Messaging Component ..................................................................... 9
2.2.2 Configuration Tools ......................................................................... 9
2.2.3 Add-On Product Modules ................................................................ 10
2.2.4 Two-Way Pagers .......................................................................... 11
2.2.5 WAP- and SMS-Enabled Cell Phones ................................................. 11
2.2.6 Applet-Based Remote Interactions ................................................... 11
2.3 TelAlert Text to Speech (TTS) ............................................................. 11
2.3.1 Full Range of Voice Destinations ...................................................... 11
2.3.2 Customizable Vocabulary in Four Languages ...................................... 11
2.3.3 Interactive Voice Response (IVR) ..................................................... 11
2.3.4 Dialogic Telephony Card................................................................. 11
2.4 TelAlert 6e Integrations ..................................................................... 12
2.4.1 TelAlert 6e Integration Templates for Third-Party Applications ............... 12
2.4.2 Do-it-Yourself Integrations for In-House Applications ........................... 12
2.5 Supported Platforms .......................................................................... 13
2.5.1 Web Server ................................................................................. 13
2.5.2 Database Server........................................................................... 13
2.5.3 Messaging Server and Client Platforms ............................................. 14
2.5.4 Client Platforms ............................................................................ 15
2.5.5 Operating Systems Not Supported for Version 5.7 .............................. 17
2.6 TelAlert 6e Documentation ................................................................. 17
2.6.1 TelAlert 6e Administrator Guide ....................................................... 17
2.6.2 TelAlert 6e Installation Guide .......................................................... 17
2.6.3 TelAlert 6e Online Help .................................................................. 17
2.6.4 TelAlert 6e Keyword and Command Reference ................................... 17
2.6.5 Integration Instructions ................................................................. 18
2.6.6 TelAlert 6e Failover Module Guide .................................................... 18
2.7 TelAlert Messaging Server File Locations ............................................... 18
Technical Overview ...................................................................... 19
3.1 Overview ........................................................................................ 19
3.2 How TelAlert Messaging Server Works .................................................. 19
3.2.1 A Typical Alert ............................................................................. 20
3.3 Server Processes and Command Line Clients .......................................... 21
3.4 Server Processes .............................................................................. 21
3.4.1 telalerte (TelAlertE.exe) ................................................................. 21
3.4.2 telaconfe (TelaConfE.exe) .............................................................. 21
3.4.3 telalertd (TelAlertD.exe) ................................................................ 22
3.4.4 telalertf (TelAlertF.exe) .................................................................. 22
3.4.5 telalertm (TelAlertM.exe) ............................................................... 22
3.4.6 telalertr (TelAlertR.exe) ................................................................. 22
3.4.7 telalerts (TelAlertS.exe) ................................................................. 22
3.4.8 telalertv (TelAlertV.exe) ................................................................. 22
3.4.9 readmail (ReadMail.exe) ................................................................ 22
3.4.10 ntfysrvr (NtfySrvr.exe) ................................................................ 22
3.4.11 hostaddr (HostAddr.exe) .............................................................. 22
3.4.12 killtela (KillTela.exe) .................................................................... 23
3.4.13 mailaddr (MailAddr.exe) ............................................................... 23
3.5 Command Line Clients ....................................................................... 23
3.5.1 telalert (TelAlert.exe) .................................................................... 23
3.5.2 telalconf (TelaConf.exe) ................................................................. 23
3.5.3 telalertc (TelAlertC.exe) ................................................................. 23
3.5.4 telalerth (TelAlertH.exe) ................................................................ 23
3.5.5 telalerths (TelAlertHS.exe) ............................................................. 24
3.6 Key TelAlert Files .............................................................................. 24
3.6.1 telalert.trail ................................................................................. 24
3.6.2 telalert.alert ................................................................................ 24
3.6.3 telalert[e/f/r/s/d/m/h/v].log ........................................................... 24
3.6.4 telalert.sects ................................................................................ 24
3.6.5 telalert.ini ................................................................................... 24
3.7 Key Configuration Concepts ................................................................ 25
Implementation Planning ............................................................. 27
4.1 Overview ........................................................................................ 27
4.2 Your Accomplishments So Far ............................................................. 27
4.3 The Alert Timeline ............................................................................. 28
4.3.1 Send and Release ......................................................................... 28
4.3.2 Send, Wait, and Release ................................................................ 28
4.3.3 Send, Wait, Hold, and Release ........................................................ 29
4.3.4 The Alert Timeline and Escalations ................................................... 30
4.3.5 Summary .................................................................................... 30
4.3.6 Organizational Scenarios ................................................................ 31
4.3.7 Scenario One: Paging Only—Small Organization ................................. 31
4.3.8 Scenario Two: Paging, Voice, and Email—Small Organization ................ 36
4.3.9 Scenario Three: A Larger Organization .............................................. 39
Configuration Basics ..................................................................... 43
5.1 Overview ........................................................................................ 43
5.2 TelAlert Configuration Methods: TADesktop; TelAlert 6e Web Interface ...... 43
5.3 What is TelAlert Desktop?................................................................... 44
5.3.1 The Desktop Window ..................................................................... 44
5.3.2 TelAdmin .................................................................................... 44
5.3.3 TelAlert Monitor............................................................................ 44
5.3.4 Wireless Destination Setup Wizard ................................................... 44
5.3.5 Group Setup Wizard ...................................................................... 45
5.3.6 Host Properties Monitoring ............................................................. 45
5.3.7 TelAlert Web UI Launch ................................................................. 45
5.4 Components of the TelAlert Desktop Window ......................................... 45
5.4.1 Administering a TelAlert Server ....................................................... 46
5.4.2 Administering a TelAlert 6e Server ................................................... 46
5.5 Connecting to a TelAlert Host .............................................................. 47
5.5.1 Configuring the Desktop to Connect to a TelAlert Server ...................... 47
5.6 Configuring TelAdmin Save and Backup Options ..................................... 48
5.6.1 Enabling Auto-Save....................................................................... 48
5.6.2 Enabling Backup ........................................................................... 49
5.6.3 Setting Up Failover ....................................................................... 49
5.7 Using TelAdmin to Configure TelAlert Messaging Server ........................... 49
5.7.1 About TelAdmin ............................................................................ 50
5.7.2 The TelAdmin Window ................................................................... 50
5.7.3 Configuring TelAlert Messaging Server .............................................. 51
5.7.4 Making Configuration Changes ........................................................ 51
5.7.5 TelAdmin Menu Items .................................................................... 52
5.7.6 Importing Data from Windows Clipboard ........................................... 54
5.7.7 Desktop Locking ........................................................................... 56
5.8 Understanding Configuration Examples ................................................. 57
5.9 What is TheTelAlert 6e Web Interface? .................................................. 58
5.10 Logging In ....................................................................................... 59
5.11 Navigating ....................................................................................... 60
5.11.1 Home ....................................................................................... 61
5.11.2 Alerts ....................................................................................... 62
5.11.3 Users ........................................................................................ 64
5.11.4 Devices ..................................................................................... 64
5.11.5 Groups...................................................................................... 65
5.11.6 Schedules .................................................................................. 65
The Role of Ports in TelAlert ......................................................... 67
6.1 Overview ........................................................................................ 67
6.2 What is a Port? ................................................................................. 67
6.3 Basic Port Considerations ................................................................... 68
6.4 If You Are Using a Terminal Server....................................................... 71
6.4.1 Testing Connectivity on a Terminal Server ......................................... 72
6.5 More Advanced Port Considerations ...................................................... 72
6.5.1 Directing Specific Notifications to Specific Ports .................................. 72
6.5.2 Providing Port Backup.................................................................... 74
6.5.3 Controlling Port Deactivation Due To Errors ....................................... 75
6.5.4 What Remote Ports Are Used For ..................................................... 76
Dialing the Telephone ................................................................... 79
7.1 Overview ........................................................................................ 79
7.2 What’s So Hard About Dialing the Phone? .............................................. 79
7.2.1 Local Dialing ................................................................................ 80
7.2.2 Alternate Numbers ........................................................................ 80
7.2.3 Inside and Outside Lines ................................................................ 80
7.2.4 Special Dialing Scenarios ............................................................... 80
7.2.5 Dialing After the Main Number is Answered ....................................... 80
7.2.6 Inserting Pauses During Dialing ....................................................... 80
7.3 Dialing Logic .................................................................................... 81
7.3.1 Dialing Components ...................................................................... 81
7.3.2 Dialing Process ............................................................................. 82
7.4 Local Dialing .................................................................................... 82
7.4.1 Normal Local Dialing ..................................................................... 82
7.4.2 Ten-Digit Local Dialing ................................................................... 83
7.4.3 Eleven-Digit Local Dialing ............................................................... 83
7.5 Long Distance Dialing ........................................................................ 83
7.5.1 Normal Long Distance Dialing ......................................................... 83
7.5.2 Other Long Distance Dialing............................................................ 84
7.5.3 Alternate Numbers ........................................................................ 84
7.6 Inside and Outside Lines .................................................................... 85
7.6.1 Getting an Outside Line ................................................................. 85
7.6.2 Getting an Inside Line ................................................................... 85
7.7 Special Dialing Scenarios .................................................................... 86
7.8 Dialing After the Main Number is Answered ............................................ 86
7.8.1 Dialing a Number, Then an Extension ............................................... 86
7.8.2 Dialing a Number, Then Accessing a Mailbox ...................................... 87
7.9 Inserting Pauses During Dialing ........................................................... 87
7.10 Specifying Telephone Dialing Components at the Command Line................ 88
7.11 Overriding the Need for Dialtone .......................................................... 88
Configuring for Paging Notification ............................................... 89
8.1 Overview ........................................................................................ 89
8.2 Getting Started ................................................................................ 89
8.2.1 Needed Information ...................................................................... 89
8.2.2 General Considerations .................................................................. 90
8.3 Setting Up Text Paging ...................................................................... 91
8.3.1 Creating a Text Pager [Configurations] Definition ................................ 91
8.3.2 Pointing to a Modem ..................................................................... 91
8.3.3 Creating a Text Pager Destination .................................................... 92
8.3.4 Sending a Page by Invoking a Destination ......................................... 93
8.3.5 Sending a Page Without Invoking a Destination .................................. 93
8.3.6 Sending to Text Pagers via [Configurations] Definitions of Type=InteractiveTextPager .................................................................... 93
8.3.7 Sending Text Pages via Modem without TAP (Protocol=Chat) ................ 94
8.4 Setting Up Numeric Paging ................................................................. 98
8.4.1 Sending Numeric Pages Using the TAP Protocol .................................. 98
8.4.2 Sending Numeric Pages Without TAP ................................................ 99
8.5 Setting Up Two-Way Paging .............................................................. 102
8.5.1 Creating a Two-Way Pager [Configurations] Definition ....................... 102
8.5.2 Pointing to a Modem ................................................................... 103
8.5.3 Creating Two-Way Pager Destinations ............................................ 104
8.5.4 Enabling Responses .................................................................... 104
8.5.5 Enabling Polling .......................................................................... 107
8.5.6 Enabling Notifications .................................................................. 107
8.6 Setting Up Requests: Unsolicited Messages From Two-Way Pagers ........... 108
8.6.1 Receiving Requests ..................................................................... 108
8.6.2 Having Requests Trigger [Notifications] Actions ................................ 108
8.6.3 Simulating Requests for Testing Purposes ....................................... 108
8.7 Setting Up Internet-Based Paging ...................................................... 109
8.7.1 One-Way Internet-Based Paging .................................................... 109
8.7.2 Two-Way Internet-Based Paging .................................................... 110
8.8 Initiating Pages via Email ................................................................. 113
8.8.1 Responses to Two-Way Email-Based Text Pages ............................... 113
8.9 Adding ID Numbers to Pages ............................................................ 114
Configuring for Voice Notification ............................................... 117
9.1 Overview ...................................................................................... 117
9.2 Configuration for Voice Notification .................................................... 117
Configuring for Other Notification Media ..................................... 119
10.1 Overview ...................................................................................... 119
10.2 Getting Started .............................................................................. 119
10.2.1 Needed Information .................................................................. 119
10.3 Setting up Electronic Signboard Notification ......................................... 121
10.3.1 Signboard Overview .................................................................. 121
10.3.2 Initial Signboard Firmware Setup ................................................. 121
10.4 Standard Signboard Setup (DeviceSubtype=2) ..................................... 122
10.4.1 TelAlert-Controlled Signboard Message Display ............................... 122
10.4.2 Signboard [Port] Definition ......................................................... 122
10.4.3 Signboard [Configurations] Definition ........................................... 123
10.4.4 Signboard [Destinations] Definitions ............................................. 125
10.4.5 Sending Messages to the Signboard ............................................. 125
10.4.6 Controlling Signboard Text Color and Effects .................................. 125
10.4.7 Configuring Multiple Signboards ................................................... 127
10.5 Alternative Signboard Setup (DeviceSubtype=1) .................................. 128
10.5.1 Signboard [Port] Definition when DeviceSubtype=1 ......................... 128
10.5.2 Signboard [Configurations] Definition when DeviceSubtype=1 ........... 128
10.5.3 Additional Signboard Firmware Setup when DeviceSubtype=1 ........... 129
10.5.4 Signboard [Destinations] Definitions when DeviceSubtype=1 ............ 130
10.6 Setting up Email Notification ............................................................. 133
10.6.1 Email [Port] Definition ............................................................... 134
10.6.2 Email [Configurations] Definition .................................................. 134
10.6.3 Email [Destinations] Definition .................................................... 135
10.6.4 Using Email as a Backup Notification Medium ................................. 135
10.6.5 Handling Responses to Email With Readmail .................................. 136
10.7 Setting Up SpectraLink LCD Notification .............................................. 140
10.7.1 SpectraLink LCD [Port] Definition ................................................. 140
10.7.2 SpectraLink LCD [Configurations] Definition ................................... 140
10.7.3 SpectraLink LCD [Destinations] Definitions .................................... 141
10.8 Setting up Command Line Notification ................................................ 141
10.8.1 Command-Line [Configurations] Definition ..................................... 141
10.8.2 Command-Line [Destinations] Definition........................................ 141
10.8.3 Applications for Command-Line Notification.................................... 142
10.9 POPUP Message Boxes on Windows .................................................... 143
10.10 Sending Text Messages to Other Systems............................................ 144
10.10.1 UNIX Syslog Processes ............................................................. 144
10.10.2 TelaConsole ........................................................................... 144
10.10.3 AS/400s ................................................................................ 144
10.11 Sending Text Messages to Web-Enabled Phones ................................... 145
10.12 Sending Text Messages to Nextel Cellular Phones ................................. 146
10.13 Sending One-Way Text Messages to GSM Cellular Telephones Modem ....... 147
10.14 Sending Two-Way Text Messages to SMS Mobile Telephones Via a GSM Wireless Modem .................................................................................................. 148
10.14.1 Set-Up During Installation......................................................... 148
10.14.2 New Technique in TelAlert 5.4 ................................................... 148
10.14.3 Differences Between the Two Techniques ..................................... 149
10.14.4 Samples for Both Techniques ..................................................... 150
10.15 Sending Text Messages to a DN400E Fax Modem .................................. 154
10.16 Sending a File or a Line from stdin as a Message .................................. 155
10.16.1 Sending a File as a Message ...................................................... 155
10.16.2 Sending a Line from stdin as a Message ...................................... 156
10.17 SMPP ............................................................................................ 157
10.17.1 SMPP Confirmed Delivery Option ................................................ 157
10.17.2 SMPP Sample Configuration....................................................... 157
10.18 WCTP Proxy Configuration ................................................................ 158
Applying Filtering Techniques ..................................................... 161
11.1 Overview ...................................................................................... 161
11.2 Getting Started .............................................................................. 161
11.2.1 What is Filtering? ...................................................................... 161
11.2.2 Needed Information .................................................................. 161
11.3 A Simple Filter ............................................................................... 162
11.3.1 The Scenario ............................................................................ 162
11.3.2 Procedure ................................................................................ 162
11.4 Filtering Strategies .......................................................................... 164
11.4.1 Filtering and Default Logic .......................................................... 164
11.4.2 RequiresFullMatch and Exclusive Value Combinations ....................... 165
11.4.3 RequiresClientMatch .................................................................. 167
11.4.4 The MatchKeyword .................................................................... 167
11.4.5 Filtering and Groups .................................................................. 168
11.4.6 Filtering and Schedules .............................................................. 170
11.4.7 Filtering and Users .................................................................... 170
11.5 Filtering by Message Priority ............................................................. 171
11.5.1 Extended Example .................................................................... 172
11.5.2 Default Logic ............................................................................ 173
11.6 Filtering Messages by IP Address ....................................................... 173
11.7 Filtering out Duplicate and Transient Messages ..................................... 174
11.7.1 Filtering Out Duplicate “Node Down” Messages ............................... 174
11.7.2 Suppressing Transient Messages .................................................. 175
11.8 Suppressing Unwanted Messages During Scheduled Downtime ................ 176
11.8.1 Suppressing Orphan “Up” Messages ............................................. 177
11.8.2 When a Device Does Not Come Back Online as Scheduled................. 177
11.9 Filtering Messages by Source ............................................................ 178
11.10 Pattern Matching ............................................................................ 178
11.10.1 Other Uses ............................................................................. 179
11.10.2 Pre-Defining Regular Expressions ............................................... 180
Setting Up and Applying Schedules ............................................. 183
12.1 Overview ...................................................................................... 183
12.2 Getting Started .............................................................................. 183
12.2.1 What are Schedules? ................................................................. 183
12.2.2 Needed Information .................................................................. 184
Managing Schedules ................................................................................ 184
Schedule Types .................................................................................. 184
Viewing Schedules .............................................................................. 185
12.3 Scheduling Approaches .................................................................... 186
12.3.1 Schedules and Default Logic........................................................ 186
12.4 Assigning Device Schedules .............................................................. 187
12.4.1 Adding a New Device Schedule .................................................... 190
12.5 Creating Group Member Schedules ..................................................... 191
12.5.1 Assigning Group Member Schedules ............................................. 192
12.5.2 Effect of Time Zones .................................................................. 193
Creating Extra Duty Schedules .............................................................. 194
12.5.3 Schedules and [Filter] Definitions ................................................. 194
12.5.4 Schedules and [User] Definitions ................................................. 194
12.5.5 Schedules and Message Priority ................................................... 195
Representing Users .................................................................... 197
13.1 Overview ...................................................................................... 197
13.2 Getting Started .............................................................................. 197
13.2.1 What Are Users? What Are They For? ............................................ 197
13.2.2 Needed Information .................................................................. 198
13.3 User Roles ..................................................................................... 198
13.3.1 Key Principles........................................................................... 198
13.3.2 Definitions ............................................................................... 198
13.3.3 Viewing Tabs............................................................................ 199
13.3.4 Role Editor Screen .................................................................... 200
13.4 Managing Users .............................................................................. 207
13.4.1 Adding Users............................................................................ 207
13.5 Creating a [User] definition: Essentials ............................................... 213
13.6 Values for Inheritance by Associated Destinations ................................. 213
13.6.1 Direct Inheritance ..................................................................... 213
13.6.2 Minimum of the [User] Value and the [Destinations] Default ............. 214
13.6.3 Maximum of the [User] Value and the [Destinations] Default............. 214
13.6.4 Maximum of the [User] Value, the [Destinations] Default, and the
[Configurations] Value ......................................................................... 214
13.7 Values for Dial-in and Dial-out Access ................................................. 214
13.8 User-Based Administrative Techniques ................................................ 215
13.8.1 Viewing Messages: -show ........................................................... 215
13.8.2 Getting Rid of Messages: -clear and -release .................................. 216
13.8.3 Listing Users ............................................................................ 216
Representing Devices ................................................................. 217
14.1 Overview ...................................................................................... 217
14.2 Managing Your Devices .................................................................... 217
14.2.1 Adding New Devices .................................................................. 218
14.2.2 Editing Your Devices .................................................................. 222
14.3 Assigning Device Schedules .............................................................. 222
14.3.1 Adding a New Device Schedule .................................................... 225
14.3.2 Removing Your Devices .............................................................. 226
Enabling Responses .................................................................... 227
15.1 Overview ...................................................................................... 227
15.2 Getting Started .............................................................................. 227
15.2.1 What are Responses? ................................................................ 227
15.2.2 Needed Information .................................................................. 227
15.2.3 Other Considerations ................................................................. 228
15.3 Taking Advantage of Pre-Defined Responses ........................................ 228
15.3.1 Responding Via the Command Line ............................................... 229
15.4 Creating Custom Responses .............................................................. 229
15.5 Two-Way Pager Considerations.......................................................... 230
15.6 Responses and the [Notifications] Feature ...................................... 231
Broadcasting to Groups and Creating Escalations ........................ 235
16.1 Overview ...................................................................................... 235
16.2 Getting Started .............................................................................. 235
16.2.1 What Are Groups? What Are They For? .......................................... 235
16.2.2 Adding a New Group .................................................................. 236
16.2.3 Activating and De-Activating Groups ............................................. 237
16.2.4 Modifying a Group ..................................................................... 238
16.2.5 Adding Group Members .............................................................. 238
16.3 Assigning Schedules to Group Members .............................................. 240
16.3.1 Assigning a Schedule to a Group Member ...................................... 240
16.3.2 Removing Group Members .......................................................... 245
Reordering Group Members .................................................................. 245
16.4 Group Basics.................................................................................. 246
16.4.1 Building a Group From a List of Other Groups ................................. 246
16.4.2 Supported Group Attributes ........................................................ 246
16.5 Broadcast Notification ...................................................................... 247
16.5.1 About Group IDs ....................................................................... 248
16.5.2 Use of -g and -l Compared .......................................................... 248
16.5.3 Schedules and Broadcast Notifications .......................................... 248
16.6 Escalation ..................................................................................... 249
16.6.1 A Simple Escalation ................................................................... 249
16.6.2 Other Approaches to Strategy ..................................................... 251
16.6.3 Escalations Involving Subgroups .................................................. 253
16.6.4 Balancing Workloads by Rotating the First Destination ..................... 255
16.6.5 Schedules and Escalation ........................................................... 256
Processing Events ...................................................................... 257
17.1 Overview ...................................................................................... 257
17.2 Getting Started .............................................................................. 257
17.2.1 Needed Information .................................................................. 257
17.3 Event Processing Defined ................................................................. 258
17.3.1 What Is Event Processing? .......................................................... 258
17.3.2 What Is an Event? ..................................................................... 258
17.4 Event Processing Overview ............................................................... 259
17.4.1 About Notification and Related Keywords ....................................... 260
17.5 Triggering Actions ........................................................................... 260
17.5.1 Sending an SNMP Trap ............................................................... 260
17.5.2 Writing to the System Log .......................................................... 261
17.5.3 Issuing a Command .................................................................. 261
17.5.4 Making One Event Trigger Multiple Actions ..................................... 263
17.6 Alert-Related and Miscellaneous Events: The [Notification] Section ...... 263
17.6.1 Event Keywords Supported in the [Notification] Section ............... 266
17.6.2 Event Substitution Parameters Supported in the [Notification] Section....................................................................................................... 269
17.7 Process-Related Events: The [Heartbeat] Section ................................ 271
17.7.1 Event Keywords Supported in the [Heartbeat] Section ................... 271
17.7.2 Event Substitution Parameters Supported in the [Heartbeat] Section 272
17.8 Logging-Related Events: The [File] Section .......................................... 272
17.8.1 Handling Rollover of telaconfe.log and telainetde.log ................ 274
17.8.2 Handling telalert.sects and telalert.ini file Backups when TelAdmin is Used ............................................................................................. 274
17.8.3 Miscellaneous [File] Functions ................................................... 275
17.8.4 Event Substitution Parameters Supported in the [File] Section ........ 275
Miscellaneous Administrative Tasks ............................................ 277
18.1 Overview ...................................................................................... 277
18.2 Starting and Stopping TelAlert........................................................... 277
18.3 Configuring TelAlert to Run Automatically ............................................ 278
18.3.1 On Windows............................................................................. 278
18.3.2 On UNIX ................................................................................. 278
18.4 Installing TelAlert Clients.................................................................. 278
18.4.1 Configuring the Server To Accept Remote Clients ............................ 278
18.4.2 Installing the TelAdmin Client ...................................................... 279
18.4.3 Installing Remote Command-Line Clients on Windows ...................... 279
18.4.4 Installing Remote Command-Line Clients on UNIX ........................... 281
18.5 Setting up the TelAlert Web Clients .................................................... 282
18.5.1 Installing the Web Clients ........................................................... 282
18.5.2 Running Multiple Web Clients on the Same Machine ......................... 282
18.5.3 Using the Web Clients with Web-Enabled Cell Phones ....................... 283
18.5.4 Installing Online Help for the Web Clients ...................................... 283
18.5.5 Configuring telalerth with telalerth.ini ........................................... 283
18.5.6 Other Keywords ........................................................................ 288
18.6 Setting up Logging .......................................................................... 291
18.6.1 Default Log Files ....................................................................... 291
18.6.2 Setting Maximum Sizes .............................................................. 292
18.6.3 WriteExecsToTrail ..................................................................... 292
18.6.4 Configuring Additional Logging Behavior ........................................ 292
18.7 Miscellaneous Administrative Tasks .................................................... 292
18.7.1 Specifying Maximum ID Assignments ............................................ 292
18.7.2 Viewing Listen Sockets ............................................................... 293
18.8 TelAlert Web UI Administrative Tasks ................................................. 293
18.8.1 Importing Data ......................................................................... 294
18.8.2 Changing the Color Theme .......................................................... 301
18.8.3 Managing Configurations ............................................................ 301
18.8.4 Managing Departments .............................................................. 302
18.8.5 Managing Holidays .................................................................... 307
18.8.6 LDAP Configuration ................................................................... 308
18.8.7 User Role Configuration .............................................................. 309
18.8.8 Single Sign On Configuration ....................................................... 310
18.8.9 Log Viewer .............................................................................. 311
18.8.10 Setting System Preferences....................................................... 312
18.8.11 System Status Verification ........................................................ 313
18.9 Additional Admin Tasks ..................................................................... 314
18.9.1 Changing a User’s Role ............................................................... 314
18.10 System Reports .............................................................................. 314
Getting Familiar with the TelAlert Monitor ................................... 317
19.1 Overview ...................................................................................... 317
19.2 About the TelAlert Monitor Window .................................................... 318
19.3 Setting Up TelAlert Monitor ............................................................... 318
19.3.1 Configuring TelAlert Notification Paragraphs for TelAlert Monitor ......... 319
19.3.2 Configuring TelAlert Desktop’s Host Properties ................................ 319
19.4 Launching the TelAlert Monitor Window ............................................... 319
19.4.1 TelAlert Monitor Window Button ................................................... 319
19.4.2 TelAlert Desktop Tools Menu ....................................................... 320
19.4.3 TelAlert Monitor Data Dialog........................................................ 320
19.5 Using TelAlert Monitor ..................................................................... 321
19.5.1 TelAlert Monitor AlertTree ........................................................... 322
19.5.2 Icons ...................................................................................... 323
19.5.3 TelAlert Monitor Toolbar ............................................................. 326
TelAlert Monitor Tabs .......................................................................... 328
Alert Monitor Send Message Interface Dialog ........................................... 330
Security Features ....................................................................... 333
20.1 Overview ...................................................................................... 333
20.2 TelAlert’s Security-Conscious Architecture ........................................... 333
20.2.1 telalerte: The Central Hub of TelAlert ........................................ 334
20.2.2 The Media Controllers ................................................................ 335
20.2.3 TelAlert Desktop ....................................................................... 336
20.2.4 Client Programs ........................................................................ 336
20.3 Password Encryption ....................................................................... 337
20.4 Scheduling of Client Connections ....................................................... 338
20.5 Authentication for Admin and Client Connections .................................. 338
20.6 Control Over Remote Connections ...................................................... 339
20.7 Security Event Available in [Notifications] ....................................... 340
20.8 Control Over IVR Interactions ........................................................... 340
20.9 Using SSL with Skytel Devices ........................................................... 340
20.9.1 Obtain and Install Wrapper/Proxy Software .................................... 341
20.10 Development Example ..................................................................... 345
Integrating XML Output .............................................................. 351
21.1 Overview ...................................................................................... 351
21.2 Enabling XML Output ....................................................................... 351
21.3 Defining the Task............................................................................ 354
21.4 A (Very) Brief Overview of XML ......................................................... 355
21.5 The Parser Toolkit ........................................................................... 357
21.6 The Event Matrix ............................................................................ 358
21.7 The User Methods ........................................................................... 360
21.8 The Notification Objects ................................................................... 363
21.9 Development Example ..................................................................... 364
21.9.1 Step 1: Create A New User Object ................................................ 364
1
Introduction
1.1 Overview
This chapter includes the following sections:
� An overview of the TelAlert Administrator Guide and other TelAlert documentation.
1.2 Guide Introduction
Thank you for using the MIR3 TelAlert™ Administrator Guide, your primary source for information
about the use of all features in the TelAlert system. The purpose of this Guide is to provide detailed
information on how to use these functions in the TelAlert system. It assumes you have installed
TelAlert and are ready to begin configuring and administering it.
1.2.1 Contents
To help you learn how to use the TelAlert system effectively, the first page of each chapter includes a
bulleted table of contents summarizing the information in the chapter. Each chapter also contains
step-by-step instructions and procedures for using each function with the TelAlert system. The Guide
provides administrator-directed information, including adding Users, Setting up connections to
service providers, and the optiona available for the TelAlert components.
1.2.2 Audience
The TelAlert Administrator Guide is designed for use by individuals who configure the TelAlert
system.
2 | TelAlert 6e™ Administrator Guide - Version 6.1.29
1.2.3 Related Technical Documentation
There are other sources of information available concerning deployment of the TelAlert system:
� TelAlert Users Guide - This guide contains complete instructions for individuals who
configure notifications using the TelAlert system.
� TelAlert Voice and Hardware Guide - This guide contains complete instructions on
sending Text to Speech (TTS) notifications using a TelAlert Dialogic telephony card.
� TelAlert Keyword and Command Reference - This guide contains information that was
previously part of the Administrator Guide. It is a detailed reference to the keywords
supported by the TelAlert configuration file, the commands and command line options supported by TelAlert, and the event and state messages issued by TelAlert.
� The TelAlert Desktop Guide - This guide contains details on using the TelAlert Desktop—
including TelAdmin, a GUI-based configuration tool that is included with TelAlert. TelAdmin
allows you to configure TelAlert from within a graphical application rather than from a command line.
1.3 Product Support Contact Information
1.4 TelAlert™ Solutions from MIR3
TelAlert is a trademark of MIR3, Inc., but is referred to without trademark symbols in the
remainder of this document.
Refer to Appendix: MIR3 Contact Information for MIR3 customer support.
Chapter 1: Introduction | 3
1.5 Guide Conventions
This guide is written in Microsoft Word format and converted to PDF format to preserve the
formatting. The following information provides you with the key to help you identify information as
you navigate through this Guide:
Example Purpose
Use of Monospaced Fonts
telalertc -i DestinationName -m "Message" Italicized text within a command line example represents
a variable. In the above example, DestinationName is the invocation of an item in TelAlert’s configuration
file; message represents the message text to be sent by TelAlert.
2001/03/16 11:50:11>Event [21]Alert Completed (23), Status: [81]Message sent, TelamonTestPage
Command line text — Text
representing information entered
by the user at the command line or
presented by TelAlert as output is
shown in a monospaced font.
Click OK.
Within procedural (how-to) text, boldface words are
characters you type or elements you can click. Within
overview or conceptual text, bolded words may simply
represent concepts that have been highlighted to
emphasize their relative importance.
1. Go to the Add User
page.
Within procedural text, numbered steps denote actions that
should be followed in sequence.
Message Formatting
In this guide, message text passed on the command line is enclosed in quotation marks.
This is not required in all cases, but putting your message text in quotation marks is an
excellent habit, as it ensures that neither TelAlert nor any shell you might be using will read the message as anything other than a string of text to be delivered.
4 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Example Purpose
"Open telalert.ini and search for ..."
" ... gives the file a .bak extension and then ..."
File names and extensions — The same
monospaced font is used to represent file names
and extensions.
{LauraTextPager}
...
Configuration=SkyTelNationalTe
xtPager
PIN=4850879
The ellipses (...) indicate information that
may be present in the actual
telalert.ini entry but which is
omitted in the example because it is not
relevant here.
telalert.iniexamples — Entries drawn from the
TelAlert configuration file are also represented in
a monospaced font.
Click OK.
Within procedural (how-to) text, boldface words
are characters you type or elements you can
click. Within overview or conceptual text, bolded
words may simply represent concepts that have
been highlighted to emphasize their relative
importance.
2. Go to the Add User page. Within procedural text, numbered steps denote
actions that should be followed in sequence.
� Click Save to save your work.
� Click Cancel to exit without
saving.
Within procedural text, bulleted text denotes
available options. Within overview or conceptual
text, bulleted text also denotes supporting
information that is subordinate to the major
topic being discussed in the Guide.
The light bulb icon denotes a helpful tip.
The information icon denotes reference material.
The note icon indicates definitions or
considerations that help you understand the
related task.
Chapter 1: Introduction | 5
1.5.1 Screen Captures
Due to the flexibility of permissions in the TelAlert system, some of the functionality represented in
the screen captures for this Guide is not always visible to, or functional for, all users. The User
Interface screen captures are intended for instructional use. The system administrator determines
access to specific functions using the role-based access functions available in the TelAlert system.
1.5.2 File Locations
By default, TelAlert is installed in /usr/telalert on UNIX systems. Note that some files, (including log
files) are placed in /tmp. On Windows files are placed in c:\Program Files\telalert. Other
TelAlert files are placed in directories relative to this location.
You are not required to accept these defaults during installation, but all references to file locations in
TelAlert documentation assume (for simplicity of representation) that these default settings have
been used.
1.6 Structure of the Administrator Guide
The following is a brief outline of the structure of the Administrator Guide, which should help you
identify the parts that will be relevant for you as you go about the work of configuring TelAlert.
1.6.1 Chapter 1: Introduction
This chapter presents a general overview of TelAlert from a product perspective.
1.6.2 Chapter 2: What is TelAlert 6e
This chapter presents a general overview of TelAlert from a technical perspective.
1.6.3 Chapter 3: Technical Overview
This chapter presents a general overview of TelAlert from a technical perspective.
1.6.4 Chapter 4: Implementation Planning
The present chapter focuses on familiarizing you with the work you must do to configure TelAlert to
meet your organization’s specific needs.
1.6.5 Chapter 5: Configuration Basics
Beginning with version 5.0, TelAlert can be configured using either a text editor or a graphical
interface provided by MIR3. This chapter discusses the differences between the two approaches,
helping you choose the one that is right for your organization.
Broken Lines in telalert.ini
In TelAlert configuration examples presented here, some lines are too long to be
presented as single lines. In such cases, the line is broken and continued below. The
continuation is indented. It is assumed that, in the TelAlert entry itself, the line will not
actually be broken. Note that telalert(c) does not support breaking command lines.
6 | TelAlert 6e™ Administrator Guide - Version 6.1.29
1.6.6 Chapter 6: The Role of Ports in TelAlert
[Port] definitions are key to all notifications. This chapter explains their standard role and the
settings you need to understand in order to take advantage of special port-related functionality,
including port backup and notification via remote ports. The things you will learn in this chapter will
be relevant to a great deal of the other work you will do while setting up TelAlert.
1.6.7 Chapter 7: Dialing the Telephone
Many of TelAlert’s paging and voice notification capabilities rely on dialing the telephone. This
chapter explains all of the configuration settings that control how TelAlert dials the telephone,
teaching you to handle a wide variety of special dialing scenarios, from overlapping area codes to
special billing codes to inside and outside lines. The things you will learn in this chapter will be
relevant to a great deal of the other work you will do while setting up TelAlert.
1.6.8 Chapter 8: Configuring for Paging Notification
Paging is the most commonly used notification medium supported by TelAlert. Setting up paging
involves setting up [Configurations] definitions for all the paging services and pager types your
organization uses and then creating a [Destinations] definition corresponding to each of the
pagers to which you want notifications to be sent.
This chapter walks you through the procedures required to set up a number of different types of
paging: numeric and alphanumeric (i.e., text), and two-way. It also covers the differences between
sending pages using a standard modem connected to the machine on which TelAlert is running and
Internet-based access to paging services.
1.6.9 Chapter 9: Configuring for Text to Speech (TTS) Notification
Text to Speech (TTS) is the second most commonly used notification medium supported by TelAlert.
If you plan to use TelAlert’s voice capability, you should have purchased a TelAlert Dialogic telephony
card and installed and tested it following the directions in the TelAlert Voice and Hardware
Guide. Once TTS is in place, most of your work will consist of setting up specific
[Configurations] and [Destinations] definitions appropriate for voice notifications.
One important aspect of this process is determining how TelAlert should behave when a number it
calls is answered—for instance, whether it should expect to reach a voice mail system or a human
user whom it must ask for identification before reading its message.
All the information regarding the TelAlert Dialogic telephony card and software configuration for
voice functionality is now covered in chapters 2 through 4 of the TelAlert Voice and Hardware
Guide.
Information on Configuring for TTS Notification is now in the TelAlert Voice and
Hardware Guide
Since TelAlert TTS functionality requires a TelAlert Dialogic telephony card, the
information on software and hardware configuration for voice functionality now resides in the TelAlert Voice and Hardware Guide.
Chapter 1: Introduction | 7
1.6.10 Chapter 10: Configuring for Other Notification Media
Because paging and voice are the notification methods most often used by TelAlert users, the
Administrator Guide deals with them in separate chapters. In this chapter, you will find coverage
of the setup required for sending notifications via other supported media, including email, command
line destinations, electronic signboards, SpectraLink campus phone systems, other computer
systems (UNIX syslog processes, AS/400s, and TelaConsole installations), and Web-enabled and
text-screen-equipped cellular phones.
1.6.11 Chapter 11: Applying Filtering Techniques
Once you understand the basics of sending messages (covered in the chapters on paging, voice, and
other notification media), you can use a variety of techniques to have TelAlert restrict the messages
it sends, based on specified conditions. You can have TelAlert delay sending a message for a certain
amount of time, send the message only after it has been asked to send one or more duplicates, send
the message immediately and then suppress all duplicates, or send the message immediately and
then send only a subset of duplicates. You can also use [Filter] definitions and -tags values to
invoke additional rules for deciding which destinations in a group to choose when sending a
message. This chapter covers these and other filtering techniques.
1.6.12 Chapter 12: Setting Up and Applying Schedules
[Schedule] definitions can be invoked in [Destinations] or [User] definitions. At whatever level you invoke a schedule, TelAlert uses this information to evaluate affected destinations and
determine which are valid at the time TelAlert sends a notification.
Schedules can play a role in notifications sent to a single destination, but primarily they serve to
determine which of a group of destinations are valid at any given time. They are an important part of
implementing TelAlert’s escalation capabilities, but, even when used solely in conjunction with simple
group sends, they allow you to differentiate between on-duty and off-duty destinations so that the
right people are notified every time.
1.6.13 Chapter 13: Representing Users
[User] definitions are a means of representing people in your TelAlert configuration. This allows you to store certain user-specific information conveniently and apply it where necessary (in a
[Destinations] definition, for instance) simply by referring to the appropriate [User]
definition. This offers advantages for both sending messages and administering the sending of
messages. Also, [User] definitions are required for certain types of notifications. This chapter
explains all you need to know about defining users in the TelAlert configuration file.
1.6.14 Chapter 14: Enabling Responses
Recipients of TelAlert messages can respond remotely using two-way pagers or touch-tone
telephones; they can also issue a command line response on a machine on which telalertc is
installed. The most basic aspects of TelAlert’s support for responses require no setup; this chapter
covers these but focuses on techniques for creating customized [Response] definitions. These can play a role in escalations; they can also be used in conjunction with [Notifications] definitions
to initiate additional actions.
8 | TelAlert 6e™ Administrator Guide - Version 6.1.29
1.6.15 Chapter 15: Broadcasting to Groups and Creating Escalations
Groups are collections of destinations. Setting up [Group] definitions is very simple; the principal
challenge is looking at your organization and its notification needs and deciding what groups to
create. The best way to approach this issue is to consider what groups already exist within your
organization—implicitly or explicitly— among the pool of potential message recipients. You might
form groups on the basis of a wide range of traits: e.g., functional area, physical location, shift, or
level of responsibility/authority.
You can use [Group] definitions to send messages to a number of destinations at once
(broadcasting). You use a combination of [Group] and [Strategy] definitions to perform an escalation—sending the message either to a series of individual destinations, one at a time, or to all
the destinations comprising one subgroup, then to all the destinations comprising the next subgroup,
and so on. This chapter covers all the details of creating [Group] and [Strategy] definitions and using them for broadcast notifications and escalations.
1.6.16 Chapter 16: Processing Events
TelAlert is able to recognize a wide range of internal events—some relating to notifications, some
relating to input from environmental monitors, some relating to logging, and some relating to the
state of TelAlert’s constituent processes. This chapter explains the procedures for having TelAlert pay
attention to designated events and process them according to rules you specify.
1.6.17 Chapter 17: Miscellaneous Administrative Tasks
This chapter covers a variety of administrative tasks, including running TelAlert as a service on
Windows, setting up the TelAlert Web client, installing clients, and starting, stopping, and initializing
TelAlert.
1.6.18 Chapter 18: TelAlert Monitor
This chapter provides a guide on the TelAlert Monitor interface, and its usage.
1.6.19 Chapter 19: Security Features
This chapter shows how security enhancements have been woven into the architecture of TelAlert,
along with some practical examples of new security features.
1.6.20 Chapter 20: Integrating XML Output
This chapter shows how TelAlert’s XML output can be integrated with various third-party applications.
2
What is TelAlert 6e?
2.1 Overview
This chapter contains high-level look at TelAlert 6e, integrations, and documentation.
2.2 What is TelAlert 6e?
TelAlert 6e is an enterprise messaging platform comprised of a central messaging component, a set
of configuration tools, and add-on product modules.
2.2.1 Messaging Component
The central messaging component is called TelAlert Messaging Server. System administrators
("administrators") configure and maintain TelAlert Messaging Server.
2.2.2 Configuration Tools
Administrators configure TelAlert Messaging Server and apply business rules using these tools:
� TelAlert Desktop. This is an administrative user interface (UI) for configuring one or more
TelAlert Messaging Server installations. After installing TelAlert 6e, the first thing
administrators do is use TelAlert Desktop to setup the initial configuration of TelAlert
Messaging Server for their enterprise. This initial configuration serves as the first building
block. On top of this, administrator, supervisor, and staff-level users make additional configuration changes through the TelAlert Web UI.
� TelAdmin. Accessed via TelAlert Desktop, this is a tool for configuring administrator-level
features of TelAlert Messaging Server.
10 | TelAlert 6e™ Administrator Guide - Version 6.1.29
� TelAlert Web UI. This is a tool primarily dedicated to end-user (supervisors and staff)
features. These include creating users, adding users’ communication devices, creating
groups of users, devices, and other groups, and creating schedules (on-duty, off-duty, and so
on). However, administrators also use the TelAlert Web UI to import user data, manage
departments, create holiday schedules, enable LDAP authentication at log, and other
complete other tasks (see the Getting Started section in the TelAlert Web UI online help for details). In some cases, administrators may need to use the end-user features as well.
2.2.3 Add-On Product Modules
You can extend the capabilities of the TelAlert 6e platform with the Failover module. Modules are
purchased separately.
TelAlert 6e Takes Messages from Any Source...
TelAlert 6e works with virtually any kind of application, including network monitoring, enterprise
management, help desk, and dispatch solutions—anything capable of generating event-based
messages and issuing user-defined Windows or UNIX commands.
... Applies Your Business Rules
TelAlert 6e lets you exert an unparalleled degree of control over how it processes messages. You
can:
� Define groups for broadcast notifications—or person-by-person escalations that ensure
someone responds, even if the first addressee is unavailable.
� Set up rules governing how escalations proceed.
� Create schedules determining when each support technician is available to receive messages.
� Process messages based on priority.
� Create filters to weed out trivial messages and automatically direct important messages to the right people.
... Sends Messages to the Right Destinations
TelAlert 6e can deliver text messages to a wide range of destinations, including:
� Cell phones equipped with text screens (WAP or SMS)
� Wireless PDAs (RIM, Palm, Visor)
� Pagers
� Email addresses
� Electronic Signboards
... And Accepts and Processes Responses
TelAlert 6e does much more than deliver messages. It also allows recipients to respond to messages—a
key factor in TelAlert 6e's ability escalate an alert and ensure that someone takes control of the
situation.
Chapter 2: What is TelAlert 6e? | 11
2.2.4 Two-Way Pagers
Recipients can choose from a customizable menu of reply options to accept or decline messages,
update trouble tickets, ping a node, and more. More sophisticated functionality can be achieved
through server-side scripting.
2.2.5 WAP- and SMS-Enabled Cell Phones
Recipients can wirelessly acknowledge and manage messages through the TelAlert Web Clients.
These are two client applications that run on Web servers and can be accessed from any Web
browser. They are different than the TelAlert 6e Web UI.
2.2.6 Applet-Based Remote Interactions
MIR3 Professional Services can develop custom applets for today's leading two-way wireless devices.
Users benefit from familiar, graphical interfaces that provide powerful remote control over back-
office applications.
2.3 TelAlert Text to Speech (TTS)
TelAlert Text to Speech (TTS) gives you all the capabilities of TelAlert, plus the license and hardware
you need to deliver voice messages and let recipients interact with TelAlert and integrated
applications via touch-tone telephone.
See the TelAlert Voice and Hardware Guide for complete technical instructions relating to
TelAlert TTS functionality.
2.3.1 Full Range of Voice Destinations
TelAlert Voice can dial a telephone number, monitor call progress, validate the identity of the person
who answers, and then speak its message. When appropriate, it will negotiate voicemail or
answering machine systems and leave a recorded message.
2.3.2 Customizable Vocabulary in Four Languages
The voice fonts in TelAlert TSS are generated by AT&T’s Natural Voices. These fonts are available in
English, French, German, and Spanish. All languages are available in male and females voices.
English is also available in American, UK and Indian Accent.
2.3.3 Interactive Voice Response (IVR)
Users can enter keypad input to accept or decline messages when they are delivered by TelAlert over
the telephone. Users can also dial in and interact with TelAlert —and even the backoffice applications
with which it is integrated—via customizable IVR menus.
2.3.4 Dialogic Telephony Card
Windows users can choose to plug a Dialogic telephony card into the machine on which TelAlert is
installed or it can be configured on a remote Windows computer.
12 | TelAlert 6e™ Administrator Guide - Version 6.1.29
2.4 TelAlert 6e Integrations
TelAlert 6e is designed to work with other applications—to take the messages they generate and,
following your business rules, pass them to the right people, using the medium of your choice.
2.4.1 TelAlert 6e Integration Templates for Third-Party Applications
It is easy to make TelAlert 6e work with almost any application, whether it be a network monitoring,
enterprise management, help desk, or dispatch solution. The following integrations have been
developed and documented by TelAlert engineers. Many come with special scripts and other support
files that help you get up and running as quickly as possible.
� Computer Associates TNG Advanced Help Desk
� Computer Associates Unicenter TNG
� HP Software Operations Manager (formerly HP OpenView IT/Operations)
� HP Software Network Node Manager
� HP Software ServiceDesk
� HP Software ServiceCenter (formerly Peregrine)
� HP Software ServiceManager
� Remedy AR System
� Remedy Help Desk
� Tivoli Enterprise Console
� Tivoli NetView
2.4.2 Do-it-Yourself Integrations for In-House Applications
Even with applications for which no certified integration exists, integration with TelAlert 6e is
typically a simple matter, since most TelAlert 6e integrations are carried out at the command line.
For instance, perhaps your organization relies on an application it has developed in-house. If this
application can be configured to issue UNIX or NT commands in response to specified events, it can
be integrated with TelAlert 6e.
If you choose to perform your own integration, you can also use the TelAlert 6e API or Java class.
Chapter 2: What is TelAlert 6e? | 13
2.5 Supported Platforms
The list below is current as of this writing. Please refer to the current TelAlert Release Notes for the
most up to date platform support.
2.5.1 Web Server
Microsoft
Windows (32 bit – Server) (4.0/2000/XP Professional) EXISTING
Windows (32 bit – Server) (2003) EXISTING
Windows (32 bit – Server) (2008) NEW
Linux
Red Hat Enterprise Linux AS release 4 EXISTING
Java
Java JRE 1.5 (5.0) EXISTING
Tomcat
Tomcat 5.5.X EXISTING
Web Browser
A JDK 1.1 compatible web browser EXISTING
2.5.2 Database Server
Database
Oracle 10g EXISTING
SQL Server 2000 SP 4 and 2005 (2005 recommended)* EXISTING
mySQL 5.0 and above EXISTING
*If using SQL Server express all TCP ports must be set to 1433 as shown in the figure below.
14 | TelAlert 6e™ Administrator Guide - Version 6.1.29
2.5.3 Messaging Server and Client Platforms
� HP-UX PA-RISC 1.1 (11.31 and higher)
� HP-UX PA-RISC 2.0 (11.31 and higher)
� HP-UX Itanium2 (11.31 and higher)
� Linux (glibc 2.5) (Intel x86 32bit) (Red Hat 5.4)
� Windows (32 bit – Server) (2000)
� Windows (32 bit – Server) (2003)
� Windows (32 bit – Server) (2008)
� Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (SPARC 32/64 bit)
� Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (Intel X86 32/64 bit)
� Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (SPARC 32/64 bit)
� Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (Intel X86 32/64 bit)
Chapter 2: What is TelAlert 6e? | 15
2.5.4 Client Platforms
Client systems have 3 states, supported on the current version, supported with an older version and
discontinued. All 5.00 – 5.70 client versions are compatible with the 5.71 server software.
Operating System Status
AIX
AIX 3.2.5 Supported with TA 5.20
AIX 4.1.3 (and higher) Supported with TA 5.20
AIX 5.2 (and higher) Supported with TA 5.60
HP-UX
HP-UX PA-RISC 1.0 (9.04 and higher) Supported with TA 5.50
HP-UX PA-RISC 1.1 (9.04 and higher) Supported with TA 5.50
HP-UX PA-RISC 1.1 (10.20 and higher) Supported with TA 5.70
HP-UX PA-RISC 2.0 (10.20 and higher) Supported with TA 5.70
HP-UX PA-RISC 1.1 (11.31 and higher) EXISTING
HP-UX PA-RISC 2.0 (11.31 and higher) EXISTING
HP-UX Itanium2 (11.31 and higher) EXISTING
Java
Java 1.50 (TelAlert Admin "telalert") EXISTING
Java 1.50 (TelAlert EndUser "telalertc") EXISTING
Java 1.60 (TelAlert Admin "telalert") EXISTING
Java 1.60 (TelAlert EndUser "telalertc") EXISTING
Linux
Linux (glibc 2.0) (Intel x86 32bit) Supported with TA 5.70
Linux (glibc 2.1) (Intel x86 32bit) Supported with TA 5.70
Linux (glibc 2.5) (Intel x86 32bit) (Red Hat 5.4) NEW
Microsoft
Windows (32 bit – Server) (4.0/2000/XP Professional) EXISTING
Windows (32 bit – Server) (2003) EXISTING
Windows (32 bit – Server) (2008) NEW
16 | TelAlert 6e™ Administrator Guide - Version 6.1.29
SGI
SGI Irix Supported with TA 5.50
SGI MIPS ABI Supported with TA 5.50
SCO
SCO Release 3 Supported with TA 5.50
SCO Release 5 Supported with TA 5.50
Sun
SunOS 4.1.3 (SPARC 32bit) Supported with TA 5.50
Solaris 2.7 (Solaris 7) + (SunOS 5.7+) (SPARC 32/64 bit) Supported with TA 5.70
Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (Intel X86 32/64 bit) NEW
Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (SPARC 32/64 bit) NEW
Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (Intel X86 32/64 bit) NEW
Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (SPARC 32/64 bit) NEW
Other
AT&T GIS (System 3000) Supported with TA 5.50
BSDI 4.1 Supported with TA 5.50
Digital Unix (Tru64 UNIX 5.1A BL4) Supported with TA 5.70
Tandem Guardian & Tandem OSS Supported with TA 4.03
IBM OS/2 Supported with TA 5.10
HP MPE/iX (WRQ format) Supported with TA 5.20
Chapter 2: What is TelAlert 6e? | 17
2.5.5 Operating Systems Not Supported for Version 5.7
TelAlert no longer has access to the following platforms, so we cannot build 5.7 server or client
software for them; nor can we provide bug fixes for prior versions. Customers with support
contracts, who are running TelAlert version 5.1 or 5.2 on these platforms, can continue to receive
technical support with configuration, operation, and other such issues that are not related to the
operating system. We encourage migrating as soon as possible to a fully-supported platform.
Server/Client platforms:
� HP-UX PA-RISC 1.1 (10.20 and higher)
� HP-UX PA-RISC 2.0 (10.20 and higher)
� AIX 5.2 (No AIX version is supported in this release)
� Linux (glibc 2.0) (Intel x86 32bit)
� Linux (glibc 2.1) (Intel x86 32bit)
� Solaris 2.7 (Solaris 7) + (SunOS 5.7+) (SPARC 32/64 bit)
� Digital Unix (Tru64 UNIX 5.1A BL4)
2.6 TelAlert 6e Documentation
The TelAlert 6e documentation set can be downloaded from
http://www.telalert.com/products/telalert/doc.php. It includes the following documents:
2.6.1 TelAlert 6e Administrator Guide
The TelAlert 6e Administrator Guide is the most comprehensive TelAlert 6e resource. It is
primarily a how-to document that assumes that you have installed TelAlert 6e and are ready to
begin configuring and administering it.
2.6.2 TelAlert 6e Installation Guide
The TelAlert 6e Installation Guide provides detailed installation instructions for new users. If you
are migrating from TelAlert (TelAlert Messaging Server) or TelAlert Corporate Messenger, contact
Technical Support.
2.6.3 TelAlert 6e Online Help
The TelAlert 6e Online Help provides conceptual and procedural assistance in using the TelAlert Web UI.
2.6.4 TelAlert 6e Keyword and Command Reference
The TelAlert 6e Keyword and Command Reference is a detailed reference to the keywords
supported by the TelAlert 6e, and the event and state messages issued by TelAlert.
18 | TelAlert 6e™ Administrator Guide - Version 6.1.29
2.6.5 Integration Instructions
TelAlert 6e’s template integration instructions contain the information you need to integrate TelAlert
6e with a variety of commercial applications. Datasheets are available from the MIR3 Web site;
request detail documentation and scripts from TelAlert Sales or TelAlert Support.
2.6.6 TelAlert 6e Failover Module Guide
The TelAlert 6e Alert Failover Module Guide describes how to install, configure, and use the
Failover module.
2.7 TelAlert Messaging Server File Locations
By default, TelAlert Messaging Server is installed in /usr/telalert on UNIX systems. Note that
some files, including log files, are placed in /tmp.
On Windows, TelAlert Messaging Server files are placed in c:\ProgramFiles\telalert. Other
TelAlert files are placed in directories relative to this location.
You are not required to accept these defaults during installation, but all references to file locations
in TelAlert documentation assume (for simplicity of representation) that these default settings have
been used.
3
Technical Overview
3.1 Overview
This chapter contains a high-level look at TelAlert Messaging Server from a technical perspective:
how it works, the programs and processes comprising it, key TelAlert Messaging Server files, the
concepts underlying TelAlert Messaging Server configuration, some frequently asked questions—
and their answers.
3.2 How TelAlert Messaging Server Works
TelAlert Messaging Server follows instructions issued by TelAlert 6e users and applications. TelAlert
Messaging Server can accept instructions from users via TelAlert Desktop, TelAdmin (a
configuration tool in TelAlert Desktop), and the TelAlert Web UI. TelAlert Messaging Server can also
accept instructions from integrated applications via calls to TelAlert 6e API functions or Java
methods, and from command-line clients. Instructions to TelAlert Messaging Server fall into one of
three categories:
� Notification
� Adminstrative
� Responsive
Notification Instructions
Notification instructions specify a message that TelAlert Messaging Server is to send to one or
more recipients. Notification instructions can originate directly from an application, such as a
network monitoring application, or from TelAlert 6e users. Notification instructions from
applications generally utilize a TelAlert API or one of several command-line client programs.
Notification instructions from TelAlert 6e users generally use the TelAlert 6e Web UI.
Administrative Instructions
Administrative instructions relate to configuring the TelAlert environment (for example, modem
and Internet connections, information about the wireless providers that are used, and so on),
starting and stopping TelAlert Messaging Server, and checking the TelAlert Messaging Server’s
processing of notification instructions. Administrative functions dealing with starting and stopping
TelAlert Messaging Server are generally done via the command-line clients. They are also automated
as part of the startup and shutdown of the underlying operating system. Administrative functions
20 | TelAlert 6e™ Administrator Guide - Version 6.1.29
dealing with checking the status of TelAlert Messaging Server’s processing of notification instructions
are done via a combination of command-line clients, TelAdmin, and the TelAlert 6e Web UI.
Responsive Instructions
Responsive instructions come from message recipients and acknowledge receipt of the message,
update the status of a problem, ask for more information, and so on.
The main TelAlert Messaging Server process is telalerte. telalerte validates these
instructions against TelAlert Messaging Server configuration information and queues tasks to be
performed by other server processes, which in turn are responsible for interactions with specific
devices or connections, such as modems, Dialogic telephony cards, and sockets-based Internet
connections.
3.2.1 A Typical Alert
A typical scenario has TelAlert Messaging Server running on the same server machine as a network
management application (referred to here as the “controlling application”). This application has
been configured to respond to certain network events by passing an appropriate command to
TelAlert using telalertc. Thus, when the controlling application detects a node failure, for
example, it issues a command to TelAlert, along with the message to be delivered.
The following diagram shows how a network monitoring application, on detecting that a server is
down, could use TelAlert to send a message to a single text pager:
Figure 1. A Typical TelAlert Send
First, the controlling application issues the following command:
telalertc -i BobTextPager -m "node 2745 down"
This command invokes telalertc (the command-line client), which passes the command to
telalerte (the primary TelAlert server process).
telalerte then looks in telalert.sects, the configuration file, to find the definition for the
recipient, the configuration information for the modem to be used, etc. Next telalerte tells
telalertm (TelAlert’s modem daemon, the process that actually controls the modem) precisely
what to do, providing it with instructions for dialing the specified service provider, the PIN for this
particular recipient, and finally the message itself.
All the while, telalerte records each step in the process in a file called
telalert.trail. It also records this alert as active in the telalert.alert file.
Chapter 3: Technical Overview | 21
3.3 Server Processes and Command Line Clients
TelAlert Messaging Server is comprised of several server processes, and it is capable of receiving
command line instructions from various command line clients. Some of these processes and
command line clients have been mentioned already in this chapter. Each is described in greater
detail below.
3.4 Server Processes
This section describes many of the server processes that comprise TelAlert Messaging Server.
3.4.1 telalerte (TelAlertE.exe)
telalerte is the core messaging component of TelAlert Messaging Server. A continually running
daemon process, telalerte takes commands and messages received by telalert or
telalertc (the command line clients, sometimes shown as telalert(c)) and renders them
complete, incorporating information referred to in the TelAlert configuration file. It then passes
complete instructions to the daemon responsible for carrying out the responsibility at hand.
telalerte tracks all TelAlert Messaging Server activity, recording it in a comprehensive events
file called telalert.trail. It maintains a record of all active alerts in telalert.alert.
telalerte is also the part of TelAlert Messaging Server that processes responses and requests. If
a message recipient dials in and acknowledges receipt of a message using TelAlert’s voice menus,
this response is passed by telalertd (the daemon handling interactions with the TelAlert Voice
Engine or Dialogic telephony card) to telalerte, which updates the status of the alert (internally
and, where applicable, with the monitoring application that originally issued the command) to
reflect the acknowledgment. Similarly, if someone uses telalert to request a list of all active
alerts, it is telalerte that retrieves this information and passes it to telalert for display.
3.4.2 telaconfe (TelaConfE.exe)
telaconfe is the database management system that controls and stores information on changes
you make to your configuration using TelAdmin. On Windows, telaconfe runs as a service. On
UNIX, telaconfe runs as a daemon. On both Windows and UNIX, telaconfe can accept
instructions from other applications or from the telaconf command line client. On Windows,
telaconfe should be configured to start up automatically when the system boots up. See the
TelAlert 6e Installation Guide for additional information.
On Windows, if necessary, you can start telaconfe manually by issuing the following command:
net start telaconf
To verify that the process has started, issue the following command:
telaconf -status
On UNIX, you can also configure telaconfe to start automatically when the system boots up. For
details, see the telaconf.init.d file, which contains comments about how to customize it and
copy it to the startup directory. It can also be manually started with the command
telaconf -start.
If an error message such as Error*Can't connect to host... appears in either a popup box
inside TelAdmin, or on the command line, there's a good chance that telaconf has not been
started.
22 | TelAlert 6e™ Administrator Guide - Version 6.1.29
3.4.3 telalertd (TelAlertD.exe)
The child of telalerte that handles Voice Engine ports. telalertd is the process responsible
for operation of the TelAlert Voice Engine. Following instructions provided by telalerte, the
Voice Engine controls the modem of the Engine and any external devices connected to it. It also
provides the Engine with the messages that it is to read.
3.4.4 telalertf (TelAlertF.exe)
The child of telalerte that handles fax ports.
3.4.5 telalertm (TelAlertM.exe)
The child of telalerte that handles modem ports. telalertm is the process responsible for
dialing the modem of the server machine on which TelAlert is installed and, following instructions
passed to it by telalerte, sending and receiving information over this connection. telalertm
handles only numeric and text paging and polling.
3.4.6 telalertr (TelAlertR.exe)
The child of telalerte that handles relay ports. telalertr is the process responsible for
controlling electronic signboards and other RS232 devices (excluding the TelAlert Engine and
modems).
3.4.7 telalerts (TelAlertS.exe)
The child of telalerte that handles Internet ports. telalerts is the process responsible for
all sockets-based TelAlert interactions. It communicates with SMTP and SNPP servers to send email
and online pages, respectively.
3.4.8 telalertv (TelAlertV.exe)
The child of telalerte that handles Dialogic ports.
3.4.9 readmail (ReadMail.exe)
TelAlert comes with an email-reading program that allows TelAlert to accept and process replies
using email. This includes replies to messages sent straightforwardly as emails and replies to
certain two-way pager notifications (PageNet and WebLink Wireless) that take the form of emails.
See the section Handling Responses to Email With Readmail in Chapter 10 of this manual for
more information.
3.4.10 ntfysrvr (NtfySrvr.exe)
The ntfysrvr process transmits a copy of every message status event. This information is
needed for the Alert Monitor in TelAlert Desktop and the alert lists and details in the TelAlert Web
UI. ntfysrvr uses a "publish-subscribe" model. ntfysrvr makes the data available (publish),
and applications that want a copy of the message status event data stream initiate a connection to
ntfysrvr (subscribe). So a single instance of ntfysrvr can provide message status event
data to an unlimited number of other applications.
3.4.11 hostaddr (HostAddr.exe)
The hostaddr process tests the server’s networking setup to see what it thinks its DNS name
and IP address are.
Chapter 3: Technical Overview | 23
3.4.12 killtela (KillTela.exe)
Only for Windows, the killtela process allows killing hung server processes (telalerte and
its children). Windows does not come with an equivalent of *nix's KILL command, and Task
Manager will often not touch telalerte and its children because of permissions issues.
3.4.13 mailaddr (MailAddr.exe)
The mailaddr process tests the DNS MX (Mail eXchanger) setup for a particular domain, and it
helps in configuring and testing TelAlert's ability to send using the SMTP (email) protocol.
3.5 Command Line Clients
This section lists the command line clients that can send instructions to TelAlert Messaging Server.
3.5.1 telalert (TelAlert.exe)
telalert is a command line client used to issue administrative instructions to telalerte. It
can also be used to issue the same notification and response instructions as those supported by
telalertc.
Most administrative commands can be issued on any machine on which telalert is installed,
regardless of whether it is the same machine on which telalerte is running. Certain key
administrative commands, including -start, -stop, -compile, and
-init, must originate on the telalerte machine; they cannot be given remotely.
3.5.2 telalconf (TelaConf.exe)
telaconf is a command line client for the telaconfe server.
3.5.3 telalertc (TelAlertC.exe)
telalertc is a command line client designed as an altrernative means (to the TelAlert Web UI)
for end users to issue notification and response instructions to telalerte. It can be run on the
same machine as the TelAlert server. It can also be installed on another machine and used to
interact with telalerte remotely.
3.5.4 telalerth (TelAlertH.exe)
telalerth is CGI-bin client with end user capabilities that allows a Web server to communicate
with telalerte. telalerth is designed to run under a Web (Apache) or servlet (Tomcat). For
instance, if you set up a Web form for users to acknowledge or send alerts, telalerth takes the
information sent via this form to the Web server and passes it to telalerte in a form
telalerte can understand.
telalert vs. telalertc
It is recommended that you use telalertc to issue all TelAlert commands other than
the administrative commands unique to telalert—even when issuing the command
from the machine running the TelAlert server, where telalert is also available.
The reason is simple: when you use telalertc, there is never a danger of accidentally
stopping, re-starting, or re-initializing TelAlert. telalert is the sole means of issuing
still other commands (including -clearall, -releaseall, -ackall, and -nakall)
that you would not want to give accidentally.
24 | TelAlert 6e™ Administrator Guide - Version 6.1.29
3.5.5 telalerths (TelAlertHS.exe)
telalerths is CGI-bin client with admin user capabilities that allows a Web server to communicate
with telalerte. telalerths is designed to run under a Web (Apache) or servlet (Tomcat).
3.6 Key TelAlert Files
Below is a description of some of the key files comprising a TelAlert installation.
3.6.1 telalert.trail
telalerte records all TelAlert activity in this file. When it reaches a specified size (100 K is the
default), the file name is changed to telalert.trbak and telalerte begins a new trail file.
This backup file will be overwritten each time the current trail file reaches 100K. (The
TrailSwitchCmd= line in the [Files] section lets you define an external process for archiving
the data in these backup .trail files.)
3.6.2 telalert.alert
Maintained by telalerte, telalert.alert is a continuously updated file containing all the
information TelAlert needs to process all active alerts.
3.6.3 telalert[e/f/r/s/d/m/h/v].log
By default, TelAlert maintains a separate log file for each of the daemon processes.
telalerte.log is unnumbered, but each of the others (telalertd2.log, for instance) is
marked with a number indicating the place (sequentially) of the definition under [Port] with
which it is associated. The numbering is necessary because a TelAlert installation may feature more
than one instance of the d, s, h, r, and m processes.
3.6.4 telalert.sects
This is TelAlert’s configuration file. It contains a variety of information that TelAlert uses to carry
out commands. This includes licensing details; information about ports, devices, groups,
schedules, and users; and instructions about sending messages to specific destinations and
general destination types.
telalerte reads this file in order to process commands. You can control the way TelAlert works
by using TelAdmin and the TelAlert 6e Web UI to modify this file.
telalert.sects is in a binary format. To generate a human readable format, see the
telalert.ini section below.
3.6.5 telalert.ini
telalert.ini is divided into “sections” headed by words enclosed in “straight” [brackets]. Many
of these sections are further subdivided into “definitions” headed by words enclosed in “curly”
{braces}. Lines in the telalert.ini file that are neither section nor definition headings take the
form keyword=value, where keyword is any of the many words TelAlert is programmed to
recognize (including but not limited to section names), and value is the value you assign
(including but not limited to definition names).
When TelAlert is installed, the first version of the binary telalert.sects file is "compiled" from
a human-readable text file named telalert.ini. (telalert.ini may actually be a set of files, where the primary telalert.ini file contains $include commands that reference other .ini files during the compilation process.) When using stand alone TelAlert vs. TelAlert 6e, users
have the option of using either the telalert.ini file or Desktop Admin for configuring
TelAlert. In TelAlert 6e all subsequent configuration changes must be made by directly changing
Chapter 3: Technical Overview | 25
telalert.sects. This is done by Desktop Admin for certain sections and the Web UI for others and never the telalert.ini file. For details on which configuration method to use when see
Chapter 5 Configuration Basics. The telalert.ini file can still be used to illustrate all the
different configuration settings in one flat file. It may also be used as a back up file for the
current configurations. To make a backup file and save it to telalert.ini enter in the
following command:
telalert –verifyini –value > telalert.ini
For additional information see Handling telalert.sects and telalert.ini file backups
when TelAdmin is used in Chapter 17
Figure 2. TelAlert Files, Processes, and Destinations
3.7 Key Configuration Concepts
In order to understand your notification and response objectives, TelAlert relies on two sources of
information. The first is the command interface (be it command line, API functions, or Java
methods), which may be used by another program or a human user. The second is the TelAlert
configuration file—telalert.sects. These two sources are heavily dependent on one another.
While it is possible to pass varying amounts of information directly on the command line, virtually
all commands use configuration keywords to make explicit reference to information stored in the
configuration file. For example, to send a message to Bob’s text pager, you might use the
following command:
telalertc -c SkyTelNationalTextPager -pin 1234567 -m "node 2745
down"
26 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Here, -c tells TelAlert to understand SkyTelNationalTextPager as a reference to the
[Configurations] definition of the same name. This definition contains information on how to
use the SkyTel service, but the PIN for the intended individual recipient is passed here on the
command line, as is the message itself (the text following -m, which is best enclosed in quotation
marks).
Alternatively, you could issue a command referring to a specific “destination” (see below) defined
in the configuration file. For instance:
telalertc -i BobTextPager -m "node 2745 down"
Here, -i tells TelAlert to understand BobTextPager as referring to a [Destinations]
definition (as opposed to a [Configurations] or [Group] definition, signaled by -c and -g,
respectively). Typically, {BobTextPager} would include the PIN and, by means of a keyword
reference, needed configuration information (that stored in the definition of, for instance,
{SkyTelNationalTextPager}).
Command-line invocation of configuration data is key to much of TelAlert’s flexibility and power—
most notably, its scheduling, group-send, escalation, and response functionality. The following
discussions are intended to acquaint you with the concepts you need to understand to configure
TelAlert. Each discussion focuses on the concept at hand but introduces related concepts where
necessary to help you develop a sense of the big picture—how the various pieces of configuration
data combine to deliver some of TelAlert’s most valuable benefits.
4
Implementation Planning 4.1 Overview
An introduction to the work of setting up TelAlert to meet your organization’s unique notification needs.
4.2 Your Accomplishments So Far
Chapter 2: What is TelAlert 6e and Chapter 3: Technical Overview provide a conceptual
understanding of TelAlert, from both a product and a technical perspective. This chapter is designed to
acquaint you with the major issues you will face as you prepare to implement TelAlert in ways that
make sense for your company. It also explains how the organization of the Administrator Guide is
connected to the work you have ahead of you.
Here it is assumed that you have read the previous chapters and are familiar with basic TelAlert
terminology. Further, by now you should have installed the product following instructions in the
Installation Guide and checked your installation by sending a test page. Also, you should have
read the integration guide pertaining to any third-party product(s) with which you plan to integrate
TelAlert. As you will see, integration accompanies rather than follows general implementation, and,
as you move ahead, it will be helpful to understand what kind of integration you need to perform.
Integration Assumptions
TelAlert is designed to work with a controlling application. Many such applications control
TelAlert via the command line—either directly, issuing a TelAlert command just as a human
user might, or indirectly, invoking a script that builds and issues a TelAlert command. (Some
others call TelAlert APIs or Java classes to communicate directly with TelAlert.) Because the
command itself is the key to achieving the desired TelAlert behavior, the rest of the
Administrator Guide focuses on these commands and associated parameters, ignoring the
different ways they might be produced in different integrations.
Integrations differ also in that some store a portion of the contact information required for
sending notifications in the controlling application’s database, while others store all such
information in the TelAlert configuration file. In order to give you the most complete picture
of TelAlert implementation capabilities, the Administrator Guide assumes the latter
scenario.
28 | TelAlert 6e™ Administrator Guide - Version 6.1.29
4.3 The Alert Timeline
As you begin considering your own implementation, it may be helpful for you to think of TelAlert and
its capabilities in terms of a timeline along which the events in the life of an alert can be plotted.
4.3.1 Send and Release
Fundamentally, TelAlert is a means of taking a message from an external source (a controlling
application or utility) and passing it to an external target (the message recipient). Once you have
set up a [Destinations] definition and a [Configurations] definition for it to refer to, the
controlling application can issue a command to TelAlert telling it to send a message to this
destination. For example:
telalertc -i JohnTextPager -m "node 2745 down"
Assuming no special settings or command line options are used, this alert is completed as soon as
the message is delivered:
Figure 3. Simple Alert Timeline
This continues to be true as you add other [Configurations] and [Destinations]
definitions to the mix, thus making other notification media available, and even as you begin
sending messages to more than one destination and filtering these destinations according to the
ones considered on-duty. Whether you are sending a message to one or many destinations,
TelAlert’s basic procedure is the same: it sends the message to the specified destination or
destinations and then lets go of the alert.
Note that TelAlert knows nothing about nodes, node numbers, or downtime. It simply takes the
text of the message received from the controlling application, and sends it to the destination
indicated by the command.
4.3.2 Send, Wait, and Release
This basic procedure changes only when you introduce the element of a response. When a message
recipient is expected to respond to a message, TelAlert has to keep the alert and message alive
even after sending the message to all specified destinations; otherwise, it would not be able to
receive a response.
This extension of the timeline relies on the -ackwait command line option or the value assigned
to AcknowledgeWait (which can be set in a [Configurations], [Destinations], or [Group] definition). Consider the following command:
telalertc -i JohnTextPager -m "node 2745 down" -ackwait 10m
As before, the message is going to be sent to a single destination. The addition of -ackwait 10m tells TelAlert to hang on to the message for ten minutes after it has been delivered, awaiting a
response from the recipient. If, within the ten-minute window, TelAlert receives positive
acknowledgment, it considers the alert complete and lets it go. Likewise, if the ten minutes elapses
without any response, TelAlert lets go of the alert.
Chapter 4: Implementation Planning | 29
Figure 4. Extended Alert Timeline: -ackwait
What does this extension of the timeline accomplish? Since the message is being sent to a single
destination, there is no question of any TelAlert-directed escalation taking place as the result of a
response or non-response. But, for as long as the message and (as a consequence) the alert
remain alive after message delivery (here, ten minutes), TelAlert can accept a response and pass it
to a controlling application. Thus, your help desk application (for instance) will know whether the
problem is being handled—something it could not learn unless the alert were held after the point of
delivery.
4.3.3 Send, Wait, Hold, and Release
The timeline may be extended somewhat further in cases where the recipient can acknowledge and
“hold” the message. Imagine that a message recipient is alerted to a problem of such severity that
it should be tracked beyond the mere acknowledgment of the message. If he or she gives an
acknowledge-and-hold response, TelAlert will keep the message active until it is given a “release”
command.
Figure 5. Extended Alert Timeline: -ackhold
The limit to this held state is set by the value assigned to ReleaseWait. This specifies how long
TelAlert will wait after beginning to hold the message before it releases it automatically.
Using the -holdrefresh parameter with a command has a special effect on the ReleaseWait
value: -holdrefresh causes TelAlert to reset the ReleaseWaittimer each time TelAlert
receives a response other than one instructing it to release the message (these might be status
reports that are written to a file in the controlling application, for instance). Thus, it is possible to
extend the held state of the message indefinitely.
30 | TelAlert 6e™ Administrator Guide - Version 6.1.29
4.3.4 The Alert Timeline and Escalations
The introduction of escalations—achieved using [Group] and [Strategy] definitions—changes the timeline model of a TelAlert alert slightly. Even here, however, the basic idea is the same:
unless it is told to do otherwise, TelAlert considers the alert complete when it has finished sending
all the messages that comprise it.
In an escalation scenario, the main factor governing the life of the alert is the value assigned to the
Complete keyword, which is included in the [Strategy] definition. As long as this criterion has
not been met, TelAlert keeps the alert alive.
An individual message recipient may positively acknowledge having received it and thus cause
TelAlert to let go of that particular “send” (one of the multiple notifications that may result when an
alert is sent to multiple destinations). However, if this individual acknowledgment does not meet
the completion criterion for the alert, the alert itself remains alive.
Likewise, an individual message recipient may acknowledge and hold a message. This affects the
state of the alert itself only if the acknowledgment meets the completion criterion; otherwise it
affects only the state of the individual send. In this case, TelAlert holds the message but continues
to process other sends and responses associated with the alert until the completion criterion is
met. When this happens, TelAlert stops processing sends and clears all messages in an ackwait
state. It continues to hold the held message, however, and as a result the alert remains alive until
the message is released, the ReleaseWait timer expires, or the alert is cleared by the sender or
a TelAlert administrator.
4.3.5 Summary
The timeline of a TelAlert alert is, by default, very short and simple. Unless it is configured to do
otherwise, TelAlert sends all the messages and immediately releases the alert to which they are
related. Extending the life of the alert beyond that point is essential if you want to track
acknowledgement of messages, perform escalations, or let users interact with TelAlert.
Most of the basic configuration issues involved in a TelAlert implementation do not affect this basic
timeline model: it remains in effect regardless of the notification medium, the number of
destinations invoked, the schedules associated with them, and the strategy at work. The key to
extending the timeline is the enabling of responses. For instance, if the -ackwait parameter is
used on the command line, TelAlert will hold on to the alert and wait for a response. If a message
recipient acknowledges and holds the message, TelAlert holds the message pending a command to
release it.
As you proceed with your implementation, keep the timeline model in mind. It will help you
understand what you can accomplish when tackling a configuration issue.
Chapter 4: Implementation Planning | 31
4.3.6 Organizational Scenarios
In what follows, you will find high-level descriptions of three implementation scenarios, ranging
from the very simple to the relatively complex. Because of the significant differences in needs,
structures, and procedures in different organizations, it is impossible to provide you with a precise
blueprint for the work you must do to implement TelAlert in your own. These descriptions are
offered primarily so you can get some sense of the possibilities available to you and the work
required in different instances.
All of these process summaries assume that TelAlert (and, where applicable, the Dialogic telephony
card) is installed and configured to the point that it can send a test page. You should read all three,
as the later ones build on (rather than repeat) the information contained in the first two.
4.3.7 Scenario One: Paging Only—Small Organization
Some people who implement TelAlert want to use it merely to page the members of a small support
group under certain circumstances. The following describes the steps likely to be followed in such a case.
1. Set up [Configurations] Definitions for Paging
In a small organization, it is common for everyone to use the same paging service provider, so you
might have to create only one [Configurations] definition. Here, though, assume that there
are three hands-on support employees with local-coverage paging and a manager who uses a
national service from another provider.
First, create the definition for the local service based on information found in the appropriate file in
the Pagers directory:
[Configurations]
...
{ATTWichitaTextPager}
Type=TextPager
Speed=2400
AreaCode=316
Number=636-4110
Now, go to [PhonePrefixes] and set LocalAreaCode to match the local area code (in this case, 316). This ensures that TelAlert will not dial the area code when it sends notifications using
this definition. Next, create the [Configurations] definition for the national paging service. This too should be based on information contained in the file from the Pagers directory.
[Configurations]
...
{SkyTelNationalTextPager}
A Word About These Scenarios
Here you will find some issues covered in enough detail so that you may be able to
accomplish certain basic goals without looking elsewhere in this guide. But these
scenarios are not intended as a substitute for the more complete coverage provided in
subsequent chapters of this guide. In addition to giving you a sense of what lies ahead,
these scenarios should help you navigate the rest of the TelAlert documentation and determine what coverage is pertinent for you and what you may safely ignore.
32 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Type=TextPager
MaxMessagesPerCall=100
ServiceMaxMessageLength=242
ServiceSupportsMultiBlocks=True
Speed=19200
AreaCode=800
Number=679-2778
For a detailed discussion of these settings, refer to Chapter 8: Configuring for Paging Notification.
2. Set up Destinations
Next, you then would set up four [Destinations] definitions, one for each pager to which
TelAlert will be sending notifications. The following are for the three support employees. Notice that
they all refer to the same [Configurations] definition. These are examples of the data in the
telalert.sects file and are shown in telalert.ini format. The {JohnTextPager}
[Destinations] entry in the telalert.ini format is the same as the JohnTextPager Device
shown in the TelAlert 6e Web UI.
[Destinations]
...
{JohnTextPager}
Configuration=ATTWichitaTextPager
PIN=1234567
{CynthiaTextPager}
Configuration=ATTWichitaTextPager
PIN=2345678
{DavidTextPager}
Configuration=ATTWichitaTextPager
PIN=3456789
You can name these definitions anything you like, but including the person’s name, along with
“text” and “pager,” in the name you assign may be helpful later, even if there currently are no
other entries with which these might be confused.
Next, create the destination for their manager:
[Destinations]
...
{RachelNationalTextPager}
Configuration=SkyTelNationalTextPager
PIN=4567890
For a detailed discussion of these settings, refer to Chapter 8: Configuring for Paging
Notification.
Chapter 4: Implementation Planning | 33
3. Create Groups
At this point, there are just a few [Group] definitions to create. Later, when you begin setting up escalation strategies, you may find that you want to add others or make changes to these (for
instance, since strategies are associated with groups, you may want to create several versions of
the same group and assign each a different strategy).
First, under [Group], create an entry that points to the destinations for all three support
employees. This might be used for standard notifications.
[Group]
...
{Support}
Destinations=’"JohnTextPager","CynthiaTextPager","DavidTextPager"’
Now, because there are some problems that you will want to bring directly to the attention of the
senior support employee (David) and the manager (Rachel), create a [Group] definition that
points only to their destinations.
[Group]
...
{SupportTop}
Destinations=’"DavidTextPager","RachelNationalTextPager"’
Finally, create a [Group] definition that points to both another group—{Support}—and a
destination— {RachelNationalTextPager}. You might use this for the most urgent
messages.
[Group]
...
{SupportAll}
Destinations=’"Support","RachelNationalTextPager"’
Note that, until you set up [Strategy] definitions, messages directed to these groups will go to
all destinations all at once. For a detailed discussion of these settings, refer to Chapter 15:
Broadcasting to Groups and Creating Escalations.
4. Set up Schedules
Recognizing that not all support personnel are on duty around the clock, you may want to associate
a [Schedule] definition (or two) with each destination so that messages are sent to on-duty
destinations only.
Under [Schedule], create an entry for each destination. For instance:
[Schedule]
...
{CynthiaPageSched}
Monday=07:00-16:00
Tuesday=07:00-16:00
Wednesday=07:00-16:00
Thursday=07:00-16:00
Friday=07:00-16:00
34 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Next, under each of the four destinations you created, set the following values:
Schedule=name_of_schedule
Here, name_of_schedule matches the name of the regular schedule you created for this
destination under [Schedule]. For the destination {CynthiaTextPager},
name_of_schedule would be {CynthiaPageSched}. You can name a schedule anything
you like, but, if it is unique to the person and/or destination in question, you should choose a name
that makes the relationship clear.
Note that, if some employees have the same schedule, their [Destinations] definitions can
invoke the same regular schedules; you need not create unique entries for each. For instance, a
[Schedule] definition called {OfficeHours} might suffice as the regular schedule for almost
all users.
For a detailed discussion of these settings, refer to Chapter 12: Setting Up and Applying
Schedules.
5. Enable Responses
In the present scenario, none of the destinations are of a type that permits a response; while you
may invoke a set of possible responses when you send a message, there is no way for these
options to be displayed to recipients. The set of invoked response options will be available to them
should they decide to reply via the command line, however, and thus you might want to set up a
basic menu of replies that users would understand to be available. Under [Response], create
the following entry:
[Response]
...
{Basic}
NumReplies=4
Acked=1
NotAcked=2
AckedHold=3
Released=4
Reply1=’Yes’
Reply2=’No’
Reply3=’Hold’
Reply4=’Release’
Once this is in place, you (or the application controlling TelAlert) can invoke this set of responses
on the command line when sending a message:
telalertc -g Support -m "node 2745 down" -ackwait 1h -response Basic
Any recipient of this message could go to a networked computer on which telalertc was installed
and issue a reply, like so:
telalertc -reply sendID yes
Here, sendID is the integer uniquely identifying the message sent to this recipient. (The command
telalertc -showalert will display the IDs of active sends.) Even if you do not want to use this set of responses when you send to regular text pager destinations, setting it up now prepares
you for the addition of two-way pagers in the future.
Chapter 4: Implementation Planning | 35
For a detailed discussion of these settings, refer to Chapter 14: Enabling Responses.
6. Create Strategies
The final step in implementing TelAlert in this scenario is setting up [Strategy] definitions that
enable alert escalation—so that a message is sent first to one destination, then another, then
another, until certain conditions are met.
In an organization this size, you might need only one. Under [Strategy], create the following
entry:
[Strategy]
...
{FirstAcknowledge}
Complete=Acked>0
Escalate=Incomplete=0
According to this definition, escalation will cease upon the first positive acknowledgment of the
message; this is because the first acknowledgment meets the definition of “complete” found in the
[Strategy] definition. As long as no acknowledgment is given, escalation will continue until
there are no more valid destinations to which TelAlert can send the message.
Once this strategy is in place, it is merely a question of when and how to invoke it. You can do so
at the command line (by including -strategy FirstAcknowledge). You can also refer to it within a [Group] definition, so that every message sent to that group is subject to this escalation
strategy.
Perhaps this makes especially good sense for one of the groups you have already created,
{SupportAll}. Simply set a Strategy value here, like so:
[Group]
...
{SupportAll}
Destinations=’"Support","RachelNationalTextPager"’
Strategy=FirstAcknowledge
Now, any message sent to this group with -response Basic and -ackwait time appended at the
command line will invoke this strategy. First the message will be sent to all valid destinations
comprising {Support} simultaneously. If, after the specified amount of time has passed, no
positive acknowledgment has been received, the message will be sent to
{RachelNationalTextPager}. Note that, since the only way to respond in this scenario is via
the command line, a relatively long -ackwait parameter is most suitable.
Response-dependent escalations are more useful in situations supporting response via two-way
pager or inbound voice (refer to Scenario Two below). In any event, however, this is an effective
means of ensuring that a critical message reaches someone, up to and including the person holding
ultimate responsibility. For a detailed discussion of these settings, refer to Chapter 15:
Broadcasting to Groups and Creating Escalations.
Response Menus vs. Response Commands
You do not have to set up a [Response] definition for message recipients to be able to
acknowledge the message on the command line. -ack, -nak, -ackhold, and -release are TelAlert commands all users can use with regard to any message in an ackwait state (or, in the case of -release, a held state)—even if no responses were
associated with the send.
36 | TelAlert 6e™ Administrator Guide - Version 6.1.29
4.3.8 Scenario Two: Paging, Voice, and Email—Small Organization
Assuming an organization of the same size, adding voice and email to the list of notification media
is a relatively simple matter. At its most basic, it consists of adding two new [Configurations]
definitions and a set of new [Destinations] definitions for each destination to which you
anticipate sending messages.
Beyond this, you may want to work with your schedules, groups, and strategies to arrive at an
overall configuration that allows you to take full advantage of the newly enabled media.
This scenario builds on concepts introduced in “Scenario One: Paging Only—Small Organization,”
which we recommend you read first. Note that voice notification requires a TelAlert Dialogic
telephony card.
Set Outbound Voice Configuration
First, under [Configurations], create a definition for outbound voice notification (your
outbound voice destinations will in turn invoke this entry). The information comprising this
definition relates to TelAlert’s behavior after the phone is answered:
[Configurations]
...
{OutboundVoice}
Type=InteractiveTTS
ToneConfirmWait=3s
AnswerConfirmationRequired=True
UserRequired=True
PreMsgWait=0.5s
PostMsgWait=1s
When TelAlert attempts to make a voice notification using this [Configurations] definition and
the phone is answered, it identifies itself and gives the person on the other end of the line three
seconds (ToneConfirmWait=3s) to press the # key. Then, because UserRequired=True, it
asks the user to key in his or her password, followed by the # key.
Once TelAlert has verified the user’s identity, it reads the message and provides a pre-defined set
of responses, allowing the user to positively acknowledge, negatively acknowledge, or acknowledge
and hold the message. These are built-in responses; they are not related to those made available
through invocation of a [Response] definition.
Note that the Type setting is what connects this [Configurations] definition to
{TTS_Port1}, a definition under [Port]; this is how TelAlert knows to use a TTS port for
notifications based on this [Configurations] definition. If you did not set up this [Port]
definition when you installed and tested the TelAlert Engine, you will have to do so now.
For a detailed discussion of these settings, refer to Chapter 3 of the TelAlert Voice and
Hardware Guide.
Chapter 4: Implementation Planning | 37
Add Voice Destinations
Since the instructions for calling voice destinations differ from one case to the next, this
information is kept in the [Destinations] definitions themselves. Here you might create one
voice destination for each of the people for whom you created paging destinations earlier. For
example:
[Destinations]
...
{JohnHome}
User=John
Configuration=OutboundVoice
AreaCode=316
Number=555-1212
Because UserRequired=True, each destination referring to that [Configurations]
definition must contain a User value. Thus, before setting up voice destinations for each of your
support employees, you will need to set up corresponding entries under [User]:
[User]
...
{John}
Active=True
Password=letmein
Alternatively, you could set User=Operator under each voice destination and set up a single
entry, {Operator}, under [User]. This setup will not allow you to distinguish between users
(all will be recognized as “operator”), but it does ensure that no one can receive a voice notification
without providing an authorizing password.
For a detailed discussion of these settings, refer to Chapter 3 of the TelAlert Voice and
Hardware Guide.
Apply Group, Schedule, and Strategy Definitions
Once the voice [Configurations] and [Destinations] definitions are in place, you (or the
application controlling TelAlert) can send a voice notification using a command such as this:
telalertc -i JohnHome -m "node 2745 down"
To send voice notifications to groups, invoke schedules, and perform escalations, you will have to
do some more work, using techniques similar to those you used when setting up paging:
1. First, refer to these new voice destinations in [Group] definitions. One option you have is
to set up voice-only groups that parallel existing groups of pagers. Alternatively, you can
form groups comprised of different kinds of destinations. For instance, you could construct
a group out of {DavidTextPager} and {RachelCellPhone} and use it so that any
page not acknowledged by David within a certain time would result in a call to Rachel’s
mobile phone.
2. Second, create [Schedule] definitions for these destinations. You can do this by defining
new regular and extended entries under [Schedule] and referring to them by setting Schedule values under each voice [Destinations] definition. Or, if these voice
destinations are to be valid at exactly the same times as your pagers, you can have each
point to schedules you have already created.
3. Third, set a Strategy value for each of the [Group] definitions you create.
38 | TelAlert 6e™ Administrator Guide - Version 6.1.29
For a detailed discussion of these settings, refer to Chapter 15: Broadcasting to Groups and
Creating Escalations and Chapter 12: Setting Up and Applying Schedules.
Set [Configurations] Definitions for Email
With email, the same model applies. First create the [Configurations] definition that will be used to send email notifications:
[Configurations]
...
{Email}
Type=Email
Model=Internet
Host=server.domain.com
Service=smtp
From=’[email protected]’
Together, Type=Email and Model=Internet point to the {Internet} definition under
[Port], which you should set up now, if you have not done so already.
Add Email Destinations
Next, create a destination for each person to whom you want to be able to send email notifications.
For example:
[Destinations]
...
{CynthiaEmail}
FullName=’Cynthia Jasper’ Configuration=Email
To=’[email protected]’
With these definitions in place, you (or the application controlling TelAlert) can send an email
notification using a command such as this:
telalertc -i CynthiaEmail -m "node 2745 down"
Note: it is not a good idea to invoke a [Response] definition when sending an email notification,
given the time that may elapse before the email is received and read. Likewise, email is not a good
medium to use as part of an escalation. Some organizations reserve it for very low-priority alerts;
others send all messages via a primary medium (pagers, for instance) and as a matter of course
copy them to email destinations. One way to do this is by adding Users to Groups, each User
pairing a paging and a matching email destination.
For a detailed discussion of these settings, refer to Chapter 10: Configuring for Other
Notification Media.
Chapter 4: Implementation Planning | 39
4.3.9 Scenario Three: A Larger Organization
When implementing TelAlert in a considerably larger organization than the one just described, the
main two additional challenges concern the work’s increased volume and complexity.
Higher Volume
There are a number of reasons for the increased volume of work:
� You will very likely be creating more [Configurations] definitions, and you will certainly be creating many more destinations.
� For each destination, you may be creating one or two unique schedules, and for every
human user you may decide to create a separate [User] definition and then associate
each with the appropriate destinations.
� There will be more groups to create, and some of these may be comprised of a large
number of destinations.
� Even if you opt to use only one [Response] and one [Strategy] definition, tending to
the other parts of this implementation will demand considerably more effort than in a small organization.
Greater Complexity
The greater complexity is partly the consequence of the greater volume. For instance:
� More destinations means more choices as to how to set up your groups.
� Likewise, the fact that significant numbers of destinations will be on duty at precisely the
same times may lead you to set up a system of shared schedules—something that, though rather complicated, will save on maintenance in the long run.
At the same time, a larger organization is more likely to have needs that can be met only through
more complex techniques:
� In order to achieve certain escalation effects, you may have to develop your [Group] and [Strategy] definitions at the same time, or you may need to return to your originally
created groups and add to or modify them based on what you want to accomplish.
� As mentioned earlier, you might create several otherwise identical versions of a group,
associating each with a different [Strategy] definition.
� You may find that there are times when you want a message to go to a particular person,
via a destination that TelAlert chooses based on scheduling. This requires creating a set of groups, each referring to all of the destinations linked to each person.
� Once you have done this, you will have to decide if and when these groups should comprise larger ones and what escalation strategies, if any, should be applied.
40 | TelAlert 6e™ Administrator Guide - Version 6.1.29
First Cover the Basics
Because of this additional volume and complexity, it is essential that you first take care of the
basics when implementing TelAlert in a larger organization. In a small company, the amount of
rework necessitated by a piecemeal or trial-and-error approach may be negligible. In a large
organization, however, you can run into a lot of problems if you fail to begin with a solid foundation
on which to erect more complex configurational elements.
� For TelAlert 6e, first set up a system of [User] definitions that makes sense for what you
want to do.
o Note that all Users must belong to one or more Departments. To start, Users can
be all assigned to a few Departments or even the Default Department. Changes
to Department assignment can be made later with little impact. For more on Departments, see Managing Departments in Chapter 18.
o Users must also be assigned a Role. Roles are discussed in User Roles in Chapter 13.
� Next, create all your [Configurations] and [Destinations] definitions.
� Finally, create [Schedule] definitions and associate these with the destinations in as
hierarchical a way as possible (i.e., by sharing identical schedules whenever possible).
Then Focus on Outcomes
Once you have your foundation in place, shift your focus to the outcomes you want to achieve.
Most behaviors not already made possible by the foundation (e.g., sending to a single destination)
are related to escalation and as such involve the creation and invocation of [Group], [Response], and [Strategy] definitions. This is the work that requires the most careful planning.
As you proceed, you should be thinking explicitly about situations in which you will be sending
notifications to more than one destination. Be sure to begin with what you see as the most
important or most common situations.
Here are some issues to consider that will affect the groups you construct and the strategies you apply:
� What is the goal of the notification?
� To what destinations is it appropriate to send the notification?
� Should the notification be sent to the destinations all at once or sequentially?
� Should the set of appropriate destinations be further broken down, so that the notification
goes first to one subgroup and then to another? Or are all of the destinations roughly equivalent?
� Under what conditions should TelAlert stop escalating the alert?
� Under what conditions should TelAlert release the alert?
� Is it desirable that the notification be received by more than one person in the group? By everyone in the group?
� Is a response necessary?
Chapter 4: Implementation Planning | 41
� What response options will be provided? What responses can affect the processing of the alert?
� How would you like an urgent alert handled in a worst-case scenario—for instance, if no support personnel could be contacted?
� Will a response from a message recipient be used to control an external application?
Work Towards an Economical Configuration
Whether you are building your foundation or have begun erecting [Group] and [Strategy] definitions on top of it, it is a good idea to work towards as economical a configuration as
possible—i.e., one that does not needlessly repeat information but instead uses cross-references
and inheritance to make single entries broadly available. Doing so means less work up front and
easier maintenance down the road.
This principle is mentioned above, with regard to representing work schedules. If everyone is on
one of three work schedules, there is no point in creating more than three corresponding
[Schedule] definitions. Even if work schedules are spread across time zones, you can avoid entering one for every single destination. For instance, if your team works an 8:00 am to 5:00 pm
schedule based on their local time zone, you can create a single Schedule. As Schedules are
assigned to a Device or a member of a Group in the Web UI, the Schedule inherits the time zone of
the associated User.
There are several other common opportunities for creating an economical configuration. Below are
some methods to keep in mind:
� If you want to include the members of one group in a larger one, include them as a
subgroup. You can do this even if you want these destinations treated as if they had been
listed individually—by setting SubgroupEscalation=True in the larger [Group]
definition.
� If you will be using the same strategy in most or all of your escalations, specify it under
[Group] by setting a default Strategy value. Then include a Strategy setting in the definitions of only those groups for which you want another strategy to apply. This
group-level strategy specification overrides the default. Note that the default is set in the TelAdmin tool on the TelAlert Desktop.
5
Configuration Basics 5.1 Overview
An overview of the concepts you will use to configure TelAlert 6e, including a comparison of the
tools for performing configuration tasks.
� TADesktop
� TelAlert 6e Web Interface
5.2 TelAlert Configuration Methods: TADesktop;
TelAlert 6e Web Interface
TelAlert Messaging Server is the central messaging component of TelAlert 6e. It
determines how alerts are processed based on the commands it receives from integrated
applications, the command line, or the TelAlert Web UI. The following tools are needed to
configure and maintain TelAlert Messaging Server:
� The TelAdmin tool in TelAlert Desktop
� The TelAlert Web UI
Both of these tools modify settings in the TelAlert Messaging Server configuration file. This
file is divided into sections noted by words in [straight brackets]. Many of these [sections]
are further divided into {definitions}. Within [sections] and {definitions} are keywords that
are assigned values using the TelAdmin tool or the TelAlert Web UI.
The TelAdmin tool is used to configure and maintain the keywords that are of interest to
administrators, such as those for [Configurations] and [Ports]. The [Configurations] section
contains entries defining generic configuration information for different notification media
types (for example, e-mail or a specific kind of pager). The TelAlert 6e administrator needs
to define these generic settings for the types of media his/her organization will need. For
example, the administrator defines settings for the type of text pager and paging service.
Once that is done, any TelAlert 6e user (administrator, supervisor, or staff) can use the
TelAlert Web UI to add a specific paging device by selecting the [Text Pager] configuration
and adding details about their specific device.
44 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Note that administrators will also use the TelAlert Web UI for certain other administrator
tasks. However, as a self-service configuration tool, the TelAlert Web UI is used primarily
by end-users--supervisors and staff users--to modify keywords relating to users, groups,
devices, and scheduling.
5.3 What is TelAlert Desktop?
TelAlert Desktop is a graphical environment that makes configuring and managing your TelAlert
installation easier and faster. TelAlert Desktop incorporates the following components:
5.3.1 The Desktop Window
The Desktop window contains the menu items and toolbars you will need to work with the tools
that comprise the Desktop.
5.3.2 TelAdmin
The Desktop is the home of TelAdmin, the graphical application used to configure and manage
TelAlert. Although TelAdmin runs on Windows, it may be used to configure TelAlert installations
running on Windows and UNIX platforms.
TelAdmin allows you to configure TelAlert with an easy to use graphical interface. Multiple
TelAdmin windows may be opened within the TelAlert Desktop to simultaneously manage multiple
TelAlert hosts.
5.3.3 TelAlert Monitor
This feature allows you to observe the current status of alerts and messages. The display
characteristics may be customized to suit a particular purpose.
5.3.4 Wireless Destination Setup Wizard
The Desktop features a Wireless Destination Setup Wizard, that allows editing and viewing of
Destination properties. The wizard walks you through all the necessary steps, prompting you for
the information required to create Destinations for a variety of wireless devices.
Important Note: In the TelAlert Web UI, communication devices are called "Devices," but in the TelAdmin tool and related documentation, the term for
communication devices is "Destinations." Regardless of the term used, in
TelAlert 6e, devices/destinations are always created and modified using the
TelAlert Web UI.
Note: When TelAlert is installed, the first version of the binary telalert.sects file is "compiled" from a human-readable text file named telalert.ini. (telalert.ini may actually be a set of files, where the primary telalert.ini file contains $include commands that reference other .ini files during the compilation process.) All subsequent configuration
changes must be made by changing telalert.sects via TelAdmin or the Web UI. (Never modify the telalert.sects file directly.) Therefore, we recommend removing all telalert.ini files to reduce the risk of inconsistent configuration specifications.
Chapter 5: Configuration Basics | 45
5.3.5 Group Setup Wizard
The new Group Setup wizard walks you through the process of creating and maintaining TelAlert
Groups that are used for sending messages to multiple Destinations.
5.3.6 Host Properties Monitoring
The Host Properties Monitoring facility allows administrators to check the status of TelAlert hosts.
5.3.7 TelAlert Web UI Launch
TelAlert Desktop Provides a quick launch capability to login to the TelAlert 6e Web UI.
5.4 Components of the TelAlert Desktop Window
When you first open TelAlert Desktop, the main Desktop window will be displayed, followed by the
Welcome splash screen.
Figure 6. TelAlert Desktop Environment
If you are running TelAlert Desktop for the first time, you will need to configure connection
parameters for a TelAlert host before using any of the tools. New TelAlert hosts may be and
properties for existing hosts may be edited using the Hosts menu.
A drop-down list box in TelAlert Desktop’s toolbar (Figure 7) displays a list of TelAlert hosts that
have been configured. The menu options and toolbar buttons will launch tools and perform
operations for the TelAlert host that is selected in this list box.
46 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 7. Host Selection
When a host that is managed by TelAlert 6e is selected the toolbar buttons and menu options are
different than those that are displayed for a host that is not managed by TelAlert 6e.
Figure 8. Menu Bar - TelAlert Classic Mode
Figure 8. Menu Bar – 6e Mode
While communicating with a server this icon found on the top right hand corner will be animated to inform you that the desktop is sending data to a TelAlert server or waiting for a
response.
The host monitoring area will display all the hosts (with an abbreviated host name) you are
connected to and their status. If the color is green, the connection to the host is up. If it is red,
the connection to the host is down.
The status bar on the bottom will display details of the connection.
5.4.1 Administering a TelAlert Server
Menu items across the top of the window are used to access functionality of the tool with which
you are working. These menu items dynamically update, depending on the component of the
Desktop you are using. In the TelAlert classic mode the TelAdmin, Destination Wizard Group
Wizard and TelAlert Monitor tools are available. These tools may be launched from the tools
menu, toolbar buttons.
5.4.2 Administering a TelAlert 6e Server
Some TelAlert Desktop features are restricted when working with TelAlert server that is managed
by the TelAlert 6e Web UI. Section paragraphs that are managed by the TelAlert 6e Web UI cannot
be modified using the TelAlert Desktop’s TelAdmin tool. This restriction applies to Destination,
Group, Schedule and User paragraphs. The TelAlert Desktop Group Wizard and Destination Wizard
are not available when connected to a TelAlert server that is managed by TelAlert 6e.
The TelAlert Desktop’s toolbar buttons and menus are automatically updated to indicate toolbar to
indicate which operations are allowed for the selected TelAlert server. The TelAdmin menus and
toolbar buttons are updated to indicate which operations are allowed for the selected
section/paragraph on a particular TelAlert server.
Chapter 5: Configuration Basics | 47
In the TelAlert 6e mode the TelAdmin, TelAlert Monitor tools and TelAlert 6e web interface may be
launched from the tools menu, toolbar buttons.
Advanced administration of TelAlert 6e managed servers (configurations, ports, etc.) can only be
accomplished using the TelAdmin interface. The administration of most of the common functions
(devices, users, groups and schedules) is done using the TelAlert 6e browser interface.
5.5 Connecting to a TelAlert Host
The first time you start the desktop, you will have to create a host.
To create additional connections to other hosts by choosing Hosts > Add New Hosts…
5.5.1 Configuring the Desktop to Connect to a TelAlert Server
The Desktop can be configured to connect to one or many TelAlert or TelAlert 6e Messaging
Servers using TelAdmin. The Messaging Servers can be local to the TelAdmin instance or on
another machine, for example, one running on a non-Windows machine. This means you can use
TelAdmin to configure and administer all TelAlert installations, even though the Desktop runs only
on Windows. You do this by adding information to the telalert.hosts and telaconf.hosts files on
the TelAlert server. These files list the clients that are authorized to connect to the TelAlert
Server.
00.y
See the discussion of telalert.hosts in the section Command Line Options for Modifying Filter Files,
in Chapter 3 of the TelAlert Keyword and Command Reference for more information.
Note: If you use TelAlert Desktop to configure a local TelAlert server, the installation
process will automatically create a Host for you. If all hosts are removed from the host
selection list, the Add Host dialog will automatically display the next time when
TelAdmin, Destination Wizard, or Group Wizard is started.
The objects under the icon for your Host are servers. These objects should not be
confused with the contents of either the telalert.hosts file (which lists the clients
authorized to connect to TelAlert), or the telaconf.hosts file, (which lists the clients
authorized to connect to TelAdmin). In order for TelAdmin to be able to connect to each
TelAlert Server, the IP address of the node running TelAdmin must be added to the
telalert.hosts and telaconf.hosts files on each TelAlert Messaging Server.
Note that telaconf.hosts should contain the following entries:
� All nodes where TelAdmin will connect from
� The TelAlert 6e Web Server
The telalert.hosts file should contain the following entries:
� All nodes where TelAdmin will connect from
� The TelAlert 6e Web Server
� All nodes where telalertc will connect from
48 | TelAlert 6e™ Administrator Guide - Version 6.1.29
On the TelAlert Server
Add the IP address of the machine running TelAlert Desktop on the TelAlert server. This is the
machine to which you want to connect using TelAdmin.
1. Using a text editor, edit the telaconf.hosts file and add the IP address of the client machine.
2. Execute this command:
telaconf -reload
3. Or, you could use the telaconf utility to add this information as follows. In this example,
IP_Address is the IP address the server where TelAdmin runs.
telaconf -accept IP_Address -insert -write
5.6 Configuring TelAdmin Save and Backup Options
When you make changes using TelAdmin, a file called telalert.sects is modified. It is from this
binary file that TelAlert actually draws the information it needs to process alerts.
By default, changes made using TelAdmin are automatically saved whenever any change is made.
However, changes can be saved manually using the File/Save Data command, and activated
using the File/Reload Data command. These commands cause TelAdmin to update the
telalert.sects file. (For a complete discussion of how TelAlert’s file structure works, see the
Switching between Configuration Methods section later in this manual.) However, you can
alter TelAdmin’s saving process using several keywords in the [Files] section.
When working with keywords in the [Files] section, be sure to check if the default values that
appear reflect the situation you want. Depending on the version you are using, different default
values might be specified.
5.6.1 Enabling Auto-Save
For example, consider the following settings, (accessible by double-clicking the File icon in the left
pane of TelAdmin, and choosing the Conf tab on the tabbed dialog that appears):
Figure 9. Section: File Paragraph: File
Chapter 5: Configuration Basics | 49
Setting WriteSectsFileAfterChanges to True causes TelAdmin to save changes
automatically, at the interval specified by WriteSectsFileInterval. Users have only to click
the Update or Save button, and their changes will be written the next time the interval expires.
Setting WriteSectsFileInterval at a value of 0m means that TelAdmin will save any
changes (that is, write TelAlert.sects to disk) immediately. Changes are written every time a
user clicks Update or Save.
Setting ReloadAfterSectsFileWritten to True causes TelAdmin to activate changes
automatically after it saves them by having TelAlert reload the newly written .sects file, the
binary file from which TelAlert actually draws the information it needs to process alerts. This
eliminates the need to use the File/Reload Data command to activate changes manually.
Typically, if you are using TelAdmin’s auto-save features, you will want to set this to True. You
might set it to False if you wanted to make extensive changes over a period of time without having
them affect TelAlert’s operational data.
5.6.2 Enabling Backup
When you enable auto-save, it is a good idea to enable automatic backups as well. Otherwise you
might corrupt your settings file and not have a recent backup. Consider the following settings:
[Files]
... NumIniSectsFileBackups=2
BackupIniFile=telalert
Setting NumIniSectsFileBackups to 2 means that TelAlert will keep the two most recent backup
copies of telalert.sects. You may raise this as high as 10. See the entry for this keyword in Chapter
2 of the TelAlert Keyword and Command Reference for more details.
By default, BackupIniFile is blank. If you enter a string for its value, TelAlert will create backup
copies of that file at the same time it backs up telalert.sects. See the entry for BackupIniFile in
Chapter 2 of the TelAlert Keyword and Command Reference for more details.
5.6.3 Setting Up Failover
You can set up a failover TelAlert Messaging Server Machine that stays in sync, in terms of
configuration changes, with your primary Telalert Messaging Server machine. For
information about setting up failover for TelAlert Messaging Server, see the TelAlert 6e
Failover Module Guide.
5.7 Using TelAdmin to Configure TelAlert Messaging
Server
This section covers the following topics:
� About TelAdmin
� The TelAdmin window
� Configuring TelAlert Messaging Server
� Making configuration changes
� TelAdmin menu items
� Importing data from Windows clipboard
50 | TelAlert 6e™ Administrator Guide - Version 6.1.29
� Desktop locking
5.7.1 About TelAdmin
The TelAdmin tool in TelAlert Desktop is used to configure and maintain TelAlert
Messaging Server. Specifically, it is used to configure and maintain the sections of telalert.sects that are of interest to system administrators, such as ports.
Generally, administrators need to configure these sections before others in the
organization can start making additional configuration changes through the self-
service TelAlert WebUI. (Note that administrators will also use the TelAlert Web UI
for certain administrator tasks.)
The TelAdmin tool is accessed from the TelAlert Desktop Tools menu. TelAdmin is not a
simple graphical configuration-file editor, but rather a front-end for a TelAlert-
proprietary multi-user transactional database system (the telaconfe server daemon). Using TelAdmin, multiple administrators may simultaneously update the configuration,
and a record-locking system ensures that they do not accidentally overwrite each
other’s changes. Administrators can also manage multiple TelAlert Messaging Server
hosts from a single instance of TelAdmin. You can control which administrators can revise which aspects of TelAlert Messaging Server using TelAdmin. For details, see
Configuring TelAlert to Run Automatically in Chapter 18.
5.7.2 The TelAdmin Window
TelAdmin displays a graphical representation of TelAlert’s sections (for example, the
[Configuration] and [Destination] sections) in a tree structure in the left
pane of the main window. The definitions under each section (if any) are displayed
in the right pane when you click a section icon on the tree--similar to how the
Windows Registry Editor displays registry keys and values. (For a complete
discussion of sections and definitions in TelAlert, see Chapter 3, Technical
Overview.)
Figure 10 shows the Destination section highlighted in the left pane, with all the
[Destination] definitions displayed in the right pane. A context menu is
displayed when you right-click an item in the left pane. This functionality is also
available as a tool bar menu on the TelAdmin window.
Chapter 5: Configuration Basics | 51
Figure 10. The TelAdmin window
5.7.3 Configuring TelAlert Messaging Server
You can create and modify every aspect of TelAlert Messaging Server using TelAdmin,
except schedules, groups, users, and devices. These are configured using the TelAlert
Web UI. However, before being able to configure devices using the TelAlert Web UI,
you must create [Configurations].
To learn how to create and modify specific [Configurations] to meet your
business needs, see the following chapters:
� Chapter 8, Configuring for Paging Notification
� Chapter 9, Configuring for Voice Notification
� Chapter 10, Configuring for Other Notification Media
5.7.4 Making Configuration Changes
Typically you will want to modify one or more of the definitions in the right pane. To
do so, double-click the definition in the right pane (or right-click and choose Update
or Display). For sections that don’t use definitions, right-click the sections icon on
the tree and choose Update or Display.
A dialog appears, displaying the editable parameters of the definition. Figure 11
shows a typical definition screen.
52 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 11. Typical Definition
Here, you can set values for any of the keywords allowed in the definition.
Depending on the type of keyword value, you may use a pull-down list, type a string
or number in a field, or set a time, date, or some other type of formatted data. You
can access additional values by clicking the tabs.
Default values in Definition windows are displayed in normal typeface; values that
have been modified are displayed in bold. It is also possible to restore the default
values by simply right-clicking on a non-default value, and choosing Restore
Defaults.
Clicking a View button displays the referenced definition. This display is read-only; to
change the referenced definition, you must access it directly, through the TelAdmin tree.
For detailed explanations of all the keywords contained in TelAdmin’s sections and
definitions, see Chapter 2 of the TelAlert Keyword and Command Reference.
When you are finished making changes, click the Save button to commit the
changes. Click Import… to import definitions from a file or the clipboard. Click
Cancel to dismiss the dialog without saving changes.
5.7.5 TelAdmin Menu Items
This section describes the main Desktop menu items that apply to TelAdmin. The
Desktop menu items change dynamically depending on whether the TelAdmin window
is active, the TelAlert Monitor window is active, or neither window is active.
Edit Menu
When you click on a section, paragraph, and definition icon in TelAdmin, the Edit
menu items update automatically to include some or all of the following commands,
Chapter 5: Configuration Basics | 53
depending upon which icon is selected and the current state of telalert.sects. The
right-click menu and the TelAdmin window toolbar also update automatically. Please
note that only Display and References will be available for sections under the control
of the TelAlert 6e Web UI.
� Add New - Creates a new definition with default values.
� Display - Displays a read-only version of the dialog box.
� Copy - Creates a new definition with the same values as the selected definition.
TelAdmin will prompt for the name of the new definition.
� Rename - Lets you change the selected definitions name.
� Update - Brings up the dialog box in which you can change the selected definitions keyword values.
� Delete - Deletes the selected definition.
� References. Displays a list of definitions that refer to the select definition. You
can use this, for example, to see which [Destination] definitions are associated with a particular [Configuration] definition.
54 | TelAlert 6e™ Administrator Guide - Version 6.1.29
5.7.6 Importing Data from Windows Clipboard
TelAdmin supports an import function that allows you to copy all or part of an
individual TelAdmin entry from data stored on the Windows clipboard, instead of
having to type each individual value into the keyword fields on the TelAdmin panel.
This simplifies common administrative tasks such as:
� Applying a new TelAlert license key that you received in an email
� Copying entry examples from the PDF copies of the TelAlert manuals
� Applying integration-specific changes from the TelAlert sample files and documentation for that integration
� Applying new service provider [Configuration] entries obtained from:
http://www.telalert.com/support/misc/configurations
Is there a replacement for this URL?
� Applying changes emailed to you from TelAlert Technical Support
Note: The import feature is disabled for Destinations, Users, Groups, and Schedules.
To use the import function, once you have opened TelAdmin, navigate to the desired
section and subsection in the left pane (for instance, License, or TextPager under
Destination). Then, complete the appropriate steps below.
Existing vs. New Entry
For an existing entry:
1. If it is a section that does not allow definitions (such as License), double-click
the section entry in the left pane.
2. If it is a section that allows definitions, but you want to change the section
defaults rather than an individual definition, double-click the <default> entry in
the right pane. (Note that for sections that have subsections, like [Destination],
there is only one <default> for the entire section; there are not <defaults> for
each subsection.)
3. If you are modifying an individual definition, double-click its entry in the right
pane. A tabbed panel appears, displaying all of the fields for the entry, together
with their current values.
Chapter 5: Configuration Basics | 55
For a new entry:
1. If you want to add a new definition entry, right-click the section name (if it is a
section that has subsections, right-click the subsection name instead). From the
drop-down menu, select Add New. In the Add New Paragraph dialog, enter
the name of the new entry, and any other fields that are required (the available
fields vary according to the section). The name entered here will override any
{Definitionname} included in the imported data. Click OK.
2. A tabbed panel appears, displaying all of the fields for the entry, together with
their default values. Once the appropriate tabbed panel is displayed in
TelAdmin, get the data to be imported onto the Clipboard.
Copy the Data from an Application
1. Open the tool from which you want to import data from. (For instance, Outlook,
Acrobat Reader, Notepad, Wordpad, Internet Explorer etc.)
2. Select the data to be copied. The most that can be copied at one time is a single
definition (with or without the [Sectionname] or {Definitionname} at the
beginning. Any [Sectionname] or {Definitionname} copied onto the clipboard will
be ignored, and the [Sectionname] or {Definitionname} selected in TelAdmin
will be retained). If you have multiple definitions to import, you will need to do
them one at a time. It is possible to copy less than a complete definition; the
minimum amount to copy is a single Keyword=value line. Lines that have been
commented out with a leading # will be ignored. Lines that begin with $include
are also ignored; you will need to open the $include file directly in a text editor,
and copy directly from it. Lines starting with Password= are also ignored; see
below for setting passwords.
3. After the data has been highlighted, copy it to the clipboard (using Ctrl-C or
whatever copy method the tool you are copying from uses).
Import the Data into TelAdmin
1. Click the Import... button at the bottom of the panel. A dialog window appears.
2. In the Import Options box at the bottom of the window, select the appropriate
radio button to specify whether those fields in the entry that do not have new
values specified in the Clipboard data should retain their current (custom)
values, or be reset to default values.
3. In certain circumstances (such as the License section, which must always be
replaced as a unit), the Use current choice will be grayed out, and Use default
will be the only possible choice. When Use current is selected, the preview box
will display the current set of custom keyword-value pairs that will be retained.
4. Click the Get Clipboard button. (If this is grayed out, then the clipboard does
not contain any text data.)
5. The Import results box will display the keyword-value pairs read from the
clipboard. If an invalid keyword is read in this section, an error message
appears. If an illegal value is read (out of range, etc.) an error message
appears. If no errors occur, the Apply button will be enabled.
56 | TelAlert 6e™ Administrator Guide - Version 6.1.29
6. Any Password= keyword-value data on the clipboard will be ignored. This is
because TelAdmin always displays passwords as ******, and thus you would
not be able to view the password value that was being imported. If the
definition being updated supports Password=, then the Set Password button
will be enabled, and you can click it to bring up the standard TelAdmin password
setting dialog box. Note that it is not necessary to set the password here; you
can set it back on the main panel.
7. If errors occur, you can either hit the Cancel button, or you can correct the data
on the clipboard (perhaps by copying a different selection of lines), and hit the
Get Clipboard button again.
8. Click the Apply button. The Import dialog appears. The imported values are
displayed in the appropriate fields, and if the Use defaults radio button was
selected during import, all other fields will be reset to defaults.
9. Change any other field values as needed, and click Save. The imported values
are not permanently saved until you click the Save button.
5.7.7 Desktop Locking
Desktop locking prevents unintended results when multiple users simultaneously
save changes to TelAlert configuration data.
TelAlert Desktop reads a particular section and paragraph into a cache. Modifications
are made to the cache and when the modifications are going to be written, the
paragraphs are locked during this time, changes are written and paragraphs
unlocked. This is a simple scenario when no one else is concurrently making changes.
If another person makes a change to the system concurrently and you choose to
save, one of 3 different dialog boxes will be displayed.
� The lock failure dialog will be displayed informing you that the lock failed because someone else locked the paragraph.
� The Database Busy dialog will be displayed when the application tries to lock a
paragraph that is already locked. You may retry the save operation or cancel the save operation.
� The Overwrite Warning dialog is displayed when another user has saved changes
to a paragraph that you modified. This displays a list of paragraphs changed by the other user and the property values for the selected paragraph.
When you click on any of the properties, a Property Merge dialog displays. When this
happens, you need to select the value you want to store in the database. After
clicking OK, the Confirm Definition Changes dialog displays to confirm your changes.
Chapter 5: Configuration Basics | 57
5.8 Understanding Configuration Examples
In this Administrator Guide, examples of configuration tasks usually include samples of
keyword-value pairs as they would appear in a text telalert.ini file. The level of organization
known as a Section is represented by [square brackets]. The level of organization known as a
Definition is represented by {curly brackets}. (See “Key Configuration Concepts” in Chapter 3:
Technical Overview for detailed discussion of these terms.). Consider the following example:
[Configurations]
...
{OutboundVoiceLive}
Type=InteractiveTTS
AnswerConfirmationRequired=True
ToneConfirmWait=15
UserRequired=True
This text example’s information can be applied to all of the configuration methods:
� If you are using TelAdmin, the line [Configurations] tells you to expand the
Configuration heading in the tree in TelAdmin’s left pane. The line
Type=InteractiveTTS tells you to select the InteractiveTTS subtree under
Configuration in TelAdmin’s left pane. The line enclosed in curly brackets tells you to
select (or create) a definition named OutboundVoiceLive in the TelAdmin’s right pane.
The other lines tell you which keywords to modify, and what values to enter in each. For
example, UserRequired=True tells you to choose True from the UserRequired drop-
down list. See the TelAlert Desktop User Guide for further information.
Figure 12. TADesktop Configuration section
58 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 13. TADesktop Configuration screen
5.9 What is TheTelAlert 6e Web Interface?
The TelAlert Web UI is a corporate portal application that enables members of your organization to
manage TelAlert Messaging Server and issue peer-to-peer messages using TelAlert’s messaging
capabilities. The TelAlert Web UI also serves as a graphical interface for TelAlert administration,
allowing users to manage tasks such as device management, leaving administrators free to focus
on mission-critical activities.
With TelAlert 6e, any user in the system can use the TelAlert Web UI to:
� Send Alerts - to users, devices, and groups (alert recipients) per the sender’s own unique delivery and response rules
� Respond to Alerts - Reply to alerts that you have received.
� Monitor the Status of Alerts - Your personal alert status board is on the Home page in
the My Top 5 Active Alerts section. It shows details about active alerts routed through
TelAlert initiated by and received by you. It also provides an easy tool for sending, viewing alert details and responding to alerts.
� Maintain Devices - Manage their own devices and create and assign device schedules for
those devices.
� Subscribe to Groups - Add yourself to a group to receive alerts that are sent to that
group.
� View Group Schedules - View your on duty, holiday and vacation schedules. A separate
schedule exists for each group that you belong to.
Chapter 5: Configuration Basics | 59
In addition to the above features, administrators and supervisors can use the TelAlert Web UI to:
� Manage Groups and Group Schedules. This facilitates automated broadcasts or escalations of mission-critical alerts at a group level.
� Configure Security — Authentication to the TelAlert Web UI can be performed locally or
using an existing LDAP (Lightweight Directory Access Protocol) or LDAPS (Secure) system. Single Sign On can also be enabled.
� View Alert Status Boards — On the Mange Alerts page, administrators and supervisors
have three views into alert activity. Like staff users they will see the Alerts Received and
the Alerts Sent by the logged in user. An additional Department Alerts view displays alerts
sent by and received by all users, devices and groups sharing the same department as the
logged in user. For most administrators the Department Alerts view is a system-wide alert status board displaying all alerts routed through TelAlert.
� Manage Users - Users can be added to the system and assigned to departments and groups. Administrators can create Departments for the system.
� Create and Assign Schedules — TelAlert 6e allows you to send alerts based on
availability schedules (such as during scheduled work hours, but excluding company
holidays). Supervisors and administrators are able to create group member schedules and
assign them to group members. They can add vacation schedules for all users in their department. Administrators can add holiday schedules for the entire system.
� Reports — The reports that are shipped with TelAlert 6e provide insight into the day-to-day activity of TelAlert.
As stated previously TelAdmin will remain the primary tool for most administrative
configurations, however Administrators may have the need to modify users, groups, devices, and scheduling which is done using the TelAlert Web UI.
5.10 Logging In
All users must log in before they can access the features found in the Web User Interface (Web UI).
User authentication can involve manually entering a username and password stored in the TelAlert
database or client LDAP/LDAPS database or automatically using SSO. A username and password
should be provided to you by your system administrator, administrator or supervisor. You will also
need a link or URL to the TelAlert 6e Log In screen.
During the installation of TelAlert 6e a single system wide, master account is created. Using this
log in username and password, the system administrator can log in and create additional users.
Users added to the system with the role of administrator or supervisor can create other users,
selecting a username and temporary password that can be changed by the user once they have
initially logged in.
If the batch import process is used to populate the database and to create user accounts, users
will be able to log in to the system once the import is complete and they have been provided with
their log in username and password.
To log in to the TelAlert 6e system, do the following:
1. Enter the appropriate URL into your Internet browser.
2. On the TelAlert 6e Log In screen, enter your assigned username and password.
3. Select the Log In button. After successfully logging in, the TelAlert 6e Home page appears.
60 | TelAlert 6e™ Administrator Guide - Version 6.1.29
5.11 Navigating
Use the main menu, comprised of navigation tabs at the top of each page to access the main
sections in the TelAlert web UI. The navigation tabs are customized according to the logged in
user’s role. Users with the role of Administrator have access to all 6e features and will therefore
see all navigation tabs.
Please note that version 6.2.0 of TelAlert 6e added the ability to add custom roles and modify the
out-of-the-box roles. The examples below are based on the default permissions assigned to the
out-of-the-box roles.
Figure 14. TelAlert 6e Navigation Tabs (Admin View)
Users with the role of Supervisor have access to most 6e features and will see all of the navigation
tabs except for the Admin Tools tab.
Figure 15. TelAlert 6e Navigation Tabs (Supervisor View)
Users with the staff user role can access their own information but do not have access to the site
management tabs.
Figure 16. TelAlert 6e Navigation Tabs (Staff View)
Chapter 5: Configuration Basics | 61
To navigate the TelAlert web UI, use the following tabs:
� Home
� Alerts
� Users
� Devices
� Groups
� Schedules
� Subscriptions
� Reports
� Admin Tools
5.11.1 Home
On the Home page, you can:
� View the five most recent active alerts that you have sent or received. If more than five
active alerts exist, you can view the remainder of active alerts by selecting the View All Active Alerts Received/Sent button.
� View the details of your five most recent active alerts.
� View a list of devices you own.
� View a list of groups you are a member of.
� View your schedules for the current week.
62 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 17. Home Page Portlets
In TelAlert 6e, a device is anything you can use to receive an alert. For example, e-mail is
considered a device. Therefore, if your email account is set up in the TelAlert 6e system, it will
appear as a device.
5.11.2 Alerts
In the Alerts area, you can:
� View a list of alerts that have been sent to or received by you and your devices. If you are
a supervisor or administrator, you will see all alerts sent and received by the users, devices
and groups that belong to your department. The system administrator can see all alerts that have been sent and received.
� View a list of alerts that have been sent or received by you and reply to those alerts.
� Send a new alert
� Search for specific alerts
� Export alert information for reporting purposes
� Manage Alert Templates
Chapter 5: Configuration Basics | 63
Figure 18. Manage Department Alerts page (Admin/Supervisor View)
Figure 19. Manage Alerts page (Staff User View)
64 | TelAlert 6e™ Administrator Guide - Version 6.1.29
5.11.3 Users
The Users tab is only available to administrators and supervisors. In the Users section you can
manage users that belong to your department. You can create users, edit their information and
delete user records. The system administrator can create, edit and delete users within all
departments.
Figure 20. Manage Users page (Admin/Supervisor view)
5.11.4 Devices
In the Devices area, you can view, add, edit and delete devices that you own. You can also create
schedules that can be assigned to your devices. Advanced parameters can be specified for
devices. Supervisors and administrators can manage their own devices as well as those owned by
other users in their department. System administrators can manage all devices.
Figure 21. Manage Devices page (Admin/Supervisor view)
Chapter 5: Configuration Basics | 65
5.11.5 Groups
In the Groups section, you can view a list of groups that contain you or one of your devices as a
member. Supervisors and administrators can manage groups that they or a device they own is a
member of as well as all groups assigned to their department. System administrators can manage
all groups. Groups can be created, edited and deleted from the Manage Groups page. When
editing group details you can add yourself or other users, devices and groups in your department
to groups, define escalation settings for the group and assign schedules to group members.
Figure 22. Manage Groups page (Admin/Supervisor view)
5.11.6 Schedules
The Schedule page provides supervisors and administrators with the ability to create, edit and
delete global and group schedules and edit and delete Device schedules. Device schedules can only
be created from within the Devices section. All global, group and device schedule templates
assigned to specific groups or devices within their department are available to supervisors and
administrators. Global and group schedules can be assigned to group members on the Edit Group
Member Schedule page under the Groups tab. These schedules are applied to group members
only when an alert is sent to the group. They do not influence alerts sent directly to the user,
device or subgroup itself. Device schedules determine availability for the device and owner of the
device for all alerts unless overridden by a group or global schedule.
66 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 23. Manage Schedules page (Admin/Supervisor view)
Under the Schedules tab, staff users can view their device schedules and see a calendar display of
their group member schedules. The Schedule display is based on group membership and reflects
their On Duty hours within a particular group. To schedule availability for individual devices see
Editing Your Devices.
Figure 24. Schedules page (Staff view)
6
The Role of Ports in
TelAlert 6.1 Overview
An introduction to the "port" concept in TelAlert and instructions for configuring [Port]definitions to
achieve the desired notification behavior.
6.2 What is a Port?
Port can refer to the physical connection between the computer on which TelAlert is running and a
device (e.g., a modem, electronic signboard, TelAlert Engine) or network. It can also refer to the
computer’s software-based representation of this connection: the file (e.g., COM2, tty00) that controls it.
Within TelAlert, however, port refers to the entry under [Port] in the TelAlert configuration file
that identifies a connection as available for sending notifications. This definition also provides
TelAlert with the information it needs to use the connected device.
For TelAlert to work properly, all required ports must be set up correctly—in all three senses of the
term.
The physical connection between device and computer must be correct.
The file associated with the port at the operating system level must be set up correctly.
The [Port] definition in the TelAlert configuration file must point to the correct port and accurately
and completely describe its properties, and those of the connected device.
The first two issues are covered in the Quick Start Guide. This chapter covers the third: the issues
you must take into account when setting up, within TelAlert, the ports you need for the kinds of
notifications you want to carry out.
68 | TelAlert 6e™ Administrator Guide - Version 6.1.29
6.3 Basic Port Considerations
The key element common to all [Port] definitions is Model, which identifies the kind of device
connected to the port and allows TelAlert to determine the kinds of notifications for which the port
may be used. There are eight supported Model values:
� Modem—for a port to which a modem is connected.
� DirectModem—for a port to which a modem hooked to a leased line is connected.
� FaxModem—for a port to which a DN400E fax modem is connected to send text messages
to fax machines.
� TTS—for a port to which a Dialogic telephony card is connected using Text to Speech
(TTS).
� Internet—for the computer’s Internet connection.
� Device—for a port to which a device of any kind not explicitly supported by the other
models is connected (electronic signboards, most commonly).
� Remote—for another installation of TelAlert with which the installation on the local
machine is to communicate.
� Gateway—for another installation of a TelAlert server that is behind a firewall.
Obsolete Model values:
� Voice—for a port to which a Dialogic telephony card is connected using prerecorded
words. (Obsolete)
� EngineMini—for a port to which a TelAlert Voice Engine is connected. (Obsolete)
� Engine—for a port to which a TelAlert Classic Engine is connected. (Obsolete)
� EngineSensor—for a port to which a TelAlert Sensor Interface Unit is connected.
(Obsolete)
� EngineRelay—for a port to which a TelAlert Relay Interface Unit is connected.
(Obsolete)
� EngineAnalog—for a port to which certain environmental monitors which connect via
the Sensor Interface Unit is connected. (Obsolete)
Ports Defined During Installation, But …
The TelAlert installation application asks you questions about the connections and devices
that TelAlert will use to deliver notifications. Using this information, it automatically
creates the corresponding [Port] definitions. You may never need to make any port-related changes to your TelAlert configuration. However, this chapter tells you what you
need to know if you want to add a port, change a port’s definition, or understand how a
port figures in TelAlert notifications. Note that port changes may require a new Key value
(under [License]). Additional charges may apply.
Chapter 6: The Role of Ports in TelAlert | 69
The other most essential [Port] components vary according to the Model value set. These are
discussed below.
Modem
A [Port] definition of Model=Modem requires Dev, Speed, Modem, and PhonePrefixes values.
Dev—The name of the file associated with the physical port to which the modem is connected
(e.g., COM2,tty00).
Speed—The speed at which you want to communicate with the modem.
Modem—The name of the [Modem] section corresponding to the model of the modem.
PhonePrefixes—The name of the [PhonePrefixes] section describing the attributes of the
telephone line to which the modem is attached. For information on these settings, refer to Chapter
6: Dialing the Telephone, and the TelAlert Keyword and Command Reference.
DirectModem
A [Port] definition of Model=DirectModem requires Dev and Speed values. No Modem value
is needed: because the modem will not be used to dial, TelAlert does not need to know the special
command set associated with the modem’s model.
Dev—The name of the file associated with the physical port to which the modem is connected
(e.g., COM2, tty00).
Speed—The speed at which you want to communicate with the modem.
FaxModem
A [Port] definition of Model=FaxModem requires Dev, Speed, Modem, and PhonePrefixes values.
Dev—The name of the file associated with the physical port to which the modem is connected
(e.g., COM2,tty00).
Speed—The speed at which you want to communicate with the modem.
Modem—The name of the [Modem]section corresponding to the model of the modem.
PhonePrefixes—The name of the [PhonePrefixes] section describing the attributes of the
telephone line to which the modem is attached. For information on these settings, refer to Chapter
6: Dialing the Telephone, and the TelAlert Keyword and Command Reference.
70 | TelAlert 6e™ Administrator Guide - Version 6.1.29
TTS
A [Port] definition of Model=TTS requires VoiceLine and PhonePrefixesvalues.
VoiceLine—A single Dialogic telephony card can support a number of telephone lines. A separate
[Port] definition is required for each. The telephone line to which a given [Port] definition
pertains is indicated by the value it assigns VoiceLine: e.g., 1, 2, 3, etc. The proper value is determined by the number of the jack on the card into which the line is plugged.
PhonePrefixes—The name of the [PhonePrefixes] section describing the attributes of the
telephone line to which the card is attached. For information on these settings, refer to Chapter 6:
Dialing the Telephone, and the TelAlert Keyword and Command Reference.
Internet
A [Port] definition of Model=Internet requires no additional values.
Device
A [Port] definition of Model=Device requires Dev and Speed values. If the device is a
signboard, the definition also requires a value for DeviceSubType and (if DeviceSubtype is
set to 2) AlphaAddresses.
Dev—The name of the file associated with the physical port to which the device is connected (e.g.,
COM2, tty00).
Speed—The speed at which you want to communicate with the device.
DeviceSubtype—The type of device. 0 is generic; 1 is a signboard to be managed outside of
TelAlert; 2 is a signboard to be managed by TelAlert; 3 is a SpectraLink telephone system.
AlphaAddresses—A range list that provides the addresses of each of a series of daisy-chained
signboards (used only when DeviceSubtype=2).
Referring to Physical Ports on Windows
On Windows, TelAlert now allows the Dev value under [Port] to be entered in either of two formats—
Dev=COMn
Dev=COMn:
—where n is the number of the port.
Chapter 6: The Role of Ports in TelAlert | 71
Remote
A [Port] definition of Model=Remote requires Host and Service values.
Host—The host name (or IP address) of the remote machine on which TelAlert is installed.
Service—The name or number of the port on which the remote installation of TelAlert runs.
Gateway
A [Port] definition of Model=Gateway requires Host and Service values.
Host—The host name (or IP address) of the gateway machine on which TelAlert is installed.
Service—The name or number of the port on which the gateway installation of TelAlert runs.
6.4 If You Are Using a Terminal Server
If you are connecting a device to a terminal server rather than a port on the machine on which
TelAlert is installed, the [Port] definition must be set up differently. It will contain no Dev or
Speed value. It may contain other components in addition to the following, but these are the ones
specific to terminal servers:
DeviceHost—The host name (or IP address) of the terminal server.
DeviceService—The name or number of the port on the terminal server to which the device is
connected.
NetDevice—Set to True.
SoftwareParity—Set to True if the device to which you are connecting is a modem; False
otherwise.
You also must modify the configuration of the terminal server itself:
� Its speed setting must match the speed of the device.
� Its parity setting must be 8/none except where Model=Device. In this case, the
terminal server’s parity setting is determined by the DeviceSubtype value:
0—whatever value is needed to match the device’s parity setting
1—7/even
2—7/even
3—7/even
72 | TelAlert 6e™ Administrator Guide - Version 6.1.29
6.4.1 Testing Connectivity on a Terminal Server
TelAlert comes with two programs: termserv.exe and testcomm.exe. These programs have a
.exe suffix on Windows, but no suffix on UNIX.
The termserv program cannot be used to test connectivity to a real terminal server. The purpose
of termserv is to make a PC with an attached modem act like a terminal server if you do not
have a real terminal server. MIR3 recommends using testcomm to test your real terminal server.
Please note that using testcomm with a terminal server is different from using testcomm with a
standard modem. Use the following syntax with testcomm for testing your real terminal server:
testcomm nm server_name_or_ip server_port
if a standard modem is attached to the terminal server, or:
testcomm nmg server_name_or_ip server_port
if a GSM wireless modem is attached to the terminal server. For example:
testcomm nm 1.2.3.4 4001
testcomm nmg lantronix 3001
6.5 More Advanced Port Considerations
6.5.1 Directing Specific Notifications to Specific Ports
Type/Types
How does TelAlert know to use a given port for a given notification? All notifications are carried out
using a [Configurations] entry, which always contains a Type value. Similarly, all [Port] definitions contain, implicitly or explicitly, a Types value (note that this keyword is plural). If the
[Configurations] definition’s Type value matches one of the items listed as part of the
[Port] definition’s Types value, that port is considered to be appropriate for notifications based
on that [Configurations] definition. Consider these examples:
[Port]
...
{Engine1}
Active=True
Model=Engine
Types=Speaker,Display,NumericPager,TextPager,InteractiveTextPager,Mode
m,InteractiveModem,Voice,InteractiveVoice,Relay
Dev=/dev/com/2
Speed=19200
Modem=[Modem.EngineCermetek]
[Configurations]
...
{TelamonTestPage}
Type=TextPager
Speed=19200
AreaCode=800
Number=679-2778
Chapter 6: The Role of Ports in TelAlert | 73
Here, TelAlert recognizes {Engine1} as an appropriate port for processing notifications based on {TelamonTestPage} because TextPager is one of the “types” listed in the port’s definition. If you also had a [Port] definition of Model=Modem, it would (by virtue of its default settings) also
have a Types value containing TextPager. Thus, TelAlert could use either port to deliver
notifications based on this [Configurations] definition. Which one it would actually use in any
given case is determined by (1) the order in which they were created in TelAdmin and (2) whether
the first one is available at the time TelAlert goes to process the notification. (If this behavior is not
acceptable, you may alter it using the Class keyword discussed immediately below.)
Note that there is a default Types value for all [Port] definitions of a given model. For instance, the Types value shown above is the default for [Port] definitions of Model=Engine and would
hold even if this value were not explicitly assigned in the configuration file. This default value
cannot be expanded; it consists of all the types that a given model is capable of supporting. But it
can be pared down so that a given [Port] definition will not be used to process notifications of an
excluded type.
Why would you want to do this? If you use TelAlert to send both text and numeric pages and have
both a Voice Engine and a modem at your disposal, you might want to make sure that numeric
pages go out through the Engine only (since an Engine’s listening abilities make it easier to send
numeric pages), while allowing text pages to be sent using whichever was available. By modifying
the [Port] definition associated with the modem so that the Types value no longer included
NumericPager, you could ensure that TelAlert never used the modem to send numeric pages.
Assuming the Voice Engine was the only other appropriate mechanism, TelAlert would always use it
instead.
Class
The Class keyword gives you an additional degree of control over which ports are used for which
notifications. By assigning a Class value (an arbitrary integer) to a [Configurations] definition, you can tie that definition to any [Port] definition(s) to which you assign a matching
Class value.
Almost exclusively, Class is used to ensure that pages sent over a leased line
(Model=DirectModem) use the appropriate [Port] definition. For instance, perhaps you send
pages using two paging service providers. One you connect to via dial-up, the other via a leased
line. To achieve this, you would assign a Class value of 1 to the [Configuration] definition
that should use the leased line and the same Class value to the corresponding [Port]
definition. In both the dial-up [Configuration] definition and the corresponding [Port] definition, you would allow the Class value to default to 0 (i.e., by not setting a Class value).
Sometimes Class is Required
There are scenarios in which you might use Class to achieve a desired but optional
behavior. A scenario in which you use a leased line and a regular line to send pages via
different service providers, however, would require some form of Class-based
exclusion. Otherwise, TelAlert would try to use the leased-line port to send other notifications, and these pages would not go through.
74 | TelAlert 6e™ Administrator Guide - Version 6.1.29
If in addition to the leased line you had several regular telephone lines, all with modems attached,
they would all be available to the [Configurations] definition that did not specify a Class
value as long as they, too, did not specify a Class value (in which case it would default to 0).
Conversely, [Port] definitions can have more than one Class value (for instance: Class=1,3).
This allows you to point several [Configuration] definitions to a single port. By setting up
several [Port] definitions with multiple, overlapping Class values, you can give certain
[Configuration] definitions access to several ports while making others completely off-limits.
In this abbreviated example, assume that all [Port] definitions match all [Configuration]
definitions in terms of Type:
[Port]
...
{Port1}
Class=1,2
{Port2}
Class=2,3
{Port3}
Class=1,3
[Configurations]
...
{ConfigurationA}
Class=1
{ConfigurationB}
Class=2
{ConfigurationC}
Class=3
Here, notifications based on {ConfigurationA} will be processed using {Port1} or {Port3}
but never {Port2}. Notifications based on {ConfigurationB} will be processed using {Port1} or {Port2} but never {Port3}. And notifications based on {ConfigurationC} will
be processed using {Port2} or {Port3} but never {Port1}.
6.5.2 Providing Port Backup
Another keyword allows you to specify a [Port] definition to be used in conjunction with a given
[Configurations] definition only if all other ports associated with it cease to be available. This
keyword is BackupClass. To use it, you must be using Class values to link
[Configurations] definitions to [Port] definitions.
If you assign a BackupClass value of 1 to a [Port]definition, TelAlert will use this port to
process notifications based on [Configurations] definitions of Class=1 if all ports of this class are unavailable at the time they are needed. (Of course, the [Port] definition containing the BackupClass value will continue to be used as a regular, primary port for notifications based
on [Configurations] definitions with appropriate Class and Type values.)
Chapter 6: The Role of Ports in TelAlert | 75
This is useful if you have leased lines and a regular line, each dedicated to sends that use different
service providers, but want to use the regular line as a backup for notifications that would normally
be sent over the leased lines. Consider this abbreviated example:
[Port]
...
{LeasedLinePortProviderA}
Class=1
{LeasedLinePortProviderB}
Class=2
{DialOutPort}
#defaults to Class=0 BackupClass=1,2
[Configurations]
...
{LeasedLineConfigurationProviderA}
Class=1
{LeasedLineConfigurationProviderB}
Class=2
{DialOutConfiguration}
#defaults to Class=0
Here, TelAlert understands {DialOutPort} as the port to use to back up the two leased line
ports, as well as any other ports of Class=1 and Class=2, if unavailable.
6.5.3 Controlling Port Deactivation Due To Errors
Ports can encounter errors, such as no dial tone, or IP socket connection failure. For dialup phone
line based ports (Engine, EngineMini, FaxModem, Modem, TTS, and Voice), TelAlert can track both ’Dialing’ errors at the server end (no response to ’AT’ commands, no dial tone, etc.)
which block use of the port with ALL service providers; and ’Connect’ errors at the provider end
(busy signals, no answering modem handshake tone, etc.) which block use of the port with a
SINGLE service provider. Generally, TelAlert customers ignore dialup phone line based ’Connect’
errors at the [Port] level, tracking them instead at the [Configuration] level. For other
ports (Device, DirectModem, Internet, and Remote) TelAlert tracks only ’Connect’ errors, since it cannot distinguish between an error at the server end (an unplugged cable) and an error at
the service provider end of the connection. Generally, TelAlert customers track these ’Connect’
errors at the [Port] level. (Note that the special-purpose EngineAnalog, EngineRelay, and EngineSensor ports do not track either ’Dialing’ or ’Connect’ errors.)
In general, if a customer has multiple interchangeable ports of a particular type that are being used
in a rotation (for instance, 3 Modem ports), it is useful to deactivate a port that is encountering
consistent ’Dialing’ errors, because messages will go out faster if they are not delayed by repeated
error retry cycles on the bad port. However, if a customer only has a single port of a particular
type, it’s more likely that the customer will want to report the errors for follow up, but keep the
port active in the hope the problem will be resolved.
76 | TelAlert 6e™ Administrator Guide - Version 6.1.29
When a port is deactivated for either ’Dialing’ or ’Connect’ errors, TelAlert will execute
[Heartbeat] Error and [Notification] Activation events, if any are defined. TelAlert will then attempt to reactivate the port, if its MaxAutoActivates keyword has a value > 0. It will wait for the time specified by the AutoActivateWait keyword before attempting the
reactivation. Once the number of reactivation attempts has reached the value specified by
MaxAutoActivates, TelAlert will wait for 60 minutes (regardless of the AutoActivateWait
setting), reset its activation attempt counter to zero, and start another cycle of activation attempts
up to the MaxAutoActivates limit.
For ’Dialing’ errors, the keywords DialingErrorLimit, DialingErrorWindow, and
DialingErrorLimitDeactivation are used. If both DialingErrorLimit and DialingErrorWindow are zero, errors will not be tracked for port deactivation purposes.
Otherwise, DialingErrorWindow is a ’sliding’ window of the immediately preceding dialing
attempts, and if the number of dialing errors in that ’sliding’ window reaches the
DialingErrorLimit value, then the port deactivation process will be initiated. Whether or not the port is ACTUALLY deactivated depends on the setting of
DialingErrorLimitDeactivation; if False, the [Heartbeat]Error and [Notification] Activation events, if any, will be executed for warning and tracking purposes, but the dialing error counter will be reset to zero rather than deactivating the port
(MaxAutoActivatesand AutoActivateWait will not come into consideration.)
For example, if DialingErrorLimit=2 and DialingErrorWindow=100, port deactivation
will be initiated if just a couple of errors occur; while if DialingErrorLimit=30and DialingErrorWindow=30, then port deactivation will only be initiated if it’s become clear that
no messages are getting through at all.
For ’Connect’ errors, there’s a similar set of keywords ConnectErrorLimit, ConnectErrorWindow, and ConnectErrorLimitDeactivation.
6.5.4 What Remote Ports Are Used For
Remote Ports allow one TelAlert server to utilize certain Ports physically connected to another
TelAlert server; for instance, a server in New York could utilize ports connected to a server in San
Francisco, Berlin, or New Delhi. The only types of Ports that can be accessed remotely are Engine
(including Sensor and Relay); Modem (including DirectModem and FaxModem); Voice; and Device
(such as Signboards). Internet Ports cannot be accessed remotely. 'Command' Configurations are
not associated with any Port, Remote or otherwise, so it is not possible to issue OS commands
remotely.
Setting Up a Remote Port
It is possible to set up TelAlert so that notification tasks presented to one TelAlert installation are
processed by another one in a remote location. Note that you can take advantage of this
functionality only if it was included as part of your purchase and is permitted by the terms of your
license.
Hosts that can connect to TelAlert remotely are listed in the telalert.remote hosts file. This
file is similar in form to telalert.hosts, but controls access by remote TelAlert servers.
The usefulness of a remote port is illustrated by the following example. You have two TelAlert
installations, one in New York and one in San Francisco, and there is a network connection between
the two. An employee in San Francisco sometimes needs to receive pages originating in New York
but does not have a national paging service. If no remote port is used, the New York TelAlert
installation must dial a long distance number to page this employee.
Chapter 6: The Role of Ports in TelAlert | 77
However, using a remote port, you can have the New York installation pass the notification along to
the San Francisco installation, which can in turn page the employee by making a local call. To do
this, you must first configure both machines so they agree as to the socket number over which
they will communicate. You do this by adding the following line to the operating system’s
services file:
telaremt 25376/tcp # TelAlert Remote
(In Windows, services is in the directory %windir%\system32\drivers\etc\services; in
UNIX, it is in the directory \etc.) You can specify any socket number, as long as the two machines
agree and no other service is using that socket. Likewise, you can call the service anything you
like, as long as you use the same name in both places and refer to it correctly in the TelAlert
configuration file.
After this step, the only required configuration changes are changes to the New York installation’s
configuration file. You must create a new [Port] definition and add a value to the
[Configurations] definition that had been used to page the San Francisco employee.
[Port]
...
{SanFranciscoRemote}
Active=True
Model=Remote
Service=telaremt
Host=Name/IP Address of SF Machine [Configurations]
...
{SanFranciscoServiceProvider}
Type=TextPager
Speed=2400
AreaCode=415
Number=5551212
Remote=SanFranciscoRemote
LocalIfRemoteDown=True
Here, the Remote value in {SanFranciscoServiceProvider} causes notifications originating in New York and based on this [Configurations] definition to be processed using the {SanFranciscoRemote} port definition, which gives the New York TelAlert installation the information it needs to contact the San Francisco installation and have it process the notification.
Further, by setting LocalIfRemoteDown to True in {SanFranciscoServiceProvider},
you can ensure that the New York installation will use a local port to send the notification if it
cannot make contact with the San Francisco installation.
78 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Command Line Options for Remote Ports
The command line option -refuseremote, used by itself, directs the TelAlert server to refuse all
remote connections. The option -acceptremote, used by itself, reverses the effect of a previous
-refuseremote; however, remote connections after an –acceptremote are still required to
match an entry in the telalert.remote filter file. The options –acceptremote and –refuseremote can be used together with the one of the options -insert, -delete, -reload, -verify and -write to modify and display the contents of the telalert.remote filter file.
In addition, each remote connection and disconnection invokes the event keyword Server in the
[Notification] section. [Notification] definitions including the Server keyword can only be referenced from the [Limits] Notification, NotificationLog, NotificationTrap, NotificationITV, NotificationITV1, and NotificationITV2 keywords.
7
Dialing the Telephone 7.1 Overview
Coverage of techniques relating to TelAlert ability to dial a telephone number— needed for most
notifications that will be delivered via text to speech or pager.
7.2 What’s So Hard About Dialing the Phone?
The most common types of TelAlert notifications involve dialing the telephone. In some cases,
pages can be initiated over the Internet, either via email or the Web, but in the usual paging
scenario, TelAlert uses an external modem to dial the telephone number of the paging service
provider’s system. Similarly, the usual scenario requires that TelAlert dial a telephone number in
order to speak the message, either live to the intended person or into a voice mail system.
At its simplest, correctly dialing the phone is effortless: TelAlert simply dials the Number value that
you have provided in the [Destinations] or [Configurations] definition. But your situation may require that you take other factors into account to get TelAlert to dial properly. These
factors are listed below and explained in greater detail on subsequent pages.
TelAlert Does Not Use Windows’s Modem Settings
In Windows, TelAlert controls the modem directly. It ignores any settings in the Modem and Telephony control panel applets.
80 | TelAlert 6e™ Administrator Guide - Version 6.1.29
7.2.1 Local Dialing
Much local dialing is completely straightforward, involving simple seven-digit dialing. However,
some areas require that you dial the area code, even for local numbers. This involves some special
settings. Is the number you must call a long distance number? If so, you must provide the area
code and give TelAlert any special instructions for long distance dialing: long distance access codes,
billing codes, and so on.
7.2.2 Alternate Numbers
Special keywords allow you to specify an alternate number (and, if necessary, area code) for
TelAlert to use if there is a problem connecting using the main number.
7.2.3 Inside and Outside Lines
If TelAlert is connected through a PBX, it may have to dial a special digit to get an outside line, or
before dialing an internal extension.
7.2.4 Special Dialing Scenarios
Aside from the typical local vs. long distance and inside vs. outside considerations, you may find
that some scenarios call for special dialing—for instance, international calling. There are several
keywords you can use to accommodate special dialing needs.
7.2.5 Dialing After the Main Number is Answered
Some voice notifications involve dialing a main number, then an extension after the main number
is answered. Extension and related keywords allow you to control this behavior.
7.2.6 Inserting Pauses During Dialing
You may need to have TelAlert pause at one or more points in the dialing process. You can achieve
this using a comma (,).
Chapter 7: Dialing the Telephone | 81
7.3 Dialing Logic
7.3.1 Dialing Components
The complete number that TelAlert dials for a given notification is usually constructed out of parts.
Some of these are typically included in the [Destinations] or [Configurations] definition used to process the notification:
� Number
� AreaCode
Two other parts may be found here as well. Note that these are not dialed as part of the main
number.
� Extension
� Mailbox
Other parts are typically found in the set of [PhonePrefixes] settings associated with the
telephone line (via the relevant [Port] definition) that will be used to send the notification.
(There can be more than one [PhonePrefixes] section. A given [Port] definition is linked to a given [PhonePrefixes] section through the former’s use of the PhonePrefixes keyword.)
When used, the following are dialed before the beginning of the main number (or before the area
code, if one is used):
� LocalAccess
� LongDistAccess
� AlternateLongDistAccess
� InsideAccess
� SpecialAccess
The following are dialed after the main number, to provide billing code information if it is required
by your PBX system:
� LongDistBillingCode
� AlternateLongDistBillingCode
� SpecialBillingCode
In addition, other values typically set in [PhonePrefixes] allow TelAlert to determine how to
proceed when asked to dial a number:
� InsideDigitCount
� SpecialDigitCount
� LocalAreaCode
� AlternateLocalAreaCodes
� AlternateLongDistanceAreaCodes
82 | TelAlert 6e™ Administrator Guide - Version 6.1.29
7.3.2 Dialing Process
Based on values in the [Configurations] and/or [Destinations] definition, and settings
under [PhonePrefixes], telephone dialing proceeds as follows:
If the Number value is comprised of a number of digits equal to or less than InsideDigitCount, then …
� TelAlert dials the InsideAccess value (if any), then the Number value.
If the Number value is comprised of a number of digits equal to or greater than SpecialDigitCount, then …
� TelAlert dials the SpecialAccess value (if any), then the Numbervalue, and then the
SpecialBillingCode value (if any). In these instances, AreaCode is ignored and not
dialed.
If the Number value is comprised of a number of digits neither less than or equal to InsideDigitCount nor greater than or equal to SpecialDigitCount, then …
� If AreaCode is blank or matches LocalAreaCode, TelAlert dials the LocalAccess
value (if any), then the Number value.
� If AreaCode matches AlternateLocalAreaCode, TelAlert dials the LocalAccess
value (if any), then the AreaCode value, and then the Number value.
� If AreaCode is not blank, does not match LocalAreaCode, and does not match any
value listed for AlternateLongDistAreaCodes, TelAlert dials the LongDistAccess value (if any), then AreaCode, then the Number value, then the
LongDistBillingCodevalue (if any).
� If AreaCode matches any value listed for AlternateLongDistAreaCodes, TelAlert dials the AlternateLongDistAccess value (if any), then AreaCode, then the
Numbervalue, and then the AlternateLongDistBillingCode value (if any).
7.4 Local Dialing
7.4.1 Normal Local Dialing
“Normal” local dialing—i.e., seven-digit dialing—is very simple.
1. Set AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual.
2. In the appropriate [PhonePrefixes] section, set the LocalAreaCode value to the local area code.
3. If you have not already done so, set LocalAccess under [PhonePrefixes]. This is
the value TelAlert must dial (if any) to get an outside line on which to make a local call.
Because the area code matches LocalAreaCode, TelAlert simply dials the LocalAccess value
(if any) and the number.
Chapter 7: Dialing the Telephone | 83
7.4.2 Ten-Digit Local Dialing
In some areas, you must dial the area code for some or all local numbers. This involves some
special settings.
1. Set AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual.
2. In the [PhonePrefixes] section:
If you use seven-digit dialing for numbers in your own area code, but ten-digit dialing for
local numbers in other area codes, enter your area code in LocalAreaCode, and the
other local area codes in AlternateLocalAreaCodes.
If you use ten-digit dialing for all local calls, leave LocalAreaCode blank, and enter all local area codes, including your own, in AlternateLocalAreaCodes.
3. If you have not already done so, set LocalAccess under [PhonePrefixes]. This is
the value TelAlert must dial (if any) to get an outside line on which to make a local call.
Here, if the area code matches one of those listed in AlternateLocalAreaCodes, TelAlert
dials the LocalAccess value, the AreaCode value, and the Number value.
7.4.3 Eleven-Digit Local Dialing
In some areas, you must dial 1 and the area code for all numbers, both local and long distance. In
such cases, leave both LocalAreaCode and AlternateLocalAreaCodes blank.
Within TelAlert, a number that requires dialing a 1 and an area code counts as a long distance
number, even if the call resembles a local call in that there is no toll charge associated with it. If
you wish to dial local and long-distance eleven-digit calls differently, refer to the configuration
instructions in “Other Long Distance Dialing” below.
7.5 Long Distance Dialing
Does the number TelAlert must dial require dialing a 1, then an area code (a total of eleven digits)?
If so, you must treat it as a long distance call. “Normal Long Distance Dialing” explains the typical
long distance setup. Below this, in “Other Long Distance Dialing,” you will find an alternate setup,
which may be useful for 800/888 calls or eleven-digit calls for which there are no charges.
7.5.1 Normal Long Distance Dialing
This is the setup for most long distance dialing that TelAlert is asked to do.
Set the Number and AreaCodevalues in either the [Configurations] or the [Destinations] definition. As a general rule, if you dial the same number to reach different people (as in the case of a number that gives you access to a voice mail system, or the number for
a paging service provider’s system), it makes sense to put these values in the
[Configurations] definition.
If they are unique to a given person, they belong in the [Destinations] definition. (It is a good
idea always to provide an AreaCode, even for local numbers.)
You must also make sure that your local area code (LocalAreaCode) is set in the
[PhonePrefixes] section associated with the telephone line to be used. Before dialing, TelAlert
compares the AreaCode involved in the notification against this value. If they do not match, it
knows to dial the area code.
84 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Finally, set LongDistAccess and LongDistBillingCode. LongDistAccess is the value TelAlert must enter to access a line on which a long distance call can be placed; it may be the same
value required to access an outside line for local calls, followed by 1 (e.g., 91).
LongDistBillingCode is a value your organization may use to ensure proper billing or tracking
of long distance calls. For instance, each person or each department may have a special billing code.
7.5.2 Other Long Distance Dialing
The above description covers most long distance dialing that TelAlert will be asked to do. There are
related keywords designed to accommodate other scenarios. For instance, your PBX may require
you to dial 8 to access a line for calling long distance, but it may treat 800 or 888 calls as local,
requiring you to dial the 9 that gives you access to a local outside line and then a 1. Similarly,
there are areas in which certain calls require a 1 and an area code but incur no charges and thus
are treated by the PBX as local calls.
1. Provide AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual.
2. Enter the relevant area code(s) (e.g., 800, 888, or others) in the list of
AlternateLongDistAreaCodes under the appropriate [PhonePrefixes] section.
3. Finally, set AlternateLongDistAccess and AlternateLongDistBillingCode.
AlternateLongDistAccess is the value TelAlert must enter to access a line on which
this type of call can be placed; it may be the same value required to access an outside line
for local calls, followed by 1(e.g., 91). AlternateLongDistBillingCode is a value
your organization may use to ensure proper billing or tracking of long distance calls. For
instance, each person or each department may have a special billing code. It may be that
no such code is required for calls of this type.
When TelAlert sees that the area code provided does not match the LocalAreaCode value, it
checks the value against those listed for AlternateLongDistAreaCodes. When it finds it listed
there, it uses the AlternateLongDistAccess and AlternateLongDistBillingCode values,
instead of LongDistAccess and LongDistBillingCode.
7.5.3 Alternate Numbers
When appropriate, you can specify an alternate number for TelAlert to dial when it is unable to
deliver the message to the primary number.
To use this feature, simply specify a value for AlternateNumber in the same definition as
Number. When using AlternateNumber, TelAlert uses AlternateAreaCode and
AlternateExtension, so if those numbers are needed be sure to specify them as well, even if
the values are identical to those for AreaCode and Extension.
These alternate numbers are subject to all the same digit-counting and area code logic as Number and AreaCode.
Chapter 7: Dialing the Telephone | 85
7.6 Inside and Outside Lines
If TelAlert is connected through a PBX, it may have to dial a special digit to get an outside line, or
before dialing an internal extension.
7.6.1 Getting an Outside Line
If your organization uses a PBX, you may need to have TelAlert take special steps to reach an outside
line before dialing the main number. In such cases, you tell TelAlert how to get an outside line using
the LocalAccess, LongDistAccess, and AlternateLongDistAccess values, set in the
appropriate [PhonePrefixes] section. (Depending on your implementation, SpecialAccess
may also be relevant for getting an outside line. See Special Dialing Scenarios.)
� TelAlert uses LocalAccess when the number it is dialing is not associated with an area
code, is associated with an area code that matches LocalAreaCode, or is associated
with an area code listed in AlternateLocalAreaCodes.
� TelAlert uses LongDistAccess when the area code does not match LocalAreaCode,
unless it matches a value in AlternateLongDistAreaCodes, in which case it uses
AlternateLongDistAccess. Typically, these values are comprised of (1) the number
required to get the outside line and (2) the 1 that precedes the area code in a long distance number.
7.6.2 Getting an Inside Line
Depending on how your organization’s PBX is set up, TelAlert may not need to do anything special
to dial an inside extension; it may be a matter of simply picking up the line and dialing. Here, you
would list the extension as the Numbervalue and set InsideDigitCount to the number of
digits comprising your extensions. With these settings in place, TelAlert sees that the Number value
is equal to or less than InsideDigitCount and simply dials the number, without worrying about
area code.
If your PBX requires that some special value be entered before dialing an internal extension,
however, you will also need to set an InsideAccess value. Thus, when the InsideDigitCount criterion
is met, TelAlert will dial the InsideAccessvalue first, then the Numbervalue.
Often a Part of Local and Long Distance Calling
Because getting an outside line is commonly a part of making a local or long distance
call, it is covered in greater detail in the preceding sections addressing local and long distance dialing.
86 | TelAlert 6e™ Administrator Guide - Version 6.1.29
7.7 Special Dialing Scenarios
You may find that some scenarios call for special dialing, aside from the typical local vs. long
distance and inside vs. outside considerations. A common example is international calling. There
are several keywords you can use to accommodate international calling and other special dialing
needs.
� SpecialDigitCount
� SpecialAccess
� SpecialBillingCode
SpecialDigitCount works much like InsideDigitCount. You use it to indicate what kinds
of numbers TelAlert should treat specially—i.e., by ignoring area code considerations and dialing
the SpecialAccess value, the SpecialBillingCode value (if any), and then the Number
value. A number is treated in this way if it is comprised of a number of digits equal to or greater
than SpecialDigitCount (whereas a number is treated according to the rules of inside access if it is comprised of a number of digits equal to or less than InsideDigitCount).
If you are in the United States and want TelAlert to dial an international number, typically you
would assign SpecialAccess a value of 011 and SpecialDigitCount a value of 9.
SpecialBillingCode is optional; whether you assign a value here depends on whether your
phone system requires such a billing code to be entered.
If you are using a PBX and must dial a number to get an outside line, you would include this
number as part of the SpecialAccess value—making it 9011, for instance.
7.8 Dialing After the Main Number is Answered
When you want TelAlert to dial an internal extension, you simply enter the extension as the
Number value; this is covered above, in “Inside and Outside Lines.”
In the present section, dialing an extension refers to a call in which you place a regular local or
long distance call and want to enter an extension after the main number is answered. Extension
and related keywords allow you to do this. Though similar, Mailbox and related keywords are
used for a very different purpose, described below.
7.8.1 Dialing a Number, Then an Extension
Typically, you use Extension when you need TelAlert to dial a main number, recognize that it
has been answered (by an auto-attendant), then dial an extension and recognize when it has been
answered.
If the [Configurations]or [Destinations]definition used in processing a notification
includes a value for Extension, TelAlert dials the main number and, when it determines that the
call has been answered, begins waiting the number of seconds specified by ExtensionWait (if any). When this time elapses, it dials the value assigned to Extension and waits the amount of
time assigned to ExtensionListenDelay (if any). When this time elapses, TelAlert once again
begins listening for the call to be answered. When it detects an answer, it proceeds according to
whether it expects a person or a system to answer.
For more information on dialing extensions, refer to Chapter 3 of the TelAlert Voice and
Hardware Guide.
Chapter 7: Dialing the Telephone | 87
7.8.2 Dialing a Number, Then Accessing a Mailbox
Typically, you use Mailbox when you need TelAlert to dial a number and then, having reached
the desired destination, enter other values that allow it to navigate the telephone system in some
specific way—to access a voice mailbox, for instance, so it can leave a message.
For instance, you might use Mailbox if you want TelAlert to dial a number that, once answered,
offers the caller the option of pressing 1 and leaving a voice mail message.
If an extension were required to reach this destination, you would use both Extension and
Mailbox values; in this case, Mailbox would come into play only after the second answer (the
answering of the extension). Mailbox can be present in both the [Configurations] and the [Destinations] definition. If values are assigned in both places, both will be used together,
without separation, in that order. MailboxWait can be specified in the [Configurations] definition; this tells TelAlert how long to wait after the call has been answered before entering the
first of the Mailbox values.
For notifications processed using a [Configurations] definition of Type=InteractiveTTS,
the presence of a Mailbox value also serves to tell TelAlert that it should leave a message if it
does not reach a live person. Where this is the desired behavior, at least some Mailbox value (a
comma, for instance) is required by TelAlert, even if the phone system does not require one.
7.9 Inserting Pauses During Dialing
You may find that you need to have TelAlert pause at one or more points in the dialing process.
When dialing a modem, you can achieve this using a comma (,). You should never include a
comma in any part of a number to be dialed by a Dialogic telephony card.
When asked to process a notification that involves dialing the phone, TelAlert assembles the
number from the relevant components and dials it in its entirety, without any pauses. For instance,
it might piece the number together out of 81(LongDistAccess), 800(AreaCode),
555-1212(Number), and 77 (LongDistBillingCode), and then dial 81800555121277, all in a single motion.
If you found that your PBX had trouble processing the number when dialed in this way, you could
insert pauses to separate the various components. For instance, you might define
LongDistAccess as 81, and LongDistBillingCodeas 77. Typically, no pauses would be necessary between AreaCode and Number.
The length of the pause created by a single comma is set by the modem’s S8 register. In most
modems, the factory default is two seconds. To read the register’s current value, control the
modem with a terminal emulator, and enter the command:
ats8?
To change the register’s setting, use the following command, where n is the length of the pause in
seconds:
ats8=n
Various keywords associated with Extension and Mailbox (ExtensionWait, ExtensionListenDelay, MailboxWait) also provide means of inserting pauses into certain
types of voice-based notifications. For more information, refer to Chapter 3 of the TelAlert Voice
and Hardware Guide.
88 | TelAlert 6e™ Administrator Guide - Version 6.1.29
7.10 Specifying Telephone Dialing Components at
the Command Line
When useful, instead of specifying telephone number components using keywords in
[Configurations] or [Destinations] definitions, you may specify them at the command line:
command-line option equivalent to keyword(s)
-altext ### AlternateExtension
-an (###)###-#### (AlternateAreaCode)AlternateNumber
-ext ### Extension
-mailbox ### Mailbox
-n (###)###-#### (AreaCode)Number
Note that you can use these options only to supply missing values. Any values set with keywords
will override those specified at the command line.
See the TelAlert Keyword and Command Reference for detailed instructions.
7.11 Overriding the Need for Dialtone
Some PBXs either do not provide a dialtone at all, or provide an unusual dialtone the
modem/Dialogic telephony card does not recognize. In such cases it is necessary to customize the
appropriate modem.setups file so that the modem or Dialogic telephony card will skip the
dialtone check and "blind dial" instead.
In this situation, change the modem AT setup commands to skip dial tone detection. While you
should check the particular modem’s documentation, this is usually done by changing X4 to X3.
Normally TelAlert has X4 in the Setup0 string of the modem.setups file. If you use X3, you may
also need to change the length of time that the modem pauses between when it goes "off-hook"
and when it starts to blind dial. Again, check the particular modem’s documentation, but usually
this is done by adding a S6=4 to one of the Setup strings (in this case, we’re setting a pause of 4
seconds).
8
Configuring for Paging
Notification 8.1 Overview
Instructions for setting up TelAlert to send notifications to numeric, text, and two-way
pagers. This chapter covers creating paging-related [Port], [Configurations], [Destinations] (including settings for sending pages via the Internet using SNPP and
TMEX), and [Response] definitions and shows you how to use these definitions and the
TelAlert command line to send pages.
8.2 Getting Started
8.2.1 Needed Information
As suggested in Implementation Planning, before proceeding with the work described in this
chapter you should gather complete information on each of your organization’s paging services.
This will be used in setting up [Configurations] definitions for paging.
� name of service
� service type (text, numeric, or two-way; dial-up or Internet-based)
� coverage (local or national)
� connect speed (needed for dial-up service only)
� Internet name or IP address for service provider’s host machine (needed for Internet-
based service only)
� telephone number for paging (needed only for services that require dialing a single
telephone number)
90 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Next, gather information relating to each of the pagers used by your organization. This will be used
in setting up [Destinations] definitions for paging.
� PIN
� name of user(s)
� telephone number (needed only for services that assign a different phone number to each pager)
8.2.2 General Considerations
Users
In this chapter, the issue of creating [User] definitions and referring to them in [Destinations]
definitions is not addressed explicitly. This is because this keyword-based technique is reqired for
TelAlert 6e and is automatically handled by the Web UI.
For complete information on creating and invoking [User] definitions, refer to Chapter 13:
Representing Users.
Choice of Modems
You can set up paging so that TelAlert will automatically send using the second modem listed under
[Port] when the first is in use. Details on specifying which modem is used appear later in this
chapter, as well as in Chapter 5: The Role of Ports in TelAlert. For the moment, you need to be
aware that it is possible to specify which to use and some of the reasons for choosing one over the
other.
Local Area Code
Be sure that the correct local area code appears under [PhonePrefixes]. This is important for
all TelAlert features that involve dialing, not just paging. The proper LocalAreaCode value is the
area code for your location, regardless of the area code associated with your [Configurations]
definitions. In most parts of the U.S., when reading a [Configurations] definition, TelAlert
compares the area code it finds there against this value, then dials the area code only if the two do
not match. (This is not the case in New York City and other areas where you must dial the area
code for all calls.) For more information, refer to Chapter 7: Dialing the Telephone.
Reaching an Outside Line and Other Special Dialing Techniques
For any notification method that requires dialing, there are a number of special techniques you may
need to employ in order to take into account particular aspects of your organization’s phone system
or policies: techniques for getting an outside line, for initiating a long-distance call, for dialing when a
dialtone is not present etc. For complete coverage of these topics, refer to Chapter 7: Dialing the
Telephone.
Chapter 8: Configuring for Paging Notification | 91
8.3 Setting Up Text Paging
Text paging is the most common type of paging used by businesses and other organizations. Its
protocol, TAP, permits the sending of messages containing both numeric and text characters.
8.3.1 Creating a Text Pager [Configurations] Definition
To enable text paging with TelAlert, you must set up at least one text pager [Configurations]
definition. You should be able to find the information you need in one of the pager configuration
files provided by MIR3. (telalert/Pagers is the default location for these files).
Under [Configurations], create a definition for your paging service. It will look something like
this:
[Configurations]
...
{ATTWichitaTextPager}
Type=TextPager
Speed=2400
AreaCode=316
Number=636-4110
A [Configurations] definition may contain other settings as well. For a complete list, refer to
the TelAlert Keyword and Command Reference.
8.3.2 Pointing to a Modem
TelAlert can use either an internal or external modem to send pages. TelAlert determines which
modem to use by reading keywords in each of the port definitions (under [Port]) and matching
these values to the values assigned to corresponding keywords found in the relevant
[Configurations] definition.
For instance, the sample [Configurations] definition presented above contains a setting
Type=TextPager. Assuming you have made no changes to the [Port] definitions labeled
{Modem}, you will find in each a Type setting in which TextPager is one of a series of listed
items. Under such a setup, both ports can be used for sending pages to destinations that invoke
this [Configurations] definition; TelAlert goes through the list of matching entries in the order
in which they appear under [Port], choosing the first one that is not currently in use.
A [Configurations] definition can also be tied to a particular port by including a Model setting and matching its value to the value assigned this keyword in the desired [Port] definition.
Class=anyinteger is yet another setting that can be used in this way; to use this keyword, simply assign the same Class value in both the port and the [Configurations] definition.
Why is there more than one keyword for associating a [Configurations] definition with a port?
If two are used in a given [Configurations] definition, TelAlert will use a port only if both
values match those assigned to the corresponding keywords in the [Port] definition. If three are
used, all three must match. Consider the following:
92 | TelAlert 6e™ Administrator Guide - Version 6.1.29
[Port]
...
{Engine}
Active=True
Model=Engine
Types=Speaker,Display,NumericPager,TextPager, InteractiveTextPager,Modem,InteractiveModem,Voice,& InteractiveVoice,Relay
Dev=/dev/tty00
Speed=19200
Modem=Engine
{Modem}
Active=True
Model=Modem
Types=NumericPager,TextPager,InteractiveTextPager,Modem,& InteractiveModem
Dev=/dev/tty00
Speed=19200
Modem=Hayes1200
Given these settings, a [Configurations] definition that contained a Type=TextPager setting could use either port. By contrast, a [Configurations] definition containing
Type=TextPager and Model=Modem settings would be able to use only the external modem.
The third keyword option, Class, extends your ability to include and exclude port choices for each
[Configurations] definition. A large organization might use a half-dozen service providers, and
a bank of external modems, some of which may be connected to lines dedicated to a single service
provider. Being able to use two or even three keywords to link [Configurations] definitions to
ports makes it possible to give each some port flexibility while removing some ports completely
from its list of options.
8.3.3 Creating a Text Pager Destination
You do not have to create a [Destinations] definition to send a page (refer to Sending a Page
Without Invoking a Destination below), but this is a very common approach.
For each destination to which you want to send pages, using the Web UI, create a separate entry
under [Destinations], like so:
[Destinations]
...
{JohnTextPager}
Configuration=ATTWichitaTextPager
PIN=1234567
Chapter 8: Configuring for Paging Notification | 93
Note that a text pager destination is typically comprised of:
1. A name that uniquely identifies it within the context of TelAlert.
2. A reference to an existing [Configurations] definition.
3. A PIN that uniquely identifies the pager within the context of the paging service.
For a complete list, refer to Chapter 2: Keyword Reference, in the TelAlert Keyword and
Command Reference.
8.3.4 Sending a Page by Invoking a Destination
You can send pages to a destination using a command like this:
telalertc -i JohnTextPager -m "this is a test"
TelAlert understands how to send this page based on information contained in the
[Destinations] definition and the [Configurations] definition to which it refers.
8.3.5 Sending a Page Without Invoking a Destination
You can send a message to a pager without creating a [Destinations] definition for it (or
without invoking a destination you have already created) by invoking the proper
[Configurations] definition and providing destination-related information on the command
line:
telalertc -c ATTWichitaTextPager -pin 1234567 -m "this is a test"
Any value that can be included in a [Destinations] definition can be specified here. These values
must be preceded by the relevant keyword, which in turn must be preceded by a minus sign:
-user, -schedule, etc.
8.3.6 Sending to Text Pagers via [Configurations] Definitions of Type=InteractiveTextPager
SkyTel allows you to send pages to one-way text pagers using the TMEX protocol, more commonly
associated with two-way text paging, by using a [Configurations] definition of
Type=InteractiveTextPager and Protocol=TMEX. To do this, you must include a PagerType value in the [Configurations] definition. Three values are allowed:
� PagerType=0 is the default. (This is identical in meaning to PagerType=2.) If you do not specify a value, TelAlert takes this value.
� PagerType=1 is the correct value if you want to use the configuration for one-way paging.
� PagerType=2 is the correct value if you want to use the configuration for two-way paging.
94 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Note that the same [Configurations] definition cannot be used for both one-way and two-way
paging. If you want to send pages of both types, you must create a separate [Configurations]
definition for each and have each destination refer to the appropriate one. If you ask TelAlert to
send a message to a group of destinations, some of which point to one [Configurations]
definition and some of which point to the other, TelAlert will deliver all messages to SkyTel in the
same telephone call.
TelAlert will still understand a one-way text pager destination used in conjunction with such a
[Configurations] definition as one-way. Thus, if you wanted to provide a message formatted
specifically for a one-way pager used in this way, you would use the -mP command line option.
8.3.7 Sending Text Pages via Modem without TAP (Protocol=Chat)
Some European text paging services, including Orange GSM/SMS Cellular Phone & Hutchinson
Paging, VodaPage Premier Text Paging Service, and Vodaphone GSM/SMS Cellular Phone do not
support TAP. Their modem interfaces are designed to interact with an actual human being using a
terminal-emulation program.
To send pages to such a system, use TelAlert’s Chat protocol, which is a variation on the protocol
used in UUCP chat scripts. The keywords ChatLogon, ChatScript, and ChatLogoff allow you
to define simple scripts that watch for the host to send certain strings, such as “Please enter pager
number” or “Send a message,” and send other strings, such as “5551212” or “node 5213 is down,”
in return.
The Chat keywords’ values are “chat scripts,” strings containing pairs of “expect” and “send”
parameters. An expect parameter defines a string that the paging system will send to TelAlert
(such as “pager number”); the send parameter that follows defines the string that TelAlert will
send in response (such as the pager number associated with the destination or passed with the
–pin option at the command line).
In addition to text, the expect and send parameters may contain the following codes:
Codes used in both expect and send parameters
Codes used in send parameters only
\W## set timeout to ## seconds \E echo check on
\ - (hyphen) \e echo check off
\b bell \c suppress carriage return at end of send
\n line feed \d pause 1 second
\r carriage return \p pause .25 seconds
\s space \P the pager number (from PIN keyword or –pin option)
\t tab \A the password (from Access keyword)
\\ backslash \M the message text
\x## hex character number ##
\### octal character number ###
If you do not set a timeout with \W##, TelAlert uses the one set by the TextPagerWait
keyword, which has a default value of 10 seconds. Turning on echo check in a send parameter will
cause the chat script to fail if the paging service does not echo back all of the sent text.
Chapter 8: Configuring for Paging Notification | 95
Chat Protocol Example #1: VodaPage
Chat scripts are most easily explained by analyzing a real-world example, such as the VodaPage
Premier Text Paging Service. When a user dials in with a terminal emulation program, it prompts
for the pager number as follows:
Please Enter Required Pager Number -
After the user enters the pager number, VodaPage prompts for the message:
Please Enter Alpha-numeric Message (up to 80 characters) -
After the user enters the message, VodaPage returns to the first prompt, where the user may
either enter another pager number or simply hang up to complete the session.
An appropriate set of [Configurations] keywords for this service would include:
[Configurations]
...
{VodaPagePremierTextPager}
Type=TextPager
Parity=None
Protocol=Chat
ChatLogon=’Number\s\-\s’
ChatScript=’"" \P characters)\s\-\r\n \M Number\s\-\s’ ChatLogoff=’’
MaxMessagesPerCall=10
MaxMessageLength=80
After the call is connected, TelAlert executes the chat script defined by ChatLogon. First it waits
to see the string “Number -” (Number\ s\-\s). If the paging service sends that string within the timeout, since there is no send parameter, TelAlert simply moves on to the script defined by
ChatScript; otherwise, it fails and goes on to ChatLogoff.
If TelAlert gets to the ChatScript string at all, the first thing it needs to do is send the pager
number. This script contains three expect/send pairs:
1. The script starts with an empty expect parameter ("") followed by \P, which tells TelAlert
to send the value of the ${PIN} variable (that is, the pager number associated with this
destination by the PIN keyword or passed at the command line by the -pin option)
immediately.
2. After sending the pager number, TelAlert waits for the string “characters) -” followed by a
carriage return (\r) and line feed (\n). If it receives the string before the timeout, it sends
the value of the ${Message} variable (that is, the message text); otherwise, it fails and
goes on to ChatLogoff.
3. If TelAlert sends the message successfully, it waits for the string “Number -” (just as it did
in the ChatLogon script). If TelAlert (1) receives that string before the timeout, (2) has
another message to send to this service, and (3) has not yet sent the maximum number of
messages indicated by the MaxMessagesPerCall keyword, TelAlert starts ChatScript over at
step 1. Otherwise—that is, if If TelAlert has no more messages to send, or it does not
receive the string within the timeout—it goes on to ChatLogoff.
One way or another, TelAlert will eventually get to the ChatLogoff script. Since in this case it is
empty (""), TelAlert continues processing the event, normally by hanging up and putting the
message(s) in the sent state.
96 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Detecting Invalid PIN Numbers
The example configuration above does not take into account the possibility that you may send
VodaPage the wrong pager number, in which case the service will return the error message,
“Invalid Pager Number.” You can handle that possibility by adding the ChatRejected keyword:
[Configurations]
...
{VodaPagePremierTextPager}
...
ChatRejected=’Invalid’
With this setting, if the paging service sends the word “Invalid” while ChatScript is active,
TelAlert will assume the PIN number is bad, hang up, and put the message into the “message
rejected” state. If it has other messages to send the service, it will redial the service and continue
with the next message.
Chat Protocol Example #2: Orange
For another example, consider the Orange GSM/SMS Cellular Phone & Hutchinson Paging Terminal
Interface. This service presents a user dialing in with a terminal emulation program with the
following menu:
Please choose an option (do not press return) : S :- Send a message H :- Help E :- Exit
If the user presses “s,” this prompt appears:
Enter destination Orange or Hutchison Pager number and press return:
After entering the pager number after the colon, the user sees this prompt:
Type your message (160 characters max) and press return to send:
After the user enters the message after the colon, the system again displays the send/help/exit
menu. An appropriate set of [Configurations] keywords for this service would be:
Type=TextPager
Parity=None
Protocol=Chat
ChatLogon=’Exit\r\n’
ChatScript=’"" S\c return\r\n\r\n: \E\P send\r\n\r\n: \M Exit\r\n’ ChatLogoff=’"" E\c’ MaxMessagesPerCall=10
MaxMessageLength=160
ChatLogon waits for the last part of the menu (the string “Exit” followed by a carriage return
and line feed). Since the send parameter is missing, TelAlert goes directly to ChatScript when it
detects the string, or directly to ChatLogoff if the timeout expires first.
Chapter 8: Configuring for Paging Notification | 97
ChatScript contains four expect/send parameter pairs:
1. This pair has a blank expect, so it immediately sends an S followed by a carriage return.
2. Waits for the colon after the pager-number prompt, then sends the ${PIN} value. The \E means that TelAlert will check to make sure the paging service echoes back the PIN
correctly.
3. Waits for the colon after the message prompt, then sends the ${Message} value.
4. Waits for the menu to appear again, then starts ChatScript over or moves on to
ChatLogoff, as discussed in the previous example.
If the timeout expires on any of the expect parameters, TelAlert moves on to ChatLogoff.
Since ChatLogoff has a blank expect parameter, TelAlert immediately sends an E followed by a
carriage return, telling the paging system that it is exiting. TelAlert then continues processing the
event, normally by hanging up and putting the message(s) in the sent state.
Summary and Additional Information on Chat Scripts
To summarize, when you use the Chat protocol, TelAlert performs the following steps:
1. Connects to text paging service by modem.
2. Runs ChatLogon. If the script fails, TelAlert goes to step 4.
3. Runs ChatScript repeatedly, once for each message. If the script fails or TelAlert hits
the limit set by MaxMessagesPerCall, it goes to step 4. If TelAlert receives the
ChatRejected string, it hangs up, puts the current message into the “message rejected”
state, and goes to step 5.
4. Runs ChatLogoff.
5. If TelAlert has additional messages for the service, it starts over with step 1.
TelAlert’s chat scripts take the form of pairs of expect and send parameters, separated by spaces.
For example, here are four pairs:
If an expect parameter is not followed by a send parameter, as in the last of the sections outlined
above, when TelAlert detects the expect string it goes on to the next expect parameter or, if as in
this case it is at the end of the script, considers the script complete.
98 | TelAlert 6e™ Administrator Guide - Version 6.1.29
8.4 Setting Up Numeric Paging
Setting up numeric paging is similar to setting up text paging in that both involve creating a
[Configurations] definition for each service provider and (optionally) a [Destinations]
definition for each pager. One difference is that a typical numeric pager is associated with its own
unique phone number, so the Number setting (as in phone number) usually appears as part of the
destination, not the [Configurations] definition. A more fundamental difference rests with the
challenge of getting your modem to communicate with the numeric paging service.
When you use TelAlert to send a text page, you call a line reserved for modem-to-modem
communication. Your modem—whether in the Engine or an external one—already understands how
to participate in the handshaking process required to communicate with the service provider; no
special settings are required to instruct the modem what to do, or when to do it.
Some numeric paging services also provide special lines for modem-to-modem communications. If
that method is available, we strongly recommend you use it, as described below in “Sending
Numeric Pages Using the TAP Protocol.” Other numeric paging services require TelAlert to dial the
same number used by human users. In that case, follow the instructions in Sending Numeric
Pages Without TAP.
8.4.1 Sending Numeric Pages Using the TAP Protocol
The better of the two alternatives is to send the numeric page using the service provider’s text-
paging (or TAP) line, just as if you were sending a text message. Most local text paging services
support this by default; most national services do not but will enable it for your account free of
charge, upon request. Be sure to check with your provider before proceeding.
1. Create a special [Configurations] definition for the TAP-based paging service through
which you will be sending numeric pages. Base this definition on information you will find
in the appropriate pager configuration file provided by Vytek Messaging Services, Inc.
(/usr/telalert/Pagers is the default location for these files). For example:
[Configurations]
...
{ATTWichitaTextPagerNumeric}
Type=TextPager
Speed=2400
AreaCode=316
Number=636-4110
NumericMessageOnly=True
2. Make two changes to the settings you find in this file (these changes are reflected in the
above sample):
First, give it a special name to indicate that it is a text paging [Configurations]
definition intended for numeric pages only.
Second, include a special setting, NumericMessageOnly=True. This is necessary to
ensure that TelAlert does not attempt to send text pages using this [Configurations]
definition.
Chapter 8: Configuring for Paging Notification | 99
This setting may come into play in a send to a group of destinations that specifies both a
text and a numeric message in order to let TelAlert decide which version to send to each
destination. Normally, the Type setting determines which version of the message is sent
to a given destination, but setting NumericMessageOnly to True overrides this, ensuring that TelAlert sends only the numeric message to pagers using this
[Configurations] definition. For more information, refer to the discussion of
message-specific command line options (-m, -mi, -mp, etc.) in Chapter 3: Command Line Reference in the TelAlert Keyword and Command Reference.
3. Next, under [Destinations], create entries for all the numeric pagers to which you will
be sending pages using the special [Configurations] definition you created. For
instance:
[Destinations]
...
{CynthiaNumericPager}
Configuration=ATTWichitaTextPagerNumeric
PIN=5551212
In each of these entries, be sure to refer to the appropriate [Configurations]
definition by name. Assuming each pager has its own unique local phone number, this
number (without the area code) will serve as the correct PIN value.
You can send pages by issuing a command that invokes the destination. For example:
telalertc -i CynthiaNumericPager -m "0123456789"
You can also send pages using the above [Configurations] definition and no destination, if you
like, by passing information specific to the pager on the command line: telalertc -c ATTWichitaTextPagerNumeric -pin 5551212 –m "0123456789"
8.4.2 Sending Numeric Pages Without TAP
As discussed above, if your numeric paging service supports TAP, you should use it.
If you cannot use TAP, you can send numeric pages with a conventional modem. You must set a
fixed amount of time to wait after dialing before sending the page. If the number of rings before
the line picks up varies, or the length of any voice recording changes, TelAlert may send the page
too late or too soon, and the message will not go through. This method is highly reliable only with
paging services that always answer the line in exactly the same way.
Multiple Pages Per Phone Call With TAP
In addition to simplifying the numeric paging setup, the TAP option lets you send more
than one page per phone call. This is not possible when you send numeric pages using your service provider’s standard numeric paging dial-up number.
100 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Sending Numeric Pages Without TAP, Using a Conventional Modem
If you cannot use TAP, and do not have a TelAlert Engine (or have one but are reserving it for voice
applications), you will send your numeric pages using a conventional modem. This is problematic,
since a standard modem cannot detect the tone or silence that indicates it is time to send the
page: it can recognize a busy signal but nothing more. Thus, instead of telling it what to listen for
and under what conditions to respond, you are limited to telling it how long to wait before
delivering the message, before ending the call, etc.
In other words, the modem does much of its work “blind.” For that reason, the crucial keyword in
such configurations is called BlindAnswerWait.
1. Under [Configurations], create an entry for the numeric paging service based on the
appropriate configuration information found in the file called numeric in the Pagers
subdirectory. For example:
[Configurations]
...
{NumericPager}
Type=NumericPager
Model=Modem
BlindAnswerWait=10s
PINRequired=False
Terminator=#
PostMsgWait=2s
2. Make necessary changes to this [Configurations] definition, as detailed below:
First, be sure the definition points exclusively to the TelAlert modem port. If you also have
an Engine port configured and both list NumericPager among their types, having
Type=NumericPager in the [Configurations] definition is not sufficient. Above, Model has been set to Modem; this, in combination with the Type value, should uniquely
identify the modem port.
Second, set PINRequired to False if your numeric paging service does not require a
PIN (typically, local numeric paging services assign each pager a unique local phone
number that serves to identify it).
Third, examine the settings related to the timing of TelAlert’s delivery of the message.
Remember, your modem cannot listen for or respond to a tone; here, it is simply a matter
of coming up with a “blind” timing pattern that allows it to deliver the message at the right
time, relative to what takes place at the other end of the line. You will have to experiment
with these settings to find the combination that works best with your service. These
settings are:
BlindAnswerWait—10s specifies how long after the completion of dialing TelAlert will
wait before “blindly” delivering its message. If this is set too low, TelAlert may deliver the
message when the phone is still ringing. If it is set too high, the service may hang up on
TelAlert before it delivers the message. To determine what value to assign here, call the
numeric paging service and count the seconds that elapse from the time you finish dialing
until you hear the tones. Repeat this procedure until you are confident of the consistency
of this timing. To accommodate each additional ring, you will need to add a full six seconds
to the BlindAnswerWait value, since a standard ring cycle is six seconds. You must make sure that this additional time does not cause the service to time out on occasions
when the line is answered more quickly.
Chapter 8: Configuring for Paging Notification | 101
Terminator—This is the tone that TelAlert issues to signal the end of message
transmission. Most services ask callers to press the pound (#) key after entering the
numeric message. After issuing this tone, TelAlert waits the amount of time specified by
PostMsgWait and hangs up.
PostMsgWait—2s specifies how long after message transmission (which includes the issuing of the terminator tone) TelAlert should wait before hanging up. This is needed in
cases where the service provider issues a “fake” busy signal after it hears the terminator
tone; if you permit the modem to detect this, it will report that it received a busy signal
and you will not know whether the message was actually delivered.
3. Under [Destinations], create an entry for each numeric pager. For example:
[Destinations]
...
{CynthiaNumericPager}
Configuration=NumericPager
Area Code=316 Number=555-1212
Since this pager has its own unique telephone number, this number appears here, not in
the [Configurations] definition.
4. Have TelAlert re-read its configuration file, then test the configuration by sending a page
to the destination, like so:
telalertc -i CynthiaNumericPager -m "0123456789"
Even if the message goes through the first time, you should pay close attention to your
success rate for messages sent using this [Configurations] definition, in case
adjustments are needed.
If it does not go through, you will need to try again, this time tracking dial and call
progress in the telalert.trail file. To do this, give one of the following two
commands in a separate command window. On UNIX:
tail -f $TELALERTDIR/telalert.trail
On Windows:
tail -f telalert.trail
Tone Recognition Settings Not Needed
Some of the configuration settings used for sending numeric pages via the Engine’s
modem are not needed here (e.g., ToneWait, AnswerToneOnly, ToneRepeats,
MinToneOn, MaxToneOn, MinToneOff, MaxToneOff, and PreMsgWait).
If you model your standard numeric paging [Configurations] definition on a
definition that contains these settings, you can either delete them or leave them intact.
Assigning a value to BlindAnswerWait causes TelAlert to ignore all settings related to
tone recognition.
102 | TelAlert 6e™ Administrator Guide - Version 6.1.29
8.5 Setting Up Two-Way Paging
Because two-way pagers are a special kind of text pager, much of the work involved in setting up
two-way paging is exactly the same as the work involved in setting up regular text paging. The
main differences pertain to setting up a [Response] definition and telling TelAlert how often to
poll the service provider for available responses.
8.5.1 Creating a Two-Way Pager [Configurations] Definition
To enable two-way paging with TelAlert, you must set up at least one two-way pager
[Configurations] definition. You should be able to find the information you need in one of the
pager configuration files provided by MIR3 (telalert/Pagers is the default location for these
files).
Under [Configurations], create an entry for your two-way paging service, based on the
information you find in the appropriate pagers file. This definition will look something like this:
[Configurations]
...
{SkyTelITwoWayTextPager}
Type=InteractiveTextPager
Protocol=TMEX
Parity=None
MaxMessagesPerCall=100
Speed=19200
AreaCode=800
Number=679-2778
Note the type, InteractiveTextPager, and the “I” (for “interactive”) in the name:
SkyTelITwoWayTextPager. Other [Configurations] definition names may refer to
two-way paging, but only if Typeequals InteractiveTextPager will the definition support
two-way paging (some other two-way [Configurations] definitions, of Type=TextPager, are
for sending regular text pages to two-way pagers).
The Protocol keyword refers to the protocol used to send information back and forth from the
pager. The pagers that TelAlert supports use many different protocols: refer to Chapter 2 of the
TelAlert Keyword and Command Reference for details on the Protocol keyword.
Above, Parity=None is a setting required by the protocol used for two-way paging, TMEX (Telocator Message Entry). MaxMessagesPerCall is a limit specified by your service provider;
the number entered here must not exceed this limit. The Speed setting should be correct for the
service provider, assuming you are using configuration information from the Pagers directory.
Chapter 8: Configuring for Paging Notification | 103
8.5.2 Pointing to a Modem
TelAlert can use either an external modem or the modem in the TelAlert Voice Engine (assuming an
Engine is installed) to send two-way pages. TelAlert determines which one to use by reading
keywords in each of the [Port] definitions and matching these values to the values assigned to
corresponding keywords found in the relevant [Configurations] definition.
For instance, the sample [Configurations] definition presented above contains a setting
Type=InteractiveTextPager. Assuming you have made no changes to the [Port]
definitions labeled {Modem}, you will find in each a Type setting in which
InteractiveTextPager is one of a series of listed items. Under such a setup, both ports can
be used for sending pages to destinations that invoke this [Configurations] definition; TelAlert
goes through the list of matching [Port] definitions in the order in which they appear under
[Port], choosing the first one that is not currently in use.
A [Configurations] definition can also be tied to a particular port by including a Model setting
and matching its value to the value assigned this keyword in the desired [Port] definition.
Class=anyinteger is yet another setting that can be used in this way.
Why is there more than one keyword for associating a [Configurations] definition with a port?
If two are used in a given [Configurations] definition, TelAlert will use a port only if both
values match those assigned to the corresponding keywords in the [Port] definition. If three are
used, all three must match. Consider the following:
[Port]
...
{EngineMini}
Active=True
Model=EngineMini
Types=Speaker,Display,NumericPager,TextPager,InteractiveTextPage
r,&
Modem,InteractiveModem,Voice,InteractiveVoice,Relay
Dev=/dev/tty00
Speed=19200
Modem=EngineMini
{Modem}
Active=True
Model=Modem
Types=NumericPager,TextPager,InteractiveTextPager,Modem,Interact
iveModem
Dev=/dev/tty00
Speed=19200
Modem=Hayes1200
Given these settings, a [Configurations] definition that contained a
Type=InteractiveTextPager setting could use either port. By contrast, a
[Configurations] definition containing Type=InteractiveTextPagerand Model=Modem
settings would be able to use only the external modem.
104 | TelAlert 6e™ Administrator Guide - Version 6.1.29
The third keyword option, Class, extends your ability to include and exclude port choices for each
[Configurations] definition. A large organization might use a half-dozen service providers, two
or more Engines, and a bank of external modems, some of which may be connected to lines
dedicated to a single service provider. Being able to use two or even three keywords to link
[Configurations] definitions to ports makes it possible to give each [Configurations]
definition some port flexibility while removing some ports completely from its list of choices.
8.5.3 Creating Two-Way Pager Destinations
For each pager to which you want to send two-way pages, create an entry under [Destinations],
like so:
[Destinations]
...
{JohnTwoWayTextPager}
Configuration=SkyTelITwoWayTextPager
PIN=1234567
Note that a two-way pager destination is typically comprised of:
1. A name that uniquely identifies it within the context of TelAlert.
2. A reference to an existing [Configurations] definition.
3. A PIN that uniquely identifies the pager within the context of the paging service.
A [Destinations] definition may contain other settings as well, including User and Schedule.
For a complete list, refer to Chapter 2: Keyword Reference, in the TelAlert Keyword and
Command Reference.
Though recommended, setting up destinations is optional. As explained below, at the beginning of
Enabling Responses, you can invoke a [Configurations] definition and provide destination-
related information on the command line.
8.5.4 Enabling Responses
You can send a message by invoking a destination in a command like this:
telalertc -i JohnTwoWayTextPager -m "this is a test"
You can also send a message using the [Configurations] definition only, passing destination-related
information on the command line:
telalertc -c SkyTelITwoWayTextPager -pin 1234567 -m "this is a test"
Chapter 8: Configuring for Paging Notification | 105
Unless you attach a menu of responses to the messages you send, you cannot take advantage of
the medium’s two-way functionality. To do this, follow these steps.
1. Examine the response entries found under [Response]. These are ready for you to refer
to on the command line. For example:
[Response]
...
{Basic}
NumReplies=6
Acked=1
AckedHold=3,4,6
NotAcked=2
Released=5
Reply1=Yes
Reply2=No
Reply3=Hold
Reply4=Info
#Reply4 means the user will be sending additional info #(requires use of a special notification script) Reply5=Release
Reply6=Ping
#Reply6 runs a script that pings a node and reports the result #to the user (requires use of a special notification script)
You can invoke any existing [Response] definition when sending a message to a two-way
pager using an interactive [Configurations] definition:
telalertc -i JohnTwoWayTextPager -m "this is a test" -response Basic -ackwait 15m
In this example, these responses will show up on the pager, in the form of a menu of choices:
Yes, No, Hold, Info, Release, Ping. Each response maps to a TelAlert command by way
of the Acked, AckedHold, NotAcked, and Released settings in the [Response]
definition, so that Yes positively acknowledges the message, No negatively acknowledges it,
and so on.
-ackwait is Essential to Responses
The -ackwait parameter is essential anytime you want to make it possible for the
message recipient to respond: without it, TelAlert would not hold on to the message after delivery and thus would not be in a position to accept a response.
106 | TelAlert 6e™ Administrator Guide - Version 6.1.29
2. Modify the existing [Response] definitions, or create new ones, as necessary.
For instance, you might want to make the above set of responses even more basic by
removing Info and Ping, so that there is a one-to-one correspondence between menu
items and TelAlert commands. Or you might want to add more responses that map to
Acked, AckedHold, NotAcked, or Released, so that these responses carry out the
corresponding action within TelAlert while providing more detailed information. For
example:
[Response]
...
{DetailedReplies}
NumReplies=8
Acked=1,2
AckedHold=5,6
NotAcked=3,4
Released=7,8
Reply1=’Yes<1Hour’
#Reply1 means yes, in less than one hour Reply2=’Yes>1Hour’
#Reply2 means yes, in more than one hour Reply3=NoBusy
#Reply3 means no, I am busy Reply4=NoOffDuty
#Reply4 means no, I am off duty Reply5=HoldWillHandle
#Reply5 means hold, I will handle it Reply6=HoldWillDelegate
#Reply6 means hold, I will assign this to someone else Reply7=ReleaseFixed
#Reply7 means release, this is fixed Reply8=ReleaseNotFixed
#Reply8 means release, but this is not fixed
Here, two responses map to each command, allowing the respondent to positively
acknowledge the message in two ways, negatively acknowledge the message two ways,
and so on. (The intended meaning of each response is explained in a comment line.)
The text of the response will be available in the telalert.trail file. You can make
much better use of this sort of response-related information when using TelAlert’s
“notification” feature. For more information, refer to Enabling Notifications below.
Chapter 8: Configuring for Paging Notification | 107
8.5.5 Enabling Polling
Polling is the means by which TelAlert retrieves the responses returned by message recipients.
Polling is necessary because a response to a two-way page is not automatically delivered to the
originator of the page; rather, the service provider holds it until contacted by the originator, at
which point it hands it over.
TelAlert knows to poll for responses whenever it sends a page that meets three conditions:
� The page must use a [Configurations] definition in which Type is set to
InteractiveTextPager.
� The command generating the alert must specify an -ackwait value.
� The command generating the alert must specify a set of responses.
In addition, the message must still be active: it must be in either an ackwaitor ackheld state.
Otherwise, from TelAlert’s point of view, the message no longer exists and there is no reason for
TelAlert to poll for a response.
The only aspect of polling that it is possible to control is the frequency with which TelAlert dials in
to check for responses. You can do this by changing the CheckITPRepliesInterval setting
under [Limits]. The default is 5m.
Note that this single setting is used by all [Configurations] definitions of
Type=InteractiveTextPager. You may find that a value of less than 5m interferes with
TelAlert’s attempts to deliver messages, since it will cause TelAlert to spend more time polling for
responses. At the same time, this value must be less than any -ackwait value you assign;
otherwise, messages will always expire before TelAlert has a chance to dial in and check for a
response.
8.5.6 Enabling Notifications
Responses are useful because they allow message recipients to affect message status by remotely
issuing a TelAlert command. Customized responses are useful because they allow message
recipients to provide extra information—information in addition to the information implied by an
-ack, -nak, -hold, or -release.
Customized responses become considerably more powerful when used in conjunction with
TelAlert’s “notification” feature, which allows the text of a response to be passed to an external
target—a log file or TelAlert’s controlling application, for example. This makes it much easier to
track the information returned with a response. It also greatly extends the user’s ability to carry
out procedures remotely, since responses can be set up to trigger highly customizable scripts.
Because the notification feature has a wide range of applications—many unrelated to two-way
paging— complete information on setting it up is provided elsewhere in this guide. For detailed
instructions, refer to Chapter 16: Processing Events.
108 | TelAlert 6e™ Administrator Guide - Version 6.1.29
8.6 Setting Up Requests: Unsolicited Messages From
Two-Way Pagers
8.6.1 Receiving Requests
SkyTel and Bell South Wireless Data (BSWD) offer two-way paging services that support
unsolicited messages. In other words, a person with one of these pagers can use it to initiate a
message—also called a request—that is not a response to any page. The person or program dialing
in to the paging provider’s system to check for messages can ask for messages that have come in
response to a specific page, or for all unsolicited messages.
To enable this feature, set PollRequests to True in the relevant [Configurations]. This
setting will cause TelAlert to poll for unsolicited messages at the interval specified in [Limits] by
the CheckITPRepliesInterval keyword. (This value applies to all polling for all configurations
and paging services.)
Any configuration in which PollRequests is set to True also requires ServerPIN and Access
values. ServerPIN is the identifier that tells the service who is asking for the messages. Access is the security code or password associated with the account.
For BSWD, ServerPIN is the DAS account Administrator. Note that BSWD requires ServerPIN
and Access values for both regular two-way polling and unsolicited polling. SkyTel does not
require them for regular two-way polling, but they will be used if you provide them.
8.6.2 Having Requests Trigger [Notifications] Actions
A reply received in response to a two-way page can trigger an action defined in
[Notifications]. The key to this is the NotificationReply keyword in the configuration, which points to the correct [Notifications] definition.
To have unsolicited messages—i.e., “requests”—retrieved by TelAlert trigger an action, use the
NotificationRequest and Request keywords. The first goes in the relevant [Configurations] definition and points to a [Notifications] definition, which in turn
specifies a Request value. For detailed information on using this feature, refer to Chapter 16:
Processing Events.
8.6.3 Simulating Requests for Testing Purposes
You can use the -request command option to submit simulated requests to TelAlert at the
command line:
telalert -request string
The request will be processed using the [Notifications] definition specified by the
NotificationRequest keyword in the [Limits] section.
This setting can be made to determine what [Notifications] definition is used in other
circumstances, as well. For example, you could create a voice menu script that offers a "place a
request" option to users who call and identify themselves to the TelAlert Voice Engine. This script
could then process the user-provided input by creating and executing a TelAlert command that
includes -request input. In such a case, the [Notifications] definition referred to by the
[Limits] section’s NotificationRequest keyword will be used to process this command.
Chapter 8: Configuring for Paging Notification | 109
8.7 Setting Up Internet-Based Paging
Depending on your service provider, you may be able to initiate either one-way or two-way text
pages over the Internet. Both processes are described below.
8.7.1 One-Way Internet-Based Paging
One of the one-way Internet protocols supported by TelAlert is SNPP, Simple Network Paging
Protocol. Using SNPP, TelAlert can pass a message (along with information identifying the intended
destination) to an application the service provider maintains on a machine accessible over the
Internet. This application then takes the information and sends the page.
1. To send pages via SNPP, first create an Internet entry under [Port]:
[Port]
...
{Internet}
Active=True
Model=Internet
Types=Email,TextPager,InteractiveTextPager
Active means that the port is active and available to be used by TelAlert. Model and Types are keywords that form the association between this [Port] definition and the [Configurations] definition(s) in which these values match.
2. Next, set up a [Configurations] definition that uses the [Port] definition of
Model=Internet. Use the information you find for your service provider in the
appropriate pagers file. On Windows systems, these files will be in
%TELALERTCFG%\Pagers; on UNIX systems they will be in
${TELALERTCFG:-/usr/telalert}/Pagers. If you cannot find the pager
configuration you need in this directory and are having trouble creating one, please contact
our Technical Support staff. We may have already written the configuration you want.
The [Configurations] definition will look something like this:
[Configurations]
...
{PagemartSNPPTextPager}
Type=TextPager
Protocol=SNPP
Model=Internet
MaxMessagesPerCall=100
Host=pagemart.net
#Host=198.78.254.130
Service=444
TextPagerWait=30s
Type and Model determine which port this [Configurations] definition uses; both the
values assigned here must match the values set in the [Port] definition for that port to be
used. Since this is an Internet transmission for one-way paging, it will use
Protocol=SNPP. MaxMessagesPerCall is a limit determined by the service provider; the number you enter here must not exceed the provider’s limit. Host is the
Internet name or IP address of the machine running the paging application (you may need
to contact your service provider to learn the correct value). Service is the Internet port
or service name used by SNPP; the default, as defined by this standard, is 444.
110 | TelAlert 6e™ Administrator Guide - Version 6.1.29
TextPagerWait is the amount of time TelAlert should wait for a response from the
paging provider before it considers the connection to be non-functioning and the send to
have failed.
3. Finally, set up a destination that uses this [Configurations] definition. You will need to
include some information on the particular pager you are defining.
[Destinations]
...
{RachelOneWayTextPager}
Configuration=PagemartSNPPTextPager
PIN=4567890
....
You can send a page by issuing a command that invokes the destination. For example:
telalertc -i RachelOneWayTextPager -m "this is a test"
You can also invoke the [Configurations] definition and pass destination-related information
(in this case, the PIN number for the pager) on the command line. For example:
telalertc -c PagemartSNPPTextPager -pin 4567890 -m "this is a test"
8.7.2 Two-Way Internet-Based Paging
The setup process for two-way Internet paging is similar to most others. It involves creating a
[Port] definition, a [Configurations] definition that is associated with this port via its Type
value, and a destination that specifies this [Configurations] definition. It is similar to dial-up
two-way paging in particular in that it requires you to enable responses. It differs from all other
paging setups in that it uses its own protocol: TMEX, the Telocator Message Entry protocol. This
difference will show up in a number of small ways as you proceed with the setup.
TelAlert users will find many of the definitions they need already in TelAdmin.
[Port] Definition
The [Configurations] definition you are going to select or create will use the Internet port
represented by the following definition. If this definition is not already in place, it may mean that
your license does not support an Internet port. In this case, you should contact your MIR3 sales
representative.
[Port]
...
{Internet}
Active=True
Model=Internet
Types=Email,TextPager,InteractiveTextPager
This [Port] definition is associated with particular [Configurations] definitions by means of
the Model and Types lines. Active=True means that the port is available for use by TelAlert.
Chapter 8: Configuring for Paging Notification | 111
[Configurations] Definition
Next, choose and set up a [Configurations] definition. Use the information you find for your
service provider in the appropriate pagers file. On Windows systems, these files are located in
%TELALERTCFG%\Pagers; on UNIX systems they are located in
${TELALERTCFG:-/usr/ telalert}/Pagers.
Your configuration will look something like this:
[Configurations]
...
{SkyTelInetTwoWayTextPager}
Type=InteractiveTextPager
Protocol=TMEX
Model=Internet
MaxMessagesPerCall=100
ServerPIN=serverpin
Access=password
PollRequests=False
Host=skysock.skytel.com
Service=2502
DialBackup=5
Parity=None
Speed=19200
AreaCode=800
Number=679-2778
The values assigned to Type and Model tie this [Configurations] definition to one of your
[Port] definitions (in this case, {Internet}). The communication protocol is TMEX.
MaxMessagesPerCall is a limit determined by your service provider; the number you enter
here must not exceed this limit. ServerPIN and Access will usually be needed,; contact your
service provider if you do not have the correct values for these. Host is the Internet name or IP
address of the machine running the paging application (you may need to contact your service
provider to learn the correct value). Service is the Internet port or service name used by TMEX;
the default, as defined by this standard, is 2502.
The last five settings in this entry, beginning with DialBackup, are optional. Taken together,
they permit pages to be sent via dial-up if TelAlert encounters (in this case) five connect failures in
the course of attempting to send a page using this [Configurations] definition.
In the current example, as soon as TelAlert encounters the fifth connection error in attempting to
send a page, it dials the number you provide here and, still using the TMEX protocol, transmits the
message to the service provider. Parity=None is the correct value relating to all dial-up TMEX
paging, as is the Speed setting presented here.
Connecting to BSWD via the Internet
Bell South’s two-way paging service allows you to initiate pages via the Internet. To take
advantage of this capability, TelAlert has been modified to support the associated
protocol. Thus, in the relevant [Configurations] definition, Protocol should be set to
XSOCKET. This [Configurations] definition also requires ServerPIN (DAS account Administrator) and Access(password) values.
112 | TelAlert 6e™ Administrator Guide - Version 6.1.29
[Destinations] Definition
Under [Destinations], create an entry for the two-way pager to which you want to send pages:
[Destinations]
...
{DavidTwoWayInternetPage}
Configuration=SkyTelInetTwoWayTextPager
PIN=3456789
[Response] Definition
TelAlert comes with basic, built-in response functionality that you can take advantage of when
sending to two-way destinations. This can be enhanced using an invoked [Response] definition.
For more information, refer to the discussion of responses in the preceding section on regular (i.e.,
non-Internet-based) two-way paging.
Polling
Polling is the means by which TelAlert checks for responses to two-way pages it has sent. When it
polls, TelAlert uses the same [Configurations] definition that it used to send the original page.
If you send a two-way page via the Internet, TelAlert attempts to retrieve a response by the same
medium. If DialBackup is specified and TelAlert encounters the specified number of connect
errors in attempting to poll, it will use the DialBackup information to poll by dial-up. For more
detailed information, refer to the discussion of polling in the preceding section on regular (i.e., non-
Internet-based) two-way polling.
[Notifications] Definition
As discussed under “Setting Up Two-Way Paging,” response functionality can be significantly
expanded using TelAlert’s “notification” feature, which allows you to pass customized responses to
a log file or another application. Thus, you can enable a response that will update a trouble ticket
in the controlling application with which you have integrated TelAlert; likewise, you can enable a
response that, by triggering a script, will carry out a diagnostic or administrative operation.
Because the notification feature has many uses that are not specifically related to paging, it is
covered elsewhere. For detailed instructions, refer to Chapter 16: Processing Events.
Chapter 8: Configuring for Paging Notification | 113
8.8 Initiating Pages via Email
Some paging service providers allow you to initiate pages by sending email to an account linked to
a pager. Normally, the practice is to address such messages with the recipient’s PIN and the
provider’s domain, for instance, [email protected].
To set up TelAlert to use this method, use the To keyword in a [Configurations] definition of
Type=TextPager to define the provider’s domain, and the PIN keyword in associated
[Destinations] definitions to provide the rest of the address. For example:
[Configurations]
...
{EmailPage}
Type=TextPager
Model=Internet
Host=mailserver.com
Service=smtp
From=’[email protected]’
To=${PIN}@pagingprovider.com
[Destinations]
...
{BobEmailPager}
...
PIN=1234567
When processing a notification to {BobEmailPager}, TelAlert will the take PIN value from the
invoked destination, substitute it for the ${PIN} in the configuration’s To value, and use that as the address for the email message.
The more important application of this feature, however, is for users who store PINs outside of
TelAlert and pass them on the command line, bypassing any references to destinations in the
configuration file. Here, as long as the invoked [Configurations] definition contains the correct
To value (see above), the command line need not contain any email-related information. For
instance:
telalertc -c EmailPage -pin 1234567 2345678 3456789 -m "this is a test"
8.8.1 Responses to Two-Way Email-Based Text Pages
A helper application, called Readmail, is a program that can parse and process emails sent as
responses to TelAlert notifications, including notifications sent straightforwardly as emails and
pager notifications sent by the above-described email-based mechanism. For information on using
Readmail to process email responses, refer to Handling Responses to Email With Readmail.
114 | TelAlert 6e™ Administrator Guide - Version 6.1.29
8.9 Adding ID Numbers to Pages
It is often useful to add TelAlert’s internal tracking numbers to pager messages. (For an overview
of TelAlert’s ID numbers, refer to Command Line Options Following a Send in Chapter 3 of the
TelAlert Keyword and Command Reference.)
Note that you can add ID numbers when using any notification medium. The techniques are
covered here simply because they are more useful with pagers than with other media.
Adding Send IDs to Pages
Adding the send ID gives one-way pager users the information they need to respond to pages via
the command-line or Web client, or by dialing into a TelAlert Voice Engine. You can make TelAlert
add the send ID automatically to all messages sent using a particular [Configurations] or
[Destinations] definition by including the following line:
AddSendIDtoMessage=True
With this setting, messages sent using this configuration or destination will be preceded by the
send ID number and a colon. For example:
6488:node 5681 down
Alternatively, you can add the send ID to the message manually by including the ${SendID}
substitution parameter at the command line. For example:
telalertc -i BobNumericPager -m "\${SendID}:node 5681 down" -ackwait 1h
Adding Track IDs to Pages
Most paging services have no way of tracking whether a pager has actually received a message or
not. With such services, you can easily miss a message and never know it.
TelAlert’s track ID feature deals with this potential problem by automatically numbering each
message sent to a particular destination. With this option enabled, users can tell if a page is
missing by the gap in sequence. For example, consider this series of pager messages:
145:node 1250 down
146:node 5206 down
148:node 9864 down
In this case, the user would know to contact TelAlert (through the Web, command-line client, or
dialing in to a TelAlert Voice Engine) to check for a message with track ID 147.
To enable the feature, add the following lines to the relevant [Destinations] definitions, or to
enable track IDs for all pagers, add them to the relevant [Configurations] definition(s):
MaxTrackID=999
AddTrackIDtoMessage=True
Chapter 8: Configuring for Paging Notification | 115
Setting MaxTrackID to a value higher than 0 (its default) causes TelAlert to assign track ID
numbers to messages sent using this configuration or destination. The value is the number after
which TelAlert restarts track ID numbering at 1.
Setting AddTrackIDtoMessage to True causes the track IDs to be added to the beginning of
the message text, as shown in the examples above. If you have AddSendIDtoMessage also set
to True, in the message text the send ID precedes the track ID, and the two are separated by a
colon.
Alternatively, you can leave AddTrackIDtoMessage set to its default value of False, and add
track IDs to selected messages using the ${TrackID} substitution parameter. For example:
telalertc -i BobNumericPager -m "\${TrackID}:node 1250 down" -ackwait 1h
When you set AddTrackIDtoMessage to True, you may also wish to set an AcknowledgeWait value in the same definition to ensure that messages sent without an -
ackwait will be active long enough to be recovered in the event they are not delivered to the
pager.
Adding Alert or Group IDs to Pages
Under some circumstances, it may be helpful to add alert or group IDs to messages. You can add
them at the command line, using substitution parameters:
telalertc -i BobNumericPager -m "\${AlertID}:node 1250 down" -ackwait 1h telalertc -i BobNumericPager -m "\${GroupID}:node 1250 down" -ackwait 1h
No Track IDs Assigned When Using -c
Track IDs are assigned only to messages sent to defined destinations. Hence, regardless
of the [Configurations] settings, when you send a message using -c no track ID will
be assigned.
Escalation May Cause Gaps in Track ID Sequence
Track IDs are assigned to messages at the time they are created. When an alert is
directed to a group with an associated [Strategy] definition, all messages are created
at once. When a member of the group acknowledges one of those messages, any still-
unsent messages are normally cleared, producing a gap in track ID sequence at the
destinations to which they would have been sent.
9
Configuring for Voice
Notification 9.1 Overview
Information on software configuration for voice functionality has been moved to the TelAlert Voice
and Hardware Guide.
9.2 Configuration for Voice Notification
Voice is the second most commonly used notification medium supported by TelAlert. If you plan to
use TelAlert’s voice capability, you should have purchased a Dialogic telephony card and installed
and tested it following the directions in the TelAlert Voice and Hardware Guide. Once the
Dialogic telephony card is in place, most of your work will consist of setting up specific
[Configurations] and [Destinations] definitions appropriate for voice notifications.
All the information regarding the Dialogic telephony card and software configuration for voice
functionality is now covered in the TelAlert Voice and Hardware Guide.
Information on Configuring for Voice Notification is now in the TelAlert Voice
and Hardware Guide
Since TelAlert voice functionality requires a Dialogic telephony card, the information on
software and hardware configuration for voice functionality now resides in the TelAlert Voice and Hardware Guide.
10
Configuring for Other Notification Media
10.1 Overview
Instructions for setting up TelAlert to send notifications to non-voice, non-pager destinations such
as email, electronic signboards, the LCD text displays of SpectraLink wireless telephones, and the
command line. This chapter covers creating [Configurations] and [Destinations]
definitions for these media and using these definitions and the TelAlert command line to send
messages.
10.2 Getting Started
10.2.1 Needed Information
For electronic signboard notification setup, you need to know:
� the name of the physical port to which it is connected, or if it is connected to a terminal
server, the servers’s IP address and the number of the appropriate TCP port
For email notification setup, you need to know:
� the names and email addresses for all the people to whom you want to be able to send
messages
� the Internet name or IP address of the mail server TelAlert will use to send email
� the address you want to appear in the “From” field on every email
For SpectraLink LCD notification setup, you need to know:
� the extension numbers of all the SpectraLink telephones to which you want to be able to send messages
� the address of the serial port to which the Open Applications Interface Gateway is
connected
120 | TelAlert 6e™ Administrator Guide - Version 6.1.29
For command line notification setup, you need to know:
� the full path to the application you want to trigger
� the command you want to give
� the shell you want to use (if any)
To set up TelAlert to send messages to other systems (UNIX syslog processes, TelaConsole
running on an Windows machine, and AS/400s), you need to know:
� the appropriate Serviceand Host value for the system in question (when sending messages to UNIX syslog processes, TelaConsole, or an AS/400)
� the “Facility Code” and “Priority” values required by the system in question (when sending messages to UNIX syslog processes or TelaConsole)
� a valid login value and the queue in which you want the message to be placed (when sending messages to an AS/400)
� a special AS/400 program, QSYSOPR, available from Patrick Townsend Associates (when sending messages to an AS/400)
To set up TelAlert to send messages to Web-enabled cellular telephones, you need to know:
� the host name and service value for the Nextel server
� the exact TelAlert Web client URL to which recipients should go to retrieve their messages
To set up TelAlert to send two-way messages to Nextel cellular phones equipped with text
screens, you need to know:
� the host name of the Nextel server
� the PIN for any phones to which you will be sending messages
� an email address within your organization’s domain to which responses can be sent
Key Values in License may need updating when creating new Ports
Note that adding new [Port] definitions may require a new Key value (under [License]),
depending on the number of licenses you purchased. Additional charges may apply. Contact your MIR3 Sales Representative for more information on adding new [Ports].
Chapter 10: Configuring for Other Notification Media | 121
10.3 Setting up Electronic Signboard Notification
10.3.1 Signboard Overview
There are two basic approaches to setting up Alpha electronic signboards to display TelAlert
messages. (Alpha is the only brand of signboard TelAlert supports directly.)
The standard and easier method is to let TelAlert control message display (DeviceSubType=2 in
the signboard’s [Port] definition). You set the maximum number of messages to rotate among,
whether to drop older messages to make room for new ones, and a few other simple options, and
TelAlert handles the details.
Alternatively, you can configure TelAlert to let another application control message display
(DeviceSubType=1 in the signboard’s [Port] definition). This option is popular among call-
center users and others who want their signboards to display a fixed number of continuously
updated messages displaying such current information as the number of calls waiting and the
average hold time.
Whichever approach you choose, the basic elements comprising a signboard setup are the same: a
[Port] definition and a [Configurations] definition. A [Destinations] definition is another
common piece of the configuration, though it is not always required.
10.3.2 Initial Signboard Firmware Setup
If you have more than one signboard, you will need to set each to use a different serial address
(the number portion of the Mailbox keyword value, discussed below). Depending on the model,
you may perform this task using buttons on the signboard, its remote control, or bundled software.
The default value is usually 01, so if you have only one signboard this step is probably
unnecessary. If your signboard does not work, check to make sure the serial address is set to 01.
Note that this serial address has nothing to do with your computer’s serial port number. It is simply
an arbitrary hexadecimal number that allows you to control multiple signboards individually.
Choose addresses that use the digits 0 through 9 only; do not use A through F.
If you have many signboards, you may wish to group them by assigning serial addresses with the
same first or last digit, for example 01, 02, and 03, or 10, 20, and 30. Using Mailbox wildcards
(discussed below), you can then use a single TelAlert send to display the same message on all
signboards in a group. For example, if you configured the signboards in your help-desk offices to
use 01, 11, and 21, and those in network managers’ offices to use 02, 12, and 22, you could use
commands like the following to send messages to the two groups:
telalertc -c signboard -mailbox ?1 -m "hello help desk office" -ackwait 10m telalertc -c signboard -mailbox ?2 -m "hello network managers" -ackwait 10m
122 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.4 Standard Signboard Setup (DeviceSubtype=2)
The following discussion covers the configuration changes required for TelAlert to control how
messages are displayed on your signboard. See “Alternative Signboard Setup
(DeviceSubtype=1)” below for instructions on configuring TelAlert to let another application
control message display.
10.4.1 TelAlert-Controlled Signboard Message Display
When TelAlert controls a signboard, it automatically rotates among active messages, up to the
number set by the MaxTextFiles keyword value. You can raise that setting from its default of
ten messages, but keep in mind that if you raise it too high, messages can take a very long time to
cycle, which will delay response.
By default, once the number of active signboard messages reaches the value of MaxTextFiles,
the next signboard message sent will be held until one of the active messages is acknowledged.
Alternatively, you can have TelAlert drop older messages from the display to make room for newer
ones, by setting TextFilesFIFO to True. With that setting, TelAlert will display each message
for at least two minutes before bumping it. You can adjust that minimum display time by changing
the TextFilesFIFOMinDisplayTime value. Note that FIFO drops messages only from the
signboard; they remain active in TelAlert, and expire or escalate just as they would have if they
had not been bumped.
10.4.2 Signboard [Port] Definition
Complete the tasks described in “Initial Signboard Firmware Setup” before proceeding with the
instructions in this section.
The [Port] definition tells TelAlert where to find and how to communicate with the signboard. All
signboards that share a single serial port (either on the computer running telalerte or on a terminal
server) share a single [Port] definition.
Here is a typical [Port] definition for a UNIX system with a signboard attached to its serial port:
[Port]
...
{SignboardPort}
Active=True
Model=Device
Types=Device
DeviceSubType=2
SoftwareParity=False
Dev=/dev/com/a
Speed=9600
AlphaAddresses=1
The configuration for Windows is the same, except for the dev= value:
{SignboardPort}
...
Dev=com2
Chapter 10: Configuring for Other Notification Media | 123
A signboard connected to a terminal server has no dev= value. Instead, it includes the following
keyword values:
{SignboardPort}
NetDevice=True
DeviceHost=192.168.168.140
DeviceService=3001
Model—This keyword identifies the kind of device connected to the port and allows TelAlert to
determine the kinds of notifications for which the port may be used. In [Port] definitions relating
to signboards, it must be set to Device.
Types—Not relevant to signboards. Where Model=Device, Types must also be Device.
DeviceSubtype—Set to 2 if you want TelAlert to control message display; set to 1 if you want TelAlert to let another application control message display.
SoftwareParity—Not relevant to signboards. Leave blank or set at default value of False.
Dev—The name of the physical port to which the signboard is connected.
Speed—For signboards, must be set to 9600.
AlphaAddresses—A list of the serial addresses (discussed under “Initial Signboard Firmware
Setup” above) of daisy-chained signboards sharing this port, expressed as two-digit decimal
numbers separated by commas: for example, 1-3,11-13,21-23. For a single signboard, normally
left blank or set at default value of 1. (This keyword is ignored when DeviceSubtype=1.)
NetDevice—Set to its default value of False if the signboard is connected to serial port of the computer running telalerte. Set to True if the signboard is connected to a terminal server.
DeviceHost—The IP address or network name of the terminal server to which the signboard is connected.
DeviceService—The number of the TCP port TelAlert is to use to communicate with the terminal
server to which the signboard is connected.
10.4.3 Signboard [Configurations] Definition
Normally you will create only one [Configurations] definition for each signboard [Port]
definition. Multiple signboards that share the same [Port] definition can share the same
[Configurations] definition by referencing it in individual [Destinations] definitions.
[Configurations]
...
{SignConfigST2}
Type=Device
DeviceSubtype=2
Parity=Even
Mailbox=Z
Terminator=
ServiceMaxMessageLength=960
MaxTextFiles=10
TextFilesFIFO=True
TextFilesFIFOMinDisplayTime=2m
FailWait=2
124 | TelAlert 6e™ Administrator Guide - Version 6.1.29
TextFilesEmptyMessage=\x1B b \x1C1\x13
Type—With signboards, always set Type=Device (to match the setting in the [Port] definition).
DeviceSubtype—Must be set to match the setting in the [Port] definition.
Parity—For signboards, must be set to Even.
Mailbox—This keyword uniquely identifies the signboard with which this [Configurations]
definition is associated. Mailbox values are comprised of (1) a letter indicating type (one-line vs.
two-line, for instance) and (2) a two-digit hexadecimal number (01 to FF) corresponding to the signboard’s serial address (discussed under “Initial Signboard Firmware Setup” above).
Mailbox should normally be set to Z in the [Configurations] definition. (The Z type will work with all models.) Set the serial address in the [Destinations] definitions, and TelAlert will
combine the type and serial address values when sending messages to the destinations. With this
setup, you can also specify the serial address on the command line, for example:
telalertc -c signconfigst2 -mailbox 02 -m "this is a test" -ackwait 10m
Terminator—Not relevant to signboards. Leave blank.
ServiceMaxMessageLength—Not relevant to signboards. Leave blank or set at default value of
960.
MaxTextFiles—The maximum number of messages you want the signboard to be able to hold and
cycle among. (This keyword is ignored when DeviceSubtype=1.)
TextFilesFIFO—“First in, first out.” When this value is set to False, TelAlert will count as “failed”
any message sent to the signboard when it is already holding the maximum number of active
messages. When this value is set to True and a message is sent to a signboard already holding the maximum number of active messages, TelAlert will eliminate the oldest such message to make
room for the new one. (This keyword is ignored when DeviceSubtype=1.)
TextFilesFIFOMinDisplayTime—When TextFilesFIFO=True, the minimum amount of time
TelAlert will display a message on the signboard. (This keyword is ignored when
DeviceSubtype=1.)
FailWait—Controls how many minutes TelAlert will wait before trying to send the message again
after finding that the signboard is full. You should set this to a shorter length of time than that set
by TextFileFIFOMinDisplayTime.
TextFilesEmptyMessage—Controls what is displayed on a signboard controlled by TelAlert when
there are no active messages. The default value (\x1B b \x1C1\x13) displays the current time. (This keyword is ignored when DeviceSubtype=1.)
Chapter 10: Configuring for Other Notification Media | 125
10.4.4 Signboard [Destinations] Definitions
Though it is not always necessary to create a [Destinations] definition for a signboard, doing
so may offer certain advantages. For instance, the application with which you integrate TelAlert
may be set up to begin all message-generating commands as if sending to a destination, that is,
when using the -i option. Creating a signboard [Destinations] definition lets you avoid making an exception to this general procedure.
The following definition assumes the Mailbox type has been set in the indicated configuration:
[Destinations]
...
{Sign}
Configuration=SignConfigST2
Mailbox=01
Configuration—This keyword simply points to the [Configurations] definition you want
TelAlert to use when processing alerts directed to this signboard.
Mailbox—Set the signboard’s serial address here. If you have multiple signboards, this keyword
will control which will display messages sent with this [Destinations] definition. See the
discussion of Mailbox in “Signboard [Configurations] Definition,” above.
10.4.5 Sending Messages to the Signboard
You can send messages to the signboard represented in the above example using either the –I or
–c command line options:
telalertc -i Sign -m "this is a test" -ackwait 10m
telalertc -c SignConfigST2 -mailbox 01 -m "this is a test" -ackwait 10m
The -ackwait option is required, as it determines how long the message stays on the signboard. If you send a message with no –ackwait value, it will not appear on the board, or will flash for just an instant.
10.4.6 Controlling Signboard Text Color and Effects
The display effect and color of a TelAlert signboard message is determined by an 11-character
string of signboard control codes, which as discussed below can be specified either in the
signboard’s [Destinations] definition, or at the command line with -mi.
The control string’s format is:
\x1B0[mode]\x1C[color]
126 | TelAlert 6e™ Administrator Guide - Version 6.1.29
To create a usable signboard control string, replace [mode] and [color] with codes from the
following table:
mode
code effect
color
code color
a slow continuous scroll 1 red
right to left
b no motion 2 gree
n
c flash 3 ambe
r
e scroll up
f scroll down
g scroll right to center
h scroll left to center
i wipe up
j wipe down
k wipe left
l wipe right
m scroll up with pauses
p split message and scroll in
from sides
q split message and scroll
out from center
r split message and wipe in
from sides
s split message and wipe out
from center
Including Control Codes in a [Destinations] Definition
You can include signboard control codes in the MessagePrefix value in a [Destinations] definition. With this approach, you can create a separate [Destinations] definition for each
combination of color and effects you wish to use. For example, if your signboard supports it you
could create a destination for each color:
[Destinations]
...
{SignRed}
MessagePrefix=’\x1B0a\x1C1’
...
{SignGreen}
MessagePrefix=’\x1B0a\x1C2’
...
{SignAmber}
MessagePrefix=’\x1B0a\x1C3’
...
Chapter 10: Configuring for Other Notification Media | 127
Assuming the three definitions’ other settings were identical, with this setup you could make a
message appear in the desired color by sending it to the matching destination.
Specifying Control Codes at the Command Line
Alternatively, you can specify signboard control codes at the command line. Note that you cannot
do this with signboard destinations that have control codes specified in MessagePrefix; you
must use destinations where MessagePrefix is blank. The first step is to create a [Message]
definition that will insert the parts of the control string that are always the same. For example:
[Message]
...
{Subtype2Msg}
Device=’\x1B0${Parm1}\x1C${Parm2}${Parm3}’
When you invoke that definition at the command line with -mi, TelAlert replaces ${Parm1},
${Parm2}, and ${Parm3} with the mode code, color code, and message. In other words, the syntax is:
telalertc -i Sign -mi Subtype2Msg mode_code color_code "message text"
So, for example, the following commands will display the same message in red, green, and amber,
respectively:
telalertc -i Sign -mi Subtype2Msg a 1 "node 2042 down" telalertc -i Sign -mi Subtype2Msg a 2 "node 2042 down" telalertc -i Sign -mi Subtype2Msg a 3 "node 2042 down"
10.4.7 Configuring Multiple Signboards
If you have more than one signboard, you must program each with a separate Mailbox number
(serial address), as discussed in “Initial Signboard Firmware Setup” above. You can then use those
numbers to create a separate [Destinations] definition for each signboard. For example:
telalertc -i signboard1 -m "message for signboard 1" -ackwait 10m telalertc -i signboard2 -m "message for signboard 2" -ackwait 10m
Alternatively, you can have the controlling application send messages to the appropriate signboard
by using the -mailbox command-line option. For example:
telalertc -c signboard -mailbox 01 -m "this is a test" -ackwait 10m
TelAlert supports the wildcarding of numeric Mailbox values. For instance, ?? points to all signboards, ?1 points to those with addresses that end in “1,” and 1? points to those with
addresses that start with “1.” You can use these wildcards to route a single message to multiple
destinations. For example:
telalertc -c signboard -mailbox ?1 -m "this is a test" -ackwait 10m
128 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.5 Alternative Signboard Setup (DeviceSubtype=1)
The previous section focused on installations in which TelAlert controls signboard message display.
In this section, we’ll discuss configuring TelAlert to let another application control the signboard.
With this alternative setup, the signboard will display a fixed number of continuously updated
messages from the controlling application. Typically this approach is used in call centers to display
status messages, such as current hold time, number of calls waiting, and number of calls in
progress.
As with the standard signboard setup, you must define [Port] and [Configurations]
definitions. Then you will use TelAlert to perform some additional firmware initialization. Finally,
you can either create a separate [Destinations] definition for each message, or configure the
controlling application to include the necessary signboard control codes in the message.
10.5.1 Signboard [Port] Definition when DeviceSubtype=1
Complete the tasks described in the “Initial Signboard Firmware Setup” section of “Setting up
Electronic Signboard Notification” above before proceeding with the instructions in this section.
The [Port] definition when DeviceSubtype=1 is almost identical to the one described above in
“Standard Signboard Setup (DeviceSubtype=2).” The only differences are that you can leave
out the AlphaAddresses keyword entry, and you must set the DeviceSubtype value to 1 to
enable signboard message control by the other application:
[Port]
...
{SignboardPort}
...
DeviceSubType=1
...
10.5.2 Signboard [Configurations] Definition when DeviceSubtype=1
As with a standard signboard setup, normally you will create only one [Configurations]
definition for each signboard [Port] definition. Multiple signboards that share the same port can
share the same [Configurations] definition by referencing it in individual [Destinations]
definitions.
For a DeviceSubtype=1signboard, you need only the following keywords:
Configuration
...
{SignConfigST1}
Type=Device
DeviceSubtype=1
Mailbox=...
Device and DeviceSubtype should be set as shown. See the “Signboard [Configurations]
Definition” section of “Standard Signboard Setup (DeviceSubtype=2)” above for instructions on
setting the Mailbox value. (The keywords MaxTextFiles, TextFilesFIFO,
TextFilesFIFOMinDisplayTime, and TextFilesEmptyMessagerelate only to TelAlert’s
control of signboard message display and are ignored when DeviceSubtype=1.) Note that when
Chapter 10: Configuring for Other Notification Media | 129
DeviceSubtype=2, TelAlert will not give you an error message if you provide the wrong
Mailbox value.
After you’ve saved this new definition, activate it by making TelAlert re-read its configuration file.
You must activate the new definition before you can perform the following instructions.
10.5.3 Additional Signboard Firmware Setup when DeviceSubtype=1
With an alternative signboard setup, the next step is to create a separate virtual “file” in the
signboard’s memory for each of the continuously-updated messages you want it to display. You
must perform this step after creating the port and configuration definitions, as you will use them to
send a special file-initialization message to the signboard. As with setting the signboard’s serial
address, you should only need to do this once. (If you reconfigure the signboard to use
DeviceType=2, you will need to perform this step again to switch back to DeviceType=1.)
First, make sure that the {AlphaAllocateTextFiles} definition exists and is set active in TelAlert’s
[Message] section. If not, create it, as follows:
[Message]
...
{AlphaAllocateTextFiles}
Device=’E\x24${Parm1}’
The next step is to send a special message to the configuration you just created that contains the
control codes necessary to set up the virtual files. The syntax is:
telalertc -c signconfigst1 -mailbox ?? -mi AlphaAllocateTextFiles control_codes
Programming control codes is a tedious process, but assuming you need to rotate no more than six
messages of no more than 255 characters each, you can use the following command:
telalertc -c signconfigst1 -mailbox ?? -mi AlphaAllocateTextFiles AAL00FFFFFEBAL00FFFFFECAL00FFFFFEDAL00FFFFFEEAL00FFFFFEFAL00FFFFFE
That last bit is a run-together series of six 11-character control strings, each of which creates a
virtual file. The first letter of each control string is the name of the virtual file, so the six virtual
files this command creates are named A through F. (Instead of retyping this cumbersome string,
you can simply copy it from the PDF version of this manual.)
If you need more or longer messages, you will need to write your own custom control-code string.
Here is the syntax:
� character 1: single-letter virtual file name
� character 2: A (tells signboard you are defining a text file)
� character 3: L (disables remote control; replace with U to enable)
� characters 4-7: hexadecimal number indicating file size in bytes (00FF = 255)
� characters 8-11: FFFE (tells signboard not to control display with its internal clock)
130 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Create a separate 11-character control string for each virtual file you want to create, run them all
together without spaces, and use the command above to send the whole mess to your signboard.
(Using that syntax to interpret the sample command, the signboard reads AA (create file A), L
(disable remote control while displaying file). 00FF (allocate 255 characters to file), FFEE (display
regardless of current time), BA (create file B), and so on until it has created all six virtual files.)
By default, the signboard displays each file for an equal length of time. If you do not use all six
files, you can use the AlphaTextFileSequence [Message] definition to change the display.
First, make sure that the AlphaAllocateTextFilesdefinition exists and is set active in
TelAlert’s [Message] section. If not, create it, as follows:
[Message]
...
{AlphaTextFileSequence}
Device=’E.SL${Parm1}’
Then use the following command to tell the signboard which files to display:
telalertc -c signconfigst1 -mailbox ?? -mi AlphaTextFileSequence list_of_file_names
For example, if you use only files A, B, and C, use the following command:
telalertc -c signconfigst1 -mailbox ?? -mi AlphaTextFileSequence ABC
You can also use AlphaTextFileSequence to make some messages display longer than
others. For example, to make message A display twice as long as B and C:
telalertc -c signconfigst1 -mailbox ?? -mi AlphaTextFileSequence AABC
10.5.4 Signboard [Destinations] Definitions when DeviceSubtype=1
See the “Signboard [Destinations] Definitions” section of “Standard Signboard Setup
(DeviceSubtype=2)” above for general instructions on creating signboard [Destinations]
definitions.
The only difference when DeviceSubtype=1 is that you may wish to specify the virtual-file control codes discussed in the preceding section in the MessagePrefix keyword value. Which
virtual file a TelAlert message is loaded into is determined by a two-character string of signboard
control codes. The control string’s format is:
A[file_name]
file_name is the single-letter name of the virtual file you want to hold the message. Thus, to put
a message into virtual file A, and have the signboard scroll it in red, you would use the following
string: AA
To put a message into virtual file B, you would use: AB
Chapter 10: Configuring for Other Notification Media | 131
This string must immediately precede the one discussed above in “Controlling Signboard Text Color
and Effects.” You can specify both strings in the MessagePrefix value of your signboard
[Destinations] definitions, put only the virtual-file string in MessagePrefix and have the
controlling application add the mode and color string at the command line, or have the application
that controls TelAlert specify both at the command line.
Specifying Virtual Files, Text Color, and Effects in [Destinations] Definitions
Here are four sample definitions that have all signboard control codes set in MessagePrefix.
With this approach, the controlling application does not need to send any control codes. (See
“Controlling Signboard Text Color and Effects” earlier in this chapter for instructions on setting the
display mode and color.) They send messages directed to them to virtual files A and B, and display
in red and green, as indicated by their names:
[Destinations]
...
{SignFileARed}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AA\x1B0a\x1C1’
{SignFileAGreen}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AA\x1B0a\x1C2’
{SignFileBRed}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AB\x1B0a\x1C1’
{SignFileBGreen}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AB\x1B0a\x1C2’
With those definitions, the following commands will send messages to two different virtual files:
telalertc -i signfileared -m "this goes to file A, in red" telalertc -i signfilebgreen -m "this goes to file B, in green"
-ackwait Not Required When DeviceSubtype=1
As reflected in the command examples above, there is no need to use -ackwait when
sending messages to a DeviceSubtype=1 signboard. Messages continue to display
until updated by another send to the same virtual file.
132 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Specifying Virtual Files in [Destinations] Definitions and Text Color and Effects at
the Command Line
Alternatively, you can set only the virtual file name in the MessagePrefix value, and pass the
control codes for text mode and color at the command line. This approach is useful if you want to
manage signboard virtual files within TelAlert, and have the controlling application control text
color, for example to switch status messages from green to red when conditions are abnormal.
First, create one [Destinations] definition for each virtual file you want to use. For example:
[Destinations]
...
{SignFileA}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AA’
{SignFileB}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AB’
{SignFileC}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’AC’
Then create a [Message] definition that will insert the parts of the mode/color control string that
are always the same. For example:
[Message]
...
{ModeColorMsg}
Device=’\x1B0${Parm1}\x1C${Parm2}${Parm3}’
When you invoke that definition at the command line with -mi, TelAlert replaces ${Parm1}, ${Parm2}, and ${Parm3} with the mode code, color code, and message. (See “Controlling Signboard Text Color and Effects” earlier in this chapter for instructions on setting the display
mode and color.) In other words, the syntax is:
telalertc -i SignFileA -mi ModeColorMsg mode_code color_code "message text"
With the above definitions, the following commands will cause the signboard to rotate among three
messages, with "average hold 2 minutes" and "14 calls in progress" in slowly-scrolling green text,
and "15 calls waiting" flashing red:
telalertc -i SignFileA -mi ModeColorMsg a 2 "average hold 2 minutes" telalertc -i SignFileB -mi ModeColorMsg c 1 "15 calls waiting" telalertc -i SignFileC -mi ModeColorMsg a 2 "14 calls in progress"
Chapter 10: Configuring for Other Notification Media | 133
Specifying Virtual Files, Text Color, and Effects at the Command Line
A third alternative is to specify the virtual file you want to receive a message at the command line.
When you use this method, you must also include the mode and color control codes at the
command line. (See “Controlling Signboard Text Color and Effects” earlier in this chapter for
instructions on setting the display mode and color.) Also, note that with this approach you must
use only destinations in which MessagePrefix is blank. For example:
[Destinations]
...
{Sign}
Configuration=SignConfigST1
Mailbox=’01’
Terminator=’’
MessagePrefix=’’
The first step is to create a [Message] definition that will insert the parts of the control string that
are always the same. For example:
[Message]
...
{Subtype1Msg}
Device=’A${Parm1}\x1B0${Parm2}\x1C${Parm3}${Parm4}’
When you invoke that destination at the command line with -mi, TelAlert replaces ${Parm1},
${Parm2}, ${Parm3}, and ${Parm4} with the virtual file name, mode code, color code, and
message. The syntax is:
telalertc -i sign -mi Subtype1Msg virtual_file_name mode_code color_code "message"
So, for example, the following commands will send to two different virtual files: telalertc -i sign -mi Subtype1Msg A a 1 "this goes to file A" telalertc -i Sign -mi Subtype1Msg B a 1 "this goes to file B"
10.6 Setting up Email Notification
Because the Internet is sometimes subject to delays, and because not everyone checks for new
email messages with the same frequency, email is not the most efficient or reliable notification
medium. It can be very useful, however, for low-priority messages. Also, some organizations set
up TelAlert so that every message sent via pager also is sent to the person’s email address. Used
in this way, email can serve as an effective means for backing up other media or for creating
records of messages that individual users may find valuable.
Setting up email notification involves creating a [Configurations] definition and one or more
destinations. The [Port] definition that will be referred to by the [Configurations] definition
probably already exists in your TelAlert configuration file.
You can have TelAlert use a provided helper application, called Readmail, to process responses to
email notifications. This is also useful in the case of two-way text paging services that are email-
based. For instructions on using Readmail, refer to the end of this section.
134 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.6.1 Email [Port] Definition
Under [Port], be sure that there is an {Internet} entry, that Activeis set to True, and that
one of the values listed for Types is Email. For example:
[Port]
...
{Internet}
Active=True
Model=Internet
Types=Email,TextPager,InteractiveTextPager
Model=Internet provides an additional link matching the [Configurations] definition,
below, to this [Port] definition. It also tells TelAlert which process to use in processing
notifications that invoke this [Port] definition.
10.6.2 Email [Configurations] Definition
The entry you create under [Configurations] provides the common information that TelAlert
needs to send email to your email destinations:
[Configurations]
...
{Email}
Type=Email
Model=Internet
Host=server.domain.com
Service=smtp
From=’[email protected]’
The Type and Model values link this [Configurations] definition to the correct port. Host
identifies the machine that you want to use to send email. For Service, smtp is your only choice.
You can also configure a backup email server, by adding AlternateHost and AlternateService keywords. The From line merely specifies the address that will appear in the “From” field in all emails sent by TelAlert.
The From Setting in an Email [Configurations] Definition
Setting the From value does not in itself make it possible to reply to messages sent by
TelAlert; to do this, the address entered here must be a valid one. Further, even if you set up
[email protected] on your mail server as a valid email address, sending mail to this
address is not a means of getting information into TelAlert.
Even if you do not mean to allow users to respond to TelAlert messages via email, you should
assign a valid email address to the From keyword, since many mail servers will not send email
without a valid “From” address. If you are interested in making it possible for users to respond
to notifications via email (i.e., to use email as a means of getting information into TelAlert),
you will need to use the provided Readmail program, which is governed by the [Process]
section. For more information information, see Handling Responses to Email With Readmail later in this section.
Chapter 10: Configuring for Other Notification Media | 135
10.6.3 Email [Destinations] Definition
An email destination must point to the [Configurations] definition you create for sending email
notifications. In addition, it contains the name of the recipient and that person’s complete email
address:
[Destinations]
...
{CynthiaEmail}
FullName=’Cynthia Jasper’ Configuration=Email
To=’[email protected]’
Once your [Port], [Configurations], and [Destinations] definitions are all set up, you can
send notifications to the destination on the command line, like so:
telalertc -i CynthiaEmail -m "this is a test"
Generally, you will not attach an -ackwait value to email notifications, though you certainly may
want to use -ackwait if you are sending a message via email and another medium at the same
time.
By default, TelAlert leaves the email subject line blank. You can specify a subject by adding a
Subject keyword value to the relevant [Configurations] or [Destinations] definition, or by
using the -subject command-line option. For example:
telalertc -i CynthiaEmail -m "this is a test" -subject "test message"
10.6.4 Using Email as a Backup Notification Medium
If you want all messages that you send to a person’s pager (for instance) to go also to this
person’s email address, you must combine the email destination and the pager destination in a
group and direct messages to this group, instead of an individual destination. For instance:
[Group]
...
{Cynthia}
Destinations=’"CynthiaTextPager","CynthiaEmail"’
By issuing the following command—
telalertc -g Cynthia -m "this is a test" -ackwait 15m
—you could send a message to {CynthiaTextPager} and {CynthiaEmail} simultaneously.
By associating the pager destination with a schedule and assigning no schedule to the email
destination, you could ensure that Cynthia would receive a record of all relevant alerts, even those
that occurred when, according to her pager schedule, she was off-duty.
In TelAlert 6e, the same effect is usually accomplished by including Cynthia as a User in a Group,
rather than her individual Devices.
136 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.6.5 Handling Responses to Email With Readmail
TelAlert comes with a email-reading program (readmail, or readmail.exe for Windows) that closes
the loop in email-based notifications, allowing TelAlert to accept and process replies. This includes
replies to messages sent straightforwardly as emails and replies to certain two-way pager
notifications (PageNet and WebLink Wireless) that take the form of emails.
To use Readmail, you must activate and edit the {POPClient} definition found in a new section,
called [Process], in the TelAdmin interface. This definition is responsible for starting Readmail
whenever TelAlert is started, and for setting the parameters that govern Readmail’s behavior.
{POPClient} Settings
Following is an example {POPClient} definition.
[Process]
...
{POPClient}
Active=False
Shell=""
Command=${TelAlertBin}/readmail ${EventData} -name ${Definition} -file POPClient.log -back POPClient.%Y%m%d%H%M -sleep 30 -host 127.0.0.1-service 110 -user <User> -password <Password> -send -ack -reply -request Start=${TimeStamp} Start Reset=${TimeStamp} Reset Status=${TimeStamp} Status Control=${TimeStamp} Control ${Message} Switch=${TimeStamp} Switch Stop=${TimeStamp} Stop
Active—Determines whether the definition is active. You must set this to True to use Readmail.
Shell—The shell to which TelAlert should pass the specified Command value. The value should be a
fully qualified reference, as the user’s PATH will not be used. When the Command value is not a
shell command (as is normally the case in Windows), the Shell value should be blank.
Command—The command TelAlert should issue whenever it (TelAlert) is started. This command
launches Readmail and sets the parameters that govern its behavior. TelAlert issues this command
only if Active=True.
The value assigned to this keyword in the template is comprised of a number of command line
options. -name ${Definition} invokes the name of the current [Process] definition. –file is used to specify a log file. –back is used to specify a naming convention for backup copies of this file. -sleep determines how often Readmail checks for new mail. -host, -service, -user, and
-password provide the information Readmail needs to connect to the POP host. Finally, the presence of -send, -ack, -reply, and -request determine what email messages it processes (specifically, messages that, based on their subject line, are intended to ack or nak a notification
(-ack, -nak), reply to a notification (-reply), send a new message via TelAlert (-send), or
submit a “request” (-request).
Chapter 10: Configuring for Other Notification Media | 137
Readmail 1.13, build 20021014 or later, includes an -ignore command line option that is to be
used in conjunction with -response.
Without -ignore:
-response expects the Subject line to be in the format:
Re: <SendId> <Reply>
where <Reply> will be string-matched against the list of replies contained in the -response
definition specified in the original command (the command that initiated SendID). If <Reply> is
null on the Subject line, then the first line of the message body will be taken as <Reply> and string-matched instead.
With -ignore:
-response expects the Subject line to be in the format
Re: <SendId> <whatever>
and the first line of the message body to be:
<Reply>
The <Reply> will be string-matched against the list of replies contained in the -response
definition and will always be taken from the first line of the message body. Any text that follows
<SendId> on the Subject line will be ignored.
Start, Reset, Status, Control, Switch, Stop—These keywords allow you to specify the commands to be passed to Readmail whenever the associated keyword is used on the
command line. Readmail understands a set of commands identical to this set of keywords (i.e.,
start, reset, status, control, switch, and stop), but they still must be set explicitly. Note that only
one of these, Control, is designed to allow you to pass more than just a command: to the value
of Control you can append data, either explicitly or using a substitution parameter. (In the case
of other helper applications, these keywords may be assigned other values, depending on the
commands these applications have been designed to accept.)
Readmail Logfile and Rollover Logfile
The names of the readmail logfile and rollover logfile are controlled by the -file and -back
parameters on the readmail command line:
[Process]
...
{POPClient}
...
Command=${TelAlertBin}/readmail ${EventData} -name ${Paragraph} -file POPClient.log & -back POPClient.%Y%m%d%H%M -size 50000 -time 01:00 -dayofweek 0 ...
138 | TelAlert 6e™ Administrator Guide - Version 6.1.29
If –file or -back are not specified, the built-in defaults are those shown above. In the example
for the -back filename, the ’%’ parameters are replaced at file creation time as follows:
%Y: 4-digit year %m: 2-digit month (01-12) %d: 2-digit day of month %H: 2-dight hour, 24 hour clock %M: 2-digit minute
A rollover filename will look like:
POPClient.200211260915
This allows keeping each rollover file separate, instead of having the rollover files overwrite each
other. However, there is a need to adopt some plan to archive off old rollover files. If you use
-back POPClient.bak, then the rollover files will overwrite each other.
You may include a file path in –file or -back, but the file path is relative to the path given by
telalertdir. (Also note that it’s telalertdir, not telalertbin/cfg/tmp). For example,
if you have -file /logfiles/POPClient.log, and telalertdir is /var/opt/telalert, then the fully-qualified file location will be
/var/opt/telalert/logfiles/POPClient.log.
Regarding the other logfile-related parameters:
� -size -50000 means that when the logfile reaches 50,000 bytes, it will be renamed to the
-back filename and a new logfile created with -name. To disable switching on logfile size,
omit the –size keyword (do not use -size 0).
� -time -01:00 means that the logfile will roll over to -back at 1AM. Whether it rolls over
daily or weekly depends on the value of -dayofweek. If the -time keyword is omitted,
the logfile will not roll over based on time of day.
� -dayofweek -if this keyword is specified, the logfile will roll over weekly at -time; if it is
not specified, the logfile will roll over daily at -time. The value following -dayofweek
indicates which day the weekly rollover will occur; 0=Sunday, 1=Monday, ...
6=Saturday.
MIR3 does not recommend omitting both –size and -time. If you do, then the logfile continues
to grow until the disk runs out of space. If you decide to specify both –size and -time, MIR3 recommends setting -size to a fairly high value, so that most rollovers will occur due to -time,
but if you get a sudden influx of log entries, the -size will prevent the logfile from growing to
excess size.
Readmail in Action
If the [Process] definition governing it is set to Active=True, Readmail runs when TelAlert is
started. Based on the settings found in the above example, Readmail will check mail at the
designated email address every thirty seconds. It will process emails that have been formatted to
ack, nak, or reply to TelAlert notifications. It will also process emails that have been formatted to
send notifications through TelAlert or to submit “requests” (refer to the discussion of requests in
Chapter 8: Configuring for Paging Notification).
Chapter 10: Configuring for Other Notification Media | 139
Readmail recognizes emails that it should process by parsing the subject line. Based on what it
finds there, it generates and executes an appropriate TelAlert command. Details regarding the
recognition and processing of particular kinds of emails are presented below. In most cases, users
must understand what kind of subject line Readmail looks for, in order to send an email that is
formatted appropriately.
Sending Messages—Readmail recognizes an email intended to generate a TelAlert send by the
presence (in the first line of the message’s subject line) the name of a TelAlert [Destinations]
or [Group] definition. The subject line should take the form:
destination_name
or, in the case of sends to a group:
group: group_name
The body of the email message (up to TelAlert’s configured maximum message length) will be used
as the message text.
After processing such a message, Readmail deletes it.
Acting on Outstanding Sends—Readmail recognizes an email intended to act on a TelAlert
notification by the presence of certain “magic” words in the subject line:
Ack N AckHold N Nak N Clear N Release N
In each case, N is the numeric send ID of the message to be acted upon. The body of the email
message is ignored. After processing such a message, Readmail deletes it.
Replying to Messages—Readmail recognizes emails intended to provide a canned reply to a
TelAlert notification based on the presence of Re: SendID in the subject line, where SendID is
the numeric send ID of the message to be replied to.
The body of the email provides the data that Readmail passes as the reply. It does so using this
command:
telalert -reply SendID Data
After processing such a message, Readmail deletes it.
Submitting Requests—Readmail recognizes emails intended to generate a request based on the
presence of Request: Name in the subject line, where Name is the name of the [Notifications] definition that should be used to process the request.
The body of the email provides the data that Readmail passes as part of the request. The email’s
“From” information is used to return a response to the original sender; it is passed to TelAlert using
the -replyto command line option. The entire TelAlert command takes this form:
telalert -request "Name|Data" -replyto "From_Info"
After processing such a message, Readmail deletes it.
140 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.7 Setting Up SpectraLink LCD Notification
SpectraLink’s Link system is a wireless equivalent of a PBX telephone system, and is often
integrated with conventional PBXes. You make calls within the system by dialing an extension
number, and such calls incur no telephone-company or cell-phone charges.
In addition to their standard telephone capabilities, the Link handsets include an LCD, which may
be used to display text messages. If you connect a SpectraLink Open Applications Interface (OAI)
Gateway—a modem-like box—to a TelAlert server, you can send messages to those displays,
exactly as you would to one-way text pagers.
To set up SpectraLink LCD notification, you must define a [Port] definition, a
[Configurations] definition, and [Destinations] definition for each handset to which you
wish to send text messages. To set up voice notification for the handsets, refer to Chapter 3 of the
TelAlert Voice and Hardware Guide. (The definitions used for LCD and voice notification are
completely independent.)
Contact SpectraLink for information about the OAI Gateway. See your SpectraLink documentation
for instructions on configuring handsets to use a distinctive ring pattern to indicate reception of a
text message.
10.7.1 SpectraLink LCD [Port] Definition
The [Port] definition tells TelAlert how to communicate with the OAI Gateway.
[Port]
...
{SpectraLink}
Active=True
Model=Device
Types=Device
DeviceSubtype=3
SoftwareParity=False
Dev=COM5:
Speed=9600
The Dev setting must indicate the Windows COM port or UNIX device file for the serial port to
which the OAI Gateway is connected. The other settings must be as shown. (DeviceSubtype=3
is the setting that lets TelAlert know that the device is an OAI Gateway.)
10.7.2 SpectraLink LCD [Configurations] Definition
The [Configurations] definition links the handsets’ [Destinations] definitions with the
gateway’s [Port]definition. Only the following settings are required, though you may add other
keywords, such as Priority, Schedule, or AcknowledgeWait, if appropriate.
[Configurations]
...
{SpectraLink}
Type=Device
DeviceSubtype=3
Chapter 10: Configuring for Other Notification Media | 141
10.7.3 SpectraLink LCD [Destinations] Definitions
The [Destinations] definitions provide TelAlert with the mailbox addresses of the handsets’
LCD displays. A handset’s mailbox address is the same as its extension number.
[Destinations]
...
{SpectraLink422}
Configuration=SpectraLink
Mailbox=422
{SpectraLink423}
Configuration=SpectraLink
Mailbox=423
If you configure both LCD and voice notification for the handsets, you should establish a naming
convention to make it easy to tell the two destinations apart. For example, you might use
{SpectraLinkVoice422} to send voice messages to extension 422, and
{SpectraLinkText422} to send text messages to that handset’s LCD.
10.8 Setting up Command Line Notification
You can set up TelAlert so that it carries out certain notifications by issuing a command that will
trigger a script or other application. Such a setup requires creating a [Configurations]
definition and a destination only; no [Port] definition is required.
10.8.1 Command-Line [Configurations] Definition
The [Configurations] definition serves primarily to identify the notification’s Type, which is
different from all other Type values in that it does not link to a port. If you want to use a shell to
run the command, you can specify it here.
[Configurations]
...
{Sound}
Type=Command
Shell=""
10.8.2 Command-Line [Destinations] Definition
The destination invokes the [Configurations] definition to be used and provides a range of
information specific to the notification, including the path to the application to be run and (where
needed) the path to any file the application will use.
[Destinations]
...
{Sound}
Configuration=Sound
Command=c:\WINNT\system32\mplay32.exe /play /close c:\WINNT\Media\${Message}
142 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Here, Command specifies:
� the path to the Windows Media Player
� additional instructions for this application—so that it closes after executing the command
� the path to the .wav file that the application is to play
Note that the actual .wav file is not specified. This command destination is set up so that the file can be supplied on the command line as the notification’s message, like so:
telalertc -i sound -m ding.wav
TelAlert replaces ${Message} with the command line string following the -m. If you wanted the same sound to be played for every message, you could specify the file directly in the destination, in
place of ${Message}. If you do this, you still must provide some message value on the command
line. For example:
telalertc -i sound -m ,
10.8.3 Applications for Command-Line Notification
Obviously, TelAlert’s command line notification feature has a wide range of applications, ranging
from the very simple (as shown by the above example) to much more sophisticated solutions
involving customized scripts and/or third-party programs.
For instance, if a process running on a machine on your network occasionally dies and requires
restarting, and if you have a means for getting word of its death to TelAlert, you could set up a
command line notification that would enable TelAlert to restart the process on its own. If
successfully restarting the process involved a series of commands, you could create a script that
TelAlert would invoke, passing all needed information in the command line message.
Perhaps you want TelAlert to restart the process but also to notify a support employee that the
process died. In this case, you could create a group consisting of the {Restart} destination and a
pager destination. The recipient of the page would know that TelAlert had issued the command to
restart the process; he or she could then take whatever steps necessary to make sure that the
process was in fact up and running.
Even the simple example of having TelAlert play a sound can be the core of a sophisticated notification
strategy. Imagine that, in a send to a group involving escalation, you want TelAlert to play a sound
each time the message is sent to another destination—thus providing the help desk coordinator with an
audible update of the alert’s progress. To do this, you would group each pager destination with a
suitable “sound” destination and build your main group out of these subgroups, like so:
[Group]
...
{MainSupport}
Destinations=’"DavidPager,DavidSound","JohnPager,JohnSound", "CynthiaPager,CynthiaSound"’
In this example, three different “sound” destinations are being invoked, each associated with a
different sound file. These could be files you build yourself to read aloud messages corresponding
to each user: e.g., “David is being paged,” “John is being paged,” etc.
Chapter 10: Configuring for Other Notification Media | 143
10.9 POPUP Message Boxes on Windows
Windows includes net send functionality that allows “popping up” a message box on a networked PC. Although it is possible to create a TelAlert “Command Configuration” to invoke the net send command, it is simpler to use TelAlert's built-in Protocol=WINPOP access to the functionality.
The following illustrates a Winpop example:
[Configuration]
{Winpop}
Type=TextPager
Model=Internet
Protocol=WINPOP
From="TelAlert"
[Destination]
{GeorgeWinpop}
Configuration=Winpop
To=GeorgeDesktop
telalertc -c Winpop -To GeorgeDesktop -m "Here’s a popup" telalertc -i GeorgeWinpop -m "Here’s another popup"
Note that when using -c Winpop, you use -to, not -PIN. Also notice that the To/-to value must be a DNS name; it cannot be an IP address. Also notice that From= is supported and is
included in the text displayed in the popup.
TelAlert does not support an equivalent to this popup functionality on UNIX, because of the variety
of window managers and networking protocols. If you know that a particular utility providing this
functionality is installed at your site, a “Command Configuration” can be used. The following is an
example if the smbclient utility is installed:
[Configuration]
{smbclientpop}
Type=Command
Shell="bin/sh -c" Command="smbclient -M ${PIN} -U TelAlert" Acked=252
PINRequired=True
WriteExecsToTrail=False
telalertc -c smbclientpop -PIN GeorgeDesktop -m "UNIX popup"
This UNIX “Command Configuration” example should be crossreferenced from the topic on
command configurations, since otherwise all of the command configuration examples are for
Windows.
In TelAlert release 5.0 and earlier, Type=Email was required with Protocol=WINPOP; in 5.1
and later, Type=TextPager is required instead.
144 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.10 Sending Text Messages to Other Systems
You can have TelAlert send messages to other systems, including UNIX syslog processes,
TelaConsole running on an Windows machine, and AS/400s.
10.10.1 UNIX Syslog Processes
To send messages from TelAlert to a UNIX machine's syslog process, you use a
[Configurations] definition of Type=TextPager. Here, Protocol should be set to Syslog. Service and Host should be set appropriately. "Facility code" and "priority" information required by syslog is passed as the PIN value, typically either on the command line (using -pin) or in a
[Destinations] definition (using the PIN keyword). The format for this information is
facilitycode.priority, where facilitycode is a number between 0 and 127, inclusive,
and priority is a number between 0 and 7, inclusive.
10.10.2 TelaConsole
To send messages to TelaConsole, you also use a [Configurations] definition of
Type=TextPager. Here, Protocol should be set to TelaConsole. Service and Host
should also be set appropriately. If you choose, you can provide "Facility code" and "priority"
information just as with the Syslog protocol—i.e., passed as the PIN value, typically either on
the command line (using -pin) orin a [Destinations] definition (using the PIN keyword). The
format for this information is facilitycode.priority, where facilitycode is a number
between 0 and 127, inclusive, and priority is a number between 0 and 7, inclusive.
10.10.3 AS/400s
To send messages to an AS/400, the AS/400 must have the appropriate software installed on the
AS/400. This is called QSYSOPR, available from Patrick Townsend Associates.
Sending messages to an AS/400 also involves a [Configurations] definition of
Type=TextPager in which Protocol should be set to QSYSOPR. Service and Host should also be set appropriately. The Access keyword, set in the same [Configurations] definition, is used to pass login information to the AS/400. The To keyword, typically set in a [Destinations] definition, allows you to specify the queue in which the message should be
placed. Alternatively, you can use the –to tag on the command line.
Chapter 10: Configuring for Other Notification Media | 145
10.11 Sending Text Messages to Web-Enabled Phones
You can send messages to cellular telephones equipped with a Phone.com microbrowser. The
information TelAlert first passes to the telephone is the URL for the TelAlert Web client—typically, a
qualified URL (expressed using ${SendID}) where the recipient can go to read the actual
message.
A typical [Configurations] definition looks like this:
{NextelUPNotify}
Type=TextPager
Protocol=UPNOTIFY
Host=atlsnup2.adc.nexteldata.net
Service=4445
Subject=ALERT-${SendID}
ReplyTo=http://www.company.com/cgi-
bin/telalerths?sendid=${SendID}
Type must be set to TextPager, and Protocol must be set to UPNOTIFY. The Subject
value is the message that will first show up in the recipient’s browser. The ReplyTo value is the URL to which the recipient’s browser will be directed when the recipient “reads” the message from
TelAlert.
A [Destinations] definition simply points to the [Configurations] definition and provides a
PIN, which is the telephone’s subscriber ID, not the telephone number:
{NextelUPN}
Configuration=NextelUPNotify
PIN=123456789-09876
Microbrowser-equipped telephones can also initiate interactions with TelAlert by browsing to the
URL of the TelAlert Web client.
The Web client (telalerth) that ships with TelAlert will automatically recognize microbrowsers
and present information in a form they can handle. For information on customizing the Web client’s
interactions with microbrowsers, and with browsers of all kinds, refer to Setting up the TelAlert
Web Clients in Chapter 17.
146 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.12 Sending Text Messages to Nextel Cellular Phones
TelAlert supports two-way text messaging with Nextel cellular telephones equipped with text
screens. This messaging is email-based.
Sending notifications requires a [Configurations] definition of
Type=InteractiveTextPager where Protocol=SMTP. A special keyword must be used:
ProtocolMask=4. This ensures that all reply options attached to the send are formatted
according to Nextel’s requirements. Finally, you should set AddSendIDtoMessage to True. This allows replies to the message to be linked to the original send and processed properly. Here is a
typical [Configurations] definition:
{NextelSMTPTwoWay}
Type=InteractiveTextPager
Protocol=SMTP
Host=messaging.nextel.com
Service=smtp
ProtocolMask=4
To=${PIN}@messaging.nextel.com
AddSendIDToMessage=True
PINRequired=True
A [Destinations] definition typically contains only a reference to the [Configurations]
definition and a PIN value (the telephone number):
{NextelPagerSMTP}
Configuration=NextelSMTPTwoWay
PIN=5105551212
To process responses to messages sent by this means, you should use the Readmail helper
application. For information on configuring Readmail, refer to Handling Responses to Email
With Readmail earlier in this chapter.
Certain two-way paging services (PageNet, WebLink Wireless, Verizon) support email-based two-
way messaging as well. There is generally little reason to send messages to two-way pagers by this
means, but it can be done, as described above. The ProtocolMask value must be set
appropriately, based on the requirements of each of these service providers. For PageNet, WebLink
Wireless, and Verizon, use a value of 1.
Chapter 10: Configuring for Other Notification Media | 147
10.13 Sending One-Way Text Messages to GSM Cellular
Telephones Modem
TelAlert allows you to send one-way text messages to GSM cellular telephones. Here is a sample
[Configurations] definition:
{Europolitan}
Type=InteractiveTextPager
Model=Internet
Protocol=CIMD2
ProtocolMask=0
ServerPIN=1234567890
Access=ID:password
Host=123.45.67.8
Service=9972
TextPagerWait=30s
ConfirmDelivery=True
PollRequests=True
ProcessCharacterEscapeCodes=True
QuoteControlCharacters=False
StripControlCharacters=False
$include CharMap.gsm
The [Destinations] definition typically does nothing more than point to the
[Configurations] definition and provide a PIN value:
{JeanTextMessage}
Configuration=Europolitan
PIN=phonenumber
To help users work with variations in the characters supported by GSM service providers, TelAlert
offers a character mapping feature, documented in the discussion of the CharMap keyword under
[Configurations] in Chapter 2 of the TelAlert Keyword and Command Reference. In the
above [Configurations] example, this keyword and its value are provided by reference to an
outside file, CharMap.gsm.
148 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.14 Sending Two-Way Text Messages to SMS Mobile
Telephones Via a GSM Wireless Modem
Used with a GSM wireless modem, TelAlert can send text messages directly to SMS mobile phones.
10.14.1 Set-Up During Installation
TelAlert has two techniques for handling GSM wireless modems.
The first technique was introduced in TelAlert 5.2. A combination of existing core program options
provided functionality to send messages using GSM wireless modems (the existing options were
Protocol=Chat, etc.) To handle receiving GSM messages, a “helper” program, GSMPoll, was
added; GSMPoll does have specific GSM support. This technique uses three TelAlert definitions:
1. A [Port] definition of Model=DirectModem
2. A [Configuration] definition of Type=TextPager,Protocol=Chat
3. A [Process] definition invoking the GSMPoll helper program.
One-way pages, and the outgoing part of two-way pages, are sent out via the [Port] and
[Configuration]. Responses to two-way pages come back via the [Process]; if only one-way
paging is used, the [Process] is not required.
For simplicity, in the sample definitions, the name {GSMModem} is used for the [Port] and [Configuration], and the name {GSMPoll} was used for the [Process]. These specific
names are not required; any names can be used, as long as all references to the names are
properly updated.
10.14.2 New Technique in TelAlert 5.4
A second technique was introduced in TelAlert 5.4. The “core” TelAlert programs (telalertm,
etc.) have been made “aware” of GSM wireless modems, and new program options have been
added (ModemSubtype=2,Protocol=GSM), so that the GSMPoll “helper” program is no longer
needed. This technique uses two TelAlert definitions:
A [Port] definition of Model=Modem, ModemSubtype=2
A [Configuration] definition of Type=InteractiveTextPager, Protocol=GSM
These definitions are used for both one-way and two-way paging; no [Process] is used. Again for
simplicity, the samples use the name {GSMModem} for both the [Port] and the
[Configuration], but any names can be used.
TelAlert 5.6 supports both techniques; existing GSM wireless modem users that upgrade from 5.2
to 5.4 will continue to use the older technique. If a GSM modem [Port] is defined during a new
installation of 5.4, the installer will set up a [Port] and [Configuration] using the newer
technique.
Chapter 10: Configuring for Other Notification Media | 149
10.14.3 Differences Between the Two Techniques
For one-way paging, there are not any significant pros or cons for either technique.
For two-way paging, there are some pros and cons.
First, the older technique involves having two different processes access the modem for two-way
paging (telalertm and gsmpoll). Although generally these processes share the modem
correctly, there were a few special problem situations in 5.2 (these have been addressed in 5.4);
also, the constant opening and closing of the modem port involves some overhead. The newer
technique only has one process (telalertm) access the modem.
Second, the older technique does not support custom [Response] lists. The SMS replies must be
in one of two forms:
Option SendID
or
SendID Option
where “Option” is one of Ack, Nak, Hold, Clear, Release.
The newer technique requires that a custom [Response] list be specified on the command line.
The newer technique's SMS replies must be in the form
SendID response
where “response” must be one of the responses specified on the original command (for instance, if
the original command contained the specification
-response basic
then response must be one of Yes, No, Hold, Info, Release, or Ping). Note that these “basic
responses” are not the same as the “options” for the older technique. To facilitate upgrading, a new
set of responses has been created -- refer to {GSMResponse} below. However, even with these responses, the newer technique requires SendID before the response; the older technique would accept SendID either before or after the option. Also, there isn't any newer response equivalent for the older “clear” option; this shouldn’t be a problem because “clear” is normally used when
nobody has responded, rather than as a response option in itself. These new responses would be
invoked by including
-response GSMResponse
on the telalert(c) command line.
150 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.14.4 Samples for Both Techniques
Example definitions for the older technique:
[Port] {GSMModem}
#A. Model=DirectModem because no ’dialing’ is needed to connect to # the service provider #B. Types=TextPager since only outgoing is handled by [Port] {GSMModem}; # incoming responses are handled by [Process] {GSMPoll} #C. Share=True to allow [Process] {GSMPoll} access to the modem #D. Class=1 to link with [Configuration] {GSMModem} #E. No Modem= value needed since no brand/model-specific commands are used Active=True
Model=DirectModem
Types=TextPager
Dev=<<dev>>
Speed=<<speed; some modems are 9600-only, others are 19200-only>> Share=True
Class=1
[Configuration] {GSMModem}
#A. Type=TextPager to link with [Port] {GSMModem} #B. Model=DirectModem to link with [Port] {GSMModem} #C. Protocol=Chat to allow imbedding ’AT’ commands specific to GSM # wireless modems in this configuration, since the ’core’ telalertm # executable is not aware of them #D. ChatLogon,ChatScript,ChatLogoff -- see Protocol=Chat above #E. Class=1 to link with [Port] {GSMModem} Active=True
Type=TextPager
Model=DirectModem
Speed=<<speed; some modems are 9600-only, others are 19200-only>>
Protocol=Chat
PINRequired=True
Parity=None
MaxMessageLength=160
MaxMessagesPerCall=1
Note on Using these Samples with the TelAdmin Import Function
If the following sample definitions are used with the TelAdmin Import function, be aware
that lines that require customization to a particular customer’s values, such as
Dev=<<dev>>
will not import as-is. There are two choices:
1. Edit these lines before copying to the clipboard.
2. The import function will give errors for lines that can’t be imported; make a note
of these lines and set the appropriate keyword values via the main TelAdmin panel.
Chapter 10: Configuring for Other Notification Media | 151
#ChatLogon=’"" \EAT+CMGF=1 OK’ #ChatScript=’"" \EAT+CMGS="\P" > \M\x1A\c OK’ #ChatLogon=’"" \EAT+CMGF=0 OK’ ChatLogon=""
ChatScript=’"" \EAT+CMGF=1 OK \EAT+CMGS="\P" > \M\x1A\c OK’ ChatLogoff=""
Class=1
[Process]
{GSMPoll}
# See notes for details on the Command= line Active=True
Shell=""
Command=${TelAlertBin}/gsmpoll "${EventData}" -name ${Paragraph} & -file gsmpoll.log -back gsmpoll.%Y%m%d%H%M -size 50000 & -dev COM6 -speed 9600 -parity none & -sleep 30 -debug 0 Start=${TimeStamp} Start Reset=${TimeStamp} Reset Status=${TimeStamp} Status Stop=${TimeStamp} Stop
Set Speed= to the modem’s correct speed setting (9600 for most GSM modems; because the
trailing 0 is optional, 960 is equivalent to 9600). To determine the speed of the modem (and check
the availability of the port), use testcomm, a utility included with TelAlert. Use this command line:
testcomm mg device speed
Substitute the port name for device. For speed, begin with 9600 and try other speeds (1200, 2400,
19200, 38400)as necessary. Both values must be correct to get a response from the modem.
When finished, save and implement your changes. This definition is now ready for you to use,
either with or without a [Destinations] definition pointing to it.
The following comments describe the Command= line options in [Process] {GSMPoll}:
The client polls the directly-connected GSM modem for incoming SMS messages.
The command line options are:
-file Name
The log file will be named Name. Default value is readmail.log
-back Name
The backup log file will be named Name. Default value is readmail.%Y%m%d%H%M. Both Names
are passed through strftime (). Common substitutions are:
� %Y: 4-digit year
� %m: 2-digit month (1-12)
� %d: 2-digit day of month
� %H: 2-dight hour, 24 hour clock
� %M: 2-digit minute
152 | TelAlert 6e™ Administrator Guide - Version 6.1.29
-size n
When the log file reaches n bytes, the backup log file is removed, the log file is renamed to the
backup log file and a new log file is created. By default, the log file is not switched based on size.
-time hh:mm
When the time passes hh:mm (24 hour clock), the backup log file is removed, the log file is
renamed to the backup log file and a new log file is created. By default, the log file is not switched
based on time.
-dev <device>
This is the Device where your GSM modem has been connected. This should match the Dev= value in one of your [Port] section definitions. The [Port] definition with this device specification must
have Share=True set.
-speed <speed>
The speed of the GSM modem. This should match the Speed= value in one of your [Port] section
definitions.
-sleep N
The number of seconds between poll checks. The default value is 30.
-debug N
Debug level. Set to 1024 to have modem interaction written to log file (-file)
Example definitions for the new technique:
[Port]
{GSMModem}
#A. Model=Modem and ModemSubtype=2 to invoke new ’core’ code that # is specific to GSM wireless modems; ModemSubtype=2 also links # to [Configuration] {GSMModem} #B. Modem=xxx_GSM required when Model=Modem #C. Share=True not required since GSMPoll no longer used #D. Class=1 no longer needed; [Configuration] {GSMModem} linked # by ModemSubtype=2 Active=True
Model=Modem
ModemSubtype=2
Types=TextPager,InteractiveTextPager
Modem=<<[Modem.xxx_GSM]>>
Dev=<<dev>>
Speed=<<speed; some modems are 9600-only, others are 19200-only>>
[Configuration]
{GSMModem}
Chapter 10: Configuring for Other Notification Media | 153
#A. Set Type=TextPager for one-way, InteractiveTextPager for two-way #B. Protocol=GSM enables hard-coded GSM ’AT’ modem commands in telalertm #C. ModemSubtype=2 links to [Port] {GSMModem} #D. ProtocolMask setting depends on service provider; try 0 first, then 1, then 2 #E. Set AddSendIDToMessage True for two-way, either True or False for one-way {GSMModem}
Active=True
Type=InteractiveTextPager
Protocol=GSM
Speed=<<speed; some modems are 9600-only, others are 19200-only>> ModemSubtype=2
MaxMessagesPerCall=1
PINRequired=True
PollRequests=False
# ProtocolMask::= 1 -> Send in Text Mode; 0 -> PDU mode # ProtocolMask::= 2 -> Send as Flash Message; 0 -> Normal Message # Note: Flash messages must be sent in PDU mode - e.g. a value of 3 # won’t work. ProtocolMask=0
AddSendIDToMessage=True
[Response]
{GSMResponse}
# Used to have the newer 5.4 GSM two-way responses look similar to the # older 5.2 GSM two-way responses. The older ’clear’ response is # not supported in the newer method. # TelAlert matches on case-INsensitive leading substring. For instance, since
# Reply2=Nak, then the following will match: ’N’, ’NA’, ’nak’, and ’NAK’. But # ’NO’ will NOT match because there isn’t any ’O’ in Reply2=Nak NumReplies=4
Acked=1
AckedHold=3
NotAcked=2
Released=4
Reply1=Ack
Reply2=Nak
Reply3=Hold
Reply4=Release
154 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.15 Sending Text Messages to a DN400E Fax Modem
TelAlert now supports the DN400E fax modem. Using the supported DN400E fax modem, you can
now use TelAlert to send text messages to fax machines. (Note that only the DN400E fax modem is
supported at this time.
Contact the ACM Group for more information on obtaining this fax modem: ACM Group (Advanced
Communications Methods), 103 Bullet Hole Rd, Carmel, NY 10512; (845) 228-0527.)
In the [Port] and [Configuration] sections you can now specify Model=FaxModem and Type=Fax.
The FaxFSI keyword has been added to the [Configuration] section.
The FaxCSI keyword has been added to the [Destination] section.
Typical definitions follow:
[Port]
{FaxModem1}
Model=FaxModem
Types=Fax
Dev=COM3
Speed=19200
Modem=DN400E
[Configuration]
{Fax}
Type=Fax
Model=FaxModem
FaxFSI=AAA-BBB-CCCC
[Destination]
{FaxZZZZ}
Configuration=Fax
AreaCode=AAA
Number=XXX-YYYY
FaxCSI=ZZZZ
FaxFSI (the Fax Subscriber Identifier) is the string sent by TelAlert to the remote fax machine to
indicate the source of the fax. FaxFSI can be up to 20 characters.
FaxCSI (Called Subscriber Identifier), is the string returned by the fax machine at (AAA)XXX-YYYY
to identify itself to TelAlert. If FaxCSI is specified, the value returned by the fax machine must
match FaxCSI exactly, otherwise the fax is not sent. If FaxCSI is not specified or blank, no checking is performed. FaxCSI can be up to 20 characters.
In addition, the command line option: -faxcsi string can be used to specify, but not replace, the
FaxCSI string from a [Configuration] or [Destination].
The first 32 characters of Subject= or -subject will be sent as the TTI (Transmitting Terminal Identifier) to the remote fax machine.
Chapter 10: Configuring for Other Notification Media | 155
10.16 Sending a File or a Line from stdin as a Message
10.16.1 Sending a File as a Message
It is possible to send the contents of a file as a message. This is particularly useful if the
destination is of type Email, Modem or InteractiveModem. A file’s contents may be used as
the message text. e.g.:
telalertc -i BostonModem -m ~file /tmp/salesrpt.txt
The message file is processed differently depending on the destination type. If the destination type
is anything other than Email, Modem or InteractiveModem, the file is read when the alert is initiated, and the message text is kept in telalerte’s internal tables. Thus, the text to be sent
may not be larger than MaxMessageLength, as specified in the [Configuration] or
[Destination] sections. MaxMessageLength itself has an upper limit of 960 characters if being sent through an Engine, 1920 otherwise. If the file contains references to TelAlert variables,
such as ~batteryvolts, the substitutions will be made subject to the following limitations.
� If the destination (BostonModem) is of type Email or Modem or InteractiveModem,
the message will be sent with variable substitution only if the message is shorter than MaxMessageLength.
� If the destination type is Modem or InteractiveModem and the message is longer than
MaxMessageLength, the message will be sent without variable substitution.
� If the destination is type Email, then the message file is not processed until
telalerte's telalerts child process actually connects to the smtp mail server. This
may be a concern if the message file is dynamically produced, and a new event may overwrite the existing message file before it has been read and sent.
If the client and server machines do not have shared access to a common directory, then the
telalertc client will be restricted to specifying “canned” message files that reside on the server.
OR:
The fact that the server, not the client, reads the message file is what allows the contents of the
message file to be larger than what the internal buffers in telalertc can hold. Thus, the
restriction that the server reads the file cannot be changed.
However, if the contents of the message file are short enough to fit into telalertc's buffers,
there are a couple of workarounds.The first workaround has the O/S read the file and pass it as
text to the telalertc command; it works on a UNIX system, or on a Windows system with a
Note: the message file is read by the server telalerte process, not the client telalert(c). Thus, if you are running telalertcon a client machine, you must
specify ~file with a path that the TelAlert server can follow, not a path that the
telalertc client can follow. So, you either need to move the file (using FTP or another
such protocol) from the client machine to the server machine before issuing the
telalertc command; or move the file to a file server that both machines have access
to before issuing the telalertc command; or have set up a “share” for a disk on
either the client or server machine, such that the client can place the file on the shared
disk and the server can read the file from the shared disk, before issuing the telalertc command.
156 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Bourne/Korn shell such as the MKS toolkit that can provide both command substitution
(“command”) and the "cat" command:
telalertc -host 1.2.3.4 -i destination -m ‘cat msgfile‘
The second workaround uses telalertc's "~stdin" syntax (discussed below) instead of the
"~file" syntax. In other words, if the message is in a file named msgfile, use a command like
this on Windows or UNIX:
telalertc -host 1.2.3.4 -i destination -m ~stdin < msgfile
or like this on UNIX (or on Windows with MKS):
cat msgfile | telalertc -host 1.2.3.4 -i destination -m ~stdin
Note that when using the "~stdin" syntax, only the first logical line of msgfile will be read. To
have the entire file treated as a single logical line, make sure there aren’t any imbedded <CR> or EOL characters in msgfile. If msgfile is created by an external application that embeds <CR>
and/or EOLs, then pass msgfile through a filter to remove them.
10.16.2 Sending a Line from stdin as a Message
It is also possible to have TelAlert read a single line from stdin and put it in a message. This is useful if you want TelAlert to send a one-line result of a program as the message. For example, if
you have a program that outputs a one-line message, you can send the program’s output directly,
without first having to write the message to a file and then send the file’s contents. e.g.
makeamessage | telalertc -i JackTextPager -mP ~stdin
This is simpler than:
makeamessage > tmpfile telalertc -i JackTextPager -mP ~file tmpfile rm tmpfile
Note that stdin is read by the telalert(c) command-line program, and thus this technique will work whether telalert(c) is being run on the TelAlert server, or on a client machine.
Chapter 10: Configuring for Other Notification Media | 157
10.17 SMPP
TelAlert supports the SMPP (Short Message Peer to Peer) TCP/IP protocol. Although SMPP is an
international standard, there are slight differences in implementation between different service
providers, and thus TelAlert must test and fine tune its configurations for each new provider
supporting SMPP. Currently Vytek has tested configuration for AT&T.
AT&T is providing SMPP as part of a set of advanced messaging services; customers must sign up
with AT&T for these services before the AT&T servers will accept SMPP messages from TelAlert.
SMPP is basically a one-way protocol; optionally, it can provide a confirmation of delivery to the
handheld device, although not all service providers may implement delivery confirmation, and
delivery confirmation does not show that the message has actually been read. If delivery
confirmation is supported by the service provider, TelAlert can pass the confirmation to an external
script, which users can customize to update applications such as OpenView, Remedy, etc.
Although a service provider may optionally allow the handheld device to send a SMPP message
back to TelAlert, this is not precisely “two-way messaging” in the TelAlert sense. The SMPP
protocol, unlike some other protocols, does not provide an internal “unique ID” field that
unambiguously links the original message with the return message. Instead, the user must
manually enter sufficient information in the return message to allow TelAlert to match the return
message with the original message. It is important that the user does not omit or mistypes that
information as TelAlert may not mark the alert as acknowledged, or may mark the wrong alert as
acknowledged.
MIR3 recommends that where two-way response capability is critical, users investigate the use of
protocols such as SNPP or WCTP that are designed for two-way messaging and contain internal
“unique ID” values to match original and return messages.
10.17.1 SMPP Confirmed Delivery Option
The SMPP protocol does provide for a ‘confirmed delivery’ option. If TelAlert assigns a unique ID to
the message (the TelAlert SendID) and requests delivery confirmation, then the ATT antennas will
get an ‘echo’ back from the phone to indicate the message actually arrived on the phone, and ATT
will notify TelAlert that SendIDnnnnn was actually delivered to the phone.
10.17.2 SMPP Sample Configuration
A sample TelAlert [Configuration] definition which utilizes the AT&T SMPP protocol is included
in the /Pagers/ATT subdirectory on a new installation (/New/Pagers/ATT subdirectory on an
upgrade.)
See the Keyword and Command Guide for information on setting the SMPP values for
Protocol and ProtocolMask keywords.
Note: AT&T calls partner products like TelAlert “Adapters”, because they allow customers
to quickly and easily connect mission-critical software (OpenView, Tivoli, Remedy, etc.)
to AT&T's secure and reliable communication solutions, without any need to do custom programming.
158 | TelAlert 6e™ Administrator Guide - Version 6.1.29
10.18 WCTP Proxy Configuration
By default, the WCTP protocol uses the same TCP/IP port/socket as the HTTP protocol (port 80).
Due to security concerns, more and more companies are installing HTTP Proxy Servers to control
the HTTP traffic through their firewall. These HTTP Proxy Servers can interfere with the WCTP
traffic using the same port.
TelAlert 5.6 now includes three optional [Configuration] keywords for use with a HTTP Proxy
Server, so that TelAlert can modify its WCTP processing to correctly route messages through the
Proxy Server. The boolean HTTPProxyRequired keyword (default False) indicates if a Proxy
Server exists. The HTTPProxyHost and HTTPProxyService keywords define how TelAlert should connect to the company's Proxy Server. The Host and Service keywords continue to define the connection to the messaging service provider (which is now made through the Proxy
Server instead of directly by TelAlert).
This new WCTP/HTTP-specific proxy support is in addition to the generic SOCKS proxy for which
TelAlert has continued to provide support.
The new options to enable the use of an HTTP proxy server are reflected in three new
[Configuration] variables:
� HTTPProxyRequired
A True/False variable indicating whether the Proxy mechanism is to be used (True) or not (False.)
� HTTPProxyHost
The IP address of the HTTP Proxy server. This is typically an address within the customer’s network
domain.
� HTTPProxyService
The TCP/IP port value for the HTTP Proxy server. The default text value is "webcache"; the default
numeric value is 8080. As an example, the Arch Wireless WCTP [Configuration] looks like:
{ArchWCTP}
Comment=Arch WCTP service for Two-Way messaging. Type=InteractiveTextPager
Protocol=WCTP
Host=wctp.arch.com
Service=http
# For one-way paging, set ServerPIN to yourname.yourdomain and # Access="", and un-comment both lines. # For two-way paging, you'll need to get an account set up with # Arch. Use the senderID/securityCode provided by Arch, and # un-comment both lines. # ServerPIN=<your senderID> # Access=<your securityCode> PollRequests=False
TextPagerWait=30s
ProtocolMask=32
Chapter 10: Configuring for Other Notification Media | 159
To use this with a Proxy server, running on 10.11.10.99 on port 8085:
{ArchWCTP}
Comment=Arch WCTP service for Two-Way messaging. Type=InteractiveTextPager
Protocol=WCTP
Host=wctp.arch.com
Service=http
# For one-way paging, set ServerPIN to yourname.yourdomain and # Access="", and un-comment both lines. # For two-way paging, you'll need to get an account set up with # Arch. Use the senderID/securityCode provided by Arch, and # un-comment both lines. # ServerPIN=<your senderID> # Access=<your securityCode> PollRequests=False
TextPagerWait=30s
ProtocolMask=32
HTTPProxyHost=10.11.10.99
HTTPProxyService=8085
HTTPProxyRequired=True
The following describes the differences in TelAlert’s processing when using one or the other of the
above configurations:
Non-Proxy access:
1. Connect to wctp.arch.com:http
2. Send "POST /wctp HTTP/1.1"
Proxy access:
1. Connect to 10.11.10.99:8085
2. Send "POST http://wctp.arch.com:80/wctp HTTP/1.1" Note that the numeric Service value
is substituted in the POST directive, rather than "wctp".
Simply changing HTTPProxyRequired to False will cause the Configuration to revert back to
non-Proxy mode - it’s not necessary to blank out the HTTPProxyHost/Service values, or
remove those keywords.
Note: For ’Service=http’, TelAlert looks up ’http’ in the server’s etc/hosts file, and uses
the numeric value found there (normally 80). It is legal to use ’Service=80’, which allows TelAlert to skip the etc/hosts lookup step.
160 | TelAlert 6e™ Administrator Guide - Version 6.1.29
11
Applying Filtering
Techniques 11.1 Overview
Instructions for using each of TelAlert filtering mechanisms to prevent certain messages from being
sent under certain conditions. These mechanisms rely on (1) [Filter]definitions; (2) message priority;
(3) -check string value; (4) IP address or host name, and (5) -source string.
11.2 Getting Started
11.2.1 What is Filtering?
Filtering is a means of specifying rules TelAlert is to follow in order to qualify a destination’s validity
when it prepares to send a message. You can set up filtering so that TelAlert sends the message to
no destinations except those meeting specified criteria (inclusive filtering), or so that TelAlert sends
the message to all destinations except those meeting specified criteria (exclusive filtering).
At its most basic, filtering involves associating a [Filter] definition with a destination and letting
TelAlert send or not send to the destination according to whether tags specified on the command line
match tags included in the [Filter] definition.
Commonly, filtering is used in conjunction with groups, schedules, and users. In the case of groups,
it is used to qualify the destinations comprising a group, so that some are used and some are
discarded. In the case of schedules, it provides a means of qualification in addition to a schedule, so
that the destination must be on duty and meet the filtering criteria for it to be used. In the case of
users, a [Filter] definition is associated with one or more destinations by referring to it in a
[User] definition and then invoking the user in the relevant destinations.
11.2.2 Needed Information
To set up filtering, you simply need to know the criteria you want to use to filter messages and the
destinations on which you want these criteria to operate.
162 | TelAlert 6e™ Administrator Guide - Version 6.1.29
11.3 A Simple Filter
11.3.1 The Scenario
David is the sole support technician for a small company. For simplicity’s sake, the company’s
network monitoring application is set up to generate a TelAlert alert for every network event it
detects. David wants to tell TelAlert how to determine which ones it should send to him and which
ones it should suppress. He is interested in receiving a page only when there is an event pertaining
to a server or router.
11.3.2 Procedure
To set up this simple filter, David first creates the following [Filter] definition and refers to it in
his destination. In TelAlert 6e, Filters are referenced under the Advanced tab as shown below.
[Filter]
...
{DavidFilter}
Active=True
RequiresFullMatch=False
Exclusive=False
Tags=Router,Server
[Destinations]
...
{DavidTextPager}
Configuration=ATTWichitaTextPager
PIN=3456789
Filter=DavidFilter
Chapter 11: Applying Filtering Techniques | 163
The relevant line in the [Destinations] definition is Filter=DavidFilter. The significance of
the values in the [Filter] definition is as follows:
Active—Set to True, this makes the [Filter] definition available for use by TelAlert.
RequiresFullMatch—Set to False, this means that a minimum of one tag specified in the
[Filter] definition must be matched by a tag specified on the command line for the destination to
be deemed a “match.” Set to True, this means that all tags specified in the [Filter] definition
must be matched by those on the command line. How a match is treated is determined by the
Exclusive setting.
Exclusive—This determines how TelAlert treats a destination that it, on the basis of the tags
specified and the RequiresFullMatch value, views as a “match.” When this is set to False, TelAlert will include—i.e., will deem valid—a matching destination while excluding all non-matching
destinations. When this is set to True, TelAlert will exclude—i.e., will not send to—a matching
destination while sending to all non-matching destinations.
Tags—The values entered here serve solely as a means for determining a match or non-match
between a command and a destination. Even though TelAlert understands a tag only as a string of
characters to compare against another string of characters, you should name your tags so that you
can understand what they refer to.
Having created this [Filter] definition and added this line to {DavidTextPager}, David then
modifies the network monitoring application so that, in passing news of an event to TelAlert, it
specifies a tag on the command line—server, router, modem, printer, etc.—so that the
complete command looks like this:
telalertc -i DavidTextPager -m "node down" -tags router
Here, the message is sent because (1) the destination is a match (since one tag matches and a full
match is not required); and (2) Exclusive is set to False (meaning that matching destinations, and only matching destinations, are included). Note that:
� If he changed the Exclusive setting to True, the [Filter] definition would operate
exclusively: i.e., the message would not be sent because TelAlert would exclude it, along
with any other matching destinations.
� If he changed RequiresFullMatch to True and left Exclusive set to False, the
message would not be sent. The destination is not a match because not all of the [Filter]
definition’s tags appear on the command line. As a non-match, the destination is excluded,
since the Exclusive setting specifies that only matching destinations are to be included.
� If he changed RequiresFullMatch to True and Exclusive to True, the message
would be sent. The destination is not a match because not all of the [Filter] definition’s
tags appear on the command line. As a non-match, the destination is included, since the
Exclusive setting specifies that only matching destinations will be excluded.
Now, in light of the original settings presented above, consider this command:
telalertc -i DavidTextPager -m "node down" -tags printer
164 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Here, the message is not sent because (1) the destination is a non-match (since the tag specified
here does not match any specified in the [Filter] definition); and (2) Exclusive is set to False
(meaning that matching destinations, and only matching destinations, are included). Note that:
� If he changed the Exclusive setting to True, the [Filter] definition would operate
exclusively, but here the message would be sent because TelAlert excludes only matching
destinations and includes all non-matches.
� If he changed RequiresFullMatch to True and left Exclusive set to False, the message would not be sent. The destination is not a match because none of the [Filter]
definition’s tags appear on the command line. As a non-match, the destination is excluded,
since the Exclusive setting specifies that only matching destinations are to be sent to.
� If he changed RequiresFullMatch to True and Exclusive to True, the message would be sent. The destination is not a match because none of the [Filter] definition’s
tags appear on the command line. As a non-match, the destination is included, since the
Exclusive setting specifies that only matching destinations will be excluded.
In the case of events that David wanted to be informed of no matter what, he would set up the
network monitoring application to issue appropriate commands without a -tags value:
telalertc -i DavidTextPager -m "power outage"
Without a -tags value on the command line, the [Filter] definition linked to the destination does
not come into play at all.
11.4 Filtering Strategies
11.4.1 Filtering and Default Logic
The simplest way to associate an existing [Filter] definition with a destination is to refer to the
[Filter] definition in the [Destinations] definition. You can also specify a default [Filter]
definition that will apply to all destinations except those that specify their own. Thus, in the following
example—
[Destinations]
...
Filter=DefaultFilter
...
{DavidTextPager}
...
{JohnTextPager}
...
{RachelTextPager}
...
Filter=RachelFilter
—{DavidTextPager}and {JohnTextPager} are both associated with {DefaultFilter}
while {RachelTextPager} is associated with its own [Filter] definition, {RachelFilter}.
Chapter 11: Applying Filtering Techniques | 165
A [Filter] definition specified directly on the command line overrides all others. Thus, in the case
of the following command—
telalertc -i RachelTextPager -m "this is a test" -tags router -filter DefaultFilter
—the [Filter] definition in play is {DefaultFilter} because its specification on the command
line overrides the [Filter] definition directly associated with {RachelTextPager}.
11.4.2 RequiresFullMatch and Exclusive Value Combinations
In the above scenario, David wants TelAlert to suppress all messages except those meeting either of
two conditions. He achieves this by setting both RequiresFullMatch and Exclusive to False.
Each of the four possible combinations of RequiresFullMatch and Exclusive provides a
unique effect and thus serves a relatively specific purpose.
RequiresFullMatch=False, Exclusive=False
Generally speaking, this combination is useful when you want all of the messages directed to a
destination to be filtered (and thus not sent) unless they meet specified criteria. It differs from the
True-False combination, however, in that it allows you to specify a set of criteria and have the
destination be considered valid if it matches in a single respect.
In the example provided, this combination is appropriate because David wants to filter all messages
other than those specified. At the same time, he wants to be able to provide a fairly “loose”
specification: either messages tagged with Router or messages tagged with Server.
RequiresFullMatch=False, Exclusive=True
Generally speaking, this combination is useful when you want all of the messages directed to a
destination to be sent unless they meet specified criteria (in which case you want TelAlert to discard
them). It differs from the True-True combination, however, in that it allows you to specify a set of
criteria and have the destination be excluded if it matches in any respect.
Under what circumstances might this be the appropriate combination? Perhaps you want a certain
destination to receive any message directed to it unless the message falls into one of three classes:
those relating to Web servers, those relating to mail servers, and those relating to Internet
gateways.
To accomplish this, you would:
� use the False-True combination
� include three tags in your [Filter] definition: Web, Mail, and Internet
� configure your monitoring software so that, each time it generates a TelAlert command, it
provides the information necessary to create these tags on the command line (where
appropriate)
166 | TelAlert 6e™ Administrator Guide - Version 6.1.29
RequiresFullMatch=True, Exclusive=False
Generally speaking, this combination is useful when you want all of the messages directed to a
destination to be filtered (and thus not sent) unless they meet specified criteria. It differs from the
False-False combination, however, in that it allows you to specify a set of criteria and have the
destination be considered valid only if it matches in every respect.
Under what circumstances might this be the appropriate combination? Perhaps you want a certain
destination to receive only a very narrow set of messages. For instance, your network monitoring
application may be able to generate notifications about a number of different status changes and
node types, but in this case you want to receive “node down” messages only, and only those
pertaining to downed UNIX servers—not routers, and not Windows servers.
To accomplish this, you would:
� use the True-False combination
� include three tags in your [Filter] definition: Down, Server, and UNIX
� configure your monitoring software so that, each time it generates a TelAlert command, it
provides the information necessary to create these tags on the command line (where
appropriate)
RequiresFullMatch=True, Exclusive=True
Generally speaking, this combination is useful when you want all of the messages directed to a
destination to be sent unless they meet specified criteria (in which case you want TelAlert to discard
them). It differs from the False-True combination, however, in that it allows you to specify a set
of criteria and have the destination be excluded only if it matches in every respect.
Under what circumstances might this be the appropriate combination? Perhaps you want a certain
destination to receive any message directed to it unless the message has all of three special
characteristics: it pertains to a (1) workstation (2) manufactured by Hewlett-Packard and (3) running
UNIX. To accomplish this, you would:
� use the True-True combination
� include three tags in your [Filter] definition: Workstation, HP, and UNIX
� configure your monitoring software so that, each time it generates a TelAlert command, it
provides the information necessary to create these tags on the command line (where
appropriate)
Interaction Between Exclusive and RequiresFullMatch
RequiresFullMatch works in conjunction with the tags specified in the filter and on
the command line to determine whether a destination is a “match.” Exclusive tells
TelAlert what to do with matches and, implicitly, with non-matches.
With Exclusive set to False, matching destinations are used and non-matching
destinations are discarded.
With Exclusive set to True, matching destinations are discarded and non-matching
destinations are used.
Chapter 11: Applying Filtering Techniques | 167
11.4.3 RequiresClientMatch
The RequiresClientMatch keyword has roughly the opposite effect of RequiresFullMatch:
When this keyword is set to True, the filtering condition is met only if all the tags passed on the
command line are also listed in the [Filter] definition. (Additional, non-matching tags present in
the definition do not prevent a match.) Use this keyword when you want to filter out messages with
tags that do not match a specific list.
11.4.4 The MatchKeyword
The Match keyword allows you to exert greater control over what constitutes a match. Using the two possible values for RequiresFullMatch, you can specify that a match takes place whenever
either one or all of the tags defined in the [Filter] definition are matched on the command line.
The Match keyword opens up the many possibilities lying between “one” and “all.”
Using Match, you can specify a subset of tags that must be matched, and you can do this using
conjunctional and disjunctional statements, i.e., “and” and “or” assertions. For instance, the
following Match value—
Match=(Tag1 | Tag2) & Tag3
—says that a match occurs whenever the message is accompanied by either Tag1 or Tag2 and Tag3. In other words, two of the three are required, and one of the two must be Tag3.
In this example—
Match=(Tag1 & Tag2) | (Tag3 & Tag4)
—a match is understood to occur whenever the message is accompanied by either Tag1 and Tag2 or Tag3 and Tag4. In other words, two of the four are required, and not just any two: either 1 and 2 or 3 and 4.
Match Value Expression Building Blocks
In addition to the tag names, the building blocks of a Match value expression are the “or” symbol
(|), the “and” symbol (&), and the pairs of parentheses you can use to group portions of the
expression. Parentheses are useful because TelAlert, in evaluating an expression, assigns equal
importance to both |and &; it simply reads the expression from left to right, with the outcome
depending on the first decisive operator.
For instance:
Match=Tag1 | Tag2 & Tag3
Here, if Tag1 is a match, TelAlert will recognize that the entire expression is matched as soon as it sees the |. If Tag1 is not a match, it will read on, recognizing the entire expression as matched only if both Tag2 and Tag3 are matched. In both cases, it proceeds as if the expression were written like so:
Match=Tag1 | (Tag2 & Tag3)
168 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Consider this example:
Match=Tag1 & Tag2 | Tag3
Here, if Tag1 is a match, TelAlert reads on, driven by the & operator to see if either Tag2 or Tag3 is also a match, required for the entire expression to be a match. If Tag1is not a match, TelAlert
recognizes the entire expression as a non-match as soon as it sees the &. In both cases, it is as if
the expression were written like so:
Match=Tag1 & (Tag2 | Tag3)
Even though you do not always have to use parentheses to set a Match value expression, it is a good
idea to do so anytime you are writing an expression that mixes |and & operators, since this will help
you avoid errors and reduce the potential for confusion on the part of someone examining the
expression.
Match and RequiresFullMatch
It is important to note that no value you assign to RequiresFullMatch will have any meaning if
Match is assigned a value; only one of these keywords can be in play at a time. Exclusive works in conjunction with Match just as it does with RequiresFullMatch: if the conditions for a match
are met, the destination is included or excluded, as appropriate.
11.4.5 Filtering and Groups
The following discussion concerns two points of intersection between filtering and groups. For
information on setting up and using [Group] definitions, refer to Chapter 15: Broadcasting to
Groups and Creating Escalations.
Choosing the Appropriate Destination from Within a Group
So far, this discussion of filtering has assumed that TelAlert is being asked to send a message to a
single destination, and that you want to use filtering as a means of having TelAlert act on or
disregard this request, according to specified rules. For instance, it may be that the easiest way to
integrate a network monitoring application with TelAlert is to configure it to generate a TelAlert alert
for every event that it detects. Because you do not want TelAlert to send all of these messages, you
create a [Filter] definition and refer to it in all of your destinations, such that only “real” events
generate alerts.
A far more common scenario involves messages directed to groups of destinations. Perhaps you
have a group called {Support} that is comprised of four pager destinations, one for each support
technician. Each technician is primarily responsible for one of four areas: servers, workstations,
routers, and modems. Here you could use [Filter] definitions so that your help desk software
does not have to know which destination (i.e., which support technician) to notify about a given
problem; instead, it always sends to the entire {Support} group, along with a problem-specific tag
that TelAlert uses to select the appropriate destination.
Chapter 11: Applying Filtering Techniques | 169
Consider the following [Filter] definitions, each associated with {JohnTextPager},
{DavidTextPager}, {RachelTextPager}, and {CynthiaTextPager}, respectively:
[Filter]
...
{John}
Active=True
RequiresFullMatch=False
Exclusive=False
Tags=Server
{David}
Active=True
RequiresFullMatch=False
Exclusive=False
Tags=Workstation
{Rachel}
Active=True
RequiresFullMatch=False
Exclusive=False
Tags=Router
{Cynthia}
Active=True
RequiresFullMatch=False
Exclusive=False
Tags=Modem
Now, recalling that {Support} is a group of destinations comprised of {JohnTextPager},
{DavidTextPager}, {RachelTextPager}, and {CynthiaTextPager}, consider this
command:
telalertc -g Support -m "node down" -tags server
Upon receiving this command, TelAlert would evaluate the four destinations comprising {Support},
using the [Filter] definition associated with each and the –tags value from the command line to determine which it should notify. In this case, TelAlert would notify John by sending him a page. The
advantage is that the application generating the command can follow a very simple process every
time, always specifying the same group and simply inserting a tag derived from the nature of the
problem. This is also a benefit when human users will be generating the command and are unlikely
to know who to contact.
Associating a [Filter] Definition with a Group
You can associate a [Filter] definition with a formally defined group of destinations, either by
referring to it specifically in the [Group] definition or by setting it as the default value for all groups.
A [Filter] definition specified directly in a [Group] definition overrides the default.
Note that a [Filter] definition assigned to a group is not in turn assigned to the destinations
comprising it; the [Filter] definition determines only whether the group itself is valid, given the
tags included on the command line.
170 | TelAlert 6e™ Administrator Guide - Version 6.1.29
A group can be associated with one [Filter] definition, a subgroup within that group with another,
and each of the individual destinations with still others. If, after evaluating the group’s [Filter]
definition, TelAlert finds that the group is valid, it evaluates the subgroup’s [Filter] definition. If this
too is valid, it looks at the [Filter] definitions invoked at the destination level. In such a case, the
message will be sent to a destination only if all three [Filter] definitions permit it.
11.4.6 Filtering and Schedules
A [Filter] definition is one way of qualifying a destination—i.e., of setting rules for determining
whether the destination is valid for a given message. A schedule is another means of destination
qualification. Whereas a [Filter] definition determines whether a destination is valid based on the
tag or tags accompanying the message, a schedule determines whether a destination is valid based
on the time the message is to be sent.
You do not have to do anything special to make [Filter] definitions and schedules work together. If a
destination is associated with a [Filter]definition and a [Schedule] definition, TelAlert will send it a
message that is accompanied by a -tag value only if it finds that the destination is both on duty and
valid according to the terms of the [Filter] definition.
For information on setting up and using schedules, refer to Chapter 11: Setting Up and Applying
Schedules.
11.4.7 Filtering and Users
[User] definitions offer another means of associating [Filter] definitions with destinations. You
can create a [User] definition that refers to a [Filter] definition and then refer to this [User]
definition in the destination. The [Filter] definition will operate as if it were specified there
directly. (However, if a [Filter] definition is specified directly in the destination, it will override the
one specified at the user level.)
This is an especially effective way of linking a [Filter] definition with one or more destinations
when several destinations “belong to” the same human user and you want the same [Filter]
definition to apply in all cases. For example:
[Filter]
...
{JohnFilter}
...
[User]
...
{John}
...
Filter=JohnFilter
...
[Destinations]
...
{JohnTextPager}
...
User=John
...
{JohnCellPhone}
Chapter 11: Applying Filtering Techniques | 171
...
User=John
...
{JohnHomePhone}
...
User=John
...
Here, {JohnFilter} will apply whenever TelAlert is asked to send a message (accompanied by
one or more tags) to a destination linked to {John}.
Maintaining links between [Filter] definitions and destinations in this way is valuable in part
because filtering is typically used to see that the right messages get to the right person; this method
allows you to think in terms of people as you set up filtering. If you are using [User] definitions to
link schedules to destinations, too, this method makes even more sense.
11.5 Filtering by Message Priority
There is another filtering technique that lets you determine whether a message directed to a given
destination is actually sent to that destination. This involves assigning the message a priority on the
command line and including MinFilterPriority and MaxFilterPriority values in the
[Destinations] definition. If the message’s priority is less than MinFilterPriority or
greater than MaxFilterPriority, it is not sent. Consider this destination:
[Destinations]
...
{CynthiaTextPager}
...
MinFilterPriority=50
MaxFilterPriority=80
And consider the following three commands:
telalertc -i CynthiaTextPager -m "this is a test" -priority 40 telalertc -i CynthiaTextPager -m "this is a test" -priority 80 telalertc -i CynthiaTextPager -m "this is a test" -priority 90
Here, the first message would not be sent, because its priority is less than the
MinFilterPriority assigned in the destination. The second message would be sent, because its
priority is neither less than the MinFilterPriority nor greater than the MaxFilterPriority. The third message would not be sent, because its priority is greater than
MaxFilterPriority.
Schedule-Based Filtering
Schedule-based filtering (including schedule-based filtering using –priority) is
covered in Chapter 12: Setting Up and Applying Schedules.
172 | TelAlert 6e™ Administrator Guide - Version 6.1.29
11.5.1 Extended Example
This technique is useful in a number of ways, but its most common application is to permit TelAlert
to choose the correct notification medium based on message priority. Typically, this involves defining
one or more groups. For more information on defining groups, refer to Chapter 15: Broadcasting
to Groups and Creating Escalations.
Imagine that David can be sent notifications any of three ways: by telephone, pager, and email. He
wants his least important messages to be delivered by email, the most important messages to be
delivered by pager, and those of moderate importance to be delivered by telephone. He could achieve
this by setting MinFilterPriority and MaxFilterPriority in each destination, like so:
[Destinations]
...
{DavidEmail}
...
MinFilterPriority=1
MaxFilterPriority=40
{DavidVoiceMail}
...
MinFilterPriority=40
MaxFilterPriority=80
{DavidTextPager}
...
MinFilterPriority=80
MaxFilterPriority=100
With these values in place, he could then create a group pointing to these destinations:
[Group]
...
{David}
...
Destinations=DavidEmail,DavidVoiceMail,DavidTextPager
A message directed to this group and specifying a priority would then go to whichever destination
met the filtering requirements. For instance, this message—
telalertc -g David -m "this is a test" -priority 50
—would be sent to David’s voice mail because its priority falls within the range (inclusive) specified
in the definition of {DavidVoiceMail}.
Keep in Mind …
MinFilterPriority and MaxFilterPriority do not have to be used so that they
create a middle range—e.g., from 50 to 80. You can set MinFilterPriority to 60,
for example, and MaxFilterPriority to 100; this means that all messages of
priority 60 or higher will be sent to the destination. Likewise, you can set
MinFilterPriority to 0 and MaxFilterPriority to 60; this means that all
messages of priority 60 and lower will be sent to the destination.
Chapter 11: Applying Filtering Techniques | 173
11.5.2 Default Logic
The default value for MinFilterPriority is 1, and the default value for MaxFilterPriority
is 100 — thus, by default, no messages are ever filtered on the basis of priority.
These values can be set for all destinations, all users, or all groups. They also can be set for
individual destinations, users, and groups.
Values assigned within a specific destination override values set elsewhere.
If a destination does not specify these values directly, it inherits either the settings assigned to all
destinations or the settings assigned to an associated user (regardless of whether these are specified
directly in the [User] definition or for all [User] definitions). If these values have been set both for
all destinations and for the user, TelAlert works with the lesser of the MinFilterPriority values and the greater of the MaxFilterPriority values.
MinFilterPriority and MaxFilterPriorityin Groups
If MinFilterPriority and MaxFilterPriority are set for a group, a message will not be sent to any of the destinations comprising the group unless its priority falls between these minimum
and maximum values, inclusive. If individual destinations within the group also specify these values,
either directly or by inheritance, the message’s priority must fall within these minimum and
maximum values as well for the destination to be considered valid.
11.6 Filtering Messages by IP Address
The telalert.ipchk file can be used to determine whether an alert is processed or discarded by
TelAlert based on the identity of the machine with which the alert is concerned.
Typically, you would edit this file so that it contains the IP addresses of all machines that you do not
want to be the basis for alerts. To exclude the machines with IP addresses in telalert.ipchk, you must
also set the value of the NegativeIPCheck command to True (its default is False). When you
start TelAlert, the contents of the file are loaded into an in-memory filter. To invoke this filter, you
would set up your TelAlert integration so that, each time a command to generate an alert is issued,
the IP address of the pertinent machine is included on the command line, preceded by the
-ipcheck option:
telalertc -i JohnTextPager -m "this is a test" -ipcheck 123.456.789.012
Or, if TelAlert has access to a network resource that can resolve the host name to an IP address, you
can give the -ipcheck value in the form of a host name:
telalertc -i JohnTextPager -m "this is a test" -ipcheck hostname
If the telalert.ipchk file contains the IP address for this machine, TelAlert will disregard the command. If this IP address is not listed in the file, TelAlert will process the command normally. If a
command is issued without the -ipcheck option, the filter does not come into play at all, and the
command will be processed.
174 | TelAlert 6e™ Administrator Guide - Version 6.1.29
You can edit the contents of this filter on the fly. To add an address:
telalert -insert -ipcheck IPaddress telalert -insert -ipcheck hostname
To remove an address:
telalert -delete -ipcheck IPaddress telalert -delete -ipcheck hostname
These changes are not reflected in the file unless you use the –write command line option. For more information, refer to Chapter 3 of the TelAlert Keyword and Command Reference.
11.7 Filtering out Duplicate and Transient Messages
Users who control TelAlert with network management applications frequently have problems with
duplicate messages. Another common problem is transient messages produced by devices that
occasionally go offline and come back on by themselves.
11.7.1 Filtering Out Duplicate “Node Down” Messages
Network management software typically pings devices at fixed intervals to determine whether they
are “up,” that is, on line. If the ping fails, the application assumes that the node is down, and issues
a command to TelAlert to send a “node down” message to support personnel informing them of that
fact.
In some cases, the application will send TelAlert a series of such commands, one every time it pings
the node. For example, assume that your network management application pings nodes every five
minutes. With a basic command, such as—
telalertc -i RachelPager -m "node 123 down"
—TelAlert would send a message to {RachelPager} every five minutes until the node came back
online.
In such cases, it is usually preferable to configure TelAlert to send only one “node down” message.
You can achieve that result by using a combination of -check, -holdifsent, -holdrefresh,
and -releasewait options.
The following example assumes that your network management application pings nodes every five
minutes and sends only “node down” messages through TelAlert, never “node up” messages:
telalertc -i RachelPager -m "node 123 down" -check "node 123 down" -holdifsent -holdrefresh -releasewait 6m
Reversing the Function of telalert.ipchk
You can reverse the function of telalert.ipchk by changing the value of the
NegativeIPCheck command: Setting the command to True causes commands
containing -ipcheck, with IP addresses that match those in telalert.ipchk, not
to be processed (as described above). Setting NegativeIPCheck to False (its default value), causes those commands with matching values to be included and processed.
Chapter 11: Applying Filtering Techniques | 175
When a node first goes down and TelAlert receives this command, it sends the “node down”
message. Since the command contains the -holdifsent option, TelAlert then puts the message in a held state.
If five minutes later TelAlert receives the command again, it finds that its -check string matches the held message, so it does not send the duplicate message. Since the command contains the
-holdrefresh option, TelAlert resets the -releasewait timer, holding the message for another six minutes.
If five minutes later TelAlert receives the command yet another time, it resets the -releasewait timer again, and keeps doing so until the node comes back up and the network management
application stops sending the repetitive commands. Thus TelAlert sends only one message each time
the node goes down.
11.7.2 Suppressing Transient Messages
When a node is known to go offline occasionally and come back online by itself (for example, a
printer that goes offline while a user is clearing a paper jam), you may wish to configure TelAlert to
ignore a single “node down” message from the network management application. There are two
different approaches to this problem, one for applications (like the one discussed in the previous
example) that send a series of “node down” messages, the other for applications that send a “node
down” message when they detect that a node has gone offline and a “node up” message when it
comes back online.
Suppressing Transient “Node Down” Messages
To suppress transient “node down” messages from a network management application that does not
issue “node up messages,” add the –delay and -affirm options to a command similar to the one
in the previous example:
telalertc -i RachelPager -m "node 123 down" -check "node 123 down" -holdifsent -holdrefresh -releasewait 6m -delay 7m -affirm 1
When a node first goes down and TelAlert receives this command, it does nothing immediately.
Instead, it waits for seven minutes (-delay 7) to see if it receives one (-affirm 1) additional command with a message that matches its -check string. (Note that the –affirm value represents the number of duplicates required within the time frame represented by the –delay value before TelAlert will send the original message. The original command does not count against
the -affirm count.)
If five minutes later TelAlert receives the command again, it finds that its -check string matches
the held message, sends the delayed message, and does not send the duplicate message. Since the
delayed message contains the -holdifsent option, TelAlert then puts the message in a held state.
From that point, TelAlert proceeds as in the previous example, discarding duplicate messages until
the network management goes at least six minutes without sending a “node down” command.
Suppressing Transient “Node Down” and “Node Up” Message Pairs
The following example assumes that your network management application pings nodes every five
minutes, sends a single “node down” message when a node goes offline, and sends a single “node
up” message when the node comes back online (that is, starts responding to pings again).
176 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Use a command similar to the following for “node down” messages:
telalertc -i RachelPager -m "node 123 down" -check "node 123 down" -delay 6m
Use a command similar to this one for “node up” messages:
telalertc -i RachelPager -m "node 123 up" -cancel "node 123 down"
When the network management application sends the first “node down” command, TelAlert does
nothing immediately. Instead, it waits for six minutes (-delay 6).
� If on the next ping the network management application finds the node is up, it issues the
second “node up” command. Since its -cancel string matches the delayed command’s -check string, TelAlert sends neither message.
� If, instead, on the next ping the node is still down, the network management application
does nothing. A minute later the –delay timer expires and TelAlert sends the “node down” message. When the node comes back online and the network management application
issues the second “node up” command, TelAlert will send the “node up” message, since
there is no delayed “node down” message to cancel.
11.8 Suppressing Unwanted Messages During
Scheduled Downtime
The –filterschedule command-line option treats a schedule as a filter. For example, TelAlert
will execute the following command only if the referenced {Node144} schedule is on duty:
telalert -g support -filterschedule node144 -m "this is a test"
The typical use of this technique is to associate a schedule with a device (rather than a destination),
in order to filter out messages that are sent during scheduled downtime, or at times when
unexpected downtime does not demand the immediate attention of support staff. Normally the filter
name will be the controlling application’s name for the device, and you will use the controlling
application’s device-name variable to plug the name into the commands it sends TelAlert.
The [Limits] section’s ValidateFilterSchedule keyword determines how TelAlert handles
commands that include invalid filter names in the -filterschedule device_name option. If set
to True (the default), such commands fail with a “[Filter] {device_name} not found” error. If set to False, TelAlert processes the command as if the -filterschedule option had not been
used.
Setting ValidateFilterSchedule=False allows you to configure your controlling application
to include -filterschedule device_name in all commands it sends to TelAlert. If a
device_name schedule exists, TelAlert will check it and discard the alert only if the machine is
currently scheduled to be down. If there is no device_name schedule, TelAlert will simply ignore
the filter and process the alert. This approach allows you to create schedules as needed only for
those devices that require them. (Otherwise, to avoid error messages and consequent failed alerts
you would have to create schedules for all devices.)
Chapter 11: Applying Filtering Techniques | 177
11.8.1 Suppressing Orphan “Up” Messages
When you use the -filterschedule option, after a device’s scheduled downtime is up, the controlling application may cause TelAlert to send an “up” message for which the preceding “down”
message was filtered out. You can suppress such “up” orphan messages by using -cancelnc, a
special variation of the -cancel option.
Configure the controlling application to include -delay and -check options in the commands that generate the “down” messages, and -cancelnc options in the commands that generate the “up” messages. For example:
telalertc -g support -m "node 2302 is down" -filterschedule SystemUp -check "node 2302 is down" -delay 5m
telalertc -g support -m "node 2302 is up" -filterschedule SystemUp -cancelnc "node 2302 is down"
With those commands, TelAlert will send the “up” message only if its -cancelnc string matches the -check string of a message that is not in a delayed state, for example, one that has been responded to with an ackhold. If TelAlert does not find such a match, it does not send the “up”
message, and also deletes any delayed messages that match the –cancelnc string. In other words, TelAlert sends an “up” message only when a “down” message has been sent and has not yet
been cleared.
11.8.2 When a Device Does Not Come Back Online as Scheduled
But what if the device does not come back online after the scheduled downtime? Your network
monitoring program thinks it has already sent at least one “down” message, and it may not send
another as soon as you would like. For prompt notification of a device’s failure to come back up from
scheduled downtime, add a -delay option to the command:
telalert -g support -m "node 2302 is down" -delay 5m -filterschedule SystemUp -check "node 2302 is down"
When you use -delay in combination with -filterschedule, TelAlert does not discard messages
during downtime. Instead, it delays them until the scheduled uptime, plus the number of minutes
specified in -delay. Send your “up” messages with the following command, and the “down”
messages will be sent only if the machine does not come back online within five minutes of the
scheduled time:
telalert -g support -m "node 2302 is up" -filterschedule SystemUp -cancel "node 2302 is down"
178 | TelAlert 6e™ Administrator Guide - Version 6.1.29
11.9 Filtering Messages by Source
The telalert.alert file can contain, among other things, certain filtering information referred to
by TelAlert in determining whether or not it should process each notification it receives. For instance,
as discussed above, there are ways (both automatic and manual) to load a -check value into this
file, so that any messages to which a matching -check string is affixed are discarded.
It is also possible to load a -source value into telalert.alert, so that TelAlert discards all
subsequent messages with matching –source strings. This lets you ensure that no messages from a specified source are processed.
All operations related to -source filtering must be carried out manually; they cannot be performed
as part of a send. For example:
telalert -insert -source NetworkMonitor
This inserts the -source string into telalert.alert, causing TelAlert to begin discarding
matching messages.
telalert -delete -source NetworkMonitor
This deletes the -source string from telalert.alert, causing TelAlert to stop discarding
matching messages.
telalert -verify -source
This causes TelAlert to list the –source strings currently stored in telalert.alert.
11.10 Pattern Matching
TelAlert has long included various administrative commands that can be used to view, manage, and
modify alerts in progress. These include -show, -clear, -nak, and -ack, just to name a few.
These commands can be used with an Alert ID to act on a specific alert, or they can be used with
various command line options to act on alerts that meet specified criteria. For example, you can use
these command—
telalert -show -source remedy telalert -show -source openview
—to specify that the command be executed against only those alerts that have a particular
–source string associated with them.
Beginning with TelAlert 5.4, you have much greater flexibility in specifying what alerts are acted on
by administrative commands. This flexibility is based on an entirely new section, called [Patterns],
which has been added to the configuration file.
Chapter 11: Applying Filtering Techniques | 179
Pattern-matching provides support for a wide range of Boolean and wildcard expressions. For
example, you can combine the two commands presented above into a single command:
telalert -show -selectpe source "remedy|openview"
-selectpe means “select pattern expression.” You can specify alerts according to message
content:
telalert -show -selectpe mdefault "printer.*(down|dead)"
This translates into “show all alerts that contain the word printer and either the word down or the
word dead.” You can create expressions that include unlike criteria:
telalert -show -selectpe user tom -selectpe mdefault help
This translates into “show all alerts that are (1) associated with the user Tom and (2) contain the
word help in the message.” By default, multiple –selectpe clauses are joined with a logical AND.
You can override this default with the –selectpm option, which means “select pattern match.” By adding this—
-selectpm "!user & mdefault"
—to the end of the above command line, you would be specifying those alerts that contain the word
help and are not associated with the user Tom.
11.10.1 Other Uses
There are several other command-line options available as part of TelAlert 5.4’s pattern-matching
functionality. These are designed to allow you to use it with the elimination of duplicate messages,
filtering, and the automatic cancellation of unwanted messages.
-checkpe
The –checkpe operator is used to compare a new message against messages already in the
TelAlert queue. Where previously, you might have used:
telalert -i foo -m foo -check printer is down
to prevent duplicate messages being issued with the exact check sequence specified, the -checkpe
option provides much more flexibility:
telalert -i foo -m foo -checkpe mdefault "printer.*down"
This command checks for messages that contain the string printer followed by zero or more
characters followed by the string down.
180 | TelAlert 6e™ Administrator Guide - Version 6.1.29
A more complex example could be:
telalert -i foo -m foo -checkpe mdefault "printer.*(down|dead)"
This command checks for messages that contain the string printer followed by zero or more
characters followed either by the string down or the string dead.
-filterpe
A -filterpattern is used in conjunction with -i/-g/-l/-c/-cpl and -mto filter messages. The pattern expressions are applied to the command line parameters specified with –I and -m. If the match expression is true, the message is filtered.
For example, to filter out automatically generated "Node Down" messages that contain references to
Printers:
telalert -i someone -m Node $2 Down -filterpe mdefault "printer"
will filter (skip) any message with the text "printer" in it.
-cancelpe
A –cancelpattern is used in conjunction with -i/-g/-l/-c/-cpland -m to cancel the new
message if a matching message is found. The pattern expressions are applied to existing Alerts; if
the match expression is true for an Alert, the Alert is cleared. The new message is dropped if any
Alert that was cleared had status SS_Delayed. The new message is also dropped if no Alert matched
and the -cancelnc option as specified.
11.10.2 Pre-Defining Regular Expressions
Since compilation of regular expressions (RE) can be expensive, and the possible combination of
options can be complex, it’s possible to predefine them in the [Patterns] section.
A simple pattern to match entries with Configuration names containing "Sky" (case-insensitive) could
be:
{ConfSky}
PEConfiguration=’Sky’
Match=PEConfiguration
A simple string like this is treated as though it had been specified as ".*Sky.*", meaning "0 or more characters, ’sky’, 0 or more characters".
To use this to show active sends to SkyTel (assuming that all SkyTel Configurations’ names contain
"Sky"), use:
telalert -show -selectpattern confsky
Chapter 11: Applying Filtering Techniques | 181
The following pattern additionally filters out entries with a user value other than ".*Ross.*"
{ConfSkyUserNotRoss}
PEConfiguration=’Sky’
PEUser=’Ross’
Match=PEConfiguration & !PEUser
These same tests can be implemented using adhoc patterns specified on the command line, such as
the following:
telalert -show -selectpe configuration "sky"
and:
telalert -show -selectpe configuration "sky" \-selectpe user "ross" \-selectpm "configuration & !user"
12
Setting Up and Applying
Schedules 12.1 Overview
Instructions for using [Schedule] definitions to specify the times when destinations are valid for
sending notifications.
12.2 Getting Started
12.2.1 What are Schedules?
[Schedule] definitions, like [Filter] definitions, are a means of qualifying destinations. If a destination is associated with a [Filter] definition, TelAlert understands the conditions under
which it can and cannot send a message to this destination—conditions determined by the tags
accompanying the message and the rules comprising the [Filter] definition. Similarly, if a
destination is associated with a schedule, TelAlert understands the times during which it can and
cannot send a message to this destination—times determined by the associated schedule and—
optionally—the priority of the message.
At its most basic, deploying a schedule involves associating a [Schedule] definition with a
destination and letting TelAlert send or not send to the destination according to whether the
destination is on duty at the time.
Commonly, however, schedules are used in conjunction with groups or users, as well as with
priority settings assigned to individual messages. In the first case, a schedule might be used to
qualify the destinations comprising a group, so that those that are on duty are automatically
distinguished from those that are not. In the second, a schedule is associated with one or more
destinations by referring to it in a [User] definition and then invoking the [User] definition in
the relevant destinations. Priority settings allow you to invoke alternate [Schedule] definitions
that extend a regular schedule’s hours for messages of a certain degree of importance; you can
also ensure that extremely urgent messages are sent, without regard for any schedule.
184 | TelAlert 6e™ Administrator Guide - Version 6.1.29
12.2.2 Needed Information
To set up schedules, you simply need to know the on-duty hours for each of the destinations to
which you want a schedule to apply. You can also include information about vacations and holidays,
extra duty times, and the circumstances under which you would like a message to be sent even
during off-duty hours.
Managing Schedules
This section covers the following topics:
� Schedule Types
� Viewing Schedules
� Creating Group Member Schedules
� Assigning Group Member Schedules
Schedule Types
The following schedule options allow users to determine exactly when they and each of their
devices are on duty and available to receive alerts. Some of the schedules are user specific like
vacation and device schedules. Others are specific to a particular group like group member and
extra duty schedules, only affecting alerts that are sent to a particular group. Although all
schedule types are listed below, this section focuses on schedules assigned at the group member
level.
� Holiday Schedules are system wide and affect all users in the system. Holidays are
shown in the group member schedule calendar display.
� Vacation Schedules are user specific. Users will not receive alerts during their designated vacation time.
� Vacation times appear in the group member schedule calendar display.
� Device Schedules are user specific and determine when an individual device is on duty
and available to receive alerts. Device schedules affect alerts sent directly to the device,
the owner of the device and when alerts are sent to groups containing the device or
owner. Device schedules are created for individual devices and are associated with the
owner of the device. The device schedule can only be assigned to this particular owner’s
devices. Other user’s will not see the device schedule in the Default Schedule drop-down list on the Edit Device Schedule page.
� Group Member Schedules are group specific and only influence alerts that are sent to
the group. Each member of a group is assigned a schedule which determines whether or
not that member will be notified when alerts are sent to the group. Users, devices and
groups may be members of multiple groups therefore having multiple schedules or may not be a member of any groups and have no schedules.
Schedules Specify On-Duty Hours
The main component of a schedule is a list of on-duty hours. Unless you create an
exception to these hours, they represent the only times during which a destination associated with the schedule is on-duty.
Chapter 12: Setting Up and Applying Schedules | 185
� Extra Duty Schedules, like group member schedules are group member specific. They
are assigned when it is necessary for a group member to be on duty outside of their Regular Schedule hours.
Note: All of the schedule types above can be viewed in the group member schedule calendar
display.
Viewing Schedules
Schedules can be viewed on the Home page of the application and for staff users under the
Schedules tab. Users will only see schedules if they belong to a group since the schedule display is
based on group membership. As a supervisor or administrator, you will also see the schedules for
all groups belonging to your department. The system administrator can see the schedules for all
groups in the system.
The schedule display on the Home page is a view of the user’s current week schedules. The
display on the Edit Group Schedules page for administrators and supervisors and the Schedules
page for staff users can be set to either day, week or month view. In all views your scheduling
status is represented using the following color codes:
� On Duty - You (or the devices you own) are scheduled to receive alerts during these hours.
� Extra Duty - You (or the devices you own) are scheduled to receive alerts during these hours, regardless of whether it is a vacation or holiday period.
� Vacation - The system will not alert you unless Extra Duty is configured during your vacation hours.
� Holiday - The system will not alert you on days specified as a holiday by the system administrator, unless Extra Duty is configured during the holiday.
� Off Duty - You (or the devices you own) are not scheduled to receive alerts during these hours.
� Current Time - The current time of day is highlighted in the schedule display as a vertical
orange bar. This is referred to as the Current Time Indicator and allows the user to reference the current time in the Time Zone selected in the Time Zone drop-down menu.
To display schedules in the future or past, use the Jump To date field or calendar icon to show
other duty cycles.
186 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 25. Schedule Month View
Note: By default, the schedule pages will display the time of day relative to the time zone of the
logged in user, but you can see how schedules appear to users in other time zones. So, even if you
were a user from New York (EST), you could view your schedule as it would appear to a user in San
Francisco (PST) by selecting Pacific Time in the Time Zone drop-down menu.
12.3 Scheduling Approaches
12.3.1 Schedules and Default Logic
Which Schedule is in Effect?
The way scheduling works in TelAlert 6e is different from TelAlert stand alone. In TelAlert 6e all
schedules at all levels are taken into consideration. Schedules are applied as follows:
� The simplest case to consider is sending a message to a Device that has a personal
Schedule assigned by the User. In thisa case, TelAlert will deliver the message based on the Schedule attached to the Device by the User.
� The most common scenario is that Supervisors assign Schedules to User and Devices as
they are added to Groups, and no Schedule is directly assigned to a Device by the User.
In this case, The Schedule assigned by the Supervisor applies and is unique to the Group.
That is the same User or Device can be assigned to another Group with a different Schedule.
� The last case combines these two. In this scenario, Users have assigned personal
Schedules to Devices and these Devices or Users who own them are being added to a
Group by a Supervisor. When Devices have Schedules assigned at the User level, Supervisors have two choices when adding them to a Group:
� Supervisor accepts the Default Schedule
� The message will be delivered according to the Schedule attached to the
Device by the User.
� This approach is useful when a User’s on-duty hours are the same across
many Groups.
� A change to the Schedule assigned to the Device will propagate up to all
the Groups where the Supervisor accepted the Default Schedule.
Chapter 12: Setting Up and Applying Schedules | 187
� Supervisor overrides the Default Schedule
� The message will be delivered according to the Schedule attached to the
Device by the Supervisor.
� This approach is useful where a User’s on-duty hours need to be different
in different Groups.
� The Schedule associated with the User or Device is controlled by the
Supervisor and cannot be changed by the User.
In any case, the Schedule displayed in the Web UI is the Schedule that will apply to the User. This
means that if a user has multiple devices and at least one device shows the recipient as on duty
the alert will successfully go through.
Checking from the Command Line
In order to check if a schedule is in effect, use the following command:
telalertc -checkonduty schedule testsched
or
telalertc -checkonduty schedule testsched -datetime 2001/07/04@08:00
The first syntax checks if the schedule is on duty "right now"; the second syntax checks if the
schedule is on duty on July 4 at 8AM. Besides checking an individual schedule, you can check other
definitions that have schedules linked to them, such as destinations, users, etc. For instance:
telalertc -checkonduty destination testdest
12.4 Assigning Device Schedules
Devices can be assigned schedules so that they are only available to receive alerts during specified
periods when they are considered on duty. Users can create and assign schedules for their own
devices. Supervisors and Administrators can create and assign device schedules for all devices
owned by users in their department. Defining device suchedules is optional. If you do not assign a
device schedule, the system’s default setting of 24x7, always on duty is explicitly applied.
Figure 26. Edit Device Schedule page allows user to assign a default device schedule.
188 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Device schedules tell TelAlert whether a device is on duty at the time an alert is sent. Setting up
schedules for devices rather than for people might seem counterintuitive. However, setting up
schedules for devices makes it possible to send alerts to a particular device--John’s phone--
during certain hours and to a different device--John’s pager--during other hours.
To assign a device schedule, do the following:
1. Click the Devices tab. The Manage Devices page displays.
2. Choose the device from the list by clicking the to the left of the device’s name.
3. Select the Schedule tab.
The default schedule for new devices is 24x7, indicating that the device is available to receive
alerts at any time.
4. To assign a device schedule, select the desired schedule from the Default Schedule drop-down
menu. Select the date the schedule should go into affect in the Start Date field followed by the
Save button.
Chapter 12: Setting Up and Applying Schedules | 189
Note: Device schedules are listed below global schedules in the Default Schedule drop-down
menu under the User Defined Schedules heading. Device schedules are considered User Defined
because they are linked to the owner of a device and are available to that user only for
assignment to their devices. Other users in the system will not have the ability to assign another
user’s device schedule to their own devices.
If you would like a schedule to be available to more than one user, create a global schedule
instead of a device schedule. The global schedule will appear in the Default Schedule drop-down
menu under the Global Schedule heading and will be available for use by all users in your
department.
5. When the device schedule has been assigned you will see a confirmation page indicating the
device details (in this case the schedule) have been updated successfully.
190 | TelAlert 6e™ Administrator Guide - Version 6.1.29
12.4.1 Adding a New Device Schedule
If you have not created any device schedules or do not see the desired schedule in the Default
Schedule drop-down list you can create a new device schedule.
6. To create a new device schedule select the Add a New Schedule button.
7. In the Name field, enter a name for the device schedule. The name should be unique so that
when it is displayed along with other device schedules, it is self-documenting. The device name
can be up to 20 characters long.
8. In the Description field, enter a brief description of the device schedule. This is optional, but
very useful when managing many schedules.
9. Indicate the Repeat Pattern and On Duty Hours Pattern and select the Next button.
10. Enter the times and days of the week that the device will be on duty and available to receive alerts.
Note: A device with the 9 to 5 device schedule will NOT receive alerts sent on Monday at 8:59.
The device will receive alerts sent on Monday at 9:00. Additionally, they will NOT receive alerts
sent on Monday at 17:01.
1. Select the Save button.
The device schedule is now available to assign to the selected device and any additional devices
owned by the same user on the Edit Device Details page.
2. To assign this or other device schedules to a device see Assigning Device Schedules at the top of
this section.
Chapter 12: Setting Up and Applying Schedules | 191
12.5 Creating Group Member Schedules
Global and group member schedules can be created by supervisors and administrators. They can
be made available to All Groups or limited to a particular group within the user’s department.
There are two types of regular schedules: a weekly schedule and a rotating schedule. The
standard weekly schedule starts on Sunday and ends on Saturday.
Rotation Schedules
The rotating schedule can start on any day of the week and can consist of anywhere from 1 to 98
days. Once this member’s schedule is established the next member with the same schedule will be
on duty for the specified period of time. In the case of vacation or unexpected leave the on duty
member’s date should be switched to reflect as on duty and the start dates can be readjusted
upon the missing member’s return.
Figure 27. The Manage Schedule page allows supervisors and administrators to view existing schedules.
192 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 28. Add New Schedule pages
Note: When a Schedule is created, it is not tied to a Time Zone. When a Schedule is assigned to
a User or Device, the Schedule will use the Time Zone associated with the profile of the User or
the User’s Device(s). See example in Effect of Time Zones section below.
12.5.1 Assigning Group Member Schedules
Group member schedules can be assigned by supervisors and administrators to group members
on the Edit Group Member Schedule page. TelAlert 6e gives supervisors and administrators the
option of overriding the device schedule with the group schedule or accepting the device
schedule for the group member’s schedule. If a group member schedule is not assigned, the
device schedule will determine the group member’s availability.
For a detailed procedure, refer to the Assigning Schedules to Group Members section in
Chapter 16.
Figure 29. Schedules are assigned to individual group members on the Edit Group Member Schedule page.
Chapter 12: Setting Up and Applying Schedules | 193
All members of a group must be assigned a Regular Schedule. When group members are originally
added their device schedule determines their availability. To change the default device schedule,
select one of the schedules in the Schedule drop-down menu and a Start Date. This will override
any Device Schedule set by the User.
12.5.2 Effect of Time Zones
As mentioned above, Schedules will be tied to the Time Zone of the User or the User who owns
the Device. This can have the effect of two Devices in the same Group with the same Schedule
having different on-duty times when the Users who own the Devices are in different Time Zones.
For example, a Supervisor creates a Group named US_Support. The Supervisor adds User Anne,
based in the Eastern US Time Zone, and has applied the Day Shift Schedule to her in this Group.
The Supervisor also adds User Bill, based in the Pacific US Time Zone, and has applied the same
Day Shift Schedule to him in the same Group. When the Scheduled is displayed (below), we see
that the on-duty times offset based on the different Time Zones associated with the two Users.
194 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Creating Extra Duty Schedules
Extra Duty schedules can be created for group members when they are required to work outside
of their regular schedule hours. To access the Extra Duty section, you must select the Override the
Default Schedule radio button, indicating that the schedule for the group member is being altered
from the group member’s default schedule. You can leave the default schedule selected in the
drop-down list or assign a different Override Schedule.
In the Extra Duty Schedule section enter the date and time the group member will be on duty and
the End date and time defining when the group member is no longer on duty based on the extra
duty schedule.
12.5.3 Schedules and [Filter] Definitions
A schedule, like a [Filter] definition, is a means of destination qualification. Whereas a
[Filter] definition determines whether a destination is valid based on the tag or tags
accompanying the message, a schedule determines whether a destination is valid based on the
time the message is to be sent.
You do not have to do anything special to make schedules and [Filter] definitions work
together. If a destination is associated with a schedule and a [Filter] definition, TelAlert will
send it a message only if it finds that the destination is both on duty and valid according to the
terms of the [Filter] definition.
For information on setting up and using [Filter] definitions, refer to Chapter 10: Applying
Filtering Techniques.
12.5.4 Schedules and [User] Definitions
In TelAlert 6e assigning a schedule to a user is done when the User is a member of a group. If the
user is not part of a group then their device schedule determines their availability. If their devices
have no schedules associated with them then they are considered on duty 24x7.
You may find that tying schedules to devices via group member definitions is valuable whenever
the schedules at work in an organization are connected with people, as opposed to the devices
through which they can be contacted. This method allows you to think strictly in terms of people
and their work schedules as you set up the [Schedule] definitions for notification. If you are
already using group member definitions for some other purpose (to link [Filter] definitions to
destinations, for instance), this method makes even more sense, since the group member
definitions can be made to serve two purposes.
Chapter 12: Setting Up and Applying Schedules | 195
12.5.5 Schedules and Message Priority
The keyword discussed here—OverrideSchedulePriority—is usually used to enable TelAlert
to look to override restrictive schedules in determining how to handle messages of a certain
specified urgency.
OverrideSchedulePriority
You can take special treatment of high-priority messages a step further using
OverrideSchedulePriority in a destination, a group, or a [User] definition. When a message’s
priority meets or exceeds this threshold, TelAlert will send it, completely disregarding all questions
of schedule. Simply add the OverrideSchedulePriority setting, where appropriate in the
Advanced tab of the TelAlert 6e Web UI. For example:
To use this feature, send a message with a Priority that is equal to or greater than the
OverrideSchedulePriority setting. For example:
telalertc –i Bill_email –priority 75 –m “Node Down”
There is no schedule that corresponds to OverrideSchedulePriority, since this keyword
overrides all schedules rather than invoking an alternate one.
13
Representing Users 13.1 Overview
Instructions for creating [User] definitions and using them to link values to destinations, determine TelAlert dial-in/dial-out access behavior, and perform administrative tasks.
13.2 Getting Started
13.2.1 What Are Users? What Are They For?
In TelAlert, it is important not to confuse destinations with people: a destination such as a pager
may be one of several ways a given individual can be contacted, or a destination may not be
associated with a unique individual or with any people at all—a single pager may be carried by a
different person each shift, for instance, and an electronic signboard is often used to deliver
messages to a roomful of people. [User] definitions offer a way of introducing the notion of
“people” into TelAlert’s view of the world. Their uses fall into three main categories.
1. Values for Inheritance by Associated Destinations
By referring to a [User] definition in a destination, you can cause the destination to inherit its
values: Schedule, AlternateSchedule, Password, MinFilterPriority and
MaxFilterPriority, etc. Thus, TelAlert knows how to assess the destination’s validity in light
of the message’s –priority or -filter tags, or how to determine the identity of someone with
whom it is interacting (i.e., by asking for a password when the person attempts to respond to a
notification). Note that some keywords can only be assigned to a User as a default setting for all
Users.
2. Values for Dial-In and Dial-0ut Access
Some [User] definition settings are not inherited by associated destinations; rather, they serve
to determine how TelAlert behaves when a person dials in to TelAlert and, by providing a password,
identifies himself or herself as that user.
198 | TelAlert 6e™ Administrator Guide - Version 6.1.29
3. User-Based Administrative Techniques
There are several useful administrative techniques pertaining to users. For instance, since
destinations are associated with [User] definitions, it is possible to look at outstanding messages
sent to these destinations in terms of the people with whom the destinations are associated. This is
helpful because it may be possible to notify a single person by means of a number of different
destinations. There are also commands for clearing and releasing all messages associated with a
specified [User] definition, as well as commands for viewing a list of all defined [User]
definitions.
13.2.2 Needed Information
[User] definitions must be used in conjunction with all destinations in TelAlert 6e and
destinations that invoke [Configurations] definitions of Type=InteractiveVoice or
InteractiveTTS could not operate without a user. They are also required if you wish to provide
dial-in access to TelAlert via a Dialogic telephony card. These requirements are security
precautions: human users will have to provide the password specified in their [User] definition
anytime they interact with TelAlert by these means. Please note that when LDAP is enabled for
Web login authentication, this is not the same as the user’s Web login password. There is a
separate password stored internally to TelAlert.
13.3 User Roles
TelAlert 6e customers have requested the ability to modify existing roles and create new ones.
Role Management will associate roles and permissions and provide better management of Users'
permissions.
13.3.1 Key Principles
• The system will maintain the current permissions for the existing predefined roles.
• The system will only allow users to create roles with permissions that are a subset of their
own.
• Permissions will only allow users to grant permissions to others that share a department
with the user.
13.3.2 Definitions
Roles
A role is a label applied to a set of permissions that may be given to a user.
Permissions
Each permission has 4 elements: Create, Read/Run, Update and Delete.
Chapter 13: Representing Users | 199
Predefined roles
These are roles that are predetermined and included with the original setup.
TelAlert 6e will have 4 predefined roles: System Administrator, Administrator,
Supervisor and Staff.
System Administrator
A predefined role, a System Administrator can view, create, update and delete all
users, devices, groups, departments and schedules in the system. They may run
all reports. There is only one System Administrator per installation. The System
Administrator may not be deleted or edited. The System Administrator is
automatically assigned to all Departments.
Administrator
A predefined role, an Administrator can view, create, update and delete
departments, all devices, groups, and schedules within their department and all
users except the System Administrator. They may run all reports within their
departments.
Supervisor
A predefined role, a Supervisor can view, create, update and delete all devices,
groups and schedules within their department and all users except Administrators
and the System Administrator. They may run all department reports.
Staff
A predefined role, Staff level users have access to basic profile, device and
messaging features. They also possess the ability to subscribe to groups, view
groups they are a member of and view their own schedules. They can create and
maintain their own devices and assign device schedules.
13.3.3 Viewing Tabs
The top level tabs in the system (Home, Alerts, Users, Devices, Groups, Schedules, Subscriptions, Reports, Admin Tools) are only viewable if the user has Create, View, Edit or Delete permissions on at least one of the entities displayed in the tab.
The Home tab is visible to the user if the Alerts, Devices, Groups or Schedules tab is visible.
The Subscription tab is visible to the user if the Create, Edit, or Delete permission is set for User’s Own Groups.
If the user has no permissions then no tabs will be visible. Such a user will only be able to receive alerts on devices created for them by other users with greater permissions.
200 | TelAlert 6e™ Administrator Guide - Version 6.1.29
13.3.4 Role Editor Screen
General
Selecting a create, edit or delete permission automatically gives the corresponding view permission; the view permission check box is checked and grayed out. Selecting a create permission automatically gives the corresponding edit permission; the edit permission check box is checked and grayed out.
All role changes take effect when the user logs in; if a user’s role is changed while they are logged in, they will continue with their old permissions until they log out and log in again.
Navigation – Role Management Page
Users with permissions for the Role Management page can view and edit pre-defined and custom roles.
Chapter 13: Representing Users | 201
Navigation – Edit Role Page
The Edit Role page allows administrators to define custom user roles for TelAlert 6e. It contains a set of tabs with checkboxes for the various permissions to match the tabs users see in the Web UI. All permissions that the user does not have are unchecked and unavailable (grayed out).
To get an idea how the roles are set up, it may be a good idea to look at some of the Roles already defined in TelAlert6e. This will help you define your own roles and permissions. Let’s take a look at the default “Supervisor” role. Click on the notepad icon located to the left of the Supervisor role, you should see this screen:
On the Alerts Tab you see the permissions given to Send Alerts, View ALL Users Sent or Received Alerts, Respond To Alerts and create Alert Templates, Edit Alert Templates or Delete Alert Templates.
If you remove any of the permissions on this “default” role, you affect all of the Users that have been given this role of Supervisor. In this case, it would be better to create another “Supervisor” role, give it a different name, and assign that role to the Users you want to limit some Supervisor capabilitities.
202 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Next, click on the Edit Role Details Users Tab, you should see this screen:
This screen shows the capabilities this role has pertaining to User records. They can edit their own User record and change their own Devices. They also have permissions to Create, Edit, and Delete User records as well as Create, Edit, and Delete ALL User Devices.
Next click on the Edit Role Details Groups Tab, you should see this screen:
This screen shows the capabilities this role has pertaining to Group records. They can Create, Edit , and Delete Groups as well as Group Subscriptions. They can also Edit Group Advanced Parameters.
Chapter 13: Representing Users | 203
Next click on the Edit Role Details Schedules Tab, you should see this screen:
This screen shows the capabilities this role has pertaining to Schedules. They can Create, Edit, and Delete all of their schedules as well as schedules for ALL Users, Group Schedules, and Global Schedules.
Next click on the Edit Role Details Reports Tab, you should see this screen:
This screen shows the capabilities this role has pertaining to Reports. They can run the Department Metrics report as well as the Department Group Traffic report.
204 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Next click on the Edit Role Details Admin Tools Tab, you should see this screen:
This screen shows that the Supervisor Role does not have permissions t o access anything on the Admin Tab except the System Configuration permission. Remember, this is the “Default” permissions for the Supervisor Role. Changing anything here will affect anyone who currently has the Supervisor role.
Now that you have seen how the “Default” permissions are configured, you should have a good idea how to set up your own custom Roles and Permissions.
Chapter 13: Representing Users | 205
Adding your own Custom role:
When you entered the Role Management page from the Admin Tab you are given the option to Create a new role. Click on the “Add A New Role” button. You should see this screen:
Just enter the name you want to call this new role in the Role Name field, then select the permissions you want to give this new role. You can move through all of the Tabs to select your options, then click Save to create your new Role. Keep in mind that if you Select “Create” it will also give them Edit capability.
206 | TelAlert 6e™ Administrator Guide - Version 6.1.29
TIP:
You can take an existing Role and “Save As New” to help you “copy” a role and modify as necessary.
For Example,if you click on one of the roles already created and modify it , then type in a different name, the “Save As New” button appears. You can then save it as your new role and modify accordingly. See screenshot below:
After you have Saved your new role, you will want to assign it the User or Users you created it for. Keep in mind that they will have to log off and back on for the new permissions to take effect.
Chapter 13: Representing Users | 207
13.4 Managing Users
Both supervisors and administrators can manage users. They can add users to the system and
view, edit and delete users within their departments. They can also manage user information to
control how alerts are delivered and escalated. Examples of this user information are as follows:
� What department or departments does the user belong to?
� What is the user’s role--staff, supervisor, or administrator?
� What is the user’s schedule and time zone?
� Can alerts be sent to the user, or can alerts only be sent to a single device that is shared among several users?
� Is an access key needed to send an alert to the user?
� What optional information about the user is inherited by devices associated with the user and what information is not inherited?
Before adding users in TelAlert 6e, you should consider these and other questions.
Note: When the system contains large numbers of users, the users can be filtered by
department using the By Department: drop-down menu and Search field in the Filter Results
section at the top of the Manage Users page.
Administrators can add new users to the system by importing user data through the batch
import process or by adding them manually (one at a time). Supervisors can only add users
manually.
This section describes how to add new users manually. To add new users by importing data using
batch import, see Importing Data.
13.4.1 Adding Users
To add new users manually, do the following:
1. Click the Users tab. The Manage Users page appears.
208 | TelAlert 6e™ Administrator Guide - Version 6.1.29
2. On the Manage Users page, click the Add a New User button.
3. Complete the required fields, and then click Save. For help completing the fields, see Table E,
Click on the Return to the users List link to return to the Manage Users page.
Chapter 13: Representing Users | 209
4. After adding the user you will see a confirmation page. From this page you can:
� Verify the user information is correct in the User Details section at the top of the page.
� Click the Edit this user link to edit the user details or add advanced parameters for the user.
� Click the Add another user link when adding multiple users.
� Click the Add a device to this user link to add information about how the user would like to receive notifications.
� Click on the Return to the users List link to return to the Manage Users page.
210 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Field Description
Active If a user is active, there are no restrictions to their ability to
receive alerts. If the user is inactive, the following restrictions
apply:
� The user cannot receive alerts.
� The user can be added to a group, but the user will not receive alerts sent to that group.
� The user’s devices can be added to a group, but the user’s devices will not receive alerts sent to that group.
Any user can change their Active status at anytime using the My
Account link on the Home page.
Advanced
Parameters These parameters, such as AcknowledgeWait, are TelAlert
keywords. For descriptions of these keywords, see the TelAlert
TelAlert 6e Keyword and Command Reference.
Note: The advanced parameters can be accessed by clicking on
the Advanced tab when editing a user. Advanced fields are not
accessible until after a user has been saved.
Access Key If an access key is entered, the access key will be needed to send
an alert to this user or any device owned by this user.
Note: This field is found on the Advanced Settings page.
Display User on
Recipients Page If you set this to No, this user will not appear in the available
recipients list on the Send a New Alert page.
Note: Inactivating the user will override the Display User on
Recipients Page selection and the user will not display on the
recipients page.
When a user is active, the user and their devices can receive alerts. For details, see Table E, Click
on the Return to the users List link to return to the Manage Users page.
To make a user active or inactive, do the following:
1. Click the User tab. The Manage Users page appears.
Chapter 13: Representing Users | 211
2. Click the icon next to the user record in the Manage Users list.
3. On the Edit User page, modify the Active field.
4. Click the Save button.
212 | TelAlert 6e™ Administrator Guide - Version 6.1.29
To modify an existing user’s information, do the following:
1. Click the User tab. The Manage Users page appears.
2. Click the Edit User icon next to the user record in the Manage Users list. The Edit User Details
page appears.
3. Edit the necessary fields, and then click. For help completing the fields, see Table 18: User
Fields.
Note: Changing a user’s departments will affect which users, devices and groups the user
can view. It may also affect the ability of other users to access or view the edited user’s
information.
Example of the Possible Effects of Editing a User's Department
� Department A includes User 1, User 2 and Group Y. User 1 is a member of Group Y.
� Department B includes User 3 and Group Z.
User 1 Details
� User 1 belongs to Department A. User 1 can see all users, devices and groups that belong
to Department A.
� User 1 is a member of Group Y. User 1 can see Group Y as well as all users, devices and
groups that are members of Group Y.
� Since User 2 belongs to Department A, User 1 can see User 2, and all devices owned by User 2.
� User 1 is not able to see User 3 and Group Z since they do not belong to Department A.
Department Field Edited
� User 1 is removed from Department A and added to Department B.
Result of Editing Department
� User 1 belongs to Department B. User 1 can see all users, devices and groups that belong to Department B.
� User 1 remains a member of Group Y until they are manually removed from the group,
however they will no longer see Group Y since Group Y does not belong to Department B.
� User 1 will no longer see User 2 or devices owned by User 2.
� User 1 will see User 3 and all devices owned by User 3.
� User 1 will see Group Z but will not automatically become a member of Group Z.
Note: Example above is based on users with the role of supervisor.
To delete a user from the system, do the following:
4. Click the User tab. The Manage Users page appears.
5. Click the Remove User icon next to the name of the user you want to delete.
Chapter 13: Representing Users | 213
13.5 Creating a [User] definition: Essentials
It common to set all passwords to be encrypted before being written to the telalert.sects file
by setting EncryptPasswords=True.
13.6 Values for Inheritance by Associated
Destinations
A [User] definition can contain many values in addition to the single required one (Password).
Many of these optional values are inherited by all destinations associated with the [User] definition, according to one of several rules. While you could set them directly in the destination,
you might want to set them in the [User] definition instead because (1) there are two or more
destinations associated with the [User] definition and you want these settings to apply to them all, or because (2) you want these settings to be linked conceptually with the person to whom the
destination belongs, rather than with the destination itself.
The keywords that, when set in a [User] definition, are inherited by associated destinations are listed below, categorized according to the rule by which the inheritance proceeds. Note that a value
set directly in the destination definition always overrides values set anywhere else.
13.6.1 Direct Inheritance
Direct inheritance is the most common rule. For these keywords, the value set in the [User]
definition applies to the destination just as if it had been set there directly; no other value is
considered.
� AccessKey
� Schedule
� AlternateSchedule
� Filter
� ListFilter
� Notification
� NotificationLog
� NotificationReply
Password is Required
An active [User] definition must contain a password setting. TelAdmin will not allow you
to save a [User] definition without a password.
If you create a [User] definition in which both the name and password would be indistinguishable from those in another [User] definition when entered using a touch-tone telephone keypad, TelAlert will issue a warning.
214 | TelAlert 6e™ Administrator Guide - Version 6.1.29
13.6.2 Minimum of the [User] Value and the [Destinations] Default
For these keywords, the value set in the [User] definition applies to the destination only if it is
less than the default value assigned to all destinations.
� AlternateSchedulePriority
� OverrideSchedulePriority
� MinFilterPriority
13.6.3 Maximum of the [User] Value and the [Destinations] Default
For these keywords, the value set in the [User] definition applies to the destination only if it is
more than the default value assigned to all destinations.
� MaxFilterPriority
� OnDutyWait
13.6.4 Maximum of the [User] Value, the [Destinations] Default, and the [Configurations] Value
For these keywords, the value set in the [User] definition applies to the destination only if it is
more than both the default value assigned to all destinations and the value assigned (directly or by
default) to the [Configurations] definition to which the destination points:
� Priority
� AcknowledgeWait
� ReleaseWait
13.7 Values for Dial-in and Dial-out Access
Many settings that can appear in a [User] definition govern how TelAlert behaves when a person
identifies himself or herself as that user after either dialing in to TelAlert or being telephoned by TelAlert.
DialInMenuAccess and, for instance, determine whether TelAlert offers the user a designated
voice menu of choices when the user dials in or is called. If either is set to True, you use the
Menu setting to designate the (script-based) voice menu for TelAlert to play; you could set up a
unique menu for every user, or a certain set of users could all be played the same menu. Consider
this example:
[User]
...
{Rachel}
Password=12345
DialInMenuAccess=True
DialOutMenuAccess=True
Chapter 13: Representing Users | 215
Menu=StandardVoice
These settings have very little to do with the destinations associated with {Rachel}. The one
connection is a general one: Rachel will be able to use TelAlert’s dial-in and dial-out capabilities to
access only those messages sent to destinations with which she is associated as user. However,
neither the fact that she has dial-in/dial-out access nor the Menu setting affects TelAlert’s
processing of the messages sent to these destinations. In this sense, these settings are distinct
from those discussed under “Values for Inheritance by Associated Destinations,” located earlier in
this chapter.
Below is a list of the keywords that can be assigned values in a [User] definition in order to
control TelAlert’s dial-in/dial-out behavior for that user:
� Active
� DialInMaxMessages
� DialInMenuAccess
� DialOutMaxMessages
� DialOutMenuAccess
� Menu
� ModemDialbackAreaCode
� ModemDialbackConfiguration
� ModemDialbackNumber
� Password
� VoiceDialbackAreaCode
� VoiceDialbackConfiguration
� VoiceDialbackNumber
13.8 User-Based Administrative Techniques
If your destinations are associated with [User] definitions, you can administer messages sent to
those destinations in terms of the [User] definitions with which they are associated. This may be
helpful because a [User] definition may be associated with more than one destination; it may be
convenient for you to work with all the messages relating to a person instead of having to proceed
destination by destination.
13.8.1 Viewing Messages: -show
For instance, you can see a list of all messages associated with a designated [User] definition that are in a held or ackwait state or which are still pending. To do this, issue the -show command
along with the -user tag:
216 | TelAlert 6e™ Administrator Guide - Version 6.1.29
telalert -show -user Administrator
13.8.2 Getting Rid of Messages: -clear and -release
Similarly, you can clear all non-held messages (i.e., messages in an ackwait state or which are
still pending) or release all held messages associated with the [User] definition:
telalertc -clear -user Administrator
telalertc -release -user Administrator
13.8.3 Listing Users
Another administrative function allows you to generate a list of [User] definitions. To do this,
issue this command:
telalertc -list users
1. For those [User] definitions containing a FullName value, the list you generate will
show this value instead of the name of the definition. This allows you to give your [User]
definitions a simple name (one that is easy to refer to on the command line, in destination
definitions, etc.) and still be able to determine at a glance the person to whom it belongs.
2. If ListDisplay is set to False, however, neither a [User] definition’s name nor its
FullName value will be displayed when you tell TelAlert to list all users. The default for
this value is True.
3. Finally, if you include ListFilter in your [User] definitions and assign this keyword a
value pointing to a [Filter]entry, you can impose additional restrictions on what
[User] definitions are displayed when you tell TelAlert to list them. This filtering works
just as the filtering described in the first part of Chapter 10: Applying Filtering
Techniques. Simply use a -tags value when you give the –list command, and TelAlert
will display [User] definitions according to the filtering rules you have created.
For instance, you could set up a [Filter] definition such that specifying a certain tag with the
command causes all [User] definitions pointing to that [Filter] definition to be displayed.
Having done this, you would issue a command like this to see a list of those [User] definitions:
telalertc -list users -tags RouterSupport
Alternatively, you could set up a [Filter] definition such that specifying a certain tag with the
command causes all [User] definitions pointing to that [Filter] definition not to be displayed.
The difference hinges on the Exclusive setting in the [Filter] definition. For more information,
refer to Chapter 10: Applying Filtering Techniques.
-list is Relevant for All Sections
You can issue a telalertc -list command to view a list of the definitions comprising any section in the TelAlert configuration file. Simply substitute the appropriate definition
name, like so:
telalertc -list sectionname
14
Representing Devices 14.1 Overview
The [Destination] section in TelAdmin translates to the Device tab in the TelAlert Web UI.
14.2 Managing Your Devices
Before you can receive an alert, you must be the owner of a device. The types of devices you can
use might include an e-mail account, a pager, a cell phone, and others. Your administrator can
tell you which types of devices he or she has created and activated for your organization. These
types will display in the Type/Configuration drop-down menu on the Add a New Device page.
You do not need to add a device if it has already been added for you by your supervisor or
administrator. However, if a device has been added for you, you might want to confirm that the
device is configured correctly. You may also want to assign a device schedule so that alerts are
only sent to the device during certain time periods.
To find out if you have any devices, click the tab to view the My Devices portlet. If a device has
been added for you, it will be listed on the Home page. Devices that you own are also listed on
the Devices Page found by clicking the Devices tab. Supervisors and Administrators see all
devices owned by users in their department. Staff users see only their own devices. To confirm
that a device is configured correctly for you, click the icon next to the device name. You can also
edit and delete your devices from the My Devices portlet on the Home page.
218 | TelAlert 6e™ Administrator Guide - Version 6.1.29
14.2.1 Adding New Devices
To add a new device, do the following:
1. Click the Devices tab. The Manage Devices page displays.
2. Click the Add a New Device button. The Add a New Device page displays.
3. In the device Name field, enter a name for the device. The name should be unique so that when
it is displayed along with other devices in a group, it is self-documenting. The device name can
be up to 20 characters long.
4. Assign the device an owner by selecting one of the users listed in the Owner drop-down menu.
The owner should be you if you would like the device to be associated to your user record.
Meaning that when you are listed as an alert recipient (Your name added verses your device) the
alert will automatically be sent to this device without the device being added to the alert
recipient list. Users can own many devices, but each device can have only one owner. If a device
is to be shared between multiple people, choose one of the users as the owner of the device.
When sending alerts to this device add the device as an alert recipient instead of a particular
user.
5. Select a Type/Configuration. If the desired device type does not display in the
Type/Configuration drop-down menu, an administrator needs to create it or activate it if it
already exists in the system.
Chapter 14: Representing Devices | 219
6. Administrators can create new configurations and activate existing configurations using the
TelAdmin tool in TelAlert Desktop. Use the Manage Configurations page under the Admin Tools
tab to view and reload all active configurations. Configurations must be reloaded any time a
new configuration is added or an exiting configuration’s Active/Inactive status has changed. To
reload active configurations select the Reload button on the Manage Configurations page under
Admin Tools.
It is recommended to select the Reload button on the Manage Configuration page every time a
change is made to configurations in TelAlert Desktop.
After you select a Device/Type Configuration, additional fields customized for the device type
appear.
7. Complete the configuration specific fields that appear as soon as a selection is made in the
Type/Configuration drop-down menu (i.e. An email device has a To field and a text pager has a
PIN field).
8. Click the Save button
9. After adding a device you will see a confirmation page. Verify the device details. From this page
you can click on one of the links in the Next Step section to proceed forward.
10. To define additional device parameters, select the Edit this device link and click on the tab.
220 | TelAlert 6e™ Administrator Guide - Version 6.1.29
11. Note: If you are a staff user and do not see the Advanced tab, your administrator has turned off
this feature. See Table 14. Advanced options in the devices form for additional information.
12. Make the necessary changes in the Edit Device Advanced Settings form, and then click the
Save button.
Field Input/Select
Name In the Name field, enter a name for the device. The
name should be unique so that when it is displayed
along with other devices in a group, it is self-
documenting. The device name can be up to 20
characters long.
Owner Select the owner of this device. This drop-down menu
will only allow you to assign an owner that is a member
of your department.
Device Type/
Configuration
This drop-down menu displays all the device types that
your administrator has made available to you. If you do
not see the type of device you are trying to add, ask
your administrator to have your device type enabled. To
see a list of active configurations see the Manage
Configurations page under the Admin Tools tab.
Comments/Description Enter a brief description of the device. Make sure the
comments document the device. The comment
character count displays the number of characters you
have typed in. You cannot exceed 100 characters.
Table 9. Common fields in the Devices form
Field Input/Select
To Enter the SMTP e-mail address of the device (mailbox). The e-
mail address must be valid or an error message will be
ReplyTo This is the e-mail address to which replies will be sent. This may
be left blank. This is used only when the reply address is
different from the sending address.
Subject This is the default subject when sending messages to this
device. This may be left blank.
Note: This text will be overwritten if text is entered in the
subject field in the Advanced section on the Send a New Alert
page.
Table 10. Email options in the Devices form
Chapter 14: Representing Devices | 221
Field Input/Select
PIN Enter the 10-digit phone number of the device. You may enter
hyphens and dashes.
Table 11. Text pager, interactive text pager, and GSM modem options in the Devices form
Field Input/Select
PIN Enter the pin number for the pager. The pin number can be up to
50 characters.
Table 12. Numeric pager options in the Devices form
Field Input/Select
Area Code Enter the area code up to 6 digits.
Number Enter the phone number of the device. You may enter hyphens
and dashes.
Table 13. Voice and text-to-speech options in the Devices form
Field Input/Select
Display Device on
Recipients Page
This is used to hide the device when manually sending alerts. The
device will still be visible to external systems.
Access Key When an access key is defined for a device, that access key must
be input to send an alert to that device. However, if the alert is
sent to the device because the owner is selected as a recipient or
the device is contained in a group, the user access key or group
access key, respectively, is required instead.
Table 14. Advanced options in the Devices form
222 | TelAlert 6e™ Administrator Guide - Version 6.1.29
14.2.2 Editing Your Devices
To edit one of your devices, do the following:
1. Click the Devices tab. The Manage Devices page displays.
2. In the list of devices, click the Edit Device icon to the left of the device name.
3. Modify the fields you wish to edit, and use the Advanced tab to access additional fields if
necessary. On the Edit Device page the Name field is not editable. The Device Type/Configuration
field will only contain active configurations that are of the same Device Type as the device being
edited.
� Note: If you do not see the Advanced tab and you are a staff member, your administrator has turned off this feature.
� See Tables 9 - 13 for more information about the most common fields used for various
devices. For details on any fields not listed in Tables 9 - 13, see the TelAlert 6e Keyword and Command Reference.
4. Click Save.
14.3 Assigning Device Schedules
Devices can be assigned schedules so that they are only available to receive alerts during specified
periods when they are considered on duty. Users can create and assign schedules for their own
devices. Supervisors and Administrators can
create and assign device schedules for all devices owned by users in their department. Defining
device suchedules is optional. If you do not assign a device schedule, the system’s default setting
of 24x7, always on duty applies.
Chapter 14: Representing Devices | 223
Figure 30. Edit Device Schedule page allows user to assign a default device schedule.
Device schedules tell TelAlert whether a device is on duty at the time an alert is sent. Setting up
schedules for devices rather than for people might seem counterintuitive. However, setting up
schedules for devices makes it possible to send alerts to a particular device--John’s phone--
during certain hours and to a different device--John’s pager--during other hours.
To assign a device schedule, do the following:
4. Click the Devices tab. The Manage Devices page displays.
5. Choose the device from the list by clicking the to the left of the device’s name.
6. Select the Schedule tab.
The default schedule for new devices is 24x7, indicating that the device is available to receive
alerts at any time.
224 | TelAlert 6e™ Administrator Guide - Version 6.1.29
7. To assign a device schedule, select the desired schedule from the Default Schedule drop-down
menu. Select the date the schedule should go into affect in the Start Date field followed by the
Save button.
Note: Device schedules are listed below global schedules in the Default Schedule drop-down
menu under the User Defined Schedules heading. Device schedules are considered User Defined
because they are linked to the owner of a device and are available to that user only for
assignment to their devices. Other users in the system will not have the ability to assign another
user’s device schedule to their own devices.
If you would like a schedule to be available to more than one user, create a global schedule
instead of a device schedule. The global schedule will appear in the Default Schedule drop-down
menu under the Global Schedule heading and will be available for use by all users in your
department.
8. When the device schedule has been assigned you will see a confirmation page indicating the
device details (in this case the schedule) have been updated successfully.
Chapter 14: Representing Devices | 225
14.3.1 Adding a New Device Schedule
If you have not created any device schedules or do not see the desired schedule in the Default
Schedule drop-down list you can create a new device schedule.
1. To create a new device schedule select the Add a New Schedule button.
2. In the Name field, enter a name for the device schedule. The name should be unique so that
when it is displayed along with other device schedules, it is self-documenting. The device name
can be up to 20 characters long.
3. In the Description field, enter a brief description of the device schedule. This is optional, but
very useful when managing many schedules.
4. Indicate the Repeat Pattern and On Duty Hours Pattern and select the Next button.
5. Enter the times and days of the week that the device will be on duty and available to receive alerts.
Note: A device with the 9 to 5 device schedule will NOT receive alerts sent on Monday at 8:59.
The device will receive alerts sent on Monday at 9:00. Additionally, they will NOT receive alerts
sent on Monday at 17:01.
6. Select the Save button.
The device schedule is now available to assign to the selected device and any additional devices
owned by the same user on the Edit Device Details page.
7. To assign this or other device schedules to a device see Assigning Device Schedules at the top of
this section.
226 | TelAlert 6e™ Administrator Guide - Version 6.1.29
14.3.2 Removing Your Devices
To remove your devices, do the following:
1. Click the Devices tab.
2. In the list of devices, click the icon to the left of each device you want to remove.
Removing a user’s last device removes them from all groups since users must have an active
device to belong to a group. This feature is intended to prevent alerts being sent to empty
groups.
3. In the confirmation window, cl ick OK to delete the device, or click Cancel if you do not want
to delete the device.
15
Enabling Responses 15.1 Overview
Yhis chapter contains instructions for making it possible for message recipients to respond to
notifications sent by TelAlert. This chapter focuses on two-way pager destinations but explains how
responses can be appended to messages sent to other types of destinations as well.
15.2 Getting Started
15.2.1 What are Responses?
The recipient of any TelAlert message sent with an –ackwait or AcknowledgeWait value can respond by using the command line to acknowledge, negatively acknowledge, or acknowledge and
hold the message. If you want to offer the recipient a larger or different set of response options,
you must define them under [Response] and refer to this set of responses by name on the command line when giving the command to send the message.
A set of responses invoked in this way will be presented to the recipient as a text menu when the
message is sent to an InteractiveTextPager configuration, and as a voice menu when the
message is sent to an InteractiveTTS configuration. In those cases, the recipient can respond directly by pressing a button on the pager or key on the telephone to choose one of the responses.
With other configuration types, the responses can be viewed by using the -show command-line option. They are are also appended to email notifications. The recipient can choose a response
using the –reply command-line option.
15.2.2 Needed Information
Before setting up responses, you need to know what notification medium or media you plan to use
them with, the means by which recipients will be responding, and whether your plans call for the
use of a customized script or [Notifications] definition.
228 | TelAlert 6e™ Administrator Guide - Version 6.1.29
15.2.3 Other Considerations
-ackwait or AcknowledgeWait Value Required
The -ackwait parameter is essential anytime you want to make it possible for the message
recipient to respond: without it, TelAlert would not hold on to the message after delivery and thus
would not be in a position to accept a response. (Assigning an AcknowledgeWaitvalue is a
nearly identical means of achieving the same effect. The difference is merely that
AcknowledgeWait is set within the configuration file, rather than on the command line.)
15.3 Taking Advantage of Pre-Defined Responses
TelAlert ships with two sets of pre-defined responses under [Response]. These are ready for
you to refer to on the command line. For example:
[Response]
...
{Basic}
NumReplies=6
Acked=1
AckedHold=3,4,6
NotAcked=2
Released=5
Reply1=Yes
Reply2=No
Reply3=Hold
Reply4=Info
Reply5=Release
Reply6=Ping
Here, Reply4 is intended to offer a means by which the user can send additional info (this requires the use of a script invoked using a [Notifications] definition). Reply6 is intended to allow the user to run a script that pings a node and reports the result to the user (this, too,
requires the use of a script invoked using a [Notifications] definition).
You can invoke this set of responses when sending a message to a two-way text pager:
telalertc -i JohnTwoWayTextPager -m "this is a test" -response Basic -ackwait 15m
In this example, these responses will show up on the pager, in the form of a menu of choices:
Yes, No, Hold, Info, Release, Ping. Each response maps to a TelAlert command by way of the Acked, AckedHold, NotAcked, and Released settings in the response definition, so that Yes positively acknowledges the message, No negatively acknowledges it, and so on.
-ackwaitor AcknowledgeWait Value Required
As noted at the beginning of this chapter, you must use the -ackwait command-line
option or set an AcknowledgeWaitvalue when enabling responses. Otherwise, TelAlert
would not hold on to the message after delivery and thus would not be in a position to
accept a response. Please note that -ackwait is case sensitive on the command line.
.
Chapter 15: Enabling Responses | 229
15.3.1 Responding Via the Command Line
If this set of responses is invoked when the command to send the message is given, these
responses will be available for the recipient to choose from even if the message is sent to a
destination other than a two-way text pager (in which case the response options will not be
displayed). For instance, you could invoke this set of responses when sending a message to an
electronic signboard:
telalertc -i TechSupportSignboard -m "this is a test" -response Basic -ackwait 15m
Anyone viewing the message could then go to a computer on which the TelAlert client is running
and respond using the desired response option:
telalertc -reply sendID Hold
To do this, this person would have to know that this set of responses had been attached to the
message and remember what options were available. The following command would make TelAlert
display the send ID it had assigned to the message:
telalertc -show -i TechSupportSignboard
Note that the -replycommand-line option is not case-sensitive, and you need to type only as much
of the response string as is necessary for TelAlert to distinguish it from the other choices. In the
example above, since Hold is the only response that starts with H, the following command would
work just as well:
telalertc -reply sendID h
15.4 Creating Custom Responses
It is a simple matter to modify the pre-defined [Response] definitions or create new ones of your own. For instance, you might want to make the previously cited set of responses even more
basic by removing Infoand Ping, so that there is a simple, one-to-one correspondence between menu items and TelAlert commands. Or you might want to include additional response options that
map to Acked, AckedHold, NotAcked, or Released, so that these responses carry out the corresponding action within TelAlert while providing more detailed information. For example:
[Response]
...
{Detailed}
NumReplies=8
Acked=1,2
AckedHold=5,6
NotAcked=3,4
Released=7,8
Reply1=’Yes<1Hour’
#Reply1 means yes, in less than one hour Reply2=’Yes>1Hour’
#Reply2 means yes, in more than one hour Reply3=NoBusy
#Reply3 means "no, I am busy"
230 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Reply4=NoOffDuty
#Reply4 means "no, I am off duty" Reply5=HoldWillHandle
#Reply5 means "hold, I will handle it" Reply6=HoldWillDelegate
#Reply6 means "hold, I will assign this to someone else" Reply7=ReleaseFixed
#Reply7 means "release, this is fixed" Reply8=ReleaseNotFixed
#Reply8 means "release, but this is not fixed"
Here, two responses map to each command, allowing the respondent to positively acknowledge the
message in two ways, negatively acknowledge the message in two ways, and so on. (The intended
meaning of each response is explained in a comment line.)
The text of the response will be available in the telalert.trail file. You can take greater advantage of
this sort of response-related information using TelAlert’s [Notifications] feature. For more
information, refer to Responses and the [Notifications] Feature below.
Once you have the desired set of responses in place, you can send pages by invoking the
destination in a command such as this:
telalertc -i DavidTwoWayInternetPager -m "this is a test"
-response Detailed -ackwait 15m
15.5 Two-Way Pager Considerations
Because invocation of a set of responses is handled more or less seamlessly in sends to two-way
pager destinations (i.e., the responses are presented straightforwardly as a menu of choices,
without additional effort on your part), the only detail unique to two-way pagers with which you
need to concern yourself is polling. Polling is the means by which TelAlert checks for responses to
two-way pages it has sent.
TelAlert knows to poll for responses whenever it sends a page that meets three conditions:
• The page must use a [Configurations] definition (or a destination) in which Type is defined as InteractiveTextPager.
• The command generating the alert must specify an –ackwait value (or an AcknowledgeWait value must be in effect via some other mechanism).
• The command generating the alert must specify a set of responses.
In addition, the message must still be active: it must be in either an ackwait or ackheld state.
Otherwise, from TelAlert’s point of view, the message no longer exists and there is no reason for
TelAlert to poll for a response.
When it polls, TelAlert uses the same [Configurations] definition that it used to send the
original page. If you send a two-way page via the Internet, TelAlert attempts to retrieve a response
by the same medium. If DialBackup is specified and TelAlert encounters the specified number of
connect errors in attempting to poll, it will use the DialBackup information to poll by dial-up.
Chapter 15: Enabling Responses | 231
The only aspect of polling that it is possible to control is the frequency with which TelAlert dials in
to check for responses. You can do this by changing the CheckITPRepliesInterval setting
under [Limits]. The default is 5m. This must be set to a value lower than your -ackwait value if TelAlert is to have a chance to check for a response before the message expires. In the
case of Internet-based two-way paging, a frequent polling interval is less likely to interfere with
sending pages than in the case of dial-up, since Internet-based polling ties up the port for only a
few seconds each time.
15.6 Responses and the [Notifications] Feature
Response functionality can be significantly expanded using [Notifications] definitions, which
allow you to pass designated responses to a log file or another application. Thus, you can enable a
response that will update a trouble ticket in a controlling application with which you have
integrated TelAlert; likewise, you can enable a response that, by triggering a script, will carry out a
diagnostic or administrative operation.
As mentioned above, one of the pre-defined sets of responses provided in the TelAlert
configuration file includes two responses designed to work in conjunction with a script,Reply4 and Reply6:
[Response]
... {Basic}
NumReplies=6
Acked=1
AckedHold=3,4,6
NotAcked=2
Released=5
Reply1=Yes
Reply2=No
Reply3=Hold
Reply4=Info
Reply5=Release
Reply6=Ping
You invoke such a script by referring to it in a [Notifications] definition associated with the
[Destinations] definition to which the original message was sent. For example, this
command—
telalertc -i DavidTwoWayInternetPager -m "this is a test" -response Basic -ackwait 15m -remark 192.168.168.1
—refers to a [Destinations] definition—
[Destinations]
... {DavidTwoWayInternetPager}
Configuration=SkyTelITwoWayTextPager
PIN=3456789
NotificationReply=BasicReply
232 | TelAlert 6e™ Administrator Guide - Version 6.1.29
—that points to this [Notifications] definition:
[Notifications]
... {BasicReply}
Active=True
Shell=/bin/sh -c Command=${TelAlertBin}/Scripts/reply.sh ${Message}& Reply=${TimeStamp},Reply,${Ticket},${Reply},${Configuration},${PIN},&
${Remark},${User}
In this example, if David issues the Ping reply, TelAlert interprets it as a positive acknowledgment and hold of the message. It does this much merely in accordance with the invoked [Response]
definition, {Basic}, in which Ping is mapped to AckedHold.
But, because the destination contains a NotificationReply value, TelAlert also executes
reply.sh (or, in Windows, reply.pl), the script specified in the [Notifications] definition
named {BasicReply}. reply.sh (or .pl), on the basis of the information used to generate the original message (which it is given by TelAlert), pings the node that is the focus of the alert. (This
was included on the command line using the –remark tag. reply.sh/reply.pl is designed to interpret the value following -remarkas a node address or name.) The script then passes the result
of the ping to TelAlert as the message part of a command that generates another page to
{DavidTwoWayInternetPager}. By this means, David learns the ping’s result.
The template reply.sh(or .pl), in the form provided by MIR3, serves primarily as a means of remotely carrying out a ping. It also writes all reply activity pertaining to destinations with which it
is associated to a log file (reply.log). You can edit reply.sh (or .pl) so that it does other
things; likewise, you can create any number of entirely new scripts and invoke them using the
same means.
For instance, you might modify reply.sh(or .pl)so that it gives special treatment to Reply4 of the response set called {Basic}—i.e., Info. Perhaps you want message recipients to be able to respond by returning a message that updates a field in a help desk application. Because Info is mapped to AckedHold, TelAlert itself treats this response as an acknowledgment and
hold of the message. The modified version of reply.sh(or .pl), invoked by the method
described above, could then execute a command that would pass whatever message the recipient
had appended in his or her response to a designated application.
Chapter 15: Enabling Responses | 233
Passing a NotificationReply Value on the Command Line
You can invoke the [Configurations] definition and specify destination-related information on the command line, like so:
telalertc -c SkyTelInetTwoWayTextPagerSP -pin 3456789 -m "test" -response Detailed -ackwait 15m
If this is the way you send pages and you are using the [Notifications] feature as a means of processing responses, you will need to pass the NotificationReply value
on the command line as well:
telalertc -c SkyTelInetTwoWayTextPagerSP -pin 3456789
-m "test" -response Detailed -ackwait 15m -notificationreply BasicReply.
16
Broadcasting to Groups
and Creating Escalations 16.1 Overview
Instructions for sending notifications to more than one destination using your own [Group]
definitions. This chapter covers both “broadcast” group notifications, in which the message goes
simultaneously to all members of the group, and “escalations,” in which TelAlert directs the
message to one or more destinations in sequence, according to specified rules.
16.2 Getting Started
16.2.1 What Are Groups? What Are They For?
Groups allow you to organize users and create recipient call lists for alerts. A group can include
individuals (users), devices, and/or groups. Users and devices may be assigned group member
schedules that override the default device schedule when alerts are sent to the group. Extra duty
hours can also be applied to group member schedules when additional on duty time is required.
A group is similar to an e-mail distribution list. By setting up a group, alerts can be directed to
multiple recipients. A group can be configured so that alerts are broadcast to all group members
simultaneously or escalated sequentially to each group member until one or more recipients
acknowledges delivery.
Groups can be assigned to one or more departments.
Groups can be made public to enable self-service group membership by staff members. If a group
is public, staff users can add themselves and remove themselves from the group using the
Subscriptions tab.
Groups will not display in the Add Group Recipient list in the Alerts section until at least one group
member with an active device has been added. This prevents alerts from being sent to empty groups.
Note: When the system contains large numbers of groups, the groups can be filtered by
department using the By Departments: drop-down menu and Search field in the Filter
Results section at the top of the Manage Groups page.
236 | TelAlert 6e™ Administrator Guide - Version 6.1.29
16.2.2 Adding a New Group
To add a new group, do the following:
1. Click the Devices tab. The Manage Groups page displays.
2. Click the Edit Device button. The Add a New Group page appears.
3. If you want to allow alerts to be sent to the group, in the Active field select Yes. Otherwise,
select No. Selecting No removes the group from the Recipients list on the Add Recipients page.
4. In the Name field, enter a name for the group. The group name cannot exceed 20 characters
and cannot include special characters.
5. In the Comments/Description text box, enter a brief description of the group (by function,
department, or other logical component of your organization).
6. In the Public section, select Yes if you want to allow users to be able to add and remove
themselves from the group.
7. Select the department or departments that you would like your group to belong to. To select
more than one department click on one of the departments, hold down the ctr key while
clicking on additional departments.
Chapter 16: Broadcasting to Groups and Creating Escalations | 237
Note: The departments selected will determine which users, devices and groups will be
available later to add as members of the group. The Add Group Members list will only contain
users and the devices that belong to those users and groups that belong to same department
as the new group.
8. Click the Save button.
The new group is added to the system. However, the group will not become available to receive
alerts until at least one member has been added. See Adding Group Members.
16.2.3 Activating and De-Activating Groups
When a group is active, the group can receive alerts. When the group is inactive alerts cannot be
sent to the group. To activate or inactivate a group, do the following:
1. Click the Devices tab. The Manage Groups page displays.
2. Click the Edit Group icon next to the device record in the Manage Groups list. The Edit Group
page appears
3. Modify the Active field.
4. Click the Save button.
238 | TelAlert 6e™ Administrator Guide - Version 6.1.29
16.2.4 Modifying a Group
To modify an existing group’s information, do the following:
1. Click the Groups tab. The Manage Groups page displays.
2. Click the Edit Group icon next to the group record in the Manage Groups list. The Edit Group
page appears.
3. Use the tabs--Details, Members, Escalation, Schedule, and Advanced--to make your changes.
16.2.5 Adding Group Members
To add group members, do the following:
1. Click the Groups tab. The Manage Groups page displays.
2. Choose the group you want to manage by clicking the Edit Group icon next to its name in the
list.
3. Select the Members tab. This shows the current group member list.
Chapter 16: Broadcasting to Groups and Creating Escalations | 239
4. Select the Add to Group button. This brings up the Add User Members window.
5. You can add users, devices or groups by selecting between these terms in the View By: drop-
down menu. The Add
6. Members window displays the first ten of all eligible devices, users or groups.
7. Select the entries you want to add to the group by selecting the checkbox next to each
recipient.
240 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Note: You can add a member to a group more than once. If you do, the system will send the
alert to that target as many times as it appears in the group (or until someone acknowledges the
message).
7. Select the Add Selected button to save the selected recipients on the current page. When
you have selected all desired recipients click on the Finished button to close the window
and return you to the Edit Group Members page.
8. Click the Schedule tab to assign schedules to your group members.
16.3 Assigning Schedules to Group Members
The purpose of group member schedules is to override the default device schedule of a group
member. The group member schedule will only be applied when alerts are sent to the group. They
do not influence alerts sent to other groups or to the device or user directly.
Group member schedules indicate when members are on duty or off duty when alerts are sent to
the group. When the member is on duty they will be sent an alert when alerts are sent to the
group. Group members can be users, devices or groups (subgroups). If the group member is a
user, alerts will be sent to all of their on duty devices when alerts are sent to the group. (See
Assigning Device Schedules for information about device schedules.) If the group member is a
device, alerts will be sent to that device if it is on duty when the alert is sent to the group. If the
group member is a Group (subgroup), all of the on duty members of the subgroup will be sent
alerts when an alert is sent to the group.
Note: Device schedules and escalation schedules can affect whether or not or in which order
members of a group will be sent alerts.
16.3.1 Assigning a Schedule to a Group Member
To assign a schedule to a group member, do the following:
1. Click the Groups tab. The Manage Groups page displays.
2. Click the Edit Group icon next to the name of the group that contains the members to which
you want to assign schedules. The Edit Group Details page displays.
3. Click the Schedule tab. The Edit Group Schedules page displays.
Chapter 16: Broadcasting to Groups and Creating Escalations | 241
4. In the calendar, click the name of the group member that you would like to assign a schedule.
5. In the Regular Schedule section, the radio button will default to Use the Default Schedule. For
device group members, the default schedule is referring to the schedule that has been assigned
to the device in the device section. If no schedule has been assigned to the device a 24x7
schedule applies. When the group member is a user, the default schedule is the compilation of
all of the user’s device schedules.
� To see the group member’s default schedule, select the Override the Default Schedule radio button.
� The name of the default schedule will appear in the Schedule drop-down menu.
242 | TelAlert 6e™ Administrator Guide - Version 6.1.29
6. The Schedule drop-down list contains all global schedules, group schedules created for this
group and device schedules associated with the particular group member. The device schedules
are listed as User Specific Schedules since they are associated with a user for assignment to any
of their devices.
7. Use the Schedule drop-down menu to select the desired schedule. You can select a global,
group or user specific (device) schedule. Global schedules are schedules that are available to all
groups. Group schedules are schedules that are available to the group selected in the Group
drop-down menu when the schedule was created.
8. In the Regular Schedule section, enter a schedule Start Date. This date should be today’s
date or a prior date. If a future date is entered, the system will retroactively adjust the start date
to a date in the current week. The schedule will adhere to the date, in that the schedule cycle
will begin at the specified start date and you will see a message informing you that the schedule
date has been adjusted on the confirmation page. The group member will also be on duty for
the number of schedule cycles required to backtrack to today’s date. If you want to create a
schedule that will not go into effect until a future date, the best method is to change the group’s
status or the group member’s status to inactive (don’t forget to change it back to active later).
If you change the group’s status to inactive, group members who are active can still receive
alerts that are sent to them or their device directly or using other users or groups.
Chapter 16: Broadcasting to Groups and Creating Escalations | 243
Note: Since Weekly schedules start on a Sunday, the date you enter will be changed to the
prior Sunday if necessary. If the schedule’s repeat pattern is "every X days", the date you
enter as the schedule start date will not be changed.
9. Click the Save Regular Schedule button.
10. To override all or a portion of a vacation or holiday schedule, use the Extra Duty Schedule
section to define additional on duty hours. A group member schedule must be applied before
adding Extra Duty.
11. The Extra Duty Schedule section does not appear the first time a group member schedule is
viewed or before a group member schedule has been applied. If you do not see the Extra Duty
Schedule section, an override schedule must be applied. Select the Override the default
schedule radio button followed by the Save Regular Schedule button. The Extra Duty Section is
now visible. The Extra Duty Schedule section does not appear the first time a group member
schedule is viewed or before a group member schedule has been applied. If you do not see the
Extra Duty Schedule section, an override schedule must be applied.
244 | TelAlert 6e™ Administrator Guide - Version 6.1.29
12. Enter a Start and End date. If the extra duty schedule is a single day enter that date in the Start
and End fields and select the All Day checkbox.
13. Click the Save Extra Duty Schedule button.
14. To define an Acknowledge Wait time for the group member, enter a time (in minutes) in the
Acknowledge Wait section. This setting will determine how long the alert will remain active when
sent to this group member.
15. Acknowledge Wait is specified on the Group Advanced page or if an Acknowledge Wait is defined
on the Send Alert page when the alert is sent, this value will not apply.
Chapter 16: Broadcasting to Groups and Creating Escalations | 245
16.3.2 Removing Group Members
1. Click the Groups tab. The Manage Groups page displays.
2. Choose the group you want to manage by selecting the Edit Group icon to the left of the group
name.
3. Select the Members tab. This shows the current membership.
4. Select the members you want to remove by checking the boxes and clicking the Remove
Selected button.
Reordering Group Members
When using a sequential or round-robin escalation scheme the order of the entries in the group
membership is significant. This does not apply to broadcast escalations.
5. Click the Groups tab. The Manage Groups page displays.
6. Choose the group you want to manage by selecting the Edit Group icon to the left of the group
name.
7. Select the Members tab. This shows the current membership.
8. With the mouse, click on the member you want to move, drag and drop the group member
entries until they are in the desired order.
246 | TelAlert 6e™ Administrator Guide - Version 6.1.29
16.4 Group Basics
16.4.1 Building a Group From a List of Other Groups
A group can also be a list of other groups (or “subgroups”). There is a practical difference between
defining a group as a list of destinations and as a list of other groups only when a strategy is
defined for the group (using Strategy=) or the send (using –strategy on the command line)
and the referred-to strategy contains an Escalate value. Otherwise, TelAlert treats a list of groups
as if you had listed all of the constituent destinations individually. For more information, refer to
Escalation later in this chapter.
You may also mix destinations and subgroups when defining a group. Fundamentally, nothing
distinguishes groups from subgroups; a “subgroup” is simply a group that is listed as a destination
in another group. It is permissible to create a group that refers to another group that in turn refers
to yet another group—but ultimately TelAlert must be able to resolve these references in terms of
actual destinations.
16.4.2 Supported Group Attributes
There are many values that can be specified in a group definition in order to control the effect of
directing a message to the group. The most common are listed and explained below. For a
complete list, refer to the section on groups in Chapter 2 of the TelAlert Keyword and
Command Reference.
Strategy
Strategy points to a [Strategy] definition. If you assign a value here, a send directed to the
group will be considered complete only when the strategy’s completion criterion is met. If the
strategy is also given an Escalatevalue, the send will be treated as an escalation rather than a
broadcast, and TelAlert will continue to escalate it until either the completion criterion or the
escalation criterion has been met. For more information, refer to Escalation later in this chapter.
RotateFirstDestination
Setting this to True causes TelAlert to send to the destinations comprising the group in rotation: A-B-C the first time, B-C-A the second, and C-A-B the third. This ensures that the first destination
listed is not always the first destination to which TelAlert sends the message when you direct a
message to the group.
If this is set to True in a group comprised of subgroups, TelAlert rotates the order in which it
sends the message to the subgroups. This may not be a desired effect, since, when building a
group out of subgroups, you may list them in an order reflecting their level of responsibility or
expertise: first level support, second level support, and so on.
Avoid Giving Groups and Destinations the Same Name
TelAlert allows you to give the same name to a group and a destination, but it is not a
good practice. If you include such an ambiguous name in a group definition, TelAlert will
interpret it as referring to the destination rather than, as you would likely have intended, the group.
Chapter 16: Broadcasting to Groups and Creating Escalations | 247
RotateFirstDestination has a significant effect only in the case of escalations. In broadcast scenarios, TelAlert will rotate the order in which it sends notifications, but the time involved is
usually too small to be meaningful.
Subgroup Escalation
If this is set to True, whenever the group is invoked as a component of another group, TelAlert
will treat it as if its component destinations had been listed individually. This has a significant effect
only when a strategy is in effect for the “supergroup” and that strategy contains an Escalatevalue.
For more information, refer to Escalation later in this chapter.
16.5 Broadcast Notification
The simplest use of groups is to send a message to multiple destinations all at the same time. For
example:
[Group]
...
{Support}
Destinations=DavidTextPager,RachelTextPager,CynthiaTextPager,
JohnTextPager
A message sent to this group, like so—
telalertc -g Support -m "this is a test"
—would be sent to all four destinations at once.
The same is true when a group is comprised of references to other groups, or a mixture of
references to groups and destinations. For example:
[Group]
...
{Support1}
Destinations=DayShift,NightShift
{Support2}
Destinations=ServerSupport,DesktopSupport,JaneTextPager
248 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Messages sent to either of these groups, like so—
telalertc -g Support1 -m "this is a test" telalertc -g Support2 -m "this is a test"
—would in each case be sent to all destinations at once.
A message directed to a group will be treated as a broadcast (rather than an escalation) if the
group does not invoke a strategy, or if the strategy it invokes does not contain an Escalate value. If a value is assigned to Strategy and that strategy assigns a value to Escalate, TelAlert
will handle the send as an escalation. If you plan to carry out broadcast notifications and
escalations, you may want to create two versions of every group, one with an operative escalation
criterion and one without.
16.5.1 About Group IDs
For tracking purposes, TelAlert assigns an arbitrary, unique group ID number to every alert sent to
a group. You can display active group IDs with the command telalertc -showgroup.
16.5.2 Use of -g and -l Compared
It is also possible to send to group using the -l syntax, as follows:
telalertc -l JohnTextPager,CynthiaTextPager,RouterSupportGroup -m "this is a test"
For a given alert, only one escalation strategy can be in effect. If you use the -g "group_name" syntax, it's the strategy in the "group_name" definition that is in effect.
If you use the -l syntax, you are essentially creating, on-the-fly, a one-time-use "supergroup". (If
you are logging, you can assign a name to this one-time-use group with the -name parameter.)
Regardless of whether you use -name, if you want this one-time-use group to use a strategy, you
must specify the -strategy parameter on the command line; if escalation is involved, you will need
to specify -ackwait; if you are doing two-way paging, you may want to specify the -response parameter; etc. In other words, when you use -l, you must use additional parameters on the
command line to fully define the one-time-use group you are creating on-the-fly.
16.5.3 Schedules and Broadcast Notifications
If you have a group consisting of several destinations and each is associated with a schedule,
TelAlert will distinguish between on-duty and off-duty destinations when it is asked to broadcast a
message to the group. For more information, refer to Chapter 12: Setting Up and Applying
Schedules.
Note that, to achieve this effect, the schedules associated with the group itself must be “Use the
default schedule”. Any other schedule associated with a group member overrides the schedule
associated with the destination or user.
Chapter 16: Broadcasting to Groups and Creating Escalations | 249
16.6 Escalation
Escalation is useful when you must be sure that at least one member of a group receives and
acknowledges a message, but you want to avoid, if possible, sending it to all members of the
group.
Escalation
Strategy Description
Sequential In this strategy, the alert is escalated sequentially until at least one
member acknowledges. The Ack Wait period defined for each group
member (see Adding Users) determines how long TelAlert waits before
sending the alert to the next group member.
Rotate First
Member
(Round Robin)
In this strategy, the alert is always sent to the group members
sequentially, however it will be sent initially to the next member in the
list each time a new alert is sent. When each group member has been
the first to receive an alert, the process starts again--the next alert is
sent to the first group member, the one after that is sent to the second
member first, and the third alert is sent to the third group member
first. Here is an example for a group with three members: The first alert
is sent to member 1, then escalates sequentially to member 2 and then
to member 3. The next alert is sent to member 2 first, then to member
3, and then member 1.
Broadcast In this strategy, the alert is sent to every member of the group
simultaneously.
Table 24. Escalation strategies
16.6.1 A Simple Escalation
In a scenario involving a group comprised of individual destinations, you can direct a message to
the group and have TelAlert send it to each destination individually, waiting a specified amount of
time in between sends for an acknowledgment and ending the escalation as soon as an
acknowledgment is received. Consider this example:
[Group]
...
{Support}
Destinations=DavidTextPager,RachelTextPager,CynthiaTextPager,
JohnTextPager
Strategy=FirstAcknowledge
[Strategy]
...
{FirstAcknowledge}
Complete=Acked>0
Escalate=Incomplete=0
250 | TelAlert 6e™ Administrator Guide - Version 6.1.29
With this group and this [Strategy] definition in place, a message directed to the group, like
so—
telalertc -g Support -m "this is a test" -ackwait 10m
will be sent first to David. If after ten minutes TelAlert has not received an acknowledgment from
David, it will send the message to Rachel. If after ten minutes TelAlert has not received an
acknowledgment from Rachel, it will send the message to Cynthia. If after ten minutes TelAlert has
not received an acknowledgment from Cynthia, it will send the message to John.
If David acknowledges the message during the initial ten-minute ackwait period (for an
explanation, see the following note), escalation stops and the message is not sent to anyone else.
If escalation continues, it does so only until an acknowledgment is received from one of the
recipients. This permits the fewest possible people to be contacted while at the same time ensuring
that the problem is handled.
Note that you can also have command destinations, i.e., destinations associated only with
[Configurations] definitions of Type=Command. Since there is no human at a "command"
destination, there’s no human to acknowledge the alert. Instead, the keyword Acked in the
definition of the "command" destination determines whether TelAlert considers the "command"
destination to have acknowledged the alert.
In this example, there are several things to understand about strategies in general, and the
strategy called FirstAcknowledge in particular:
� The send is treated as an escalation because the [Strategy] definition invoked by the group contains an Escalate value.
� Complete specifies the conditions under which TelAlert will consider the alert complete.
Here, Complete=Acked>0 means that a send in which this strategy is invoked will be
considered complete when at least one person has positively acknowledged it (i.e., when the number of messages “acked” is greater then zero).
� If the Complete criterion is met, TelAlert ends the escalation.
� Escalate specifies the conditions under which TelAlert will escalate the alert, assuming
the Complete criterion has not yet been met. In this example,
Escalate=Incomplete=0 means that TelAlert will send the message to the next
destination when the current send ceases to be in an incomplete state (i.e., when the
number of sends in an “incomplete” state equals zero). TelAlert treats escalation differently
when the group is comprised of subgroups. For more information, refer to Escalations Involving Subgroups later in this chapter.
Chapter 16: Broadcasting to Groups and Creating Escalations | 251
16.6.2 Other Approaches to Strategy
FirstAcknowledge is probably the most commonly used strategy, but many others are possible, as suggested by the following discussion of strategy syntax and examples.
Strategy Syntax and Examples
Completeand Escalate values can be set using relational operators, logical operators, keywords
representing TelAlert “send” states, and numerical values representing percentages of the total
number of sends. (An additional keyword is used to refer to how much time has elapsed since the
alert began.) For instance—
Complete=(Sent=100)|(Acked>=50)
—means that the alert will be considered complete when the message has been sent to 100% of
the valid destinations, or when 50% of these destinations have acknowledged the message.
The supported logical operators are:
� & AND
� | OR
� ^ exclusive OR
� ! NOT
ackwait
The key to escalation is the -ackwait numberm/h parameter used at the command line—or, alternatively, the AcknowledgeWait=numberm/h line that can be used in
defining a group or destination. These entries tell TelAlert how long to wait … but before
doing what? If there is a [Strategy] definition for TelAlert to refer to, it sends to the
first destination and waits this amount of time before following its escalation procedure.
If there is no [Strategy] definition, it sends to all destinations and waits this amount
of time before releasing the alert.
Without the -ackwait parameter or AcknowledgeWait= line, any escalation
procedure specified in a [Strategy] definition becomes meaningless, since TelAlert will
not know how long to wait before escalating the alert. In such cases, TelAlert sends to all
destinations at once.
-ackwait at the command line overrides an AcknowledgeWait value in
telalert.ini. TelAlert ignores any AcknowledgeWait value given as part of a
[Destinations] definition when that definition is invoked as part of a group.
252 | TelAlert 6e™ Administrator Guide - Version 6.1.29
The supported relational operators are:
� = equal to
� > greater than
� >= greater than or equal to
� < less than
� <= less than or equal to
� <> not equal to
“Send” states that can be referred to in [Strategy] definitions are as follows. (The numerical
values assigned to these keywords always represent the percentage of the total number of sends
that are in this state.)
� Acked—sends that have been successfully sent and acknowledged by the receiver
� NotAcked—sends that have been negatively acknowledged
� Sent—sends that have been successfully sent to their destination
� Failed—sends that could not be successfully sent to their destination and for which the
maximum number of attempts have been made (as determined by the MaxFailCalls value for that configuration)
� Cleared—sends that have been cleared using the -clear option on the command line
� Incomplete—sends that are still in progress. A send is incomplete if TelAlert has not yet
made an attempt to send to a destination, or if TelAlert is trying to send the message but has not yet succeeded
� OffDuty—sends that will never be sent because the destination is not currently on-duty
There is one other keyword that can be used in setting a Complete or Escalate value. (The
numerical value assigned to it represents a number of minutes.)
� Time—the number of minutes since TelAlert began issuing sends to the current
destination or subgroup.
Typical Escalate Value
Escalate=Incomplete=0 is the appropriate value in almost all instances. Rarely will
you need to use another setting.
Chapter 16: Broadcasting to Groups and Creating Escalations | 253
16.6.3 Escalations Involving Subgroups
Broadcasting to Subgroups
If you direct a message to a group comprised of subgroups and either (1) the supergroup does not
specify a strategy or (2) the [Strategy]definition does not contain an Escalate value,
TelAlert will send the message to all destinations at once without taking into account the divisions
represented by the subgroups.
By contrast, if you direct a message to a group comprised of subgroups and the supergroup
invokes a [Strategy] definition containing an Escalate value, TelAlert will first broadcast the
message to the destinations comprising the first subgroup. If the Escalate criterion is met, it then
moves on, broadcasting the message to the destinations comprising the second subgroup, and so
on. Consider this example:
[Group]
...
{Support}
Destinations=Subgroup1,Subgroup2,Subgroup3
Strategy=FirstAcknowledge
{Subgroup1}
Destinations=Pager1,Pager2,Pager3
{Subgroup2}
Destinations=Pager4,Pager5,Pager6
{Subgroup3}
Destinations=Pager7,Pager8,Pager9
Here, a message directed to {Support}, like so—
telalertc -g Support -m "this is a test" -ackwait 10m
—will first be sent to Pager1, Pager2, and Pager3, all at once. If none of these recipients acknowledges the message within ten minutes, it will be sent to Pager4,Pager5, and Pager6,
all at once. If none of these recipients acknowledges the message within ten minutes, it will be
sent to Pager7, Pager8, and Pager9, all at once. If none of these recipients acknowledges the message within ten minutes, the alert is marked as “finished” but not as “complete,” since the
Complete criterion was not met.
Sending to Subgroup Members Individually: SubgroupEscalation
The way TelAlert processes an escalated send to a group comprised of subgroups is changed
significantly by the use of the SubgroupEscalation keyword. TelAlert treats any group containing a subgroup in which SubgroupEscalation is set to True as if the subgroup’s destinations were included directly in the supergroup.
For instance, a group containing this Destinations setting—
Destinations=SG1,SG2,SG3
254 | TelAlert 6e™ Administrator Guide - Version 6.1.29
—would be treated if it contained this Destinations setting—
Destinations=Dest1,Dest2,Dest3,SG2,SG3
—as long as the first of the subgroups ({SG1}) had SubgroupEscalation set to True.
As a result, sends to the destinations comprising the subgroup for which
SubgroupEscalation=True are carried out one by one, as a part of the escalation process, not
as a broadcast. Consider this example:
[Group]
...
{SupportGroup}
Destinations=Group1,Group2,Group3
Strategy=FirstAcknowledge
{Group1}
Destinations=Pager1,Pager2,Pager3
SubgroupEscalation=True
{Group2}
Destinations=Pager4,Pager5,Pager6
{Group3}
Destinations=Pager7,Pager8,Pager9
Because SubgroupEscalation is set to Truein {Group1}, a message directed to {SupportGroup} would be handled as follows:
• TelAlert sends the message to Pager1.
• If this recipient does not acknowledge the message within ten minutes, TelAlert sends the
message to Pager2.
• If this recipient does not acknowledge the message within ten minutes, TelAlert sends the
message to Pager3.
• If this recipient does not acknowledge the message within ten minutes, TelAlert sends the
message to Pager4, Pager5, and Pager6, all at once.
• If none of these recipients acknowledges the message within ten minutes, TelAlert sends
the message to Pager7, Pager8, and Pager9, all at once.
• If none of these recipients acknowledges the message within ten minutes, the alert is
marked as "finished" but not as "complete," since the Complete criterion was not met.
Under what circumstances would you want to use SubgroupEscalation? Assume that you have
three groups of support technicians. Any member of any of the groups is qualified to handle a
“node down” message, but it is most appropriate to assign a member of one particular group
whenever possible.
This much is achieved simply by listing this most appropriate group first, since TelAlert sends to
the destinations in the order in which they are listed. But perhaps you also want to avoid paging all
the members of this first group each time a “node down” message is generated. By setting
SubgroupEscalation to True in the definition of this group, you cause TelAlert to send the
Chapter 16: Broadcasting to Groups and Creating Escalations | 255
message to these destinations one at a time. If none of these technicians responds during the
allotted time, the message will be sent out to all members of the second subgroup (and, after that,
to all members of the third subgroup). At this point, this may be precisely the behavior you want,
since, thirty minutes into the alert, you may be more willing to page multiple destinations
simultaneously to ensure a prompt response.
16.6.4 Balancing Workloads by Rotating the First Destination
Because TelAlert, when processing escalations, sends to destinations in the order in which they are
listed, you may find that some people are being assigned a heavier workload than others. For
instance, if JohnPager is the first destination listed in a group called {Support} that invokes a
strategy containing an Escalate value, John (when on duty) will always be the first person to
receive a page whenever a message is directed to that group.
You can address this problem using RotateFirstDestination. Set this to True in the [Group] definition, and TelAlert will begin with a different destination each time it processes a
send directed to this group: A-B-C, then B-C-A, then C-A-B, for example.
You can use RotateFirstDestination in a group comprised of subgroups to have TelAlert
rotate the order in which it sends to the subgroups. If SubgroupEscalation is True for one of
these subgroups, its destinations become part of the rotation. Likewise, in a group comprised of a
mixture of destinations and subgroups, rotation is applied to all of these entities equally.
Note that it is not common to use RotateFirstDestination to rotate the order in which TelAlert sends to subgroups, since typically the purpose of defining a group in terms of subgroups
is to arrange personnel in the order in which you want them to be contacted—from most to least
appropriate, for example, or from least to most expert.
You can invoke destination rotation at the command line using the -rotatefirstdest option. For example:
telalert -g support -rotatefirstdest -m "this is a test" -ackwait 10m
If the support group includes LucyPager, RickyPager, and EthelPager, and this is the first message sent using -rotatefirstdest, the first send will go to RickyPager. If the next
message sent to the group also includes -rotatefirstdest, its first send will go to
EthelPager. If it does not include -rotatefirstdest, the first send will go to
RickyPageragain.
Subgroup Escalation—Applicable Only to Subgroups
SubgroupEscalation=Truehas an effect only when the group functions as a subgroup—
that is, only when TelAlert computes the membership and escalation procedure for a group that lists this group as one of its Destinations values.
256 | TelAlert 6e™ Administrator Guide - Version 6.1.29
16.6.5 Schedules and Escalation
If you have a group consisting of several destinations and each is associated with a schedule,
TelAlert will distinguish between on-duty and off-duty destinations when asked to send a message
to the group, such that only on-duty destinations will be involved in the escalation. For more
information, refer to Chapter 12: Setting Up and Applying Schedules.
Note that, to achieve this effect, there must not be a schedule associated with the group itself. A
schedule associated with a group overrides all schedules associated with the destinations or
subgroups comprising the group.
17 Processing Events
17.1 Overview
Instructions for setting up TelAlert to respond automatically to specified events by issuing commands
to itself or other applications, sending SNMP traps, or writing to the operating system’s log.
17.2 Getting Started
17.2.1 Needed Information
The information you may need to gather and the preparations you may need to make in order to
apply the techniques described in this chapter can vary tremendously, depending on your purpose.
For instance:
� If you want TelAlert to log certain send-related information to a file, you will need to know
the name of this file and its location. You will need to know what information you want
logged and whether you want this information logged for all sends or sends of a certain
type only. You will also need to know what command you want TelAlert to use to carry out
this operation. Depending on the complexity of the action you want TelAlert to carry out,
you may need to devise a customized script—if you want the information to be given a special format or entered in a database, for example.
� If you want TelAlert to send SNMP traps, you will need to know the name of the SNMP
host(s). In some cases, you may have to provide an SNMP “community” name as well. You may also need to know the host service name or port number.
� If you want TelAlert to update another application when it receives a reply to a message,
you will need to know what information must be passed, the proper format, and the correct command for carrying out the interaction. This, too, may require a script.
� If you want TelAlert to send a message when an environmental monitor connected to a
TelAlert Engine detects an event, you will need to know the correct destination (or group of
destinations) and make all customary decisions about the behavior of the send (i.e., regarding strategy, replies, and so on). You will also need to know what message you want to deliver.
� If you want to be notified when process-related events occur, you will need to know what
event you want to be informed of, the information you want to be passed, and the notification mechanism you want TelAlert to use.
258 | TelAlert 6e™ Administrator Guide - Version 6.1.29
� If you want to be notified when log file size limits are reached, you will need to know what
log file(s) you are concerned about, the information you want to be passed, and the notification mechanism you want TelAlert to use.
17.3 Event Processing Defined
17.3.1 What Is Event Processing?
“Event processing” means configuring TelAlert to respond to an event with one or more of the
following actions:
� Issuing one or more commands, to itself, to other applications, or to launch custom scripts
� Sending an SNMP trap to one or more SNMP hosts.
� Writing to the system log (syslog in UNIX, the Application Event Log in Windows)
17.3.2 What Is an Event?
In this chapter, “event” refers to an occurrence internal to TelAlert. For example, when an alert is
initiated by a telalertc command, that is an event. When a user acknowledges the alert, that is
another event. There are several basic types of events, which can be grouped into three categories
based on which configuration file section defines how TelAlert will process them:
Alert-related and miscellaneous events ([Notification] section):
� An alert or send changes state (i.e., is started, held, acked, etc.)
� TelAlert receives an unsolicited request from a two-way paging service.
� TelAlert receives or hangs up an incoming call.
� A definition is activated or deactivated.
Process-related events ([Heartbeat] section):
� TelAlert process (daemon) starts, stops, or issues an error message.
� TelAlert process is running at the beginning of a new “heartbeat” interval.
Logging-related events ([File] section):
� One of TelAlert’s logs rolls over to a new file.
A Word About Scripts
You can configure TelAlert to execute a script (or a program) whenever any of the events
described in this chapter occur. This means that TelAlert’s event-handling capabilities are
limited by only the work you are willing to invest to devise a script that does what you want.
Chapter 19: Getting Familiar with the TelAlert Monitor | 259
Most logging-related functionality is covered in Chapter 17: Miscellaneous Administrative
Tasks, but logging-related event handling (i.e., specifying what TelAlert does when size limits are
reached) is covered here, in the present chapter, because of its close similarity to other event-
handling techniques.
17.4 Event Processing Overview
Configuring TelAlert to process a particular event takes at least three steps, and usually four. Here
is a brief overview of the process:
1. Select the type of event you want TelAlert to process by choosing one of the “event
keywords” (AlertStarted, Acknowledged, Start, Error, and so on) and
adding it to either the [Heartbeat] section (for process-related events), the [File]
section (for logging-related events), or a [Notification] definition (for alert-related
and miscellaneous events).
2. Define what information you want TelAlert to pass with the command or SNMP trap,
or to write to the log, in the event keyword value. Normally this string will include a
number of substitution parameters (variables) that TelAlert will replace with information
about the specific event.
Event keywords and related substitution parameters are described in detail later in this
chapter.
3. Define the action you want TelAlert to take by adding one of the following keywords
to the same definition or section:
Command: TelAlert will issue the specified command. Typically the command will include
the ${EventData} replaceable parameter, for which TelAlert will substitute the event
keyword value, with any replaceable parameters it contains expanded. See “Issuing a
Command,” below, for detailed instructions on setting this and related keyword values.
SNMPHosts: TelAlert will send an SNMP trap, which will include the expanded event
keyword value and various other information, to the specified host. See “Sending an SNMP
Trap,” below, for instructions on setting this keyword value and a discussion of what other
information is passed to the host.
WriteSysEventLog: When this keyword is set to True, TelAlert will write the event
keyword value (with any replaceable parameters it contains expanded) to syslog(in UNIX)
or the Application Event Log (in Windows). See “Writing to the System Log,” below, for
instructions on setting this keyword value.
The inclusion of the event keyword value in the command, SNMP trap, or log entry allows you to
add multiple event keywords in a single definition or section (that is, to perform steps 1 and 2
above repeatedly, with different event keywords), and have each generate a different command,
SNMP trap, or log entry.
A fourth step is necessary for notification-related events only:
4. Associate the [Notification] definition with the [Analog], [Battery], [Configuration], [Destinations], [Group], [Limits], [Port], [Power], [Relay], [Sensor], or [User] definition(s) you want to trigger the action by including a keyword value for Notification or one of the related keywords.
Alternatively, you can invoke a [Notification] definition using the –notification
(or –notificationreply or -notificationrequest) command line option.
260 | TelAlert 6e™ Administrator Guide - Version 6.1.29
17.4.1 About Notification and Related Keywords
Notification, NotificationLog, and NotificationTrap are functionally identical.
Having three keywords allows you to have different events trigger commands, log writes, and
SNMP traps.
NotificationReplyand NotificationRequest can be used only with
[Configuration], [Destinations], [Group], and [User] definitions, and are issued
only on reply and request events respectively. A [Notification] definition pointed to by one or
both of these keywords should contain no event keywords other than Reply and Request.
17.5 Triggering Actions
As discussed above, in response to an event TelAlert can send an SNMP trap, write to the system
log, or issue a command. This section provides detailed instructions on configuring each of the
three types of actions, and on configuring TelAlert to perform multiple actions in response to a
single event.
17.5.1 Sending an SNMP Trap
The following discussion assumes a familiarity with SNMP terminology and configuration. See the
documentation for the application receiving the SNMP traps for further information.
To configure TelAlert to send an SNMP trap when a particular event occurs, add the matching event
keyword and the SNMPHosts keyword to the appropriate definition or section. For example:
[Heartbeat] ...
SNMPHosts=192.168.168.168
Error=${TimeStamp} Error ${Name} ${PID}, ${StatusData}
With this configuration, whenever an error occurs in one of TelAlert’s processes, TelAlert will send
an SNMP trap to the host at IP address 192.168.168.168, using the standard service name
snmp-trap. The trap’s first variable contains the Errorevent keyword value with its replaceable
parameters expanded. (The replaceable parameters are explained in “Event Keywords Supported in
the [Heartbeat] Section,” below.) The first variable is followed by additional variables
containing the current values of each of the other replaceable parameters that are allowed in the
[Heartbeat] section.
Notes for SNMP Administrators
TelAlert’s MIB data is automatically loaded into HP OpenView IT/Operations during TelAlert
installation.
For instructions on changing the trap’s community name, or using a nonstandard service name or
port, refer to the “SNMPHosts” entry in the [Heartbeat] section of Chapter 2 of the TelAlert
Keyword and Command Reference.
Chapter 19: Getting Familiar with the TelAlert Monitor | 261
17.5.2 Writing to the System Log
To configure TelAlert to write to the system log (syslog in UNIX, the Application Event Log in
Windows) when a particular event occurs, add the matching event keyword and
WriteSysEventLog=True to the appropriate definition or section. For example:
[Heartbeat]
...
WriteSysEventLog=True
Error=${TimeStamp} Error ${Name} ${PID}, ${StatusData}
With this configuration, whenever an error occurs in one of TelAlert’s processes, TelAlert will write
the string defined by the Error event keyword value, with its replaceable parameters expanded, to
the system log.
17.5.3 Issuing a Command
Configuring TelAlert to respond to an event by sending an SNMP trap or writing to the operating
system log is straightforward. You simply add SNMPHost=hostname or
WriteSysEventLog=True to the relevant definition.
Configuring it to respond to an event by sending a command is more complicated. There are four
keywords you may use: Command, Shell, FIFOFileName, and WriteExecsToTrail:
Command: Typically, this keyword’s value contains the command string you want TelAlert to issue
at the command line, enclosed in double quotes. The string usually contains a number of
substitution parameters, especially ${EventData}, which TelAlert will expand with their current
values before issuing the command.
Shell: This specifies the shell you want to be involved in carrying out this action; the default value
is /bin/ sh -c. You are required to specify a Shell value only if (1) you want TelAlert to run a
script to process the event and (2) the script does not contain a marker that lets your system know
what shell to use to run it. When the Command value is not a shell command (as is normally the
case in Windows), the Shell value should be blank.
As far as TelAlert is concerned, Shell can contain both a shell reference (if one is needed) and the
command you want to be executed. Likewise, Command can contain the command you want to be
executed, preceded by a shell reference (if one is required). Thus, you are free to combine the
Shell and Command values and place the result entirely on one or the other of these lines.
Likewise, as long as you maintain the proper order, you are free to split their combined value
across both lines at any natural point. The program you are asking TelAlert to run, however, may
prefer a specific arrangement.
Repeating Execution Attempts
By default, the failure of a command specified using Command and/or Shell is
considered a failure, and the intended action will not be carried out. You can change this
behavior with the MaxAttempts and AttemptWait keywords.
MaxAttempts specifies the maximum number of times you want TelAlert to try to
execute the command. The default is 1; the maximum permitted value is 20.
AttemptWait specifies how many seconds you want TelAlert to wait following a failure
before trying again. The minimum value is 1; the maximum is 60. The default value is 5.
262 | TelAlert 6e™ Administrator Guide - Version 6.1.29
FIFOFileName: Assuming the program you are invoking in Shell and/or Command supports
such behavior, FIFOFileName allows you to run this program once (at the event’s first
occurrence) and write both initial and subsequent event data to a specified file that the program
can then continuously read. The value you assign FIFOFileName is the name of the file from
which you want your program to read. If you do assign it a value, you should make sure that
${FIFOFileName} appears at the point in your Command or Shell value where you want the
name of the file to be passed to the program.
WriteExecsToTrail: If you set this keyword to True, TelAlert will write the results of each
attempted execution of the command to the telalert.trail file. This can be useful when
debugging a command that does not work as expected.
Event Substitution Parameters Supported in Command and Shell Keyword Values
Shell and Command support a limited number of TelAlert substitution parameters. Most of these
are used to point to various directories in which components of TelAlert are installed. Another is
${EventData}, which is especially important. Include this substitution parameter as part of
either Shell or Command if TelAlert is to pass information from the event (as defined by the value
assigned to the event keyword) to the specified program or script. Following is a complete list of
substitutions supported in Shell and Command:
� ${Definition}— The name of the telalert.ini definition in which the Command keyword appears. When Command appears at the section level, the section name is passed instead.
� ${EventData}— The string formed based on the value assigned to the event keyword.
� ${FIFOFileName}— The name of the pipe that the program should read from (used only when the FIFOFileName keyword specifies the name of this pipe).
� ${SystemRoot}— The directory in which Windows is installed (typically c:\WINNT), or, on UNIX, the root directory (/).
� ${SystemRootFS}— The same as ${SystemRoot}, but with any backslash characters translated into forward slashes.
� ${TelAlertBin}— The value of the TelAlertBin environment variable.
� ${TelAlertBinFS}—The same as ${TelAlertBin}, but with any backslash characters translated into forward slashes.
� ${TelAlertCfg}— The value of the TelAlertCfg environment variable.
� ${TelAlertCfgFS}—The same as ${TelAlertCfg}, but with any backslash characters translated into forward slashes.
� ${TelAlertDir}— The value of the TelAlertDir environment variable.
� ${TelAlertDirFS}— The same as ${TelAlertDir}, but with any backslash characters translated into forward slashes.
� ${TelAlertTmp}— The value of the TelAlertTmp environment variable.
� ${TelAlertTmpFS}— The same as ${TelAlertTmp}, but with any backslash characters translated into forward slashes.
Chapter 19: Getting Familiar with the TelAlert Monitor | 263
17.5.4 Making One Event Trigger Multiple Actions
You can configure TelAlert to trigger multiple actions in response to a single event. There are
several ways to do this:
� You may trigger a command, an SNMP trap, and a write to the system log by including
Notification, SNMPHosts, and WriteSysEventLogin the same section or
definition.
� You may refer to multiple [Notification] definitions by including two or more of the
keywords discussed in “About Notificationand Related Keywords,” above, in the same
definition. Note that each referenced [Notification] definition may (and usually will)
include a different set of event keywords.
� The Command value in a [Notification] definition may refer to a script that performs
multiple commands.
� The SNMPHosts keyword value may contain multiple host names or IP addresses,
separated by commas.
These methods are not mutually exclusive. You may use all of them to process the same event.
17.6 Alert-Related and Miscellaneous Events: The
[Notification] Section
The event processing supported by the [Notification] section is by far TelAlert’s most flexible
and wide-ranging. You can use it to process replies received in response to TelAlert notifications,
requests sent by two-way pagers capable of initiating sends, and environmental changes detected
by a TelAlert Sensor Engine. You can also use it to process a broad spectrum of other events.
To do this, you must first understand the general principles at work in TelAlert’s event-processing
capabilities, as explained in the previous sections. The following discusses the techniques specific
to the [Notification] section and lists the events and substitution parameters it supports.
[Notification] Section Basics
All TelAlert notifications are based on a [Configuration] definition, and in any such definition
you can point to a [Notification] definition using the Notification keyword (or one of the other
keywords discussed in “About Notification and Related Keywords,” above). Any event relating
to a notification processed by this [Configuration] definition and specified in the
[Notification] definition will trigger the action represented by the combined values assigned
to Shell, Command, and the event keyword.
For instance, perhaps you have a service level agreement with your paging service provider, and
this SLA stipulates that you will not encounter more than a certain number of busy signals per 100
attempts. To monitor this, you might have your [Configuration] definition invoke a
[Notification] definition called {MonitorDialing}, and this definition might contain the
Change keyword—referring to the generic dialing event that includes dialing failures such as busy,
no dial tone, no answer, and so on. Whenever TelAlert attempts to send a notification using this
[Configuration] definition and encounters a dialing problem included under Change,
{MonitorDialing} is invoked and the specified event data (${State}, for instance) is passed
to the script or program you have indicated by the values assigned to Shell and/or Command. For
purposes of monitoring the performance of your paging service provider, you would want to pass
264 | TelAlert 6e™ Administrator Guide - Version 6.1.29
this data to a program capable of parsing it and reporting in real time on any failures exceeding the
threshold permitted by the SLA.
Replies
Any TelAlert notification that invokes a [Response] definition can be replied to by the message
recipient. Depending on the medium used to send the message, this reply can come via two-way
pager, touch-tone telephone, email or the command line. If TelAlert receives a reply and the
[Configuration] definition originally used to send the message points to a [Notification]
entry containing the Reply event keyword, TelAlert processes the reply according to the terms of
this [Notification] entry. Thus, a reply can be made to trigger a script or program, and the
information contained in the reply can be passed to this script or program in order to have TelAlert
execute an action desired by the person replying.
It is best to configure reply events using the NotificationReply keyword (discussed in “About
Notification and Related Keywords,” above). This approach leaves the Notification
keyword free for other purposes.
Note that some basic replies that can be specified in a [Response] definition (including ack,
nak, etc.) can be processed directly by TelAlert, without any action being defined under
[Notification]. Conversely, you can create other reply options that have nothing to do with
TelAlert—replies designed only to trigger and be processed by the appropriate [Notification]
definition.
Requests
Certain two-way paging services permit users to use their two-way paging devices to initiate a
“request”—a message that is not a response to any received page. TelAlert polls for requests if
PollRequests is set to True in a [Configuration] definition representing a paging service
that supports requests. (Any [Configuration] definition in which PollRequests is set to
True also requires ServerPIN and Access values. ServerPIN is the identifier that tells the
service who is asking for the messages. Access is the security code or password associated with
the account. For BSWD, ServerPIN is the DAS account Administrator. Note that BSWD requires
ServerPIN and Access values for both regular two-way polling and unsolicited polling. SkyTel
does not require them for regular two-way polling, but they will be used if you provide them.)
To have TelAlert treat the retrieval of a request as an event, use the keyword
NotificationRequest (discussed in “About Notification and Related Keywords,” above)
to invoke a [Notification] definition. Thus, a request can trigger a script or program, and the
information contained in the request can be passed to this script or program so that TelAlert
executes an action desired by the person initiating the request.
Consider this example of [Configuration] and [Notification] definitions set up for
request processing:
[Configuration]
...
{SkyTelITwoWayTextPager}
Type=InteractiveTextPager
NoneParity=True
Chapter 19: Getting Familiar with the TelAlert Monitor | 265
MaxMessagesPerCall=100
Speed=19200
AreaCode=800
Number=679-2778
NotificationReply=ReplyAction
NotificationRequest=RequestAction
[Notification]
...
{RequestAction}
Active=True
Shell=""
Command=${TelAlertCfg}/Scripts/request.sh ${EventData}
Request=${TimeStamp},Request,${RequestName},${Configuration},
${PIN},${RequestID},"${Request}"
When TelAlert retrieves a request using this [Configuration] definition, the presence of the
NotificationRequestvalue tells it to look to the invoked [Notification] definition (i.e.,
{RequestAction}) and process the retrieved message according to the terms laid out in there—
terms specified in the combination of Request, Command, and Shell. (Note that the
[Configuration] definition points to another [Notification] definition using
NotificationReply.)
It may be that your two-way paging devices are capable of initiating requests using more than one
application. If you want requests from different pager applications to result in different actions, you
can set NotificationRequest to <RequestName> (literally, “RequestName” enclosed by
angle brackets) and create [Notification] definitions with names matching the
${RequestName} value associated with each application. To use this feature, your pager
applications must be set up so that each delivers a unique ${RequestName} value. Pager
applications from Vytek Messaging Services, Inc. follow this convention. If, when using a
[Configuration] definition in which NotificationRequest=<RequestName>, TelAlert
retrieves a request with a ${RequestName} value that does not match any [Notification]
definition, it generates an error. If the ${RequestName} value reduces to Requestbecause no
vertical bar is present, TelAlert looks for a [Notification] definition called {Request}. You
may want to set up a definition with this name for use in these situations.
266 | TelAlert 6e™ Administrator Guide - Version 6.1.29
17.6.1 Event Keywords Supported in the [Notification] Section
When TelAlert detects one of these events, it takes the action you have prescribed according to the
values assigned to Command, Shell, and the corresponding event keyword.
Note that not all event keywords are meaningful for inclusion in every [Notification]
definition. For example, Sensor makes no sense in a [Notification] definition that will be
invoked by a [Configuration] definition, and AlertCompleted makes no sense in one that
will be invoked by a [Sensor] definition. Providing a keyword that is not appropriate for a given
entry does not generate an error; this keyword will simply not be used.
� AlertDelayed—The event TelAlert recognizes when an alert is delayed by virtue of a
-delay value on the command line.
� AlertStarted—The event TelAlert recognizes when an alert is started (i.e., when
TelAlert receives the command to create the alert and begins processing it).
� AlertError—The event TelAlert recognizes when an error occurs in the processing of an
alert owing to erroneous information being passed on the command line (typically, one or more invalid definition names).
� AlertNotSupported—The event TelAlert recognizes when no destination involved in an
alert is supported by TelAlert (owing typically to the absence of appropriate resources for processing the sends).
� AlertOffDuty—The event TelAlert recognizes when an alert cannot be processed
because none of the specified destinations are on duty.
� AlertFilter—The event TelAlert recognizes when an alert cannot be processed because
every specified destination is filtered according to the terms of a [Filter] definition.
� AlertCleared—The event TelAlert recognizes when an alert is cleared (i.e., when all
remaining processing is stopped by a -clearalert, -cleargroup, -clearall, or
-clear command).
� AlertCompleted—The event TelAlert recognizes when an alert completes by virtue of all
processing having been finished without being cleared.
Alerts Versus Sends
Some of the events and substitution parameters described below are related to alerts—
the comprehensive entities created within TelAlert when messages are directed to
destinations, configurations, or groups. Others have to do with sends— the smaller
entities associated with the sending of a message to a single destination. When a
message is directed to a single destination, both an alert and a send are created, and
these are more or less identical. When a message is directed to a group comprised of
three destinations, however, an alert and three sends are created. Here, the nature of a
send as a subset of an alert is most clearly illustrated. There are also “group send” entities: subsets of alerts in which a message is directed to a group of destinations.
Chapter 19: Getting Familiar with the TelAlert Monitor | 267
� AlertReleased—The event TelAlert recognizes when an alert is released from a held
state thanks to the release of all held sends using –release or –releaseall or the
alert itself using -releasealert.
� AlertCheck—The event TelAlert recognizes when an -insert -check is performed.
� Started—The event TelAlert recognizes when a send is started.
� Error—The event TelAlert recognizes when an error occurs in the processing of a send.
� ErrorLimit—The event TelAlert recognizes when a send reaches a limit defined by
DialErrorLimit and DialErrorWindow, or by ConnectErrorLimit and
ConnectErrorWindow.
� NotSupported—The event TelAlert recognizes when the destination involved in a send is
not supported by TelAlert (owing typically to the absence of appropriate resources for processing the send).
� OffDuty—The event TelAlert recognizes when a send cannot be processed because the
intended destination is not on duty.
� Filter—The event TelAlert recognizes when a send cannot be processed because the
specified destination is filtered according to the terms of a [Filter] definition.
� Change—The event TelAlert recognizes when a send is comprised of multiple processing
steps and one of these steps has been completed (this can occur because the send is set up to take multiple steps, or because of a dialing or other error).
� ReplyChange—The event TelAlert recognizes when an error occurs in the retrieval of a
reply or request.
� Reply—The event TelAlert recognizes when a reply is received.
� BadPassword—The event TelAlert recognizes when a recipient is prompted for a
password and provides an incorrect one.
� Acknowledged—The event TelAlert recognizes when a send is acknowledged using –ack
or -ackall.
� AcknowledgedHeld—The event TelAlert recognizes when a send is acknowledged and
held using -hold.
� NotAcknowledged—The event TelAlert recognizes when a send is negatively
acknowledged using –nak or -nakall.
� Cleared—The event TelAlert recognizes when a send is cleared using -clear,
-clearall, -clearalert, or -cleargroup.
� Completed—The event TelAlert recognizes when a send completes by virtue of all
processing having been finished without being cleared.
� Released—The event TelAlert recognizes when a send is released from a held state using
-release, -releaseall, or -releasealert.
268 | TelAlert 6e™ Administrator Guide - Version 6.1.29
� Connect—The event TelAlert recognizes when a step associated with answering or ending
an inbound call occurs.
� Security—All remote connects and disconnects are sent to this keyword. The
[Notification] paragraphs referenced by [Limits] Notification,
NotificationLog, NotificationTrap and NotificationITV are invoked for
each event.
� Warning—The event TelAlert recognizes when it sends a message that would have failed
had AllowUnsupportedTypeSends been set to False.
� Activation—The event TelAlert recognizes when a definition is activated or deactivated.
� Engine—The event TelAlert recognizes when a TelAlert Engine reports a change in its
status.
� Analog—The event TelAlert recognizes when a change in the status of an analog device is
reported.
� Sensor—The event TelAlert recognizes when a change in the status of a sensor device is
reported.
� Relay—The event TelAlert recognizes when a change in the status of a relay device is
reported.
� Power—The event TelAlert recognizes when a change in the power level of the TelAlert
Engine is reported.
� Battery—The event TelAlert recognizes when a change in the status of the TelAlert
Engine battery is reported.
� Talk—The event TelAlert recognizes when a –talkload is performed.
� Request—The event TelAlert recognizes when a request is received.
Non-Alert Events in the [Notification] Section
While events defined in the [Notification] section are typically triggered by
[Configuration], [Destination], [Group], or [User] definitions— that is,
by alerts—as discussed below they may also be triggered by the following events relating
to [Analog], [Battery], [Port], [Power], [Relay], or [Sensor]
definitions.
The [Limits] section can also trigger [Notification] definitions, but only for error
or activation events only, and only when no other relevant section contains the same notification keyword.
Chapter 19: Getting Familiar with the TelAlert Monitor | 269
17.6.2 Event Substitution Parameters Supported in the
[Notification] Section
Note that not all substitution parameters are appropriate for all events. If you provide an
inappropriate parameter when assigning an event value, no error will result; instead, TelAlert will
substitute an empty value.
� ${AlertID}—The alert ID.
� ${Calls}—The maximum number of call attempts that can be made, the number that
have been completed, and the number that have failed.
� ${Check}—The -checkstring.
� ${ClientHost}—The name of the host from which the command generating the alert
was received.
� ${ClientUser}—The user name on the host machine from which the command
generating the alert was received.
� ${Configuration}—The [Configuration] definition used in processing the send.
� ${ConnectID}—The ID identifying this unique telephone call.
� ${Destination}—The destination to which the send was directed.
� ${EventNum}—The event number.
� ${Group}—The name of the group specified by -g or, when using -l, by –name (if
addressed to nested groups, the top-level group; with –i and -c, the value is <none>)
� ${GroupID}—The “group send” ID.
� ${IPCheck}—The -ipcheck string.
� ${MaskedTicket}—The Ticket value following its alteration according to the terms of
the TicketMask value.
� ${Message}—The message provided at the origination of the send.
� ${Number}—The telephone number used in processing the send.
� ${PIN}—The PIN used in processing the send.
� ${Port}—The [Port] definition used in processing the send.
� ${Priority}—The Priority value provided at the origination of the send.
� ${Remark}—The -remark value associated with the send.
� ${Reply}—The actual text of the reply.
� ${ReplyID}—A pair of values: the ID assigned to the reply by TelAlert and the ID
assigned to it by the service provider.
270 | TelAlert 6e™ Administrator Guide - Version 6.1.29
� ${ReplyTo}—The ReplyTo value associated with the send.
� ${Request}—The full text of the request.
� ${RequestID}—The ID assigned to the request by the service provider.
� ${RequestName}—The text preceding the first vertical bar (|) in the request, up to
sixteen characters (if no vertical bar is present, this parameter is assigned the same value as ${Request}).
� ${RequestPIN}—The PIN or email address of the device that originated the request.
� ${SendID}—The ID associated with the send.
� ${ServerHost}—The name of the host on which TelAlert is running.
� ${Source}—The -source value provided at the origination of the send.
� ${StartTime}—The time that the processing of the send or alert was begun.
� ${State}—The current send state: ${StatusData} plus additional state information.
� ${StatusData}—The state number and associated description of this event.
� ${StateNum}—The state number of this event.
� ${Subgroup}—The name of the lowest-level subgroup to which the message was
addressed (if the message was not addressed to a group, the value is <none>)
� ${Subject}—The -subject value provided at the origination of the send.
� ${Ticket}—The -ticket value provided at the origination of the send.
� ${TimeStamp}—The time that the event occurred.
� ${To}—The To value used in processing the send.
� ${TrackID}—The tracking ID assigned to the send by TelAlert (part of a sequence
specific to each destination).
� ${Type}—The Type value of the [Configuration] definition used to process the
send.
� ${User}—The User value used in processing the send.
� ${Value}—The value reported from an analog, sensor, relay, battery, or power event.
Chapter 19: Getting Familiar with the TelAlert Monitor | 271
17.7 Process-Related Events: The [Heartbeat]
Section
The [Heartbeat] section allows you to tell TelAlert whether you would like to be kept informed
about certain events related to the state of the various TelAlert processes and, if so, the means by
which it should do so. Here, Command, Shell, and one or more event-related keywords combine
to form the string that will be passed on the command line when an event matching one of those
event keywords takes place. Consider the following example:
[Heartbeat]
Active=True
WriteExecsToTrail=False
Interval=0
Shell=""
Command=${TelAlertCfg}/Scripts/notify.sh ${EventData}
Start=${TimeStamp} ${ServerHost} Start ${Name} ${PID}, ${StatusData}
Exit=${TimeStamp} ${ServerHost} Exit ${Name} ${PID}, ${StatusData}
Error=${TimeStamp} ${ServerHost} Error ${Name} ${PID}, ${StatusData}
Update=${TimeStamp} ${ServerHost} Update ${Name} ${PID}, ${StatusData}
In this example, a script called notify.sh (or, in Windows, notify.pl) is invoked as part of
the Command value whenever one of the four specified events occurs. The data specified in the
event’s definition is passed to and processed by this script. Interval refers to the interval at
which TelAlert should issue a status update (assuming Update has been assigned a value). Other
keywords are covered below.
notify.sh is provided with TelAlert. You can customize it or invoke instead a script or program
of your choice.
17.7.1 Event Keywords Supported in the [Heartbeat] Section
In the above example, you see all four of the event keywords permitted in the [Heartbeat]
section:
� Start—The event TelAlert recognizes upon the starting of any of the TelAlert processes.
� Exit—The event TelAlert recognizes upon the termination of any of the TelAlert
processes.
� Error—The event TelAlert recognizes upon the occurrence of an error relating to any of
the TelAlert processes.
� Update—The event TelAlert recognizes if it detects a TelAlert process is running at the
beginning of a new “heartbeat” interval.
272 | TelAlert 6e™ Administrator Guide - Version 6.1.29
When TelAlert detects one of these events, it takes the action you have prescribed according to the
values assigned to Command, Shell, and the corresponding event keyword.
17.7.2 Event Substitution Parameters Supported in the [Heartbeat] Section
Comprising the value assigned to each event keyword, you see all five of the substitution
parameters supported for event definitions in the [Heartbeat] section:
� ${Name}—The name of the process associated with the event.
� ${PID}—The daemon process ID associated with the event.
� ${ServerHost}—The name of the host on which TelAlert is running.
� ${StatusData}—The state number and associated description of this event.
� ${TimeStamp}—The time of the event.
17.8 Logging-Related Events: The [File] Section
One feature of the [File] section is that it allows you to tell TelAlert whether you would like to be
informed when TelAlert’s default log files reach their maximum size and, if so, the means by which
it should do so. Here, Command, Shell, and one or more event-related keywords combine to form
the string that will be passed on the command line when an event matching one of those event
keywords takes place.
Consider the following example:
[File]
# Note that [File] is only invoked for BUILT-IN TelAlert files.
# Events associated with log files used with ’helper’ programs
# (such as readmail and gsmpoll # in [Process], or notify in
# [Notification], [Heartbeat], etc.) do NOT invoke this section.
Comment=TelAlert sample [File] Section
Active=True
AttemptWait=5m
MaxAttempts=1
SNMPHosts=""
WriteExecsToTrail=False
WriteSysEventLog=False
WriteTrapsToTrail=False
Shell=""
# Use only ONE of the following three Command= examples. Note that the
# first example, (that calls the notify.exe program) requires values for
# the FIFOFileName and EndOfData keywords. The two subsequent examples
# (for script invocation in UNIX and Windows) must have blank values for
# FIFOFileName and EndOfData
Chapter 19: Getting Familiar with the TelAlert Monitor | 273
#Example for high-volume logging to a flat file
#Command=${TelAlertBin}/notify ${Message} -file ${TelAlertDir)
# notify.log -size 50000 -time 01:00 -dayofweek 0
#FIFOFileName=${TelAlertTmp}/notify.fifo
#EndOfData=${TimeStamp} EOD
#Example for UNIX custom script invocation
# Command=${TelAlertCfg}/Scripts/notify.sh ${Message}
# FIFOFileName="" must be blank
# EndOfData=""
#Example for Windows custom script invocation
#Requires MKS Toolkit; modify location of MKS as needed
# Command="C:\Program Files\MKS Toolkit\mksnt\sh.exe
# ${TelAlertCfgFS}/Scripts/notify.ksh ${Message}
# FIFOFileName=""
# EndOfData=""
# For telalert.trail
TrailMaxFileSize=50000
TrailSwitchTime=-1
TrailSwitchDayOfWeek=-1
TrailSwitchCmd=${TimeStamp} ${Name}(${PID}) ${BaseFS} Switched to
${FileFS}
TrailErrorExit=True
TrailErrorCmd=""
# For telalerte.log
EventMaxFileSize=50000
EventSwitchTime=-1
EventSwitchDayOfWeek=-1
EventSwitchCmd=${TimeStamp} ${Name}(${PID}) ${BaseFS} Switched to
${FileFS}
EventErrorExit=True
EventErrorCmd=""
# For telalertd#.log, telalertf#.log, telalertm#.log, telalertr#.log,
# telalerts#.log, telalertv#.log
LogMaxFileSize=50000
LogSwitchTime=-1
LogSwitchDayOfWeek=-1
LogSwitchCmd=${TimeStamp} ${Name}(${PID}) ${BaseFS} Switched to
${FileFS}
LogErrorExit=True
LogErrorCmd=""
# The xxxErrorCmd values are ignored if the related xxxErrorExit=True
274 | TelAlert 6e™ Administrator Guide - Version 6.1.29
With some of these configurations, a program called notify.exe is invoked as part of the
Command value whenever one of the three specified events occurs. The data specified in the event
keyword’s value is passed to and processed by this program. notify.exe is provided with
TelAlert. You can invoke instead a program or script of your choice.
The notify executable is best for high-volume logging to a flat file. The notify scripts are best for
low-volume transfer of selected events to a custom script that takes special action on the events.
The example scripts simply log the events to a flat file; unless you customize the scripts, they have
little advantage over the executable, and have the disadvantage of additional operating-system
overhead compared to the executable.
Note that you should not have multiple invocations of the notifyexecutable with the same
FIFOFilename=value and/or the same -file filename in the Command=line.
17.8.1 Handling Rollover of telaconfe.log and telainetde.log
The [File] section also handles rollover of the telaconfe.log and telainetde.log files.
The following is a sample [File] section for handling of these files:
# TelaConf and TelaInetD do not have their own .ini or .sects
# files, so the parameters relating to their log file rollover
# are kept in telalert.ini’s [File] section. Unlike telalerte,
# telaconfe and telainetde do not have functionality to execute
# operating system commands, so these keywords do NOT exist:
# ConfSwitchCmd, ConfErrorCmd, InetdSwitchCmd, InetdErrorCmd
# For telaconfe.log
ConfMaxFileSize=50000
ConfSwitchTime=-1
ConfSwitchDayOfWeek=-1
ConfErrorExit=False
# For telainetde.log
InetdMaxFileSize=100000
InetdSwitchTime=-1
InetdSwitchDayOfWeek=-1
InetdErrorExit=False
17.8.2 Handling telalert.sects and telalert.ini file Backups when TelAdmin is Used
Use the following [File] example to handle telalert.sects and telalert.ini file
backups when using TelAdmin.
BackupIniFile=""
NumIniSectsFileBackups=2
ReloadAfterSectsFileWritten=True
WriteSectsFileAfterChanges=True
WriteSectsFileInterval=0s
NumIniSectsFileBackups is the maximum number of backup copies of telalert.ini and
telalert.sects TelAlert will maintain. The backup files are named telalert.sects.
Chapter 19: Getting Familiar with the TelAlert Monitor | 275
followed by a date-time stamp in the format YYYYMMDDHHMMSS
(Year/Month/Day/Hour/Minute/Seconds). If a file with that name already exists, TelAlert will
append a three-digit number to the end of the new file’s name. To disable backup, set
NumIniSectsFileBackups to 0.
ReloadAfterSectsFileWritten, when set to True, causes TelAlert to automatically activate
changes to telalert.sects whenever:
1. TelAdmin user executes a File / Save Data command;
2. telalert.sects is saved automatically (see WriteSectsFileInterval); or if
WriteSectsFileAfterChanges is set to True,
3. TelAdmin user presses an Update button.
WriteSectsFileAfterChanges, when set to False, causes configuration changes made with
TelAdmin to be saved only when a user executes the File / Save Data command. If set to True,
TelAlert saves configuration changes automatically at the interval specified by
WriteSectsFileInterval.
WriteSectsFileInterval is the minimum amount of time TelAlert will wait after saving
telalert.sects to disk before saving it again.
17.8.3 Miscellaneous [File] Functions
The [File] section is also used to specify the NumVoiceFiles value, as follows:
NumVoiceFiles=8
17.8.4 Event Substitution Parameters Supported in the [File] Section
These are the substitution parameters that are allowed as part of the event keyword value in your
[File] section:
� ${Base}—The name of the original log file.
� ${BaseFS}—The same as ${Base}, but with any backslash characters translated into
forward slashes.
� ${Error}—The error code from the failure of a system function (if any).
� ${File}—The name of the file to which the log was switched.
� ${FileFS}—The same as ${File}, but with any backslash characters translated into
forward slashes.
� ${Function}—The function that failed (if any).
� ${Name}—The name of the process associated with the event.
� ${PID}—The daemon process ID associated with the event.
� ${ServerHost}—The name of the host on which TelAlert is running.
� ${TimeStamp}—The time of the event.
18 Miscellaneous
Administrative Tasks 18.1 Overview
Information on many of the administrative tasks associated with running TelAlert, including
starting, stopping, and initializing TelAlert, installing clients, configuring TelAlert to run
automatically, and setting up the TelAlert Web client.
18.2 Starting and Stopping TelAlert
To start TelAlert, use this command:
telalert -start
At any time, you can stop TelAlert using this command:
telalert –stop
The -terse Command Line Option
The -terse command line option will cause TelAlert to suppress all startup output, except
for errors and warnings. For example: telalert -start -terse.
Do Not Perform an -init If You Use TelAdmin
If you are using TelAdmin, doing an -init can wipe out your TelAlert configuration.
Refer to Switching Between Configuration Methods in the TelAdmin User Guide for further discussion.
278 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.3 Configuring TelAlert to Run Automatically
18.3.1 On Windows
When you install TelAlert on Windows, the installation application automatically configures several
TelAlert services to run automatically. No change to the server configuration for all services to be
started each time the machine is re-started.
18.3.2 On UNIX
System V-Compliant Systems
On the machine on which the TelAlert server is installed, find the file called telalert.init.d.
It will be in the same directory as the telelartc file.
Copy this file to the directory on the same machine that holds the start-up scripts. Change the
name of the file to telalert.
In the appropriate run-level status directory (rc<n>.d), create a link to this file.
Non-System V-Compliant Systems
Follow the standard procedure for the system on which the TelAlert server is installed. In most
cases, this involves adding telalert –start to the system start-up script.
18.4 Installing TelAlert Clients
18.4.1 Configuring the Server To Accept Remote Clients
You must do two things before remote systems running TelAlert clients (telalertc, the Web
client, or TelAdmin) can connect to a TelAlert server:
1. Each client’s IP address must be entered in the server’s telalert.hosts file. This is
simply a list of IP addresses; edit it with any text editor and add the necessary addresses.
This step is not relevant for Web clients. List entries may use wildcards, for example
192.168.*.* (any address beginning with 192.168), or may be a range of addresses,
such as 192.168.168.38-144.
Alternatively, you can temporarily or permanently modify this list of permitted hosts using
various commands. For more information, refer to Command Line Options for Modifying
Filter Files in Chapter 3 of the TelAlert Keyword and Command Reference.
2. You must have purchased licenses sufficient to handle as many clients as you wish to be
able to connect simultaneously. Contact the MIR3 Sales Department if you need additional
licenses, or licenses for different operating systems.
If either of these conditions is not met, the client will fail with an error message, usually this one:
Exit *telalert, error 7: Can’t connect to any host
Client Licenses in Evaluation Versions
The free evaluation version of TelAlert supports remote clients. So, with any unexpired demo license,
you can add remote clients without affecting the port connections you have already set up. However,
if you plan to test a lot of different pager PINs, you may find a limitation imposed. Contact your MIR3
sales representative to increase this amount if you need to run a very large test.
Chapter 19: Getting Familiar with the TelAlert Monitor | 279
Communicating with Clients across a Firewall
TelAlert clients communicate with the TelAlert server using sockets over TCP. By default, TelAlert
uses port 25378. If you accepted the defaults when you installed TelAlert, make sure that your
firewall is set up to grant access to this port. If you must use a different port, you must change the
port used by TelAlert to one that the firewall will permit to be accessed.
To do this, add the following line to the files that control the services on both the client and server
machines. Use the desired port number in place of xxxxx.
telalert xxxxx/tcp # TelAlert
Location of files needing this change:
� UNIX servers
/etc/services
� Windows servers
%SystemRoot%\system32\drivers\etc\services
18.4.2 Installing the TelAdmin Client
TelAdmin runs only on Windows. Download the TelAlert Messaging Server software from the
TelAlert Web site: http://www.telalert.com/eval/telalert
When you install TelAlert on a Windows system, the setup utility will automatically install a copy of
TelAdmin. To install TelAdmin on other systems running Windows, unzip the downloaded file to any
directory. To run TelAdmin, double-click TelAlert.exe, or create a shortcut and add it to your
Start menu.
The first time you run TelAdmin, you must enter the TelAlert server’s IP address. Right-click the
TelAlert Hosts icon, choose Add New, enter the IP address in the TelAlert Host field, and click
OK.
18.4.3 Installing Remote Command-Line Clients on Windows
The installation application will automatically install a copy of the TelAlert client (telalertc on
UNIX, telalertc.exe on Windows) on the same machine and in the same directory as the
TelAlert server.
If you want to install a client on a remote machine, follow these steps:
One: Locate the Correct File
You can download the client application from the MIR3 web site. Using a browser, go to
http://www.mir3.com/downloads/telalert/ and give your user name and password. Download the
file appropriate to your target environment.
Two: Extract the File Onto the Machine
Extract the file onto the remote machine, in the directory of your choice. It does not matter where
you put the TelAlert client.
Three: Make Sure the Client Knows Where to Find the Server(s)
You can do this in either of two ways.
280 | TelAlert 6e™ Administrator Guide - Version 6.1.29
One, you can set the TELALERTHOST environment variable on the machine on which
the client is installed.
1. From the Start menu, choose Settings
/ Control Panel.
2. Double-click the System icon.
3. Click the Environment tab.
4. In the Variable field, type
TELALERTHOST.
5. In the Value field, type the host’s IP
address. If you have one or more
backup hosts and wish the client to roll
over automatically when the primary
host is down, add their IP addresses or
host names, separated by spaces.
6. Click Set, then click OK.
Two, you can use the -host option each time
you use this client to access the server:
telalertc -i speaker -m "this is a test" -host primary_host_IP_address 1st_backup_host_IP_address 2nd_backup_host_IP_address ...
telalertc -i speaker -m "this is a test" -host primary_host_name
1st_backup_host_name 2nd_backup_host_name ...
Chapter 19: Getting Familiar with the TelAlert Monitor | 281
18.4.4 Installing Remote Command-Line Clients on UNIX
The installation script will automatically install a copy of the TelAlert client (telalertc on UNIX,
telalertc.exe on Windows) on the same machine and in the same directory as the TelAlert
server.
If you want to install a client on a remote machine, follow these steps:
One: Locate the Correct File
You can download the client application from the MIR3 web site. Using a browser, go to
http://www.mir3.com/downloads/telalert/ and give your user name and password. Download the
file appropriate to your target environment.
Two: Extract the File Onto the Machine
Extract the file onto the remote machine, in the directory of your choice. It does not matter where
you put the TelAlert client.
Three: Make Sure the Client Knows Where to Find the Server(s)
You can do this in either of two ways.
One, you can set the TELALERTHOST environment variable on the machine on which the client is installed. Edit the shell initialization script and add the line:
TELALERTHOST=host_IP_address
If you have one or more backup hosts and wish the client to roll over automatically when the
primary host is down, add their IP addresses, separated by spaces.
TELALERTHOST=primary_host_IP_address 1st_backup_host_IP_address
2nd_backup_host_IP_address ...
Two, you can use the -host option each time you use this client to access the server:
telalertc -i speaker -m "this is a test"
–host primary_host_IP_address first_backup_host_IP_address
second_backup_host_IP_address ...
telalertc -i speaker -m "this is a test" -host primary_host_name
first_backup_host_name second_backup_host_name ...
282 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.5 Setting up the TelAlert Web Clients
TelAlert includes two client applications that run on Web servers and can be accessed from any
Web browser. TelAlertH.exe (for Windows) and telalerth (for UNIX) are functionally equivalent
to the command-line client telalertc, and TelAlertHS.exe (for Windows) and telalerths (for
UNIX) are functionally equivalent to telalert. (In fact, both can also be used as command-line
applications.)
In general, each Web client serves as a messaging interface for cell phone microbrowsers, and it
can also serve as an alternative (more lightweight) messaging interface for a standard browser.
Thus, the Web clients extend your messaging interface options. Each Web client can be used as
the sole means of sending and receiving messages, or it can be used in addition to other means of
sending and receiving messages. You can also install the TelAlertH Web client so that your support
staff can send, receive and respond to messages via a cell phone microbrowser.
18.5.1 Installing the Web Clients
To install either client, do the following:
Copy the program to a Web server’s CGI directory. In Windows, that directory is usually called
scripts; with most UNIX Web servers, it is cgi-bin. Any Web server that supports CGI scripts should
work, including the Web Server that Microsoft distributes with Windows servers.
By default, these clients assume they are running on the same computer that runs the TelAlert
server. To change that, in the same directory as the clients create a file called telalerth.ini that
contains the following line:
Host = [name or IP address of TelAlert server]
To run one of these clients, just point your browser to the program. For example:
http://www.myserver.com/scripts/telalerth.exe
http://www.myserver.com/cgi-bin/telalerth
You can also point to the server’s IP address. For example, when working at the server itself, you
could use one of these URLs:
http://127.0.0.1/scripts/telalerths.exe
http://127.0.0.1/cgi-bin/telalerths
18.5.2 Running Multiple Web Clients on the Same Machine
You can run more than one Web client on the same machine. Install telalerth, then rename it as you like— telalertHelpDesk, for example. When accessed by a browser, the program will
first look for telalertHelpDesk.ini. If it does not find this file, it will use telalerth.ini
instead.
Chapter 19: Getting Familiar with the TelAlert Monitor | 283
18.5.3 Using the Web Clients with Web-Enabled Cell Phones
Cellular telephones equipped with microbrowsers can access the TelAlert Web client. The Web client
will automatically recognize a supported microbrowser and present it with information in a suitable
format. Thus, by going to the TelAlert Web client's URL, users with these devices can view,
acknowledge, hold, negatively acknowledge, release, clear, and reply to messages, much as if they
were visiting the Web page from a networked computer.
One approach for Web-enabled phones is to send notifications that do not actually contain the
message that TelAlert has been asked to convey. Rather, they are comprised of a subject line and
a URL the recipient should visit in order to retrieve the message. A recipient’s phone indicates that
a message has arrived; when the recipient selects and "reads" the message, the microbrowser
follows the provided URL (which has the send ID appended) and connects to the TelAlert Web
client. For instructions on setting up TelAlert to send messages to Web-enabled telephones, refer to
Sending Messages to Web-Enabled Phones in Chapter 9.
18.5.4 Installing Online Help for the Web Clients
Documentation on using the Web clients is provided as a single HTML file, Webclient_help.html.
Copy this file to a directory on your Web server (not scripts or cgi-bin, since HTML files are not
allowed in those directories) and add the URL HelpURL keyword in telalerth.ini. For example:
HelpURL=http://www.myserver.com/telalert/tawchelp.html
Clicking one of the Help links in the Web client will then bring up the online help. You may need to
close your browser and reload the Web client before the link will work.
18.5.5 Configuring telalerth with telalerth.ini
You can configure the Web clients by adding lines to telalerth.ini. The procedure is similar to
the one you follow when editing telalert.ini.
telalerth.ini Sections
telalerth.ini can contain "sections" that allow it to present different options under different
circumstances. Three such sections are automatically created using these markers:
[html]
...
[hdml]
...
[wml]
...
The HTML section serves to specify attributes that should be presented to traditional Web
browsers. The HDML section serves to specify attributes that should be presented to HDML-
compliant microbrowsers. The WML serves to specify attributes that should be presented to WML-
compliant microbrowsers. Anything preceding the first section marker applies equally to all
browsers.
284 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Two other sections are automatically defined:
[User]
...
[Admins]
...
These provide for two different versions of the Web client. The "Admin" version, accessed as
telalerths rather than telalerth, allows the user to carry out actions without providing a
Administrator or password.
You can also create your own sections to present different Web client views to different users. For
example, you might give two departments their own sections, each containing options appropriate
to that department:
[Accounting]
...
[Support]
...
Users would be presented with the appropriate view when they submit a URL with
?section=sectionname appended to the end.
Customizing the "Show" and "Show Alert" Pages
You can customize pages presented to users by telalerth.
ShowTable, ShowVTable, ShowDetailHTable, and ShowDetailVTable relate to the
screen shown when uses click the Show button and the Detail screen presented when users click
the SendID link or Action button with "Details" selected in the drop-down list. These affect the
screens shown to HTML browsers only.
ShowAlertTable, ShowAlertVTable, ShowAlertDetailHTable, and ShowAlertDetailVTable all relate to the screen presented when users click the Show Alert
button and the Detail screen presented when users click the AlertID link or press the Action button
with "Details" selected in the drop-down list. These affect the screens shown to HTML browsers
only.
ShowWAPTable and ShowWAPDetail affect the options presented to microbrowsers.
ShowWhat determines what buttons are shown on the main page: Show, Show Alert, both, or
neither.
telalerth.ini Keywords
Here is a brief guide to the telalerth.ini keywords, their meanings, and default values.
Chapter 19: Getting Familiar with the TelAlert Monitor | 285
AckWait
Command-line -ackwait value. Default: 0m
AutoResetMessage
Y/N - Clear message text boxes after a send? Default: N
AutoResetOptions
Y/N - Clear Options screen values after a send? Default: N
AutoResetTargets
Y/N - Clear Destination/Group/Config values after a send? Default: N
BodyBackground
Sets HTML attribute. Default: none
BodyColorALINK
Sets HTML attribute. Default: none
BodyColorBGCOLOR
Sets HTML attribute. Default: none
BodyColorLINK
Sets HTML attribute. Default: none
BodyColorTEXT
Sets HTML attribute. Default: none
BodyColorVLINK
Sets HTML attribute. Default: none
ConnectPause
Overrides ConnectPause configuration keyword value. Default: 2
ConnectTimer
Overrides ConnectTimer configuration keyword value.
Default: 10
ConnectTries
Overrides ConnectTries configuration keyword value. Default: 5
ConnectWait
Overrides ConnectWait configuration keyword value. Default: 30
Delay
Command-line -delay value. Default: 0m
286 | TelAlert 6e™ Administrator Guide - Version 6.1.29
DestGroupOnly
Y/N - Prevent access to Configuration/User screen? Default: N
DNS
Y/N - Convert numeric IP address to name form? Default: Y
HelpURL
URL for Web client online help Default: none
Host
Same as -host command-line option Default: 127.0.0.1
IPSecurity
Y/N - Add client’s IP-address as -security option? Default: N
JavaScript
Script file name. Default: none
JavaSupport
Y/N - Support JavaScript functions? Default: Y
ListSize
Vertical height of Dest/Group lists. Default: 10
ListTags
Same as -tags command-line option. Default: none
LockConfig
Y|N - prevent changes/access to Config screen? Default: N
LockOptions
Y/N - prevent changes/access to Options screen? Default: N
LockPreferences
Y/N - prevent changes/access to Preferences screen? Default: N
LogFile
UNIX log file; Windows log file Default: /tmp/telalerth.log; C:\TEMP\TELALERTH.LOG
Logfile
Logo file name. Default: none
LogoHeight
Logo height. Default: 80
Chapter 19: Getting Familiar with the TelAlert Monitor | 287
MetaRefresh
Set to a value n to cause the “message sent” screen to automatically go back to the main screen n seconds after the send has been issued. If the value is set to 0 (the default), the client will stay on the “message sent” screen until you click one of the buttons. Default: 0
MsgSize
Number of rows in message box. Default: 5
Priority
Command-line -priority value.
Default: 50
SecurityRequired
Require use of Preferences->Security field? Default: N
Service
Same as -service command-line option.
Default: 25378
StatusWithDate
Y/N - Include Start time in Status displays? Default: Y
Verbose
Y/N - Display telalertc equivalent when commands executed?
Default: Y
288 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.5.6 Other Keywords
Most of these keywords determine what send- and alert-related information is shown on the Show
Send, Send Detail, Show Alert, and Alert Detail screens.
Values supported by ShowTable, ShowVTable, ShowDetailHTable, ShowDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows:
AltDial Alternate phone number (-an)
AltHost Alternate host/service (-ahs)
Calls e.g., "Connected 1/1, Failed 0/10, Rejected 0/1"
Conf [Configurations]
Dest [Destinations]
Dial Primary phone number (-n)
Group Group ID
Host Primary host/service (-hs)
PIN -pin value
Reply Last reply text
Send Send ID
To -to value
Track Track ID
Update Update time
User -user value
Values supported by ShowAlertTable, ShowAlertVTable, ShowAlertDetailHTable, ShowAlertDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows:
Recipient To whom was the alert sent?
Release Alert-level release info
Chapter 19: Getting Familiar with the TelAlert Monitor | 289
Values supported by all ten of the above keywords are as follows:
Alert Alert ID
Check -check value
Client IP address of message issuer
Delay -delay value
Hold -hold
IPCheck -ipcheck value
Masked Masked ticket
Message Message text
NodeAddr -nodeaddr value
Priority -priority value
Remark -remark value
ReplyTo -replyto value
Response -response value
Source -source value
Start Start time
State Message state
Subject -subject value
ShowTable
Governs Show Send page appearance. Determines what information is displayed for each send, horizontally from left to right. Default: Send,Start,User,Dest,State?128,Message
ShowVTable
Governs Show Send page appearance. Determines what information is shown for each send in one
or more rows beneath the initial row of horizontally-arranged send information.
Default: Message
ShowDetailHTable
Governs Send Detail page appearance. Determines what information is displayed for each send,
horizontally from left to right.
Default: Send,Alert,User,Dest,Conf,Source,Priority,Ticket,Masked
ShowDetailVTable
Governs Send Detail page appearance. Determines what information is shown for each send in one
or more rows, from top to bottom, beneath the initial row of horizontally-arranged send
information.
Default: Start,Update,Client,State?128,Calls,Remark,Message,Reply
290 | TelAlert 6e™ Administrator Guide - Version 6.1.29
ShowAlertTable
Governs Show Alert page appearance. Determines what information is displayed for each alert,
horizontally from left to right.
Default: Alert,Recipient,State?128,Message
ShowAlertVTable
Governs Show Alert page appearance. Determines what information is shown for each alert in one
or more rows, from top to bottom, beneath the initial row of horizontally-arranged alert
information.
Default: Message
ShowAlertDetailHTable
Governs Alert Detail page appearance. Determines what information is displayed for each alert,
horizontally from left to right.
Default: Alert,Recipient,Source,Priority,Ticket,Masked
ShowAlertDetailVTable
Governs Alert Detail page appearance. Determines what information is shown for each alert in one
or more rows, from top to bottom, beneath the initial row of horizontally-arranged alert
information.
Default: Start,Update,Client,State?128,Remark,Message,Reply
ShowContactInfo
Determines whether TelAlert sales and technical support contact info is displayed.
Default: Y
ShowWAPTable
Determines what information is shown when a microbrowser-enabled phone initially accesses the
TelAlert Web client. Message=Nlimits the number of characters shown in the message field to N.
Default: Send,Message=10
ShowWAPDetail
Determines what information is shown when a microbrowser-enabled phone selects and "reads" a
particular message.
Default: Send?128,Message
Chapter 19: Getting Familiar with the TelAlert Monitor | 291
ShowWhat
Determines what buttons are shown on the main page; can be set to Show, Show Alert, Both, or None.
Default: Both
18.6 Setting up Logging
The [Files] section governs TelAlert’s built-in logging behavior.
18.6.1 Default Log Files
By default, TelAlert maintains a variety of log files:
� telalert.trail—This is a general record of TelAlert activity.
� telalerte.log—This is the log file for telalerte, the TelAlert server. It contains all
the information TelAlert needs to process all active alerts.
� Media Controller log files -- To allow parallel processing, the telalerte server daemon
creates a separate child Media Controller process for each Active [Port] definition. Each
child process maintains its own log file; the names reflect the Media type:
telalerts#.log for Internet Socket ports, telalertm#.log forModem ports, etc.
The # is replaced by a digit (telalertv3.log, for instance) since there can be multiple
child processes for a particular Media type.
� telaconfe.log—this is the log file for telaconfe, the TelaConf server.
� Other process-specific log files—TelAlert maintains one log file for each of the other
TelAlert processes: telalerth.log for telalerth, telalertd.log for telalertd, etc. The contents vary according to the type of process.
Special Display Options for Microbrowsers
Values assigned to ShowWAPTableand ShowWAPDetail can be further specified using
these flags, each preceded by a question mark. For example, Send?128, Message shows
the send ID in bold text, followed by the message in plain text.
� 1—Splits text, causing each word to begin on a separate line.
� 2—Center-aligns text.
� 4—Left-aligns text.
� 8—Right-aligns text.
� 128—Bolds text.
� 256—Italicizes text.
� 1024—Prefixes each value with its name (i.e., Message=Hi there).
292 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.6.2 Setting Maximum Sizes
Four keywords used in the [Files] section determine the maximum sizes of these files:
� TrailMaxFileSize—determines the maximum size of telalert.trail
� EventMaxFileSize—determines the maximum size of telalerte.log
� ConfMaxFileSize—determines the maximum size of telaconfe.log
� LogMaxFileSize—determines the maximum size of each of the process-specific log files
(this value applies to all of these files)
When these limits are reached, TelAlert (1) deletes the existing backup file; (2) renames the
existing log file, giving it a .bak extension; and (3) starts a new log file.
You can set any of these keywords to 0 to prevent this procedure from being carried out. Note that
doing so will cause the file to continue to grow indefinitely, unless you manually initiate the
procedure using the -switch command (discussed in the "Administrative Command Line Options"
section of Chapter 3 of the TelAlert Keyword and Command Reference).
18.6.3 WriteExecsToTrail
WriteExecsToTrail is a supported keyword in section or definition where a Commandvalue is
specified. When this is set to True, TelAlert writes the results of executions of the specified
command to telalert.trail.
18.6.4 Configuring Additional Logging Behavior
You can achieve additional logging behavior using the Notification and NotificationLog keywords to point to a [Notifications] definition designed to log specific information about
specific events. Such a [Notifications] definition can carry out a simple command;
alternatively, it can invoke a script. For more information, refer to Chapter 15: Processing
Events.
18.7 Miscellaneous Administrative Tasks
18.7.1 Specifying Maximum ID Assignments
TelAlert assigns its own ID numbers to individual sends, “group sends,” and alerts. By default,
these numbers rolled over when they reached 65,535. You can change the point at which these
numbers roll over by setting the MaxIDvalue in the [Limits] section. 999 is the minimum,
65,535 the maximum.
Note that the telalert.alert file stores the most recently assigned numbers for individual
sends, group sends, and alerts. If you delete this file, reinstall TelAlert, or upgrade TelAlert, the
number for all three roll back to 1, regardless of your MaxID setting.
Chapter 19: Getting Familiar with the TelAlert Monitor | 293
18.7.2 Viewing Listen Sockets
telalert -status shows you a wide range of information about your implementation of TelAlert, including facts pertaining to your ports, Internet set-up, and license. This command also
displays your active listen sockets, as specified in your TelAlert environment variables or by
command line options.
Activating and Deactivating Sections and Definitions
The [Files] and [Heartbeat] sections can be activated or deactivated on the command line,
like so:
telalert -deactivate -files
telalert -activate -files telalert -deactivate -heartbeat telalert -activate -heartbeat
Likewise, any definition that supports an Active keyword can be activated or deactivated on the
command line. For instance:
telalert -deactivate -user John telalert -activate -user John
18.8 TelAlert Web UI Administrative Tasks
As a user assigned the role of administrator, you can access admin tools to aid in configuring and
managing TelAlert 6e. This section describes how to perform tasks using these tools that can be
found under the Admin tab.
294 | TelAlert 6e™ Administrator Guide - Version 6.1.29
The remainder of this section is only visible to administrators. The tasks available to
administrators are as follows:
� Importing Data
� Changing the Color Theme
� Managing Configurations
� Managing Departments
� Managing Holidays
� LDAP Configuration
� Single Sign On Configuration
� Log Viewer
� Setting System Preferences
� System Status Verification
� Changing a User’s Role
� System Reports
18.8.1 Importing Data
Before sending alerts, TelAlert needs some basic information about the potential alert recipients--
the users, devices, and groups--in your organization. You can add this information manually or
you can import it. Importing is recommended if you are adding a large number of users, devices,
groups and departments to TelAlert.
To import users, devices, groups, schedules and departments do the following:
1. Contact TelAlert Technical Support for assistance in preparing a TelAlertXchange formatted XML
file using an LDAP directory, spreadsheet, or other data source. In TelAlert 6e, this XML file is
referred to as a batch import file.
2. Once you have the XML file, log in again to the TelAlert Web UI.
3. Go to Admin > Batch Tool.
Chapter 19: Getting Familiar with the TelAlert Monitor | 295
4. Click the Add New Import File button.
5. Click the Browse button to locate your batch import file.
6. Click the Upload File button to upload the batch import file. The records appear in the Batch
Import Summary Report with a status of Pending.
7. Select the checkbox next to the Batch Import ID for the record you would like to process.
Select the checkbox at the top of the checkbox column if you would like to select all records.
8. Click the Process Records button to process the selected records. The status of the records
changes to Processed.
9. Check the status of the individual records that were created by the batch import. To do so, click
the in the Batch Import Summary Report. Records that did not get processed successfully are
indicated by the word ERROR in the Status column.
10. Correct any errors by manually adding, editing, or deleting the record. For details on how to
manually change user, device, and group records, see Supervisor Tasks.
11. Records in your XML file that do not include an <active> tag are set to Active by default. You can
change these records to Inactive, so that the user, device, or group cannot receive alerts. To do
so, see Activating and De-Activating Users and Activating and De-Activating Groups.
After you import users, devices, and groups, proceed to the next step in Common
Configuration Tasks.
296 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Sample XML File:
- <TelAlertXchange version="1.0">
- <summary>
<tool version="1.0">6e TelAlert Enterprise Migration Tool</tool>
<source>jdbc:microsoft:sqlserver://192.168.3.234:1433</source>
<comments />
<timestamp />
<record_count />
</summary>
- <records type="department" operation="insert">
- <record>
<name>TelAlert_C</name>
</record>
</records>
- <records type="user" operation="insert">
- <record>
<username>YvonneG_Admin</username>
<firstname>Yvonne</firstname>
<lastname>Fickentsher</lastname>
<password>password</password>
<role>Administrator</role>
- <departments>
<department>TelAlert_C</department>
</departments>
</record>
- <record>
<username>LisaL_Super</username>
<firstname>Lisa</firstname>
<lastname>Linden</lastname>
<password>password</password>
<role>Supervisor</role>
- <departments>
<department>TelAlert_C</department>
</departments>
</record>
- <record>
<username>TonyB_Staff</username>
<firstname>Tony</firstname>
<lastname>Nguyen</lastname>
<password>password</password>
<role>Staff</role>
- <departments>
<department>TelAlert_C</department>
</departments>
</record>
</records>
- <!--Begin Export of Destination Records-->
- <records type="destination" operation="insert">
- <record>
<name>YvonneG_Device</name>
<owner>YvonneG_Admin</owner>
<typename>Email</typename>
4-108 TelAlert 6e User Guide
- <ta_properties>
<Configuration>Email</Configuration>
<To>[email protected]</To>
</ta_properties>
</record>
Chapter 19: Getting Familiar with the TelAlert Monitor | 297
- <record>
<name>LisaL_Device</name>
<owner>LisaL_Super</owner>
<typename>Email</typename>
- <ta_properties>
<Configuration>Email</Configuration>
<To>[email protected]</To>
</ta_properties>
</record>
- <record>
<name>TonyB_Device</name>
<owner>TonyB_Staff</owner>
<typename>Email</typename>
- <ta_properties>
<Configuration>Email</Configuration>
<To>[email protected]</To>
</ta_properties>
</record>
- <record>
<name>System2_Device</name>
<owner>system</owner>
<typename>Email</typename>
- <ta_properties>
<Configuration>Email</Configuration>
<To>[email protected]</To>
</ta_properties>
</record>
</records>
- <!--Export of Global Schedule (referenced in Groups)-->
- <records type="rotation_schedule" operation="insert">
- <record>
<name>Normal_Day_Shift</name>
</record>
</records>
-<!--Begin Group Records-->
- <records type="group" operation="insert">
- <record>
<name>Dev1_Group</name>
- <members>
<destination>TonyB_Device</destination>
<destination schedule="rotation_schedule">YvonneG_Device</destination>
<user>LisaL_Super</user>
</members>
- <departments>
TelAlert 6e User Guide 4-109
<department>TelAlert_C</department>
</departments>
</record>
</records>
</TelAlertXchange>
298 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Batch Import Schedule Elements (New in Version 5.1)
Record typeElement nameDescription – Examples
destination<schedulename> - Assign schedule template to a destination
rotation_schedule<daysofweek> - Used to define on-duty time for weekly schedule using
the elements:
<MON> <MONDAY> also supported
<TUE> <TUESDAY> also supported
<WED> <WEDNESDAY> also supported
<THU> <THURSDAY> also supported
<FRI> <FRIDAY> also supported
<SAT> <SATURDAY> also supported
<SUN> <SUNDAY> also supported
<WEEKDAYS> Cannot be combined with <MON> through <FRI> elements
<WEEKENDS> Cannot be combined with <SAT> and <SUN> elements
The element values define a maximum of two time ranges using the syntax: “hh:mm
hh:mm,hh:mm hh:mm”
If <daysofweek> is omitted, a 24x7 schedule will be created (using a 1 day rotation 00:00-
23:59).
If <daysofweek> is defined, any day that is not specified is considered off-duty. Day elements
that do not contain values
(example: <FRI></FRI>) are also considered off-duty.
rotation_schedule<owner> - Associates the schedule template with a specific User. When
<owner> is defined, the schedule can only be assigned to Devices that are owned by the
specified owner. If neither an <owner> or <groupname> is defined, the resulting schedule has
“Global” scope.
rotation_schedule<groupname> - Associates the schedule template with a specific Group.
When <groupname> is defined, the schedule can only be assigned to Members of the specified
Group. The group must exist prior to importing the schedule.
Group <public> - Allows creation of private (non-public)
Groups by setting “<public>false</public>”. Groups are imported as public by default
(when this option is not specified).
Chapter 19: Getting Familiar with the TelAlert Monitor | 299
Example 1: Assign Schedule template to Destination
<records
type="destination"
operation="insert">
<record>
<name>JSmith_Pager</name>
<owner>JohnSmith</owner>
<schedulename>johnsmith_dayshift</schedulename>
<typename>Email</typename>
<ta_properties>
<Configuration>Email</Configuration>
<To>[email protected]</To>
</ta_properties>
</record>
</records> Example 2: Define Weekday Schedule template for a specific User.
<records type="rotation_schedule" operation="insert">
<record>
<name> JohnSmith Dayshift </name>
<owner>JohnSmith</owner>
<daysofweek>
<WEEKDAYS>08:00-11:59,13:00-17:59</WEEKDAYS>
</daysofweek>
</record>
</records>
<records type="rotation_schedule" operation="insert">
<record>
<name> JohnSmith Dayshift </name>
<owner>JohnSmith</owner>
<daysofweek>
<SUN></SUN> <!--empty or missing Day element == not on-duty-->
<MON>08:00-11:59,13:00-17:59</MON>
<TUE>08:00-11:59,13:00-17:59</TUE>
<WED>08:00-11:59,13:00-17:59</WED>
<THU>08:00-11:59,13:00-17:59</THU>
<FRI>08:00-11:59,13:00-17:59</FRI>
<SAT></SAT>
</daysofweek>
</record>
</records>
The example above shows two equivalent definitions for the same schedule.
300 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Example 3: Define global Weekend schedule (no <owner> is defined).
<records type="rotation_schedule" operation="insert">
<record>
<name>Global Weekend Shift</name>
<daysofweek>
<WEEKEND>08:00-20:59</WEEKEND>
</daysofweek>
</record> </records>
<records type="rotation_schedule" operation="insert">
<record>
<name>Global Weekend Shift</name>
<daysofweek>
<SAT>08:00-20:59</SUN>
<SAT>08:00-20:59</SUN>
</daysofweek>
</record>
</records>
The example above shows two equivalent definitions for the same schedule.
Example 4: Define schedule for specific Group.
<records type="rotation_schedule" operation="insert">
<record>
<name>Helpdesk Weekend Coverage</name>
<groupname>Helpdesk Group</groupname>
<daysofweek>
<WEEKEND>08:00-10:59,12:00-15:59</WEEKEND>
</daysofweek>
</record>
These schedules must be imported after importing the referenced Group. Batch import can not be
used to assign these schedules to Group Members (because the Group must be imported before
importing the schedule).
New Batch Import Data Order
The dependency order for imported record types. The import order is a follows:
12. Departments
13. Users
14. Schedules
15. Destinations
16. Groups
The order of types in the Batch Import .xml file is not important. When a file contains multiple
Insert operations (<records type="xxx" operation="insert">) each set of records will be imported
as a discrete batch. When multiple batches are selected for processing, the system will process
batches using the record type to determine the order (as defined above).
Chapter 19: Getting Familiar with the TelAlert Monitor | 301
18.8.2 Changing the Color Theme
As an administrator, you can select one of five different color themes. Simply select the radio
button for the required color theme and click . The effect for system users is immediate.
If you select a custom color theme, it opens up a wider set of customization options. To create a
custom color theme, do the following:
17. Navigate to the following folder in the TelAlert 6e application folder:
C:\Program Files\TelAlert6e\Server\tomcat\webapps\telalert\assets\
stylesheets\ color_schemes\custom
18. Edit the style.css file and modify the following set of parameters to make the 6e portal conform
to your own standards for font selection and colors.
19. Test the file inside an HTML editor so that its validity can be assured before use in the production
TelAlert application.
20. If the customization extends to buttons or other images, new image files can be built, based on
those found in the ../../../images folder. See the style.css file for the full path reference.
18.8.3 Managing Configurations
The Manage Configurations page allows the viewing of active configuration in 6e and provides
administrators with the ability to update configurations. The Manage Configurations page contains
a Reload button to import configuration data from the TA messaging server. The Reload button on
the manage configuration page should be selected any time a change is made in TAD.
302 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.8.4 Managing Departments
TelAlert 6e uses the concept of departments to divide and organize users and groups. The
department model provides partitioning for companies that would like to keep certain sections of
users and groups separate from other sections. Users within a particular department will only have
access to view/edit user, device and group details of users and groups belonging to the same
department. Using departments is not mandatory. By choosing not to create additional departments,
all users and groups in the system will belong to the same Default department and therefore will have
access to all users, devices and groups in the system. The default department name can be edited to
the name of your company or any other name that makes sense for your organization.
Figure 32. Administrators see Departments they are a member of on the Manage Departments page.
As an administrator you can create departments and view, edit and delete departments that you
are a member of. You can also view all users and groups that belong to a given department by
clicking on the Users and Groups tabs on the Edit Department Details page.
Note: The system administrator is the only user that is permanently a member of all
departments. Once an administrator is removed from a department, they will not be able to add
themselves back to that department. The system administrator is the only user that will able to
do this.
To add departments to the system, do the following:
1. Go to Admin > Manage Departments. The Manage Departments page appears.
2. Click the Add a New Department button.
Chapter 19: Getting Familiar with the TelAlert Monitor | 303
3. Enter a department name, and then click Save.
4. After adding the department you will see a confirmation page. Verify the department
information. From this page you can:
� Click on the Edit this department link to if you wish to edit the department details.
� Click on the Add users to this department link to assign users to this department.
� Click on the Add another department link if you would like to add another department.
� Click on the Return to department list link to return to the Manage Departments page.
To view the users and groups associated with a given department, do the following:
5. Navigate to Admin > Manage Departments. The Manage Departments page appears.
6. Click the Edit Department icon next to the name of the department that you would like to
view.
7. Click on the Users tab to view all users that belong to the department.
304 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 32. Users can be added to or removed from departments on the Department Users page.
Adding Users to Departments
To add department members, do the following:
1. Navigate to Admin > Manage Departments. The Manage Departments page appears.
2. Click the Edit Department icon next to the name of the department that you would like to
edit.
3. Click on the Users tab to view all users that belong to the department. See image of
Department Users page above.
4. To add a user to the department click on the name of the user in the Available Users list and
select the Move Right button.
Hint: To add more than one user at a time hold down the ctrl key while you click on each of
the names in the Available Users list and then select the Move Right button. To select all
of the users in the current view of the Available Users list, click on the Move All Right
button.
5. When the desired department members are listed in the Users in Department list, select the
Save button.
Chapter 19: Getting Familiar with the TelAlert Monitor | 305
Removing Users from Departments
To remove department members, do the following:
1. Navigate to Admin > Manage Departments. The Manage Departments page appears.
2. Click the Edit Department icon next to the name of the department that you would like to edit.
3. Click on the Users tab to view all users that belong to the department. See image of
Department Users page above.
4. To remove a user from the department click on the name of the user in the Users in Department
list and select the button.
5. To remove a user from the department click on the name of the user in the Users in Department
list and select the Move Left button.
Hint: To remove more than one user at a time hold down the ctrl key while you click on
each of the names in the Users in Department list and then select the Move Left button. To
remove all of the users in the current view of the Users in Department list, click on the
Move All Left button.
6. When the desired department members are listed in the Users in Department list select the
Save button.
Adding Groups to Departments
To add group department members, do the following:
1. Navigate to Admin > Manage Departments. The Manage Departments page appears.
2. Click the Edit Department icon next to the name of the department that you would like to edit.
3. Click on the Groups tab to view all groups belonging to the department.
306 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 33. Groups can be added to and removed from departments on the Department Groups page.
4. To add a group to the department click on the name of the group in the Available Groups list
and select the Move Right button.
Note: To add more than one group at a time hold down the ctrl key while you click on
each of the names in the Available Groups list and then select the Move Right button.
To select all of the groups in the current view of the Available Groups list, click on the
Move All Right button.
5. When the desired department members are listed in the Groups in Department list select the
Save button.
Removing Groups from Departments
To remove group department members, do the following:
6. Navigate to Admin > Manage Departments. The Manage Departments page appears.
7. Click the Edit Department icon next to the name of the department that you would like to
edit.
8. Click on the Groups tab to view all groups belonging to the department. See image above of
the Department Groups page.
9. To remove groups from the department click on the name of the group in the Groups in
Department list and select the Move Left button.
Hint: To remove more than one group at a time hold down the ctrl key while you click on
each of the names in the Groups in Department list and then select the Move Left button.
To remove all of the groups in the current view of the Groups in Department list, click on
the Move All Left button.
10. When the desired department members are listed in the Groups in Department list select the
Save button.
Editing Departments
To edit a department, do the following:
11. Navigate to Admin > Manage Departments. The Manage Departments page appears.
12. Click the Edit Department icon next to the name of the department that you would like to edit.
Figure 34. Edit Department Details page is the default view when Manage Departments is selected under
Admin Tools.
Chapter 19: Getting Familiar with the TelAlert Monitor | 307
13. Edit the fields and click Save.
Deleting Departments
To delete a department, do the following:
14. Navigate to Admin > Manage Departments. The Manage Departments page appears.
15. In the list of departments, click the Remove button for the department you want to delete.
Note: A Department cannot be deleted if users or groups belong to the department. Remove all
users and groups before deleting a department. To view existing department members select the
Users and Groups tabs. Members can be removed from departments on these pages.
18.8.5 Managing Holidays
Administrators can define up to 16 separate holidays in the system. These holidays affect all
users, devices, and groups in the system. All users, devices, and groups are considered off-duty
during holidays unless an explicit extra-duty schedule is assigned to them.
Adding Holidays
For more information on scheduling, see Managing Schedules. To add holidays to the system,
do the following:
1. Navigate to Admin > Manage Departments. The Manage Departments page appears.
2. Click the Add a New Holiday button.
3. Complete the required fields, and then click Save. The holiday is created for the date specified.
4. If the holiday is a recurring holiday (for example, an annual holiday), add a new holiday entry for
each future occurrence.
Editing Holidays
To edit a holiday, do the following:
5. Navigate to Admin > Manage Departments. The Manage Departments page appears.
6. Click the Edit Holiday icon next to the name of the holiday that you would like to edit.
7. Edit the fields and click Save.
Deleting Holidays
To delete a holiday, do the following:
308 | TelAlert 6e™ Administrator Guide - Version 6.1.29
8. Navigate to Admin > Manage Departments. The Manage Departments page appears.
9. In the list of holidays, click the Remove button for the holiday you want to delete.
18.8.6 LDAP Configuration
Enable and set Active Directory or other LDAP server authentication parameters. As an
administrator, you can configure the TelAlert Web UI to authenticate users by referring them to an
LDAP login server.
Figure 35. LDAP and LDAPS options are available on the Edit LDAP Configuration page.
To do so, modify the following settings:
� Enabled - If this is set, then users are authenticated by the configured LDAP server, using
the parameters set below.
� Secured - If this is set, then users are authenticated by the configured Secure LDAP
server, using the parameters set below.
� Protocol Version - If Select 2 or 3 depending on the desired protocol.
� Host - If This is the name or IP address of the LDAP server.
� Port - If This is the TCP/IP port number to use. The default is 389 for non-SSL and 636 for SSL but it could be different in your company.
� Root Context - If This is the path description used by the LDAP server. This is where the user records are kept.
� User Identifier - If This is the LDAP name that is given to designate a user. Most common use SAMAccountName.
� Access ID - If This is the user ID to be sent by the 6e LDAP client to perform the authentication.
� Access Password - This is the password string that is associated with the Access ID.
Your LDAP server may not need an Access ID and Access Password, so they are not required parameters.
After clicking the Save button, the system will attempt to access the LDAP server using these
credentials. An error dialog will display if there is a problem. In the case where the LDAP service,
though correctly configured, becomes unavailable, staff users and supervisors will not be able to
Chapter 19: Getting Familiar with the TelAlert Monitor | 309
log in to the application. Administrators will be permitted to log in, using their local 6e password
(which might be different from their LDAP password).
Configuring 6e Tomcat for Secure LDAP
1. Obtain a valid SSL certificate from the LDAP server.
2. Copy the certificate to the Java security folder on the TelAlert 6e Tomcat server
(i.e. C:\ProgramFiles\TelAlert6e\web\jre\lib\security).
3. Import the certificate into the Java certificate key store and follow the prompts on the screen:
C:\Program Files\TelAlert6e\web\jre\lib\security>keytool
-import -file<CERTIFICATE FILENAME> -alias <NAME FOR KEY> -
keystore cacerts
4. Once the certificate is successfully imported into the key store, it is no longer required, so it can
be removed from the Java Security directory.
5. Restart the TelAlert 6e Tomcat server.
18.8.7 User Role Configuration
Starting in TelAlert 6e v6.2.0, administrators can add customized user roles and modify the pre-
defined roles. For a complete discussion of this process, see User Roles in Chapter 13.
310 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.8.8 Single Sign On Configuration
TelAlert 6e can be integrated with corporate networks using Single Sign On. Using Single Sign On
users logged in to their corporate network will not need to log in again to use 6e.
If this is set, then users are authenticated by the corporate network server, using the Type and
User Identifier.
Type: Corporate network name/type. This is the corporate network name that is given to
designate a user.
Single Sign On Details:
� Clear Trust and Nortel are supported.
� When SSO is enabled, 6e looks for the username header variable to establish the user
identity. If it is not set, a normal login dialog is offered with a warning that SSO is configured but not working currently.
� If the username is not recognized a normal login dialog is offered with a warning that user
(username) is not a recognized 6e user.
� All SSO actions are audit logged (enable, disable, login, login fail).
� Users will not be able to reset their passwords when SSO is enabled.
o Note – In Text to speech environments, users will need to set and modify internal
TelAlert passwords even when LDAP is enabled. Contact TelAlert support for a modification to allow this feature.
� The Log Out link will not display when SSO is enabled.
Chapter 19: Getting Familiar with the TelAlert Monitor | 311
18.8.9 Log Viewer
As an administrator you can view the Audit Log, Application Log and TelAlert Trail File.
Figure 36. The Application Log View.
To access the logs:
1. Navigate to Admin > Log Viewer.
2. Select the type of log you would like to view in the View Log drop-down menu.
3. Select a value for the Number of Lines to Display Per Page field.
4. Click on the Previous and Next buttons to navigate through the log file.
312 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.8.10 Setting System Preferences
As an administrator, you can configure settings that affect how the entire TelAlert Web user
interface behaves. To access these settings, click the Administrator tab, and then click System
Preferences.
The settings you can change are as follows:
Global Settings - These setting affect the entire web site.
� Default Number of Items to Display Per Page - This value determines list size, the
number of items a user will see in a list of alerts, users, groups or devices. Individual
users can then set their own values to whatever is comfortable. This setting establishes a starting value. The acceptable range is from 1-1,000.
� Default Time Zone - This setting determines which time zone displays by default in
the Time Zone field on the Add a New User page. This does not determine the time zone for the schedule displays.
� Default Header and Display Footer - In some environments you may need to
suppress header and footer banners (for example, because your Web portal already has them).
� Display Advanced Features for Staff Members - For users whose role is supervisor
or administrator, TelAlert provides basic and advanced settings for configuring users,
devices, groups, schedules, and alerts. For users whose role is staff, TelAlert provides
basic and advanced settings for configuring devices and alerts. These advanced
settings are provided in separate sections of the Edit My Device page and the Send a
New Alert page. You can choose not to display these Advanced sections for staff users by selecting the No radio button.
Chapter 19: Getting Familiar with the TelAlert Monitor | 313
Home Page Settings - These setting affect the home page only.
� Default Refresh Rate for My Alerts Snapshot - Defines how often the alert data is
refreshed. There is a minimum limit of 60 seconds.
� Display My Snapshots - Administrators can select whether or not a selection of
snapshots display on the home page. In some environments you may want to choose
which portlet items should appear on the user’s home page. Selection is performed
with simple radio buttons.
Advanced Settings - These setting affect the entire web site.
� Default View. This value determines whether all alerts or only the active alerts display by default on the alert pages.
� Default Date Range. This value determines whether alerts sent on the current day, week, month or year will display by default on the alert pages.
Changes to these settings take effect immediately when you click the button.
18.8.11 System Status Verification
The system administrator has access to the System Status page which displays status information
and current settings for the TelAlert system. The System Status page displays application
settings, logging information, system memory statistics, TelAlert settings, DB settings and DB
connection pool settings.
To access the System Status page, do the following:
1. Go to Admin Tools and click on the System Status link.
A Data Integrity Check and 6.1 Data Upgrade are available at the bottom of the page.
The system administrator can perform a data integrity check to verify that the 6e database
properties and TelAlert sections file are in synch and that all users are correctly mapped to their
devices and groups. Selecting the Perform Check button writes all of the system status details
and results of the user integrity check to the application log. If errors are discovered during the
check see the application log for details. Running the data integrity check may degrade
performance of the server significantly. It is recommended that the process is not run if there is
any load on the system.
The Upgrade Data button should only be used when performing an upgrade to 6.1 from an
earlier version. The button should be selected before data is loaded into the system. Instructions
for using the Upgrade Data button are in the TelAlert 6e 6.1 release notes in the Upgrade section
and in the TelAlert 6e Installation and Upgrade guide.
314 | TelAlert 6e™ Administrator Guide - Version 6.1.29
18.9 Additional Admin Tasks
18.9.1 Changing a User’s Role
Only administrators can change the role of any user. To change the role of a user, do the
following:
1. Click on the User's tab. The Manage Users page displays.
2. In the list of users, find the user whose role you want to change.
3. Click on the Edit User icon next to the user name. The Edit User page displays.
4. In the Role field, select a role for the user.
5. Click Save.
18.10 System Reports
TelAlert 6e provides three sources of information about alerts:
� Alert Details - From the Alerts tab, you can click the Manage Alerts link to access a list of
all of the alerts that have been initiated in the system. This list shows whether individual
alerts are active or completed. This list can be exported and printed. You can drill down
further on individual alerts to obtain additional alert details and the status of each alert’s
Sends. A send is an alert delivery attempt or a reply attempt. A single alert can have
multiple sends, because it can be delivered to multiple recipients and replied to by multiple recipients.
� TelAlert Monitor - Using the TelAlert Monitor tool in TelAlert Desktop (the Windows-based
graphical administrative interface), you can observe real-time state changes of alerts and
their sends, and manually change the state of active alerts and sends. TelAlert Monitor is particularly useful for testing alert escalation settings.
� System Reports - System reports are useful for obtaining end-of-period reporting
information on alerts. You can select a start and end date, and then run a report that
provides totals of various alert data for that period. System reports are available through the Reports tab. System reports are only available to Administrators.
Chapter 19: Getting Familiar with the TelAlert Monitor | 315
There are two system reports:
System Metrics
This report provides the following metrics:
� Alerts - The total number of alerts initiated using TelAlert 6e during the period.
� Sends - The total number of sends initiated using TelAlert 6e during the period.
� Acknowledged - The number of sends to which a reply was returned.
� Escalated - The number of sends that were escalated.
� No Response - The number of sends to which there was no reply.
System Traffic
This report provides the following metrics:
� The total number of alerts initiated using TelAlert 6e during the period.
� The total number of sends initiated using TelAlert 6e during the period.
� The number of sends to which a reply was returned.
� The number of alert errors.
In each case, the administrator selects a start and end date for each report.
19
Getting Familiar with the TelAlert Monitor
19.1 Overview
TelAlert Desktop includes TelAlert Monitor, a tool for monitoring the current state of alerts and
their associated messages. TelAlert Monitor is also useful for observing real-time state changes
while testing (for example testing escalation). TelAlert Monitor provides the following features:
� Graphical representation of alert and message status in real-time
� The ability to manually change the state of active alerts and messages
� An interface for sending messages
� An interface for replying to messages
� An interface that can be customized to meet the needs of admin and non-admin users
� TelAlert Monitor Window views that can be customized
318 | TelAlert 6e™ Administrator Guide - Version 6.1.29
19.2 About the TelAlert Monitor Window
TelAlert Monitor is a tool for viewing TelAlert notification events. The primary feature of TelAlert
Monitor is the AlertTree in the upper window pane. The AlertTree provides a graphical, real-time
representation of TelAlert Alert/Send states and associated attribute values. The lower window
pane of the TelAlert Monitor Window displays additional information about the Alert or Send item
that is currently selected in the AlertTree.
Figure 37. TelAlert Monitor Window
The display characteristics may be customized to display a tree structure that is appropriate for
particular applications. The columns may be customized to display the most pertinent attribute
values for a particular application.
Buttons at the top of the TelAlert Monitor Window allow you to invoke actions to modify the state
of the selected Alert node or Send node. A right-click menu mirrors the button functionality. The
New Alert button launches a dialog for sending new messages. You can customize the default
buttons and other aspects of the TelAlert Monitor Window. For more information, see Customizing
TelAlert Monitor Views.
Several TelAlert Monitor windows can be active simultaneously for a particular host. This is useful
for viewing alert activity from several perspectives.
19.3 Setting Up TelAlert Monitor
TelAlert Monitor is dependent upon the TelaConf server (TelaConfE.exe) and the Notify Server
(NtfySrvr.exe). These servers run on the machine that is hosting the TelAlert server
(TelAlertE.exe). TelAlertE starts the NtfySrvr.exe process automatically by executing a command
line that is specified in a Notification paragraph. An appropriate Notification paragraph must exist
and must be referenced in the Limits section to successfully open a TelAlert Monitor Window. The
[Notification] paragraph {Command} keyword value references a TCP/IP port that must match
the port number that is specified in TelAlert Desktop’s Host Properties (associated with the
particular server).
Chapter 19: Getting Familiar with the TelAlert Monitor | 319
19.3.1 Configuring TelAlert Notification Paragraphs for TelAlert Monitor
TelAlert Servers that use TelAlert 6e are already configured to use the TelAlert Monitor tool.
TelAlert Monitor uses the same notification event stream that is used by the TelAlert 6e Status
Board.
19.3.2 Configuring TelAlert Desktop’s Host Properties
The following steps are required for both TelAlert servers managed by TelAlert 6e and non-6e
systems. These steps are only required after upgrading to 5.7.x from a previous TelAlert Desktop
version. The purpose of this procedure is to initialize Windows System Registry values associated
with existing hosts properties. These steps should be repeated for each TelAlert Host that exists in
the TelAlert Desktop’s host list. When additional host properties are created, the default registry
values will be initialized when the Host properties are saved.
1. Launch TelAlert Desktop’s Host Properties dialog (select Host Properties from the Desktop’s Hosts
menu).
2. Select the Alert Monitor Tool tab on the Host Properties dialog.
3. Verify that the NotifyServer Service value is set to ntfysrvr.
4. Click the OK button on the Host Properties dialog (accept default values for other properties on
the Alert Monitor Tool tab.
19.4 Launching the TelAlert Monitor Window
TelAdmin tool and TelAlert Desktop wizards - these tools may be launched from either a toolbar
button or from the Tools menu. The toolbar contains a Host selection (dropdown list) control that
determines which TelAlert Host (server) is associated with any newly launched tool (TelAdmin,
TelAlert Monitor or wizard). The significant difference in how these tools are integrated is that
multiple TelAlert Monitor Windows may be simultaneously active for a particular host (only one
TelAdmin view may be launched per host). This allows notification event data to be simultaneously
viewed from a variety of perspectives (for examples, alert-centric views, destination-centric views,
and group-centric views).
19.4.1 TelAlert Monitor Window Button
Figure 38 shows the TelAlert Desktop button that is used for launching the TelAlert Monitor Window.
Clicking the TelAlert Monitor Window button opens a TelAlert Monitor Window using the default
view for the currently selected TelAlert host (LocalHost is shown as the current host in Figure 31).
Figure 38. TelAlert Desktop Toolbar
320 | TelAlert 6e™ Administrator Guide - Version 6.1.29
A specific TelAlert Monitor view may be selected by clicking the down arrow next to the right of
the TelAlert Monitor Window button. This displays a dropdown list of all available views. The list
contains the names of all files with an .amv file extension that are located in the same directory
that TelAlert Desktop is executed from. Selecting a view from this list will opens a TelAlert Monitor
Window using the display settings associated with the selected view.
19.4.2 TelAlert Desktop Tools Menu
Figure 39 shows the TelAlert Desktop Tools menu that contains two options for launching TelAlert
Monitor Windows. Selecting the Realtime TelAlert Monitor option is equivalent to clicking the
TelAlert Monitor Window button. This option will open a TelAlert Monitor Window using the default
TelAlert Monitor view for the currently selected host.
The Open TelAlert Monitor Snapshot file option is used to open a TelAlert Monitor Window
containing event data that was previously saved as a snapshot (.ams) file. When this option is
selected an Open File dialog box is displayed that allows a specific snapshot file to be selected and
viewed.
Figure 39. TelAlert Desktop Tools Menu
19.4.3 TelAlert Monitor Data Dialog
The TelAlert Monitor Data dialog (shown in Figure 40) is automatically launched when the first
real-time (non-Snapshot) TelAlert Monitor Window for a particular host is launched. The TelAlert
Monitor Data dialog shows the stored notification event data that is temporarily held in volatile
memory. A data window is created for each TelAlert Host (server) that the Desktop is collecting
data from. Only one TelAlert Monitor Data dialog is created per TelAlert host. If the TelAlert
Monitor Data dialog for a particular host is closed, TelAlert Monitor stops collecting data for that
host and all current event data for the host is purged from memory.
Figure 40. TelAlert Monitor Data Dialog
Chapter 19: Getting Familiar with the TelAlert Monitor | 321
The statistics in the TelAlert Monitor Data dialog show the actual number of captured notification
events in memory. The counters also itemize the number of Alerts and Sends held in memory.
Multiple events may be associated with each Alert and each Send. These counters increment as
notification events are received and decrement as events are automatically purged from memory.
When multiple TelAlert Monitor Windows are open for a particular host, they each provide a
presentation of the same underlying data model. TelAlert Monitor builds a data model that
contains all captured notification events irrespective of filtering that may be imposed by specific
views. For this reason, the statistics may count data items that are not visible in the AlertTree.
The TelAlert Monitor Data dialog remains open when all other views are closed. This allows
collected event records to persist and allows collection of new records to continue. When a
TelAlert Monitor Window is opened while the TelAlert Monitor Data dialog is open, the AlertTree
presents data from recently collected notification events that are stored in memory. When a
TelAlert Monitor Window is opened prior to collecting notification events, the TelAlert Monitor Data
dialog launches and a TelAlert -show command is issued to capture the state of active Alerts and
Sends. The in-memory data model is initialized for the resulting -show command output. The
State attribute value for these initialized Alerts is: Initialized from Show Cmd (the StateNum
attribute value is –1).
When a TelAlert Monitor Window is opened that is associated with a snapshot file, the view is not
associated with a particular TelAlert host. Consequently, a TelAlert Monitor Data dialog is not
launched.
19.5 Using TelAlert Monitor
This section provides a detailed description of the following TelAlert Monitor features:
� TelAlert Monitor AlertTree
� TelAlert Monitor toolbar
� TelAlert Monitor tabs
� TelAlert Monitor Send Message dialog
322 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 41. TelAlert Monitor Features
19.5.1 TelAlert Monitor AlertTree
The main feature of TelAlert Monitor is the AlertTree in the top window pane. The AlertTree user
interface is a hybrid between a Windows Tree control and a Windows List control (in report mode).
The AlertTree provides a summary of Alert/Send status for a TelAlert host. The List control
(report view) features configurable columns that show attribute values for Alerts and Sends. The
tree associates Send events with their parent Alerts and features icons that indicate Alert Status,
the Configuration Type of the associated Destination and the Send’s state information. The tree’s
state icons convey the following information:
� Alert/Send Completion Status: Not Attempted, Completed, In progress (active)
� Message Delivery Status: Sent, Send Attempt Failed, Send Not Attempted (not on-duty
filtered)
� Reply/Ack/Nak Status: Expected, Received, Timeout
Chapter 19: Getting Familiar with the TelAlert Monitor | 323
19.5.2 Icons
This section describes the icons that appear in the AlertTree.
Node Type Icons
Scope (1st level) node when monitoring all events on a particular TelAlert Server
Scope (1st level) node when monitoring selected Destinations
Scope (1st level) node when monitoring selected Groups
Alert (2nd level) node when active
Alert (2nd level) node when not active
Alert (2nd level) node when information expired, pending deletion from memory and view
Destination (3rd level Send) node
Email (3rd level Send) node
Speech/TTS (3rd level Send) node
Send State Icons
Delivery not attempated: Not on-duty
Delivery not attempated: Delayed or on-duty wailt
Delivery not attempated: Filtered
Delivery in progress: Some events indicate progress
Delivery in progress: Some events indicate failure
Delivery in progress: Some events indicate progress, some indicate failure
Delivered: Waiting for reply (AckWait)
Delivery succeeded
Delivery failed
Delivery partially succeeded
Delivery partially succeeded with AckWait timeout
Delivery cancelled
324 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Reply State Icons
Note: The following reply state icons are combined with send icons to add additional meaning.
Acknowledged (Green)
Negatively Acknowledged (Red)
Other Reply (Yellow)
Held
Completed: Alert is pending removal from tree (and from memory)
Send/Reply Icon Combinations
Delivery succeeded and acknowledged
Delivery succeeded and negatively acknowledged
Delivery succeeded, some sends acknowledged, and some negatively acknowledged (or
other responses were received that did not change the acknowledged status)
Delivery Completed, some Sends Successful, some failed, some sends Acknowledged,
some Negatively Acknowledged or other responses were received that did not change the
Acknowledged status
Delivery succeeded and held
Delivery succeeded, held, and acknowledged
Delivery succeeded, held, and a reply was received that did not change the acknowledged
status
Delivered, a reply was received that did not change the acknowledged status, and waiting
for an additional reply
Delivered, held, a reply was received that did not change the acknowledged status, and
waiting for an additional reply
Delivered, waiting for reply, and some sends acknowledged
Delivered, waiting for reply, and some sends negatively acknowledged
Delivered, waiting for reply, some sends acknowledged, and some negatively
acknowledged
Chapter 19: Getting Familiar with the TelAlert Monitor | 325
Figure 42. Alert Tree Structure
Figure 42 illustrates the basic tree structure. Alert nodes have child nodes that represent their
associated Sends. Optional state icons are shown on the right side of the Alert icons and Send
icons. The structure of the tree and the visibility of state icons are configured using the TelAlert
Monitor - Preferences dialog. Completed events are automatically removed from the tree (and
from memory) after a pre-determined delay interval (defined in the Host Properties dialog). The
tree image on the right side of Figure 42 illustrates the appearance of the tree when a completed
Alert is pending removal.
TelAlert Monitor provides many options for modifying the tree appearance and structure. For more
information, see Customizing TelAlert Monitor Views. The tree structure that is shown above is
expected to be the most widely used option. This particular structure provides an alert-centric
overview of system alert processing activity. The particular tree structure in Figure 42 is referred
to as Host/Alert/Send because this name represents the hierarchy of the tree nodes.
Figure 43. Alert Tree Icon States
If one or more Sends are Held, then the Alert is in the Held state and a red (Open) box will be
overlaid on the Alert state image to indicate the Held state.
326 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Figure 43 shows the Alert Tree with labels that identify the states indicated by various icons. New
nodes (icons) appear in the tree as notification events are received. If a tree node already exists
for a particular Alert Id or Send Id, the node is updated to reflect the current state and attribute
values. Various options are provided for controlling if nodes are automatically expanded and
controlling if nodes are automatically selected (for more information, see Customizing TelAlert
Monitor Views).
Nodes may be manually selected by clicking on either a node icon or the associated text. Clicking
the right mouse button displays a context menu with options to perform operations using the Alert
Id, Send Id or other attributes associated with the selected node. Display updates will be
suspended (paused) until the context menu option is selected, a red selection bar is displayed to
indicate the display is in pause mode. Display updates may also be paused by double-clicking
(left mouse button) on a node icon or associated text, and a single click will resume updates.
A tabbed window interface located in the lower pane of the TelAlert Monitor displays detailed
information about the selected node (see Figure 43). This information is updated when the
selected node is automatically or manually changed. See section 2.1.3 for specific details about
TelAlert Monitor Tabs.
19.5.3 TelAlert Monitor Toolbar
This section describes the TelAlert Monitor Toolbar. The toolbar buttons operate on the selected
tree node. The toolbar is segmented into three bands (see Figure 43). The first band (a rebar
control) contains controls for adjusting the view. The second band contains a set of pre-defined
buttons and the third band contains customizable buttons that perform user-defined operations.
An option is provided for hiding pre-defined buttons for restricting access to particular operations.
The enabled state of both pre-defined buttons and custom buttons are determined by the state of
the currently selected item. The buttons are only enabled when the operation is appropriate for
the state of the selected item. The enabled state of context menu options mirrors the state of the
corresponding toolbar buttons.
View Properties Button
The View Properties button is used to launch the TelAlert Monitor - Preferences dialog for viewing
and changing options that determine the appearance of the currently selected view. For more
information, see Customizing TelAlert Monitor Views.
Select View Dropdown list
Many aspects of the TelAlert Monitor Window’s appearance are determined by options that are
configured using the TelAlert Monitor - Preferences dialog. These options are stored in an Alert
Monitor View file. The TelAlert Monitor - Preferences dialog can create modified copies of Alert
Monitor View (.amv) file. The View dropdown list on the toolbar is used for selecting a particular
view. This dropdown list displays the names of files with a .amv file extension that are located in
the directory that TelAlert Desktop is executed from. Views that are created on other Windows file
systems can be installed simply by copying the .amv file into the TelAlert directory. This directory
is always a sub-directory of the directory where TelAlert Desktop is installed.
View Update Pause/Continue Button
The Pause/Continue button enables or disables view updates. This is a two state button that
allows you to toggle between pause and continue modes. The button’s icon changes to indicate
the current mode. The icon will also change if the pause state is changed by double-clicking an
item in the tree or displaying the context menu. The icon flashes red when new events are
received while the display is in pause mode.
Updates Enabled Updates Paused Paused/new event received
Chapter 19: Getting Familiar with the TelAlert Monitor | 327
Snapshot Button
The Snapshot button is used to save the current in-memory state of Notification data to a file. The
in- memory notification event will be instantly serialized to a temporary file when this button is
clicked. A common File Open dialog (titled “Save TelAlert Monitor Snapshot File”) will then prompt
the user to name the snapshot file. This dialog will provide a default name using the following
convention: MMMDD- YY_hhmmss (where MM=month name, DD=day, YY=year and hhmmss –
hours/minutes/seconds using 24 hour local time). Example: Oct22-04_142416. The temporary
file is renamed when the user clicks the Save button using the specified name. The file extension
for Snapshot files is .ams (Alert Monitor Snapshot).
Snapshot (.ams) files are stored in the directory that contains the TelAlert Desktop executable.
The temporary file is named snapshot.tmp and is stored in the same directory. Snapshot files may
be opened for viewing using the TelAlert Desktop’s Tools menu.
Snapshot files contain an image of the view configuration data and notification event data that is
serialized from memory into XML text. When a snapshot is opened, the TelAlert Monitor Window
options that were in effect at the time the Snapshot is saved will determine the initial view
options. Pre-defined and User-defined toolbar buttons are not displayed when viewing a Snapshot
file. Only the Status Details and Event Info tabs may be displayed when viewing a Snapshot. The
Group/Destination Info tab, Console tab, context menu
and buttons are not displayed because a Snapshot view is not associated with a TelAlert Host,
consequently no operations or host data information are accessible.
Any Alert Monitor View (.amv) file that is locally available may be selected while viewing a
Snapshot file.
Standard Toolbar Buttons
The TelAlert Monitor Toolbar contains the following standard (pre-defined) buttons:
� New Alert - Launches the Send Message Dialog.
� Reply - Displays Response list associated with the selected Send Id, a dialog will prompt for the reply text if the selected Send is not associated with a Response list.
� Ack. Message - Changes state of selected Send to Acknowledged.
� Nak. Message - Changes state of selected Send to Negatively Acknowledged.
� Clear - Changes state of selected Send or selected Alert to Cleared.
� Release - Changes state of selected Send or selected Alert from Held to Released.
These standard toolbar buttons may be hidden for the purpose for restricting access to particular
operations. The visibility of these buttons are configured per view using the TelAlert Monitor -
Preferences dialog.
The standard buttons are only enabled when the associated operation is appropriate for the state
of the selected node, the New Alert button is always enabled.
If a Console Tab is visible and is selected in the lower pane of the TelAlert Monitor Window, the
console window will display the TelAlert command line output that results from clicking pre-
defined or user-defined buttons.
User-defined Toolbar Buttons
Toolbar buttons for performing user-defined operations may be configured using the TelAlert
Monitor - Preferences dialog. A unique set of custom buttons may be defined for each Alert
Monitor view (.amv) file. A maximum of eight user-defined buttons may be defined per view.
328 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Context Menu
The context menu appears when the right mouse button is clicked in the top pane. If the right button
is clicked while the cursor is positioned over a tree node icon or the associated text, a context menu
will popup with menu items that correspond to visible buttons (as seen in Figure 43). A separator will
divide the per- defined button operations on top from the user-defined operations on the bottom of
the menu. User-defined button that are configured to always be in enabled state will not appear on
this menu. Figure 43 shows an example context menu when a user-defined button named Forward
Copy is configured to be enabled only when a Send node is selected.
If the right button is clicked while the cursor is positioned over empty space in the top pane, a
context menu will popup containing a menu item for New Alert… and also containing menu items
that correspond to user- defined buttons that are configured to always be enabled (as seen in
Figure 44). Figure 44 shows a context menu, in this example buttons named Remove All and Test
Page are configured to always be enabled.
When an item is selected using the right mouse button, user-defined operations that are
conditionally enabled are shown on the context menu (Figure 44). When the context menu is
shown with no item selected (right-click on empty space), user-defined operations for buttons that
are always enabled are displayed (Figure 44). The enabled state of context menu options mirrors
the enabled state of the corresponding toolbar buttons.
Figure 44. Context Menu (right-click on a node or associated text)
TelAlert Monitor Tabs
This section describes the tabbed interface that is located in the bottom pane of the TelAlert
Monitor Window (see Figure 45). The following is a brief functional description of these tabs:
� Event Info. Displays current attribute values of the selected Alert or Send. These values are a composite of accumulated values from the most recent notification events.
� Event Info. Displays individual notification events and their associated attribute values for the selected Alert or Send.
� Group/Destination Info. Displays Destination paragraph keyword values or Group
paragraph keywords and members when a Send node, Destination node or Group node is selected.
� Console. Provides a console for typing TelAlert commands. When toolbar buttons are clicked the command line is also output to this window.
The Status Details tab is selected by default, this tab displays attributes associated with the Alert
node or Send node that is selected in the top pane. The Status Details tab is always visible, the
other tabs may optionally be hidden for the purpose of restricting access to attributes or command
line operations. Visibility and other options are configured per view using the TelAlert Monitor -
Preferences dialog.
The contents of the Status Details tab, Event Info tab and Group /Destination Info tab are updated
when the tree item selection in the top pane of the TelAlert Monitor Window is changed (either
manually or automatically).
Chapter 19: Getting Familiar with the TelAlert Monitor | 329
Status Details Tab
The Status Details tab displays current attribute values of the Alert node or Send node that is
selected in the top pane. These attribute values are accumulated and updated as notification
events are received.
Figure 45. Status Details Tab
This tab can be configured (using the TelAlert Monitor - Preferences dialog) to display a subset of
the available attribute values. When the Show all status attributes checkbox is checked, the value
of all available notification event attributes will be displayed, otherwise only available values for
attributes that are selected via the TelAlert Monitor - Preferences dialog will be displayed. On
option is provided to disable the Show all status attributes checkbox for the purpose of simplifying
the presentation or to prevent users from viewing particular attributes (example usage: hide
Message contents to preserve confidentially).
Event Info Tab
The Event Info tab displays notification events and their associated attribute values. This tab
contains a split window with events listed on the upper portion and attribute values for the
selected event displayed in the lower portion. The splitter control in the middle of the window can
be dragged to adjust the relative height of the upper and lower portions.
Figure 46. Event Info Tab
This tab can also be configured (using the TelAlert Monitor - Preferences dialog) to display a
subset of the available attribute values. When the Show all event attributes checkbox provides the
same functionality as the Show all status attributes checkbox that is described in the previous
section.
330 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Group/Destination Info Tab
The Group/Destination Info tab displays TelAlert paragraph keyword values for the Destination
node or Group node that is selected in the top pane. When a Destination node is selected, this tab
displays Destination keyword values and keyword values for the associated User (if any). When a
Group node is selected, this tab displays a tree showing the Group members and shows keyword
values for the selected Group or Destination in the member tree.
Figure 47. Group/Destination Info Tab (when a Destination is selected in the top pane)
The Group/Destination Info tab requires a TelaConf host connection and Owner read permission (if
Owners are used) to display paragraph data. The TelAlert Monitor caches paragraph data to
minimize TelaConf host access.
Console Tab
The Console tab provides a command line console window for typing TelAlert commands and
viewing the resulting server output. TelAlert commands resulting from toolbar buttons and context
menu operations are also displayed in the console window.
Figure 48. Console Tab
The TelAlert Monitor - Preferences dialog provides an option to disable console command line
entry. When console command line entry is enabled, the console window automatically outputs a
telalert prompt at the beginning of each line (in blue text). The –host command line option is not
needed to address a specific TelAlert server because the TelAlert Monitor Window is implicitly
associated with a particular server. The console window is equivalent to using the Admin version
of the TelAlert client. Login and passwords are not needed from the console because that TelAlert
Desktop will prompt for the login/password if needed and automatically supply these to the
TelAlert server.
Alert Monitor Send Message Interface Dialog
This section describes the Send Message dialog that is launched when the New Alert button is
clicked or the New Alert is selected from the from the context menu. This dialog provides a simple
interface for issuing Alerts (see Figure 49). When delivery options are specified the dialog box
expands to display a list of options (as shown in Figure 50).
When the Send Message dialog is launched using the context menu by right clicking on a Send
node, Destination node or Group node, the associated Destination or Group will be added to the
dialog’s Recipients list.
Chapter 19: Getting Familiar with the TelAlert Monitor | 331
Figure 49 contains an image of the Send Message dialog in its collapsed form and the associated
child dialogs (Select Recipients dialog and Delivery Options dialog). The Add Recipients button
launches Select Recipients dialog, a mixture of Destinations and Groups may be selected using
this dialog. When multiple Recipients are selected the Alert is issued using the TelAlert -l
command, this results in creating a Group on the fly named AlertN where N is the Alert ID.
The Set Delivery Options button launches the Delivery Option dialog (shown in Figure 49). The
Use current options as default… checkbox determines if the selected options will remain in effect
the next time the Send Message dialog is launched. When the Send Message dialog is launched
and delivery options are in effect, the dialog is automatically expanded (as shown in Figure 50) to
display the delivery options. The Send Message dialog is also automatically expanded when
delivery options are initially set (after clicking OK from the Delivery Option dialog).
Figure 49. Send TelAlert Message Dialog (Delivery Options and Message Recipients dialogs also shown)
20
Security Features
20.1 Overview
TelAlert is deployed in a wide variety of enterprise environments—environments that, for all their
diversity, share the same pressing need for network security. This chapter describes the key
features with which TelAlert has been equipped in order to ensure a high degree of security when
deployed as part of an enterprise network. This chapter’s aim is to familiarize system
administrators with TelAlert’s security features, and to demonstrate the ways in which these
features make TelAlert an exceptionally security-conscious application.
20.2 TelAlert’s Security-Conscious Architecture
Any good site administrator is concerned with security and knows that each new product added
may carry security risks that jeopardize applications, data, or the network as a whole.TelAlert
addresses these concerns by adopting engineering approaches which insure that potentially
troublesome areas (modem connections to the outside world, for instance) are secured. TelAlert
has been developed within the enterprise model and with years of guidance from our users—most
of whom run enterprise sites. Thanks to this heritage, TelAlert is able to address these and other
points of risk and offer a strong level of security. Understanding TelAlert’s heightened security-
consciousness begins with a look at its architecture, which spans four main areas:
334 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Architectural Area Description
telalerte The communications hub through which all traffic flows
TelAlert Media Controllers Processes that manage connections to external networks (such as
those of paging carriers). telalerte passes messages to these
processes for delivery and returns messages from them to clients.
Examples include processes such as telalerts (the network
media controller) and telalertm (the modem media controller).
TelaConf/TelAdmin TelAlert’s administrative components. These components let an
administrator control TelAlert’s operation and configuration
TelAlert Clients Programs (such as telalertc) that let end users and
applications pass messages into TelAlert. Potential risks
associated with each area can be addressed by safeguards built
into TelAlert. TelAlert allows administrators who want maximum
security to enable security features like Owners, Users,
passwords, and authentication.
Potential risks associated with each area are anticipated by safeguards that are built in to TelAlert.
TelAlert allows administrators who want maximum security to enable number of security features.
The following sections take a look at the security features of each area of TelAlert’s architecture.
20.2.1 telalerte: The Central Hub of TelAlert
Most important are the security measures taken by the telalerte process, which, thanks to its
central role, offers a hacker the opportunity to do the greatest damage. To guard against a breach,
telalerte takes the following precautions:
1. All traffic into telalerte from clients (such as telalertc) must originate from hosts
defined in the telalert.hosts file. If the host address is not present in this file,
telalerte will not allow communication from the client. For example, for a site network
on subnet 206.169.153.*, TelAlert will assume that it can accept client connections
from its local interface only (127.*.*.*) unless the telalert.hosts file is modified to
allow for other connections. For TelAlert to accept a connection from another host, the site
administrator must explicitly add its hostname or IP address to telalert.hosts.
2. TelAlert creates a port before creating the child process that will communicate using the
port. This port is only usable by telalerte and the child process - no third process can
gain access to the conversation.
3. telalerte communicates via a private protocol. For hackers to spoof network traffic,
they would require a full understanding of the TelAlert binary protocol.
4. As with all TelAlert components, all connection set-ups between telalerte and clients
are logged.
Chapter 20: Security Features | 335
20.2.2 The Media Controllers
Media controllers allow TelAlert to connect to external services such as paging gateways, mail
systems, modems, etc. When telalerte wants to send a message to a given destination (e.g., a
SkyTel two-way text pager), it passes the message to the media controller process bound to
SkyTel (telalerts). telalerte itself does not know how to speak to SkyTel; the media-controller
is the only process that knows how to speak to a given carrier over a given protocol. Media
controllers are, in effect, the translation gateways between telalerte and the real world of
messaging.
Because media controllers are points of external access and thus potential security risks, TelAlert
imposes several default security measures that must be explicitly disabled if a lower level of
security is desired:
1. TelAlert media controllers are started by telalerte. Because only telalerte knows which
network port will be used, it is very difficult to write a rogue media controller capable of
spoofing the connection.
2. Media controllers, like all connections with TelAlert, are bound to a single socket session.
This prevents rogue processes from joining an existing conversation that has been opened
by telalerte.
3. Media controller connections are set up dynamically. telalerte takes great care to
avoid persistent connections that might be vulnerable to traffic sniffing and/or network
spoofing. (Note, however, that some kinds of connections between the media controller
and the outside world are determined by the protocols used by the service: For example,
leased-line telalertm is persistent; dialup telalertm is not. Internet telalerts
using the ARDIS protocol is persistent; the SNPP protocol is not.)
4. The media controller command set as it relates to telalerte is an internal, proprietary
command set that cannot easily be managed outside of telalerte, and this binary protocol
is of little use to non-TelAlert components. Again, it important to note that connections
between the media controller and the outside world frequently rely on standard public
protocols.
5. To secure media controllers that manage external devices such as modems, TelAlert places
these devices in a non-auto-answer state and, by default, requests exclusive use of the
device. Unless the administrator places a getty program on a modem and explicitly tells
TelAlert that the device is shared, TelAlert is the only application with access to the device
(and even TelAlert is limited to access in an outbound fashion).
6. TelAlert does not provide any form of Remote Access Service (RAS). Typically, RAS
services (such as the UNIX gettyprocess) provide users with a “login” prompt. Since
TelAlert does not include the software that would provide this access, there is no way to
gain system access inbound from a modem controlled by TelAlert: its modems do not
answer calls, and, and no command processor/login session exists behind the modem to
process incoming data.
The TelAlert Engine supports dial-in access, but dial-in is not required to send voice
messages, and dial-in can easily be disabled. Even if dial-in access to TelAlert is enabled,
the Engine is listening for DTMF tones only (the tones emitted when a touch-tone
telephone keypad is pressed). Further, a password is required before callers are allowed
access to the voice menu.
336 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Circumventing all of these measures still would not give an intruder access to the host
platform. For this to be possible via an external interface such as a modem, the system
must have software listen on the port and pass incoming data to a special process (such as
a login process). TelAlert does not provide this capability. If an intruder were to gain
access to a TelAlert port and bypass TelAlert, he or she would be met with the datacom
equivalent of dead air.
7. TelAlert can be configured so that telalerte requires a special password be provided
each time a message is initiated, thus preventing a client from sending unauthorized
messages through a gateway.
8. Clients such as telalert take great care to check every packet to prevent buffer overrun.
This makes it difficult for a rogue client to force access to TelAlert or the system
underneath it via traditional intrusion methods.
It is worth noting that the activity of media controller processes, like that of all TelAlert
components, can be logged to the various log files (for example telalertm1.log,
telalerts2.log, telalert.trail, etc.) The level of detail for logging is configurable. See
the [Files] section in Chapter 2 of the TelAlert Keyword and Command Reference and
Chapter 15 of this manual for information on configuring log file features.
20.2.3 TelAlert Desktop
TelAlert maintains a large block of configuration data. Assuming the server file system is kept
secure by standard system security procedures, TelAlert can also enforce security by requiring that
all configuration clients are authorized, not only by login and password, but by a known address as
well. Just as clients gain access only after their addresses are entered in telalert.hosts,
configuration clients are granted access only after their addresses are found in telaconf.hosts,
and TelAlert will refuse a connection if the address cannot be found.
Note that TelAlert Desktop access when running on the TelAlert server machine is not controlled by
telaconf.hosts.
20.2.4 Client Programs
TelAlert client programs such as telalert and TelAdmin also do their part to ensure system
security. Each client accepts external requests, whether from a user or external application, and
performs several consistency checks on the data before actually transmitting it to the TelAlert core.
Because they parse user input directly, rather than sending it to the core for parsing, commands
are never sent to the core without first having their credentials checked. Each client program also
checks for potential security problems such as buffer overrun and illegal option values. TelAlert’s
core processes thus always receive sanitized requests from clients, greatly reducing the risk of
rogue clients accessing critical features of the core.
Chapter 20: Security Features | 337
20.3 Password Encryption
TelAlert 5.4 adds password encryption. You can activate this security feature by setting
EncryptPasswords to True under [Limits] (the default is False). With this setting, all plain-text
passwords found in any section of telalert.ini (i.e.,[Users] and [Owners]) will be
encrypted before being written to the telalert.sects file. Likewise, with this setting, a user-
provided password is encrypted before being compared with its stored counterpart.
Passwords are scrambled in such a way as to allow TelAlerte to determine that they are indeed
scrambled. This is done by recording the encrypted passwords with a leading "#" character.
Encrypted passwords are saved in the telalert.sects file with a leading "#" character. When a
telalert.sects password is found starting with a "#", it is considered to be encrypted, and the
user-provided password is encrypted before being compared with the stored version. Otherwise,
the plain-text version is compared. These comparisons are done for both [User] and [Owner]
passwords.
Whenever a [User] or [Owner] entry is changed, its password is encrypted if
EncryptPasswords=True and it isn't already encrypted. If EncryptPasswords=False, the
password is left alone.
For example, in TelAdmin, after setting: [Limits]
EncryptPasswords=True
and modifying the user John’s password in the Web UI as follows: [User]
{John}
Password=Giants
typing: telalert -read user John -hold
shows: [User]
{John}
Password=’#GeYg0xne’
If John’s definition is changed, the compile step won’t re-encrypt the password, as it’s already
encrypted (determined by the leading "#"). When EncryptPasswords is reset to False,
passwords are unchanged during compile operations. Only when the [User] or [Owner] section
entries are re-compiled are the Encryption functions performed. Any password already encrypted
will remain encrypted, regardless of the EncryptPasswords value. Only non-encrypted
passwords will be encrypted when EncryptPasswords is True.
As a result, the testing of passwords is done based on the values found in the .sects file,
irrespective of the current [Limits] EncryptPasswords value.
As a general rule, passwords specified on the command-line or via Stored Authentication must be
plain-text.
338 | TelAlert 6e™ Administrator Guide - Version 6.1.29
20.4 Scheduling of Client Connections
As mentioned above, the telalert.hosts file controls which TelAlert clients can connect to the
TelAlert server. For a client to connect, the machine on which it is installed must be named in this
file.
Starting with TelAlert 5.4, the ability of a client machine to connect can be governed by a schedule.
To do this, you alter telalert.hosts so that each machine is identified by a name in curly
brackets. To the keyword Address, assign the machine’s IP address or hostname. To the keyword
Schedule, assign a value matching the name of a TelAlert-defined schedule. For example:
{Name}
Comment=Customer Service Department
Schedule=NineToFive
Address=1.2.3.4-20
The telalert.hosts file can contain information presented in this form (where a list of IP
addresses are shown on one line), the old form (an IP address or hostname per line), or a
combination of both forms.
See Chapter 12: Setting Up and Applying Schedules for information on creating and working
with schedules.
The same approach can be used in other TelAlert files used to control client interactions with the
server: telalert.refuse, telalert.ipchk, telalert.remote, telaconf.hosts,
and telalert.master.
20.5 Authentication for Admin and Client
Connections
TelAlert can require clients to log in before passing information to the server. The Administrator
and password provided by the client on the command line are checked against the values specified
in [User] definitions (and not in [Owner] definitions). If a match is found, the command is
allowed.
“Admin” connections are connections by telalert, telalerths, and C/Java APIs with admin
capabilities.
“Client” connections are connections by telalertc and C/Java APIs without admin capabilities.
“Web client” connections are connections by telalerth.
This is accomplished using new keywords added to the [Limits] section:
AdminLoginsRequired, ClientLoginsRequired, and WebClientLoginsRequired. The
default value for these variables is False; if set to True, logins are required.
There are two approaches to passing the Administrator and password on the command line.
If you are using –host to specify multiple TelAlert servers to which clients should attempt to
connect, you must provide the appropriate Administrator and password following each specified
host. Consider this partial command line:
… -host 1.2.3.4[user1:pass1] 5.6.7.8[user2:pass2] …
Chapter 20: Security Features | 339
If you have only one TelAlert server to which clients can connect, you can begin using -host and
this associated method of providing Administrator and password. Note that there must not be any
space between the final character of the host specification and the opening bracket of the
Administrator/password combination.
Alternatively, you can use two new command line options, -loginuser and -loginpassword.
Again, here is a partial command line:
… -loginuser Joseph -loginpassword 1k2j345 …
Note, too, that where AdminLoginsRequired is False, admin clients can use this command—
telalert -validate -loginuser Foo -loginpassword Bar
—to check the validity of a login.
Note that requiring login passwords, and enabling password encryption, are separate and distinct
options. You can enable encrypted passwords without requiring logins (in this case, the encryption
would apply to passwords used for other purposes, like Voice IVR menu access). Or, you can
require logins without encrypting the login passwords.
20.6 Control Over Remote Connections
TelAlert supports “remote” functionality in which one TelAlert server connects with another and
“borrows” its modem. This is a useful way to avoid toll charges. In TelAlert, remote access is
governed by telalert.remote files, which are similar in form to telalert.hosts.
The following command line options have also been added: -acceptremote
-refuseremote
These parallel –accept and -remote and are used with -insert, -delete, -reload,
-verify, and -write to modify and display the contents of telalert.remote.
Refer to Chapter 6: Setting Up a Remote Port for more information on working with remote
connections.
340 | TelAlert 6e™ Administrator Guide - Version 6.1.29
20.7 Security Event Available in [Notifications]
A keyword, Security, can be used in the [Notifications] section to trigger specified actions
in response to security-related state changes within TelAlert.
A single “security” event—marked as “[11]Security/License”—is comprised of a number of
new state changes:
[107]No Web Clients
[108]License Expired
[109]License Limit Exceeded
[110]Admin Unacceptable
[111]Client Unacceptable
[112]Master Unacceptable
[113]Remote Unacceptable
[114]Invalid Admin Login
[115]Invalid Client Login
[116]Invalid Master Login
[117]Invalid Remote Login
[118]Not A Gateway
[119]Master Already Connected
20.8 Control Over IVR Interactions
[Configurations] definitions of Type=InteractiveModem and Type=InteractiveTTS
support two keywords. NoUserValidation suppresses the password prompt presented to dial-
in users, and NoMessageResponse suppresses the acknowledge prompt.
20.9 Using SSL with Skytel Devices
Skytel has multiple Internet servers that can accept connections from TelAlert customer servers.
The servers associated with the hostname skysock.skytel.com accept "normal" connections;
the servers associated with the hostname secure-apps.skytel.com accept encrypted
connections using the SSL protocol.
TelAlert itself only supports normal Internet connections. To utilize SSL connections, third-party
software is required. This documentation shows how to implement an SSL "wrapper/proxy" utility
using freely-available, open-source third-party software; customers can also use commercial third-
party software. This SSL wrapper/ proxy software is not downloadable from MIR3.
These instructions assume that the SSL wrapper/proxy will be installed on the TelAlert server
machine, so that TelAlert can start or stop the wrapper/proxy at the same time TelAlert starts or
stops its other processes.
Some customers may prefer to install the SSL wrapper/proxy software on a firewall or gateway
machine, instead of on the TelAlert server. This will work, but since TelAlert will no longer be able
to start or stop the wrapper/ proxy, the customer is responsible for insuring that the
wrapper/proxy is running whenever TelAlert is running.
Chapter 20: Security Features | 341
20.9.1 Obtain and Install Wrapper/Proxy Software
This has two parts - the software that adds the SSL layer to your existing Internet connection, and
a library that supports SSL encryption methods. There are two parts in order to isolate the
encryption code, because some countries restrict import/export of encryption code.
Obtain a copy of the open-source "Stunnel" executable
See http://www.stunnel.org.
For Windows, you can either download a prebuilt executable (which will restrict your choice of
compatible libraries), or download source and build an executable yourself. For UNIX, you will have
to download the source and build it yourself.
Obtain an SSL library
Two recommended libraries are SSLeay and OpenSSL. If you build your own stunnel, then you can
choose either library. If you use the prebuilt Windows executable, you must use the SSLeay library.
The following are SSLeay links:
� ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/ (Latest source and other files)
� ftp://ftp.psy.uq.oz.au/pub/Crypto/SSLapps/ (SSL-enabled FTP, Telnet, etc.)
� http://www2.psy.uq.edu.au/~ftp/Crypto (FAQ)
� http://www2.psy.uq.edu.au/~ftp/Crypto/ssl.html (programmer ref)
� http://www2.psy.uq.edu.au/~ftp/Crypto/ssleay/ (index to other docs)
� http://www2.psy.uq.edu.au/~ftp/Crypto/certs.html (info on certificates)
http://www.columbia.edu/~ariel/ssleay/ssleay-legal-faq.html (notes on legality, which is two issues patent/copyright, and government restrictions)
A prebuilt SSLeay Windows binary can also be obtained from
http://www.stunnel.org/download/binaries.html
Prebuilt UNIX binaries are not available at the time of this writing.
Here is the OpenSSL link. Notice that OpenSSL was derived from SSLeay, and is more up-to-date
than SSLeay, so it is probably the better library to use if you are building your own stunnel.
www.openssl.org (Main site)
If you are installing them on the TelAlert server, you can put them with TelAlert's executables in
the directory pointed to by the TELALERTBIN environment variable; or, you can put them in
another directory of your choice. If you use another directory, ensure that it has the proper
permissions. Make sure that the [Process] {Stunnel} definition you create to ensure that
Stunnel is running simultaneously with TelAlert (see below) references the correct directory.
If you are installing them on a separate "gateway" or "proxy" server machine, the directory to use
is entirely your choice.
342 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Ensure that Stunnel will always be running, with the proper parameters, whenever TelAlert is running.
If you have installed stunnel on the TelAlert server, you can use a [Process] definition; a
sample is given below. This sample has TelAlert run the ExecProc utility, which then runs
Stunnel, instead of having TelAlert directly run stunnel. ExecProc adds features to more
smoothly integrate Stunnel with TelAlert; for instance, ExecProc will report to TelAlert if
stunnel dies, and will cleanly terminate stunnel on command from TelAlert during a TelAlert
shutdown. ExecProc is a new program in the 5.4 release of TelAlert. Parameters that may need
to be customized in the following [Process]{Stunnel} definition:
� MaxAutoActivates controls how many times TelAlert should automatically restart Stunnel
if Stunnel dies. Increase this value if observation shows that the Stunnel connection to
Skytel often times out.
The following are subparameters in the Command= line:
� -debug 0 is the debug flag for ExecProc, not for Stunnel. Use 1 instead of 0 to
activate debugging. Debugging information is written to execproc.log.
� -cfg and –exec are ExecProc parms indicating the (-exec) executable file name,
and (-cfg) directory path where the file is located, for the program that ExecProc is to
create as a child process.
Not shown in the above example are the TelAlert [Process] standard -file, -back, and
-size parameters relating to the execproc.logfile, so the defaults are being used.
The -parms string is passed unchanged from ExecProc to the child stunnel process, so the
values in –parms are more fully documented in the Stunnel documentation. Briefly:
"-d 7778" is the socket that Stunnel will use to communicate with TelAlert.
"-r secure-apps.skytel.com:7778" is the DNS name/IP address socket that Stunnel will
use to communicate with Skytel. (If the your DNS server does not resolve secure-apps.skytel.com,
use IP addresses 204.153.80.31 or 204.153.81.31).
"-c" indicates that stunnel will run in client mode.
"-o stunnel.log" is Stunnel's logfile name.
Not shown in this example is "-D 5", which is the default control for the level of debugging
information Stunnel writes. To increase the level of information, use -D 6 or -D 7.
Chapter 20: Security Features | 343
Note that the -d socket value must match the TelAlert {SkytelxxxxSSL} definition's Service
value, and the -r socket value must match one that Skytel actually monitors, but the –d and -r
socket values do not need to be identical - it's simply a convenience.
[Process]
{Stunnel}
Active=True
WriteExecsToTrail=True
MaxAutoActivates=3
Shell=""
Command=${TelAlertBin}/ExecProc ${Message} -debug 0
-cfg ${TelAlertBin} -exec stunnel -parms "-d 7778
-r secure-apps.skytel.com:7778 -c –o stunnel.log"
Start=${TimeStamp} Start
Reset=${TimeStamp} Reset
Status=${TimeStamp} Status
#Control=${TimeStamp} Control ${Message}
#Switch=${TimeStamp} Switch
Stop=${TimeStamp} Stop
If you install stunnel on a machine other than the TelAlert server, starting or stopping Stunnel, and
providing the proper parameters, is your responsibility. Stunnel can be run under an "inetd"-type
arrangement on a UNIX "gateway" machine; refer to the Stunnel documentation. In this situation,
the [Process]{Stunnel} definition is not used.
Set up SSL-aware Skytel configuration(s) in TelAlert
The following is a completely new TelAlert Skytel configuration that uses SSL. Using this
configuration, you could have some destinations refer to the non-SSL connection using an existing
configuration like SkyTelSNPPTextPager, and other destinations refer to this new SSL
connection. This is useful for testing.
Alternatively, you could change the existing Skytel configuration to match this one; doing this
means that no changes are required to switch existing Destination entries from their existing non-
SSL Skytel configuration to the new SSL-aware Skytel configuration, which may save a lot of
editing.
{SkyTelSNPPSSL}
# SkyTel National SNPP Text Paging System for Interactive TwoWay Pagers
# Uses SSL over the Internet
# Dial Backup does NOT use SSL
Type=InteractiveTextPager
Protocol=SNPP
# ProtocolMask sets special protocol options:
# 1 - PIN is included in command replies, non-standard
# 2 - SkyTel time format which is non-standard
ProtocolMask=3
Model=Internet
344 | TelAlert 6e™ Administrator Guide - Version 6.1.29
MaxMessagesPerCall=100
# Host=127.0.0.1 connects to Stunnel running on the TelAlert server.
# If Stunnel is on a gateway machine, adjust accordingly
Host=127.0.0.1
# Connects to Stunnel using the same socket Stunnel is listening on;
# by convention, this is one of the two sockets that Skytel is
# listening on (7778 and 8889), but if necessary TelAlert and Stunnel
# can use ANY socket that is not otherwise in use on this server.
# This must match the Stunnel -d parameter
Service=7777
TextPagerWait=30s
# To enable dial backup, set DialBackup to a value > 0. To test
# DialBackup, simply give the -deactivate -process Stunnel command.
DialBackup=0
# May need to have Parity=Even instead of Parity=None to have SkyTel
# recognize the protocol properly when we failover to the modem
DialBackupProtocol=TMEX
Parity=None
Speed=19200
AreaCode=800
Number=679-2778
After the TelAlert configuration changes have been made, make sure to stop and start TelAlert to
put them into full effect, particularly since the changes involve creating new child processes
(ExecProc and stunnel). Finally, the new SSL-aware configuration should be tested.
Chapter 20: Security Features | 345
20.10 Development Example
Returning to the development example, the code needs to read input from a stream socket and
send the parsed data to a legacy system through a defined Legacy interface object. With the
information above, one can now consider the code required to accomplish this task:
Step 1: Create A New User Object Before one can override the base behavior, one must first define the new object to implement it. In
JAVA, this is done by creating a new object which extends the base class. Define a new java source
file with a new public class LegacyInterface which extends the User class:
import java.lang.* import tanotify.*; import taNotObjects.*; import LegacyMagic.*; // LegacyMagic is the packet that
// contains the legacy adapter.
public class LegacyInterface extends User {}
The first four imports bring in standard objects, the objects that define the shell and event objects,
and the interface to the Legacy backend. Next, the class is defined, including its references to the
base User class.
Now, in the Shell.java file, find the line that reads:
User myuser = new User
This is where the Shell defines the reference to the base User class. Add the import for our new class, and change the line to read:
LegacyInterface myuser = new LegacyInterface()
This step brings in the legacy interface object. To actually use this object, find the line which calls
the SetUserObject method and pass this object. (Example: parser.SetUserObject(myuser); )
That’s all there is to it. The shell will now use the new user object in place of the base class.
Since the new object is derived from the base class, all methods defined in the base User object
are still there and will be called if needed. Stopping here will create a shell which works identically
to the standard toolkit. To change behavior, one must override specific methods. In this case, the
stream source has changed from a file to a TCP socket and posting methods must be extended.
Therefore, one must override the following methods:
UserOpenStream This method must be rewritten to read from a stream
UserCloseStream This method must be rewritten to close a TCP stream
UserPostFileEvent Post file events to the legacy interface
UserPostHeartBeatEvent Post heartbeat events to the legacy interface
UserPostNotificationEvent Post notification events to the legacy interface
346 | TelAlert 6e™ Administrator Guide - Version 6.1.29
In addition, one should redefine UserAppStart and UserAppStop to support opening and closing
access to the legacy system itself. In a true production environment, one would also redefine error
handlers, etc. In this example, we will assume everything works as expected. Consider the
following JAVA code; with the exception of the legacy interface, this JAVA code meets the
requirements defined earlier in this document.
package tanotify;
/**
* This class provides an example for those wishing to write their
* own User subclass. While this class does nothing useful, developers
* can use this class as a model for a subclass that might work with
* a database or legacy system.
*/
/**
* First, import the IO package AND our object definitions
*/
import java.io.Reader;
import tanotObjects.*;
/**
* Get normal JAVA language components
*/
import java.lang.*;
import java.net.*;
import java.io.*;
/**
* First, subclass the user class and reference THIS class in the shell
* THIS IS HOW ONE WOULD CREATE THEIR OWN USER OBJECT
*/
public class DBUser extends User {
/**
* Create a Legacy object here
*/
Legacy mylegacy;
Chapter 20: Security Features | 347
/**
* In this example, the class gets its input from a socket not a
* file, Therefore, this class must override the OpenStream and
* CloseStream methods to start. Create the necessary objects for
* the socket.
*/
ServerSocket serverSocket;
Socket activeSocket;
InputStreamReader inputReader;
/**
* Our local constructor does nothing
*/
public DBUser() {
}
/**
* The post routines do nothing different from the base class
* so we’ll just call the base method via super. If not defined
* here, the base class methods would be used anyway. Here a real
* subclass might used an attached database connection,
* and use these routines to build and execute insert statements.
*/
public boolean UserPostFileEvent(taNotifyFile event) {
/**@todo: Override this tanotify.User method*/
return super.UserPostFileEvent( event);
}
public boolean UserUnknownAttribute(String elementName,
String attrName, String attrValue) {
/** Here we would override this method to handle unknown attributes
*/
/**@todo: Override this tanotify.User method*/
return super.UserUnknownAttribute(
elementName, attrName, attrValue);
}
348 | TelAlert 6e™ Administrator Guide - Version 6.1.29
public boolean UserAppStart(String[] parm1) {
/**@todo: Override this tanotify.User method*/
/** The username and password strings are defined by magic here. */
/** In real code, you’d need to define the logic */
myLegacy.OpenLegacy(usernameRef, passwordRef);
return super.UserAppStart( parm1);
}
public void UserExit() {
/**@todo: Override this tanotify.User method*/
mylegacy.CloseLegacy();
super.UserExit();
}
public boolean UserPostNotificationEvent(
taNotifyNotification event) {
/**@todo: Override this tanotify.User method*/
/**
Here one should serialize the object into a collection of strings and
place them into a vector (data)
*/
Vector data = /* Get strings out of event */
return myLegacy.PostEvent(“Notification”, data)
}
public boolean UserPostHeartBeatEvent(taNotifyHeartBeat event) {
/**@todo: Override this tanotify.User method*/
/**
Here one should serialize the object into a collection of strings and
place them into a vector (data)
*/
Vector data = /* Get strings out of event */
return myLegacy.PostEvent(“HeartBeatEvent”, data)
}
public boolean UserPostError(Exception ex) {
/**@todo: Override this tanotify.User method*/
return super.UserPostError( ex);
}
Chapter 20: Security Features | 349
public boolean UserAppStop() {
/**@todo: Override this tanotify.User method*/
return super.UserAppStop();
}
public boolean UserTick() {
/**@todo: Override this tanotify.User method*/
return super.UserTick();
}
/**
* OVERRIDE : OpenStream
* This new method gets input from a socket, not a file.
*/
public Reader OpenStream(String[] parm1) {
/**
* Get the port number for the server socket we’re listening on
*/
String listenPortString = parm1[0];
Integer iValue = new Integer(listenPortString);
int portNum = iValue.intValue();
try {
/**
* Set up the socket and get Reader and Writer interfaces from it
* once it’s active.
*/
serverSocket = new ServerSocket(portNum);
activeSocket = serverSocket.accept();inputReader = new
InputStreamReader(activeSocket.getInputStream());
PrintWriter outputWriter = new
PrintWriter(activeSocket.getOutputStream());
outputWriter.println("XML Parser ready");
return inputReader;
} catch (IOException ioex) {
ioex.printStackTrace();
return null;
}
350 | TelAlert 6e™ Administrator Guide - Version 6.1.29
}
/**
* OVERRIDE : CloseStream
* Close the stream opened by OpenStream
*/
public void CloseStream() {
try {
activeSocket.close();
serverSocket.close();
} catch (IOException ioex) {
ioex.printStackTrace();
}
}
21
Integrating XML Output
21.1 Overview
TelAlert 5.3 and beyond now supports notifications in XML format. This new interface allows developers to post notifications to third-party systems with minimal effort. In addition, developers
can use this interface to provide customer database and legacy system support. This chapter
describes the steps needed to integrate a TelAlert installation into a third-party backend. Note that this chapter assumes the reader is familiar with TelAlert, it’s notification interfaces, and
JAVA programming.
21.2 Enabling XML Output
TelAlert has two distinct circumstances in which it can produce XML output.
1. The [File] section; the [Heartbeat] section; and definitions in the [Notification] sections can specify XML format for the event data they produce. All three of these sections provide event-driven output, triggered by internal TelAlert events in
the alert lifecycle.
TelAlert includes a DTD (tanote.dtd) that defines the XML output for these events. TelAlert also includes some documentation of an example application that receives and
processes this XML event data stream.
2. The telalert –show and –showalert commands have been enhanced to produce XML-like output. This is somewhat of a curiosity; no DTD is provided, and no method of
passing the output to another application is implemented (other than the standard >>
redirection of command output to a file on both Windows and UNIX, and the "|"piping of
command output on UNIX.)
To have [File], [Heartbeat], or [Notification] produce XML output, simply include [XML] in the appropriate event keyword definitions. For example, a [Notification] definition that
includes the keyword-value pair
AlertStarted=’${TimeStamp} Alert Started ${AlertID} ${Destination} ${Ticket} ’${State}’
352 | TelAlert 6e™ Administrator Guide - Version 6.1.29
would produce output looking like this:
2002/03/18 16:31:44 Alert Started 41 Display 0 ’[20]Alert Started, Display’
while a definition that includes the keyword-value pair AlertStarted=’[XML]’ would produce output looking like this: <Notify><NotificationEvent><AlertStarted tanTimeStamp="2002-03-19T00:31:44+00:00" tanServerHost="integrationrd2.telamon.com" tanEventNum="20" tanStateNum="20" tanStatusData="[20]Alert Started" tanState="[20]Alert Started, Display" tanParagraph="NotifyLogXML" tanDefinition="NotifyLogXML" tanAlertID="41" tanDestination="Display" tanMessage="test" tanPriority="50" tanUser="" tanCheck="" tanGroup="<None>" tanIPCheck="" tanNodeAddr="" tanRemark="" tanReplyTo="" tanSource="" tanSubject="" tanTicket="0" tanMaskedTicket="0" tanClientHost="integrationrd2.telamon.com" tanClientUser="Administrator" tanGroupFullName="<None>" tanCmndID="342"/></NotificationEvent></Notify>
Among other differences, notice that the timestamp in the first example is in "local" time according
to the server clock (PST in this case), while the timestamp in the second example is in UTC (Greenwich) time. For certain variables like ${TimeStamp}whose value according to XML standards differs from older TelAlert defaults, it is now possible to define event keyword-value definitions that use TelAlert ${variablenames}and XML standards; the definition AlertStarted=’${TimeStamp,XML} Alert Started ${AlertID} ${Destination} ${Ticket} ’${State}’’ would produce output looking like this:
2002-03-19T00:31:44+00:00 Alert Started 41 Display 0 ’[20]Alert Started, Display’
[File], [Heartbeat] and [Notification] can direct their XML-formatted output to all of the same places they can direct their legacy-formatted output: appended to text files; sent to UNIX
syslog or Windows Application Event Log; etc. In addition, the "helper" application tconntfy, which
is normally used to send event data to Vytek’s TelaConsole product, can also be used to direct
XML-formatted output to another application listening on a TCP/IP socket, such as the sample JAVA
application discussed later in this chapter.
The [Limits] section has a NotificationITV keyword that enables a [Notification] definition to be invoked for every TelAlert event (most [Limits] Notificationxxx keywords
are only invoked for a specific subset of events). This keyword is useful for creating an XML data stream containing all events.
Chapter 21: Integrating XML Output | 353
Here is an example of such a setup:
[Limits] ... NotificationITV=NotifyXML ... [Notification] ... {NotifyXML} Shell="" Command=${TelAlertBin}/tconntfy ${Message} -size 50000 -raw -host
backend:8512 FIFOFileName=${TelAlertTmp}/tconntfy_xml.fifo EndOfData=${TimeStamp} EOD AlertDelayed="[xml]" AlertStarted="[xml]" AlertError="[xml]" AlertNotSupported="[xml]" AlertOffDuty="[xml]” AlertFilter="[xml] AlertCleared="[xml]" AlertCompleted="[xml]" AlertReleased="[xml]" AlertCheck="[xml]" Started="[xml]" Error="[xml]" NotSupported="[xml]" OffDuty="[xml]" Filter="[xml]" Change="[xml]" ReplyChange="[xml]" Reply="[xml]" BadPassword="[xml]" Acknowledged="[xml]" NotAcknowledged="[xml]" Cleared="[xml]" Completed="[xml]" Released="[xml]" Connect="[xml]" Activation="[xml]" Engine="[xml]" Analog="[xml]" Sensor="[xml]" Relay="[xml]" Power="[xml]" Battery="[xml]" Talk="[xml]" Request="[xml]" ErrorLimit="[xml]" Warning="[xml]" AcknowledgedHeld="[xml]"
354 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Progress="[xml]" Cmnd="[xml]" GroupStarted="[xml]" GroupOffDuty="[xml]" GroupCleared="[xml]" GroupCompleted="[xml]" Server="[xml]" Security="[xml]"
21.3 Defining the Task
In this example, assume the TelAlert administrator has a running TelAlert server, and that the
server has been configured to emit notifications via XML (consult the TelAlert documentation for
details on XML output). Furthermore, for simplicity, assume that the administrator has chosen to
have notifications carry all possible attributes. Finally, assume these notifications are being
broadcast on a socket connection to our new backend process. We will assume this backend process will listen to TCP port 8819, hostname backend. (The toolkit can easily be extended to support any interface, but TCP/IP sockets are convenient mechanisms and require minimal setup.)
In our backend process, once data is available, we want it to be posted to a legacy system. This
system could be a database, a proprietary controller or a set of disk files. In this document, we will
not discuss the legacy interface. Rather, we will assume that a JAVA package for the legacy
interface is already available to the developer with the following class object.
public class LegacyMigration extends Legacy { public boolean OpenLegacy(String account, String password); public boolean CloseLegacy(); public boolean PostEvent(String recordType, Vector data); }
The manual page for this class reads:
The legacy class must be extended by the developer to provide
three basic interfaces.
boolean OpenLegacy(String account, String password)
This method will be called when applications wish to open a
session with the legacy system. It expects a valid
account name and password pass as strings. It will attempt
to log into the legacy system. On success, it returns
true. On failure, it returns false and generates an error
in the system log.
boolean CloseLegacy()
This interface closes the active session with the legacy system.
On success, it returns true, false on failure.
Chapter 21: Integrating XML Output | 355
boolean PostEvent(String recordType, Vector data)
The PostEvent method is used to post new data into the system.
Itexpects a record type (String) and a list of data
objects, all type String. Data is simply read from the vector until all elements have been exhausted. As with other legacy routines, it returns true on success, false
on failure. On failure, the entire record is rejected.
Given this interface, one can post events to the backend system. In this example, we assume the
backend system can make sense of the data and that, in fact, errors never occur. In a true system,
legacy routines would manage error events and return events upstream.
Our task is to get a stream of notification events from a single TelAlert server and post those
events into the legacy system via this interface.
21.4 A (Very) Brief Overview of XML
TelAlert’s XML stream, like all XML, consists of a text stream describing data. To debunk an old
myth, XML does not have meaning, it is simply a representation of the data. Applications require a
definition document to describe that data – to describe to them what a given block of data means
in terms of objects. Simply having XML does not give you interoperability. This document, also supplied with TelAlert, is the data-type-document or DTD.
A DTD describes the structure of an XML document – what is allowed where and how often. While
meaning is still absent, applications can at least trust that their content is syntactically correct. As
an analogy, a JAVA class contains data in various objects. Any application can access that class and
its data – akin to the XML document and DTD - but the meaning of the sub-objects is still left to the developer. A string is a string, is a string…
In TelAlert’s XML streams, objects begin with the <Notify> tag. This tag signals the start of an
event. The event will end when a </Notify> tag is received. One and only one event will be encapsulated within these tags.
<Notify> ...event data </Notify> <Notify> ...event data </Notify>
XML purists will note the lack of a DOCTYPE statement. Technically, XML documents require a
DOCTYPE statement to tell the parser what DTD is bound to that document. Unfortunately, most
parsers will insist on parsing the DTD each and every time a DOCTYPE object is read. This may be
fine for web pages, but for streaming data, it creates a very significant performance penalty. Therefore, TelAlert uses a non-validating SAX parser – one which will accept, and ignore any
DOCTYPE references. While this speeds up parsing, it means that invalid XML will be silently
discarded. One can use a DOM-style parser, but this would increase the memory footprint, and
often the financial footprint, by orders of magnitude. (For reference, our toolkit uses the Apache
Xerces JAVA SAX parser.)
356 | TelAlert 6e™ Administrator Guide - Version 6.1.29
After a notify object, a single object event may follow. TelAlert supports three basic object types:
FileEvent Events related to the file system and log files within the server
NotificationEvent Events indicating various actions inside TelAlert
HeartBeatEvent Events TelAlert sends out to let other systems know about its general
health
As one might expect, these events are indicated by XML tags named <FileEvent>,
<NotificationEvent> and <HeartBeatEvent> respectively. As with all XML, these objects
are encapsulated inside the notify events: <Notify> <FileEvent atributelist..../> </Notify> <Notify> <HeartBeatEvent attributelist..../> </Notify>
TelAlert produces, and the parser accepts the XML shorthand for events. It is legal to end an event by closing the tag with /> rather than including the full closing tag such as <Event data> </EventData>.
Within each event, several string attributes can be defined. Consult the TelAlert documentation for the meaning of these strings. For our purposes, assume that a given notification <N1> has attributes
a, b, and c. Each attribute must contain a string value. Therefore the XML would look like:
<Notify>
<N1 a=”value1” b=”value2” c=”value3”/>
</Notify>
Chapter 21: Integrating XML Output | 357
21.5 The Parser Toolkit
Given the above XML, some code must be written to perform the following tasks:
1. Open an access port to the XML from some server using the appropriate communications
media – a socket, a file, a serial port, etc.
2. Create a parser designed to parse that XML into usable objects
3. For each object parsed, pass that object to a third-party interface
4. When done, close the third-party interface and access stream
Fortunately, our XML parser toolkit has written much of the basic skeleton already. Using this kit, a
developer will most likely need to change only one class. Overall, the toolkit consists of three JAVA
packages, only one of which requires development effort. (Source code for the entire package is
provided for those who wish to extend the package.)
Package Files Purpose
SAXTools SaxTools.java This is the parser framework. It
is the XML-aware code in the
toolkit. Once started, it drives
the parsing and calls appropriate
publish routines. Normally,
developers will not need to
change this package.
TANotObjects BasicNotification.java TANotifyFile.java TANotifyHeartBeat.java TANotifyNotification.java
This package defines the JAVA
objects that hold processed
notifications. Unless a developer
wishes to add an entirely new
type of notification, this package
can be considered “read only”.
TANotify Application.java
Shell.java
User.java
DBUser.java
The “shell” for the parser. A
developer calls this package to
start the application and to
interface his special methods into
the parser. Typically, only two
files will require work.
Since the majority of these files require no changes, this document will not discuss the files
BasicNotification.java, SAXTools.java, and Application.java. The reader may consult the source code for details in these sections. Furthermore, the entire project is written using the Xerces SAX
Parser specification (http:// www.apache.or/xml). This specification assumes the reader is familiar
with JAVA event-based programming. For those unfamiliar with event-based programming, rather
than having a standard code module that calls procedures as they occur, event programs register
with a dispatcher. During startup, the program requests that, on an event X the dispatcher should
call function funcX. This is how SAX works. Simply reading the code might confuse the reader - there is no obvious code flow. Looking deeper into SAXTools however, one finds that the
constructor registers functions on various XML events. When an element starts or ends, or during
an unknown attribute, our parser events are called by the dispatcher. Therefore, rather than
drawing a typical code diagram, this document will use an event response matrix. This matrix can
be read as “When event X occurs, call funcX”.
358 | TelAlert 6e™ Administrator Guide - Version 6.1.29
21.6 The Event Matrix
On Event In File Call Method Purpose
• Application Startup Shell UserAppStart This method in the user
object is called when the
application first starts.
Developers may use this
method to set up any special
structures and/or threads.
• Application Shutdown
Shell UserAppStop Called just before shutdown.
Developers may use this
method to perform any final
cleanup.
• Internal Error Shell &
SaxTools
UserExit When called, it means that a
shell or parser component
found an error it is not
prepared to handle. This
method is called to perform
a quick, abort-style
shutdown.
• Unknown Attributes in XML
• Unknown Elements in XML
SaxTools UserUnknownAttribute This method is called by the
parser when it finds an
attribute or element not in
its dictionary. This routine
can simply ignore or correct
the error, or shut the system
down completely.
• Shell wants to open the input stream
Shell UserOpenStream The shell calls this routine
when the shell wants the
user class to open the input
stream.
• Shell wants to close the input stream
Shell UserCloseStream Called by the shell when it
wants to close the input
stream.
• Error in XML Shell
SaxTools
UserPostError This routine is called during
parsing if invalid XML is
found. It may correct or
ignore the error, or
shutdown the process
completely.
Chapter 21: Integrating XML Output | 359
On Event In File Call Method Purpose
• A FileEvent record
has been posted
SaxTools UserPostFileEvent This method is called during
normal processing. Once the
XML parser has completely
parsed a file event, it passes
the JAVA file class to this
routine for post-processing.
• A HeartBeat record
has been posted
SaxTools UserPostHeartBeatEvent
This method is called during
normal processing. Once the
XML parser has completely
parsed a HeartBeat event,
the parser loads a JAVA
HeartBeat class and passes it
to this routine.
• Notification event
posted
SaxTools UserPostNotificationEvent
This method is called during
normal XML processing.
When the parser has
completely processed a
Notification record, it loads a
JAVA Notification object and
passes it to this method.
• Periodic
maintenance
Shell UserTick The user “tick” routine is
called every N records during
processing. (Default is five
records.) During the tick, the
user object can perform any
side tasks it needs to do.
Examples might be purging
old records from a database
or updating internal health
counters.
360 | TelAlert 6e™ Administrator Guide - Version 6.1.29
All of these events are managed by the JAVA User object. This base class (in User.java) does little
more than read records from a file and print diagnostic data to the system console. In a real
application, one needs to override this object and its methods. This is most often performed by two
steps:
1. Define a new User object, say DBUser which extends the User class.
2. Override the various methods above with application-specific methods.
3. Edit the shell code, looking for the line that says User userobject = new User. This is the
line that needs to change. The new line should become something like DBUser userobject
= new DBUser(). Since DBUser has extended User, all internal routines will work, but our
override methods will now take effect.
4. Activate the new object by calling the parsers SetUserObject routine, passing our object.
21.7 The User Methods
As stated above, developers need only create their own User object and redefine necessary
methods. (Those methods which are not redefined will simply come from the base class so no harm
will occur if someone forgets to redefine a method.) The section below defines the twelve methods
that may be defined and their functions:
Constructor User
Calling convention None
Purpose The constructor can be used to set up the user object’s data
Returns Nothing
Method OpenStream
Calling convention Reader OpenStream (String [] args)
Purpose OpenStreamis called by the shell to open the input stream. It accepts a list
of ARGV style strings. By convention, these strings define the parameters
needed to access the stream. Typically, one parameter might be the file
name, port number, etc.
Returns A valid Reader object on success, null on failure
Chapter 21: Integrating XML Output | 361
Method CloseStream
Calling convention void CloseStream ()
Purpose CloseStream is called by the shell to close the input stream created by
OpenStream.
Returns Nothing
Method
UserAppStart
Calling convention
boolean UserAppStart (String [] args)
Purpose UserAppStart is called by the shell just after application startup. It can be
used as a pre-parse step. It is similar in concept to the constructor in that it
can set up data structure, but it may be called after startup as well. As with
OpenStream, it accepts a collection of ARGV style strings which can be used
as a parameter list.
Returns Returns true if startup was successful, false otherwise. If the method
returns false, the shell will exit.
Method UserAppStop
Calling convention boolean UserAppStop ()
Purpose UserAppStop is called by the shell just before shutdown.
Returns Returns trueif termination was successful, false otherwise. If the method
returns false, the shell will exit.
Method UserExit
Calling convention void UserExit ()
Purpose UserExit is called by the shell or parser code when an abort is needed
rather than a graceful termination.
Returns Nothing
362 | TelAlert 6e™ Administrator Guide - Version 6.1.29
Method UserTick
Calling convention boolean UserTick ()
Purpose UserTick is called by parser and shell every n records. (The default is every
five records.) During this “idle” task event, the code may perform any
actions needed “out of band” of parsing.
Returns
Returns true if the shell is to continue on, falseif a shutdown is required.
Method UserPostError
Calling convention boolean UserPostError(Exception ex)
Purpose UserPostErroris called by the parser when the parser discovers malformed
XML. Normally, this would cause a SAX-exception. In this case, the parser
calls the user UserPostError passing the exception to the method. The user
method may either return true indicating the error is not critical or has
been corrected, or falseif termination is required.
Returns Returns true if the error has been corrected, false if termination is required.
Method UserUnknownAttribute
Calling convention boolean UserUnknownAttribute(String elementName, String
attrName) Purpose UserUnknownAttribute is called by the parser when it detects an attribute or
element not found in the DTD. The event is passed to the user object. If the
user object determines the element and/or attribute are acceptable, it
should return true. Otherwise, it will return falseand terminate the parser.
Returns
Returns true if the error has been corrected, false if termination is required.
Method UserPostFileEvent
Calling convention boolean UserPostFileEvent(taNotifyFile event)
Purpose Once the parser has found, and parsed a <FileEvent>XML stanza, it decodes the XML and passes the decoded JAVA object to this post method. The post
method should perform whatever action is required to post the event to
appropriate systems. Once posted, it should return true. Returning false
indicates posting failed and that the shell should terminate.
Returns Returns true if posting was successful, falseotherwise.
Chapter 21: Integrating XML Output | 363
Method UserPostHeartBeatEvent
Calling convention boolean UserPostHeartBeatEvent(taNotifyHeartBeat event)
Purpose Once the parser has found, and parsed a <HeartBeatEvent>XML stanza, it decodes the XML and passes the decoded JAVA object to this post method.
The post method should perform whatever action is required to post the
event to appropriate systems. Once posted, it should return true. Returning
false indicates posting failed and that the shell should terminate.
Returns Returns true on posting success, false if the shell should terminate.
Method UserPostNotificationEvent
Calling convention boolean UserPostNotificationEvent(taNotifyNotification event)
Purpose Once the parser has found, and parsed a <NotificationEvent>XML stanza, it decodes the XML and passes the decoded JAVA object to this post method.
The post method should perform whatever action is required to post the
event to appropriate systems. Once posted, it should return true. Returning
false indicates posting failed and that the shell should terminate.
Returns Returns true on posting success, false if the shell should terminate.
21.8 The Notification Objects
Given the user object, one can now pass data objects to backend systems. The current codekit
defines three objects:
1. taNotifyFile-The object representing [File] events 2. taNotifyHeartBeat-The object representing [HeartBeat] events 3. taNotifyNotification-The object representing [Notification] events
All three of these objects are implemented as JAVA beans. As with all JAVA beans, the actual
variables for various components are marked private. Code accesses the contents of a bean via its getX methods. For example, a [File] event has an attribute ServerHost. Rather than accessing the value of this attribute with code such as String value = taNotifyFile.ServerHost, standard JAVA beans suggest something closer to String value = taNotify.getServerHost(); This isolates the developer from the actual value of ServerHost. The method will return it as a string regardless of its internal representation. For all
notifications, consult TelAlert documentation for the appropriate attribute list. For each attribute X, each object has a getX method.
364 | TelAlert 6e™ Administrator Guide - Version 6.1.29
21.9 Development Example
Returning to the development example, the code needs to read input from a stream socket and
send the parsed data to a legacy system through a defined Legacy interface object. With the
information above, one can now consider the code required to accomplish this task:
21.9.1 Step 1: Create A New User Object
Before one can override the base behavior, one must first define the new object to implement it. In
JAVA, this is done by creating a new object which extends the base class. Define a new java source
file with a new public class LegacyInterface which extends the User class: import java.lang.* import tanotify.*; import taNotObjects.*; import LegacyMagic.*; // LegacyMagic is the packet that
// contains the legacy adapter.
public class LegacyInterface extends User {}
The first four imports bring in standard objects, the objects that define the shell and event objects,
and the interface to the Legacy backend. Next, the class is defined, including its references to the
base User class.
Now, in the Shell.java file, find the line that reads:
User myuser = new User
This is where the Shell defines the reference to the base User class. Add the import for our new
class, and change the line to read:
LegacyInterface myuser = new LegacyInterface()
This step brings in the legacy interface object. To actually use this object, find the line which calls
the SetUserObject method and pass this object. (Example: parser.SetUserObject(myuser); ) That’s all there is to it. The shell will now use the new user object in place of the base class.
Since the new object is derived from the base class, all methods defined in the base User object
are still there and will be called if needed. Stopping here will create a shell which works identically
to the standard toolkit. To change behavior, one must override specific methods. In this case, the
stream source has changed from a file to a TCP socket and posting methods must be extended.
Therefore, one must override the following methods:
UserOpenStream This method must be rewritten to read from a stream
UserCloseStream This method must be rewritten to close a TCP stream
UserPostFileEvent Post file events to the legacy interface
UserPostHeartBeatEvent Post heartbeat events to the legacy interface
UserPostNotificationEvent Post notification events to the legacy interface
Chapter 21: Integrating XML Output | 365
In addition, one should redefine UserAppStart and UserAppStop to support opening and closing
access to the legacy system itself. In a true production environment, one would also redefine error
handlers, etc. In this example, we will assume everything works as expected. Consider the
following JAVA code; with the exception of the legacy interface, this JAVA code meets the
requirements defined earlier in this document.
package tanotify; /** * This class provides an example for those wishing to write their * own User subclass. While this class does nothing useful, developers * can use this class as a model for a subclass that might work with * a database or legacy system. */ /** * First, import the IO package AND our object definitions */ import java.io.Reader; import tanotObjects.*; /** * Get normal JAVA language components */ import java.lang.*; import java.net.*; import java.io.*; /** * First, subclass the user class and reference THIS class in the shell * THIS IS HOW ONE WOULD CREATE THEIR OWN USER OBJECT */ public class DBUser extends User { /** * Create a Legacy object here */ Legacy mylegacy; /** * In this example, the class gets its input from a socket not a * file, Therefore, this class must override the OpenStream and * CloseStream methods to start. Create the necessary objects for * the socket. */ ServerSocket serverSocket; Socket activeSocket; InputStreamReader inputReader; /** * Our local constructor does nothing */ public DBUser() { } /** * The post routines do nothing different from the base class * so we’ll just call the base method via super. If not defined * here, the base class methods would be used anyway. Here a real * subclass might used an attached database connection, * and use these routines to build and execute insert statements. */ public boolean UserPostFileEvent(taNotifyFile event) { /**@todo: Override this tanotify.User method*/ return super.UserPostFileEvent( event); } public boolean UserUnknownAttribute(String elementName, String attrName, String attrValue) { /** Here we would override this method to handle unknown attributes */ /**@todo: Override this tanotify.User method*/ return super.UserUnknownAttribute( elementName, attrName, attrValue); } public boolean UserAppStart(String[] parm1) {
366 | TelAlert 6e™ Administrator Guide - Version 6.1.29
/**@todo: Override this tanotify.User method*/ /** The Administrator and password strings are defined by magic here. */ /** In real code, you’d need to define the logic */ myLegacy.OpenLegacy(AdministratorRef, passwordRef); return super.UserAppStart( parm1); } public void UserExit() { /**@todo: Override this tanotify.User method*/ mylegacy.CloseLegacy(); super.UserExit(); } public boolean UserPostNotificationEvent( taNotifyNotification event) { /**@todo: Override this tanotify.User method*/ /** Here one should serialize the object into a collection of strings and place them into a vector (data) */ Vector data = /* Get strings out of event */ return myLegacy.PostEvent(“Notification”, data) } public boolean UserPostHeartBeatEvent(taNotifyHeartBeat event) { /**@todo: Override this tanotify.User method*/ /** Here one should serialize the object into a collection of strings and place them into a vector (data) */ Vector data = /* Get strings out of event */ return myLegacy.PostEvent(“HeartBeatEvent”, data) } public boolean UserPostError(Exception ex) { /**@todo: Override this tanotify.User method*/ return super.UserPostError( ex); } public boolean UserAppStop() { /**@todo: Override this tanotify.User method*/ return super.UserAppStop(); } public boolean UserTick() { /**@todo: Override this tanotify.User method*/ return super.UserTick(); } /** * OVERRIDE : OpenStream * This new method gets input from a socket, not a file. */ public Reader OpenStream(String[] parm1) { /** * Get the port number for the server socket we’re listening on */ String listenPortString = parm1[0]; Integer iValue = new Integer(listenPortString); int portNum = iValue.intValue(); try { /** * Set up the socket and get Reader and Writer interfaces from it * once it’s active. */ serverSocket = new ServerSocket(portNum); activeSocket = serverSocket.accept();inputReader = new InputStreamReader(activeSocket.getInputStream()); PrintWriter outputWriter = new PrintWriter(activeSocket.getOutputStream()); outputWriter.println("XML Parser ready"); return inputReader; } catch (IOException ioex) {
Chapter 21: Integrating XML Output | 367
ioex.printStackTrace(); return null; } } /** * OVERRIDE : CloseStream * Close the stream opened by OpenStream */ public void CloseStream() { try { activeSocket.close(); serverSocket.close(); } catch (IOException ioex) { ioex.printStackTrace(); } } }