You are on page 1of 383

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: Document Revision:

TelAlert 6e v6.2.0 5.0

MIR3, Inc. 3398 Carmel Mountain Road San Diego, CA 92121 Phone: 858.724.1200 Fax: 858.724.1201

Email: support@mir3.com 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 1.2 Overview .......................................................................................... 1 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 2.1 2.2 Overview .......................................................................................... 9 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

What is TelAlert 6e? ....................................................................... 9

2.3

2.2.6 Applet-Based Remote Interactions ................................................... 11 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 3.1 3.2 Overview ........................................................................................ 19 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

Technical Overview ...................................................................... 19

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 4.2 4.3 Overview ........................................................................................ 27 Your Accomplishments So Far ............................................................. 27 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 OnlySmall Organization ................................. 31 4.3.8 Scenario Two: Paging, Voice, and EmailSmall Organization ................ 36 4.3.9 Scenario Three: A Larger Organization.............................................. 39

Configuration Basics ..................................................................... 43


5.1 5.2 5.3 Overview ........................................................................................ 43 TelAlert Configuration Methods: TADesktop; TelAlert 6e Web Interface ...... 43 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 6.1 6.2 6.3 6.4 Overview ........................................................................................ 67 What is a Port? ................................................................................. 67 Basic Port Considerations ................................................................... 68 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 7.1 7.2 Overview ........................................................................................ 79 Whats 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

The Role of Ports in TelAlert ......................................................... 67

Dialing the Telephone ................................................................... 79

7.5

7.4.3 Eleven-Digit Local Dialing ............................................................... 83 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 8.1 8.2 Overview ........................................................................................ 89 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

Configuring for Paging Notification ............................................... 89

8.8

8.7.2 Two-Way Internet-Based Paging.................................................... Initiating Pages via Email ................................................................. 8.8.1 Responses to Two-Way Email-Based Text Pages ............................... 8.9 Adding ID Numbers to Pages ............................................................ 9.1 9.2

110 113 113 114

Configuring for Voice Notification ............................................... 117


Overview ...................................................................................... 117 Configuration for Voice Notification .................................................... 117 119 119 119 121 121 121 122 122 122 123 125 125 125 127 128 128 128 129 130 133 134 134 135 135 136 140 140 140 141 141 141 141 142 143 144 144

Configuring for Other Notification Media ..................................... 119


10.1 Overview ...................................................................................... 10.2 Getting Started .............................................................................. 10.2.1 Needed Information .................................................................. 10.3 Setting up Electronic Signboard Notification ......................................... 10.3.1 Signboard Overview .................................................................. 10.3.2 Initial Signboard Firmware Setup ................................................. 10.4 Standard Signboard Setup (DeviceSubtype=2) ..................................... 10.4.1 TelAlert-Controlled Signboard Message Display ............................... 10.4.2 Signboard [Port] Definition ......................................................... 10.4.3 Signboard [Configurations] Definition ........................................... 10.4.4 Signboard [Destinations] Definitions ............................................. 10.4.5 Sending Messages to the Signboard ............................................. 10.4.6 Controlling Signboard Text Color and Effects .................................. 10.4.7 Configuring Multiple Signboards ................................................... 10.5 Alternative Signboard Setup (DeviceSubtype=1) .................................. 10.5.1 Signboard [Port] Definition when DeviceSubtype=1......................... 10.5.2 Signboard [Configurations] Definition when DeviceSubtype=1 ........... 10.5.3 Additional Signboard Firmware Setup when DeviceSubtype=1 ........... 10.5.4 Signboard [Destinations] Definitions when DeviceSubtype=1 ............ 10.6 Setting up Email Notification ............................................................. 10.6.1 Email [Port] Definition ............................................................... 10.6.2 Email [Configurations] Definition.................................................. 10.6.3 Email [Destinations] Definition .................................................... 10.6.4 Using Email as a Backup Notification Medium ................................. 10.6.5 Handling Responses to Email With Readmail .................................. 10.7 Setting Up SpectraLink LCD Notification .............................................. 10.7.1 SpectraLink LCD [Port] Definition ................................................. 10.7.2 SpectraLink LCD [Configurations] Definition ................................... 10.7.3 SpectraLink LCD [Destinations] Definitions .................................... 10.8 Setting up Command Line Notification ................................................ 10.8.1 Command-Line [Configurations] Definition ..................................... 10.8.2 Command-Line [Destinations] Definition........................................ 10.8.3 Applications for Command-Line Notification.................................... 10.9 POPUP Message Boxes on Windows .................................................... 10.10 Sending Text Messages to Other Systems............................................ 10.10.1 UNIX Syslog Processes .............................................................

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 ...................................................................................... 11.2 Getting Started .............................................................................. 11.2.1 What is Filtering? ...................................................................... 11.2.2 Needed Information .................................................................. 11.3 A Simple Filter ............................................................................... 11.3.1 The Scenario ............................................................................ 11.3.2 Procedure ................................................................................ 11.4 Filtering Strategies.......................................................................... 11.4.1 Filtering and Default Logic .......................................................... 11.4.2 RequiresFullMatch and Exclusive Value Combinations ....................... 11.4.3 RequiresClientMatch .................................................................. 11.4.4 The MatchKeyword .................................................................... 11.4.5 Filtering and Groups .................................................................. 11.4.6 Filtering and Schedules .............................................................. 11.4.7 Filtering and Users .................................................................... 11.5 Filtering by Message Priority ............................................................. 11.5.1 Extended Example .................................................................... 11.5.2 Default Logic............................................................................ 11.6 Filtering Messages by IP Address ....................................................... 11.7 Filtering out Duplicate and Transient Messages ..................................... 11.7.1 Filtering Out Duplicate Node Down Messages ............................... 11.7.2 Suppressing Transient Messages .................................................. 11.8 Suppressing Unwanted Messages During Scheduled Downtime ................ 11.8.1 Suppressing Orphan Up Messages ............................................. 11.8.2 When a Device Does Not Come Back Online as Scheduled................. 161 161 161 161 162 162 162 164 164 165 167 167 168 170 170 171 172 173 173 174 174 175 176 177 177

11.9 Filtering Messages by Source ............................................................ 11.10 Pattern Matching ............................................................................ 11.10.1 Other Uses............................................................................. 11.10.2 Pre-Defining Regular Expressions ............................................... 12.1 Overview ...................................................................................... 12.2 Getting Started .............................................................................. 12.2.1 What are Schedules? ................................................................. 12.2.2 Needed Information .................................................................. Managing Schedules ................................................................................ Schedule Types .................................................................................. Viewing Schedules .............................................................................. 12.3 Scheduling Approaches .................................................................... 12.3.1 Schedules and Default Logic........................................................ 12.4 Assigning Device Schedules .............................................................. 12.4.1 Adding a New Device Schedule .................................................... 12.5 Creating Group Member Schedules..................................................... 12.5.1 Assigning Group Member Schedules ............................................. 12.5.2 Effect of Time Zones.................................................................. Creating Extra Duty Schedules .............................................................. 12.5.3 Schedules and [Filter] Definitions ................................................. 12.5.4 Schedules and [User] Definitions ................................................. 12.5.5 Schedules and Message Priority ................................................... 13.1 Overview ...................................................................................... 13.2 Getting Started .............................................................................. 13.2.1 What Are Users? What Are They For? ............................................ 13.2.2 Needed Information .................................................................. 13.3 User Roles ..................................................................................... 13.3.1 Key Principles........................................................................... 13.3.2 Definitions ............................................................................... 13.3.3 Viewing Tabs............................................................................ 13.3.4 Role Editor Screen .................................................................... 13.4 Managing Users.............................................................................. 13.4.1 Adding Users............................................................................ 13.5 Creating a [User] definition: Essentials ............................................... 13.6 Values for Inheritance by Associated Destinations ................................. 13.6.1 Direct Inheritance ..................................................................... 13.6.2 Minimum of the [User] Value and the [Destinations] Default ............. 13.6.3 Maximum of the [User] Value and the [Destinations] Default............. 13.6.4 Maximum of the [User] Value, the [Destinations] Default, and the [Configurations] Value......................................................................... 13.7 Values for Dial-in and Dial-out Access ................................................. 13.8 User-Based Administrative Techniques ................................................

178 178 179 180 183 183 183 184 184 184 185 186 186 187 190 191 192 193 194 194 194 195 197 197 197 198 198 198 198 199 200 207 207 213 213 213 214 214 214 214 215

Setting Up and Applying Schedules ............................................. 183

Representing Users .................................................................... 197

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 ...................................................................................... 14.2 Managing Your Devices .................................................................... 14.2.1 Adding New Devices .................................................................. 14.2.2 Editing Your Devices .................................................................. 14.3 Assigning Device Schedules .............................................................. 14.3.1 Adding a New Device Schedule .................................................... 14.3.2 Removing Your Devices .............................................................. 15.1 Overview ...................................................................................... 15.2 Getting Started .............................................................................. 15.2.1 What are Responses? ................................................................ 15.2.2 Needed Information .................................................................. 15.2.3 Other Considerations ................................................................. 15.3 Taking Advantage of Pre-Defined Responses ........................................ 15.3.1 Responding Via the Command Line............................................... 15.4 Creating Custom Responses.............................................................. 15.5 Two-Way Pager Considerations.......................................................... 15.6 Responses and the [Notifications] Feature ...................................... 16.1 Overview ...................................................................................... 16.2 Getting Started .............................................................................. 16.2.1 What Are Groups? What Are They For?.......................................... 16.2.2 Adding a New Group.................................................................. 16.2.3 Activating and De-Activating Groups ............................................. 16.2.4 Modifying a Group ..................................................................... 16.2.5 Adding Group Members .............................................................. 16.3 Assigning Schedules to Group Members .............................................. 16.3.1 Assigning a Schedule to a Group Member ...................................... 16.3.2 Removing Group Members .......................................................... Reordering Group Members .................................................................. 16.4 Group Basics.................................................................................. 16.4.1 Building a Group From a List of Other Groups ................................. 16.4.2 Supported Group Attributes ........................................................ 16.5 Broadcast Notification ...................................................................... 16.5.1 About Group IDs ....................................................................... 16.5.2 Use of -g and -l Compared.......................................................... 16.5.3 Schedules and Broadcast Notifications .......................................... 16.6 Escalation ..................................................................................... 16.6.1 A Simple Escalation ................................................................... 16.6.2 Other Approaches to Strategy ..................................................... 217 217 218 222 222 225 226 227 227 227 227 228 228 229 229 230 231 235 235 235 236 237 238 238 240 240 245 245 246 246 246 247 248 248 248 249 249 251

Enabling Responses .................................................................... 227

Broadcasting to Groups and Creating Escalations ........................ 235

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 ...................................................................................... 18.2 Starting and Stopping TelAlert........................................................... 18.3 Configuring TelAlert to Run Automatically ............................................ 18.3.1 On Windows............................................................................. 18.3.2 On UNIX ................................................................................. 18.4 Installing TelAlert Clients.................................................................. 18.4.1 Configuring the Server To Accept Remote Clients ............................ 18.4.2 Installing the TelAdmin Client ...................................................... 18.4.3 Installing Remote Command-Line Clients on Windows ...................... 18.4.4 Installing Remote Command-Line Clients on UNIX ........................... 18.5 Setting up the TelAlert Web Clients .................................................... 18.5.1 Installing the Web Clients ........................................................... 18.5.2 Running Multiple Web Clients on the Same Machine......................... 277 277 278 278 278 278 278 279 279 281 282 282 282

18.5.3 Using the Web Clients with Web-Enabled Cell Phones....................... 18.5.4 Installing Online Help for the Web Clients ...................................... 18.5.5 Configuring telalerth with telalerth.ini ........................................... 18.5.6 Other Keywords........................................................................ 18.6 Setting up Logging .......................................................................... 18.6.1 Default Log Files ....................................................................... 18.6.2 Setting Maximum Sizes .............................................................. 18.6.3 WriteExecsToTrail ..................................................................... 18.6.4 Configuring Additional Logging Behavior ........................................ 18.7 Miscellaneous Administrative Tasks .................................................... 18.7.1 Specifying Maximum ID Assignments............................................ 18.7.2 Viewing Listen Sockets............................................................... 18.8 TelAlert Web UI Administrative Tasks ................................................. 18.8.1 Importing Data......................................................................... 18.8.2 Changing the Color Theme.......................................................... 18.8.3 Managing Configurations ............................................................ 18.8.4 Managing Departments .............................................................. 18.8.5 Managing Holidays .................................................................... 18.8.6 LDAP Configuration ................................................................... 18.8.7 User Role Configuration.............................................................. 18.8.8 Single Sign On Configuration ....................................................... 18.8.9 Log Viewer .............................................................................. 18.8.10 Setting System Preferences....................................................... 18.8.11 System Status Verification ........................................................ 18.9 Additional Admin Tasks ..................................................................... 18.9.1 Changing a Users Role ............................................................... 18.10 System Reports .............................................................................. 19.1 Overview ...................................................................................... 19.2 About the TelAlert Monitor Window .................................................... 19.3 Setting Up TelAlert Monitor ............................................................... 19.3.1 Configuring TelAlert Notification Paragraphs for TelAlert Monitor ......... 19.3.2 Configuring TelAlert Desktops Host Properties................................ 19.4 Launching the TelAlert Monitor Window ............................................... 19.4.1 TelAlert Monitor Window Button ................................................... 19.4.2 TelAlert Desktop Tools Menu ....................................................... 19.4.3 TelAlert Monitor Data Dialog........................................................ 19.5 Using TelAlert Monitor ..................................................................... 19.5.1 TelAlert Monitor AlertTree ........................................................... 19.5.2 Icons ...................................................................................... 19.5.3 TelAlert Monitor Toolbar ............................................................. TelAlert Monitor Tabs .......................................................................... Alert Monitor Send Message Interface Dialog ...........................................

283 283 283 288 291 291 292 292 292 292 292 293 293 294 301 301 302 307 308 309 310 311 312 313 314 314 314 317 318 318 319 319 319 319 320 320 321 322 323 326 328 330

Getting Familiar with the TelAlert Monitor................................... 317

Security Features ....................................................................... 333


20.1 Overview ...................................................................................... 20.2 TelAlerts Security-Conscious Architecture ........................................... 20.2.1 telalerte: The Central Hub of TelAlert ........................................ 20.2.2 The Media Controllers ................................................................ 20.2.3 TelAlert Desktop ....................................................................... 20.2.4 Client Programs ........................................................................ 20.3 Password Encryption ....................................................................... 20.4 Scheduling of Client Connections ....................................................... 20.5 Authentication for Admin and Client Connections .................................. 20.6 Control Over Remote Connections ...................................................... 20.7 Security Event Available in [Notifications]....................................... 20.8 Control Over IVR Interactions ........................................................... 20.9 Using SSL with Skytel Devices........................................................... 20.9.1 Obtain and Install Wrapper/Proxy Software.................................... 20.10 Development Example ..................................................................... 21.1 Overview ...................................................................................... 21.2 Enabling XML Output ....................................................................... 21.3 Defining the Task............................................................................ 21.4 A (Very) Brief Overview of XML ......................................................... 21.5 The Parser Toolkit ........................................................................... 21.6 The Event Matrix ............................................................................ 21.7 The User Methods ........................................................................... 21.8 The Notification Objects ................................................................... 21.9 Development Example ..................................................................... 21.9.1 Step 1: Create A New User Object................................................ 333 333 334 335 336 336 337 338 338 339 340 340 340 341 345 351 351 354 355 357 358 360 363 364 364

Integrating XML Output .............................................................. 351

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.

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


Refer to Appendix: MIR3 Contact Information for MIR3 customer support.

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.

2 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Use of Monospaced Fonts Purpose

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 TelAlerts configuration file; message represents the message text to be sent by TelAlert.

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.

2001/03/16 11:50:11>Event [21]Alert Completed (23), Status: [81]Message sent, TelamonTestPage


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. Within procedural text, numbered steps denote actions that should be followed in sequence.

1.

Go to the Add User page.

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.

Chapter 1: Introduction | 3

Example "Open

Purpose File names and extensions The same monospaced font is used to represent file names and extensions. telalert.iniexamples Entries drawn from the TelAlert configuration file are also represented in a monospaced font.

telalert.ini and search for ..."

" ... gives the file a .bak extension and then ..." {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.

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. Within procedural text, numbered steps denote actions that should be followed in sequence. 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.

2.

Go to the Add User page.

Click Save to save your work. Click Cancel to exit without saving.

The information icon denotes reference material.

The note icon indicates definitions or considerations that help you understand the related task.

4 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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 organizations 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.

Chapter 1: Introduction | 5

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 TelAlerts 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


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.

Text to Speech (TTS) is the second most commonly used notification medium supported by TelAlert. If you plan to use TelAlerts 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 answeredfor 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.

6 | TelAlert 6e Administrator Guide - Version 6.1.29

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 TelAlerts 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 TelAlerts 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.

Chapter 1: Introduction | 7

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 organizationimplicitly 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 escalationsending 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 eventssome relating to notifications, some relating to input from environmental monitors, some relating to logging, and some relating to the state of TelAlerts 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 TelAlerts XML output can be integrated with various third-party applications.

8 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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 solutionsanything 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 notificationsor 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 messagesa key factor in TelAlert 6e's ability escalate an alert and ensure that someone takes control of the situation.

10 | TelAlert 6e Administrator Guide - Version 6.1.29

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 backoffice 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&Ts 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 integratedvia 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.

Chapter 2: What is TelAlert 6e? | 11

2.4 TelAlert 6e Integrations


TelAlert 6e is designed to work with other applicationsto 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.

12 | TelAlert 6e Administrator Guide - Version 6.1.29

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) Windows (32 bit Server) (2003) Windows (32 bit Server) (2008) Linux Red Hat Enterprise Linux AS release 4 Java Java JRE 1.5 (5.0) Tomcat Tomcat 5.5.X Web Browser A JDK 1.1 compatible web browser EXISTING EXISTING EXISTING EXISTING EXISTING EXISTING NEW

2.5.2 Database Server


Database Oracle 10g SQL Server 2000 SP 4 and 2005 (2005 recommended)* mySQL 5.0 and above EXISTING EXISTING EXISTING

*If using SQL Server express all TCP ports must be set to 1433 as shown in the figure below.

Chapter 2: What is TelAlert 6e? | 13

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)

14 | TelAlert 6e Administrator Guide - Version 6.1.29

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
AIX AIX 3.2.5 AIX 4.1.3 (and higher) AIX 5.2 (and higher) HP-UX HP-UX PA-RISC 1.0 (9.04 and higher) HP-UX PA-RISC 1.1 (9.04 and higher) HP-UX PA-RISC 1.1 (10.20 and higher) HP-UX PA-RISC 2.0 (10.20 and higher) 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) Java Java 1.50 (TelAlert Admin "telalert") Java 1.50 (TelAlert EndUser "telalertc") Java 1.60 (TelAlert Admin "telalert") Java 1.60 (TelAlert EndUser "telalertc") Linux Linux (glibc 2.0) (Intel x86 32bit) Linux (glibc 2.1) (Intel x86 32bit) Linux (glibc 2.5) (Intel x86 32bit) (Red Hat 5.4) Microsoft Windows (32 bit Server) (4.0/2000/XP Professional) Windows (32 bit Server) (2003) Windows (32 bit Server) (2008)

Status

Supported with TA 5.20 Supported with TA 5.20 Supported with TA 5.60

Supported with TA 5.50 Supported with TA 5.50 Supported with TA 5.70 Supported with TA 5.70 EXISTING EXISTING EXISTING

EXISTING EXISTING EXISTING EXISTING

Supported with TA 5.70 Supported with TA 5.70

NEW

EXISTING EXISTING NEW


Chapter 2: What is TelAlert 6e? | 15

SGI SGI Irix SGI MIPS ABI SCO SCO Release 3 SCO Release 5 Sun SunOS 4.1.3 (SPARC 32bit) Solaris 2.7 (Solaris 7) + (SunOS 5.7+) (SPARC 32/64 bit) Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (Intel X86 32/64 bit) Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (SPARC 32/64 bit) Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (Intel X86 32/64 bit) Solaris 2.10 (Solaris 10) + (SunOS 5.10+) (SPARC 32/64 bit) Other AT&T GIS (System 3000) BSDI 4.1 Digital Unix (Tru64 UNIX 5.1A BL4) Tandem Guardian & Tandem OSS IBM OS/2 HP MPE/iX (WRQ format) Supported with TA 5.50 Supported with TA 5.50 Supported with TA 5.70 Supported with TA 4.03 Supported with TA 5.10 Supported with TA 5.20 Supported with TA 5.50 Supported with TA 5.70 NEW NEW NEW NEW Supported with TA 5.50 Supported with TA 5.50 Supported with TA 5.50 Supported with TA 5.50

16 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 2: What is TelAlert 6e? | 17

2.6.5 Integration Instructions


TelAlert 6es 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 some files, including log files, are placed in /tmp.

/usr/telalert on UNIX systems. Note that

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.

18 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Servers 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

dealing with checking the status of TelAlert Messaging Servers 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 (TelAlerts 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.


20 | TelAlert 6e Administrator Guide - Version 6.1.29

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. file called

telalerte tracks all TelAlert Messaging Server activity, recording it in a comprehensive events 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 TelAlerts 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.

Chapter 3: Technical Overview | 21

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 servers networking setup to see what it thinks its DNS name and IP address are.

22 | TelAlert 6e Administrator Guide - Version 6.1.29

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. telalert vs. telalertc It is recommended that you use telalertc to issue all TelAlert commands other than the administrative commands unique to telalerteven 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.

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.
Chapter 3: Technical Overview | 23

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 TelAlerts 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

24 | TelAlert 6e Administrator Guide - Version 6.1.29

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 when TelAdmin is used in Chapter 17

telalert.sects and telalert.ini file backups

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 filetelalert.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 Bobs text pager, you might use the following command:

telalertc -c SkyTelNationalTextPager -pin 1234567 -m "node 2745 down"

Chapter 3: Technical Overview | 25

-c tells TelAlert to understand SkyTelNationalTextPager as a reference to the [Configurations] definition of the same name. This definition contains information on how to
Here, 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 TelAlerts 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 picturehow the various pieces of configuration data combine to deliver some of TelAlerts most valuable benefits.

26 | TelAlert 6e Administrator Guide - Version 6.1.29

4
Implementation Planning
4.1 Overview
An introduction to the work of setting up TelAlert to meet your organizations 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 lineeither 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 applications 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.

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, TelAlerts 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.

28 | TelAlert 6e Administrator Guide - Version 6.1.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 handledsomething 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.

Chapter 4: Implementation Planning | 29

4.3.4 The Alert Timeline and Escalations


The introduction of escalationsachieved using [Group] and [Strategy] definitionschanges 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.

30 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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.

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 OnlySmall 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}


Chapter 4: Implementation Planning | 31

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 persons 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.

32 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Chapter 4: Implementation Planning | 33

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 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
Here, 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.

34 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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 escalationso 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.

Chapter 4: Implementation Planning | 35

4.3.8 Scenario Two: Paging, Voice, and EmailSmall 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 OnlySmall 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 TelAlerts 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 users 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.

36 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Rachels mobile phone. 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. Third, set a

2.

3.

Strategy value for each of the [Group] definitions you create.


Chapter 4: Implementation Planning | 37

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 used to send email notifications:

[Configurations] definition that will be

[Configurations] ... {Email} Type=Email Model=Internet Host=server.domain.com Service=smtp From=telalert@domain.com 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.
Together, 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=cynthia@domain.com


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.

38 | TelAlert 6e Administrator Guide - Version 6.1.29

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 works 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 schedulessomething 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.

Chapter 4: Implementation Planning | 39

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 want to do. o

[User] definitions that makes sense for what you

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. 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?

40 | TelAlert 6e Administrator Guide - Version 6.1.29

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 scenariofor 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 possiblei.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 individuallyby 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.

Chapter 4: Implementation Planning | 41

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.

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 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.

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.

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.

44 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Desktops 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.

Chapter 5: Configuration Basics | 45

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 Desktops 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 Desktops 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.

46 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 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.

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.

Note that telaconf.hosts should contain the following entries: 00.y 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

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.

Chapter 5: Configuration Basics | 47

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. 2. Using a text editor, edit the telaconf.hosts file and add the IP address of the client machine. 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 TelAlerts file structure works, see the Switching between Configuration Methods section later in this manual.) However, you can alter TelAdmins 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

48 | TelAlert 6e Administrator Guide - Version 6.1.29

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 TelAdmins 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 TelAlerts 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

Chapter 5: Configuration Basics | 49

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 selfservice 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 TelAlertproprietary 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 others 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 TelAlerts 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.

50 | TelAlert 6e Administrator Guide - Version 6.1.29

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 dont 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.

Chapter 5: Configuration Basics | 51

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 TelAdmins 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,

52 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 5: Configuration Basics | 53

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. 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.) 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.

2.

3.

54 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 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.

2.

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.) 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. 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).

2.

3.

Import the Data into TelAdmin


1. 2. Click the Import... button at the bottom of the panel. A dialog window appears. 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. 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. Click the Get Clipboard button. (If this is grayed out, then the clipboard does not contain any text data.) 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.

3.

4.

5.

Chapter 5: Configuration Basics | 55

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. 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. 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. Change any other field values as needed, and click Save. The imported values are not permanently saved until you click the Save button.

7.

8.

9.

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.

56 | TelAlert 6e Administrator Guide - Version 6.1.29

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 examples 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 TelAdmins left pane. The line Type=InteractiveTTS tells you to select the InteractiveTTS subtree under Configuration in TelAdmins left pane. The line enclosed in curly brackets tells you to select (or create) a definition named OutboundVoiceLive in the TelAdmins 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 dropdown list. See the TelAlert Desktop User Guide for further information.

Figure 12. TADesktop Configuration section

Chapter 5: Configuration Basics | 57

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 TelAlerts 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 senders 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.

58 | TelAlert 6e Administrator Guide - Version 6.1.29

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-today 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. 2. 3. Enter the appropriate URL into your Internet browser. On the TelAlert 6e Log In screen, enter your assigned username and password. Select the Log In button. After successfully logging in, the TelAlert 6e Home page appears.

Chapter 5: Configuration Basics | 59

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 users 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)

60 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 5: Configuration Basics | 61

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

62 | TelAlert 6e Administrator Guide - Version 6.1.29

Figure 18. Manage Department Alerts page (Admin/Supervisor View)

Figure 19. Manage Alerts page (Staff User View)

Chapter 5: Configuration Basics | 63

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)

64 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 5: Configuration Basics | 65

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)

66 | TelAlert 6e Administrator Guide - Version 6.1.29

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 computers 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 correctlyin all three senses of the term. The The The and physical connection between device and computer must be correct. file associated with the port at the operating system level must be set up correctly. [Port] definition in the TelAlert configuration file must point to the correct port and accurately 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.

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 portrelated changes to your TelAlert configuration. However, this chapter tells you what you need to know if you want to add a port, change a ports 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.

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:

Modemfor a port to which a modem is connected. DirectModemfor a port to which a modem hooked to a leased line is connected. FaxModemfor a port to which a DN400E fax modem is connected to send text messages to fax machines. TTSfor a port to which a Dialogic telephony card is connected using Text to Speech
(TTS).

Internetfor the computers Internet connection. Devicefor a port to which a device of any kind not explicitly supported by the other
models is connected (electronic signboards, most commonly).

Remotefor another installation of TelAlert with which the installation on the local machine is to communicate. Gatewayfor another installation of a TelAlert server that is behind a firewall.
Obsolete Model values:

Voicefor a port to which a Dialogic telephony card is connected using prerecorded words. (Obsolete) EngineMinifor a port to which a TelAlert Voice Engine is connected. (Obsolete) Enginefor a port to which a TelAlert Classic Engine is connected. (Obsolete) EngineSensorfor a port to which a TelAlert Sensor Interface Unit is connected.
(Obsolete)

EngineRelayfor a port to which a TelAlert Relay Interface Unit is connected.


(Obsolete)

EngineAnalogfor a port to which certain environmental monitors which connect via


the Sensor Interface Unit is connected. (Obsolete)

68 | TelAlert 6e Administrator Guide - Version 6.1.29

The other most essential discussed below.

[Port] components vary according to the Model value set. These are

Modem
A [Port] definition of values.

Model=Modem requires Dev, Speed, Modem, and PhonePrefixes

DevThe name of the file associated with the physical port to which the modem is connected (e.g., COM2,tty00). SpeedThe speed at which you want to communicate with the modem. ModemThe name of the [Modem] section corresponding to the model of the modem. PhonePrefixesThe 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 modems model.

DevThe name of the file associated with the physical port to which the modem is connected (e.g., COM2, tty00). SpeedThe speed at which you want to communicate with the modem.
FaxModem

[Port] definition of Model=FaxModem requires Dev, Speed, Modem, and PhonePrefixes values.
A

DevThe name of the file associated with the physical port to which the modem is connected (e.g., COM2,tty00). SpeedThe speed at which you want to communicate with the modem. ModemThe name of the [Modem]section corresponding to the model of the modem. PhonePrefixesThe 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.

Chapter 6: The Role of Ports in TelAlert | 69

TTS
A

[Port] definition of Model=TTS requires VoiceLine and PhonePrefixesvalues.

VoiceLineA 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.

PhonePrefixesThe 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.

DevThe name of the file associated with the physical port to which the device is connected (e.g., COM2, tty00).

Referring to Physical Ports on Windows On Windows, TelAlert now allows the Dev value under two formats

[Port] to be entered in either of

Dev=COMn Dev=COMn:
where

n is the number of the port.

SpeedThe speed at which you want to communicate with the device. DeviceSubtypeThe 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. AlphaAddressesA range list that provides the addresses of each of a series of daisy-chained signboards (used only when DeviceSubtype=2).

70 | TelAlert 6e Administrator Guide - Version 6.1.29

Remote
A

[Port] definition of Model=Remote requires Host and Service values.

HostThe host name (or IP address) of the remote machine on which TelAlert is installed. ServiceThe 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.

HostThe host name (or IP address) of the gateway machine on which TelAlert is installed. ServiceThe 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:

DeviceHostThe host name (or IP address) of the terminal server. DeviceServiceThe name or number of the port on the terminal server to which the device is
connected.

NetDeviceSet to True. SoftwareParitySet 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 servers parity setting is determined by the DeviceSubtype value:

0whatever value is needed to match the devices parity setting 17/even 27/even 37/even

Chapter 6: The Role of Ports in TelAlert | 71

6.4.1 Testing Connectivity on a Terminal Server


TelAlert comes with two programs: termserv.exe and .exe suffix on Windows, but no suffix on UNIX.

testcomm.exe. These programs have a

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] definitions Type value matches one of the items listed as part of the [Port] definitions 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
72 | TelAlert 6e Administrator Guide - Version 6.1.29

Here, TelAlert recognizes {Engine1} as an appropriate port for processing notifications based on {TelamonTestPage} because TextPager is one of the types listed in the ports 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 Engines 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.

Chapter 6: The Role of Ports in TelAlert | 73

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.)

74 | TelAlert 6e Administrator Guide - Version 6.1.29

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, its 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.

Chapter 6: The Role of Ports in TelAlert | 75

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.

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
For Dialing errors, the keywords 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 its become clear that no messages are getting through at all. For Connect errors, theres 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.

76 | TelAlert 6e Administrator Guide - Version 6.1.29

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 systems 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 installations 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.

Chapter 6: The Role of Ports in TelAlert | 77

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.

78 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Whats 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 providers 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 Windowss Modem Settings In Windows, TelAlert controls the modem directly. It ignores any settings in the Modem and Telephony control panel applets.

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 dialingfor 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 (,).

80 | TelAlert 6e Administrator Guide - Version 6.1.29

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 formers 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 proceed when asked to dial a number:

[PhonePrefixes] allow TelAlert to determine how to

InsideDigitCount SpecialDigitCount LocalAreaCode AlternateLocalAreaCodes AlternateLongDistanceAreaCodes


Chapter 7: Dialing the Telephone | 81

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

SpecialAccess value (if any), then the Numbervalue, and then the SpecialBillingCode value (if any). In these instances, AreaCode is ignored and not
TelAlert dials the 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 value (if any), then the Number value.

LocalAccess

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 dialingi.e., seven-digit dialingis very simple. 1. Set AreaCode and Number values in the definition, as usual. In the appropriate local area code.

[Configurations] or [Destinations]

2.

[PhonePrefixes] section, set the LocalAreaCode value to the

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 (if any) and the number.

LocalAreaCode, TelAlert simply dials the LocalAccess value

82 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 2. Set AreaCode and Number values in the definition, as usual. In the [PhonePrefixes] section:

[Configurations] or [Destinations]

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.

Number and AreaCodevalues in either the [Configurations] or the [Destinations] definition. As a general rule, if you dial the same number to reach different
Set the people (as in the case of a number that gives you access to a voice mail system, or the number for a paging service providers 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.

Chapter 7: Dialing the Telephone | 83

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.

AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual.


Provide Enter the relevant area code(s) (e.g., 800, 888, or others) in the list of AlternateLongDistAreaCodes under the appropriate [PhonePrefixes] section. Finally, set

2.

3.

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 and AreaCode.

Number

84 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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.

7.6.2 Getting an Inside Line


Depending on how your organizations 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.

Chapter 7: Dialing the Telephone | 85

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 speciallyi.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 valuemaking 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.

86 | TelAlert 6e Administrator Guide - Version 6.1.29

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 wayto 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 modems S8 register. In most modems, the factory default is two seconds. To read the registers current value, control the modem with a terminal emulator, and enter the command:

ats8?
To change the registers 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.

Chapter 7: Dialing the Telephone | 87

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 ### -an (###)###-#### -ext ### -mailbox ### -n (###)###-####

AlternateExtension (AlternateAreaCode)AlternateNumber Extension Mailbox (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 modems 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 modems documentation, but usually this is done by adding a S6=4 to one of the Setup strings (in this case, were setting a pause of 4 seconds).

88 | TelAlert 6e Administrator Guide - Version 6.1.29

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 organizations 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 providers host machine (needed for Internetbased service only) telephone number for paging (needed only for services that require dialing a single telephone number)

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 organizations 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.

90 | TelAlert 6e Administrator Guide - Version 6.1.29

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:

Chapter 8: Configuring for Paging Notification | 91

[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

92 | TelAlert 6e Administrator Guide - Version 6.1.29

Note that a text pager destination is typically comprised of: 1. 2. 3. A name that uniquely identifies it within the context of TelAlert. A reference to an existing [Configurations] definition. 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.

Chapter 8: Configuring for Paging Notification | 93

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 TelAlerts 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## \ \b \n \r \s \t \\ \x## \###

set timeout to ## seconds - (hyphen) bell line feed carriage return space tab backslash hex character number ## octal character number ###

\E \e \c \d \p \P \A \M

echo check on echo check off suppress carriage return at end of send pause 1 second pause .25 seconds the pager number (from PIN keyword or pin option) the password (from Access keyword) the message text

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.

94 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 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. 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. Otherwisethat is, if If TelAlert has no more messages to send, or it does not receive the string within the timeoutit goes on to ChatLogoff.

2.

3.

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.

Chapter 8: Configuring for Paging Notification | 95

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.
96 | TelAlert 6e Administrator Guide - Version 6.1.29

ChatScript contains four expect/send parameter pairs:


1. 2. This pair has a blank expect, so it immediately sends an

S followed by a carriage return. \E

Waits for the colon after the pager-number prompt, then sends the ${PIN} value. The means that TelAlert will check to make sure the paging service echoes back the PIN correctly. Waits for the colon after the message prompt, then sends the

3. 4.

${Message} value.

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. 2. 3. Connects to text paging service by modem. Runs

ChatLogon. If the script fails, TelAlert goes to step 4.

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. Runs

4. 5.

ChatLogoff.

If TelAlert has additional messages for the service, it starts over with step 1.

TelAlerts 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.

Chapter 8: Configuring for Paging Notification | 97

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 modemwhether in the Engine or an external onealready 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 providers textpaging (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.

98 | TelAlert 6e Administrator Guide - Version 6.1.29

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"


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 providers standard numeric paging dial-up number.

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.

Chapter 8: Configuring for Paging Notification | 99

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 TelAlerts 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:

BlindAnswerWait10s 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.

100 | TelAlert 6e Administrator Guide - Version 6.1.29

TerminatorThis 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.

PostMsgWait2s 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.
Tone Recognition Settings Not Needed Some of the configuration settings used for sending numeric pages via the Engines 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.

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

Chapter 8: Configuring for Paging Notification | 101

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 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
Note the type, 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.

102 | TelAlert 6e Administrator Guide - Version 6.1.29

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 settings would be able to use only the external modem.

Model=Modem

Chapter 8: Configuring for Paging Notification | 103

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. 2. 3. A name that uniquely identifies it within the context of TelAlert. A reference to an existing [Configurations] definition. 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 destinationrelated 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"

104 | TelAlert 6e Administrator Guide - Version 6.1.29

Unless you attach a menu of responses to the messages you send, you cannot take advantage of the mediums 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.

Chapter 8: Configuring for Paging Notification | 105

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 TelAlerts notification feature. For more information, refer to Enabling Notifications below.

106 | TelAlert 6e Administrator Guide - Version 6.1.29

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 TelAlerts 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 TelAlerts 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 informationinformation in addition to the information implied by an -ack, -nak, -hold, or -release. Customized responses become considerably more powerful when used in conjunction with TelAlerts notification feature, which allows the text of a response to be passed to an external targeta log file or TelAlerts controlling application, for example. This makes it much easier to track the information returned with a response. It also greatly extends the users 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 applicationsmany 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.

Chapter 8: Configuring for Paging Notification | 107

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 messagealso called a requestthat is not a response to any page. The person or program dialing in to the paging providers 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 messagesi.e., requestsretrieved 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 command line:

-request command option to submit simulated requests to TelAlert at the

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] sections NotificationRequest keyword will be used to process this command.

108 | TelAlert 6e Administrator Guide - Version 6.1.29

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 providers 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.
Chapter 8: Configuring for Paging Notification | 109

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.

110 | TelAlert 6e Administrator Guide - Version 6.1.29

[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 Souths 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.

Chapter 8: Configuring for Paging Notification | 111

[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., nonInternet-based) two-way polling. [Notifications] Definition As discussed under Setting Up Two-Way Paging, response functionality can be significantly expanded using TelAlerts 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.

112 | TelAlert 6e Administrator Guide - Version 6.1.29

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 recipients PIN and the providers domain, for instance, 1234567@pagingprovider.com. To set up TelAlert to use this method, use the To keyword in a [Configurations] definition of Type=TextPager to define the providers 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=alert@mailserver.com 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 configurations 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.

Chapter 8: Configuring for Paging Notification | 113

8.9 Adding ID Numbers to Pages


It is often useful to add TelAlerts internal tracking numbers to pager messages. (For an overview of TelAlerts 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 substitution parameter at the command line. For example:

${SendID}

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. TelAlerts 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

114 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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 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
When you set pager. 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 stillunsent messages are normally cleared, producing a gap in track ID sequence at the destinations to which they would have been sent.

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

Chapter 8: Configuring for Paging Notification | 115

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


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.

Voice is the second most commonly used notification medium supported by TelAlert. If you plan to use TelAlerts 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.

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 serverss 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

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 organizations 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].

120 | TelAlert 6e Administrator Guide - Version 6.1.29

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 signboards [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 signboards [Port] definition). This option is popular among callcenter 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 computers 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

Chapter 10: Configuring for Other Notification Media | 121

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

122 | TelAlert 6e Administrator Guide - Version 6.1.29

A signboard connected to a terminal server has no keyword values:

dev= value. Instead, it includes the following

{SignboardPort} NetDevice=True DeviceHost=192.168.168.140 DeviceService=3001


ModelThis 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. TypesNot relevant to signboards. Where

Model=Device, Types must also be Device. 1 if you want False.

DeviceSubtypeSet to 2 if you want TelAlert to control message display; set to TelAlert to let another application control message display.

SoftwareParity Not relevant to signboards. Leave blank or set at default value of DevThe name of the physical port to which the signboard is connected. SpeedFor signboards, must be set to

9600.

AlphaAddressesA 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.) NetDeviceSet to its default value of computer running telalerte. Set to

False if the signboard is connected to serial port of the True if the signboard is connected to a terminal server.

DeviceHostThe IP address or network name of the terminal server to which the signboard is connected. DeviceServiceThe 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
Chapter 10: Configuring for Other Notification Media | 123

TextFilesEmptyMessage=\x1B b \x1C1\x13
TypeWith signboards, always set

Type=Device (to match the setting in the [Port] definition).

DeviceSubtypeMust be set to match the setting in the [Port] definition. ParityFor signboards, must be set to

Even.

MailboxThis 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 signboards 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


TerminatorNot relevant to signboards. Leave blank. ServiceMaxMessageLengthNot relevant to signboards. Leave blank or set at default value of 960. MaxTextFilesThe maximum number of messages you want the signboard to be able to hold and cycle among. (This keyword is ignored when DeviceSubtype=1.) TextFilesFIFOFirst 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.) TextFilesFIFOMinDisplayTimeWhen TextFilesFIFO=True, the minimum amount of time TelAlert will display a message on the signboard. (This keyword is ignored when DeviceSubtype=1.) FailWaitControls 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. TextFilesEmptyMessageControls 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.)

124 | TelAlert 6e Administrator Guide - Version 6.1.29

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


ConfigurationThis keyword simply points to the [Configurations] definition you want TelAlert to use when processing alerts directed to this signboard. MailboxSet the signboards 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 signboards [Destinations] definition, or at the command line with -mi. The control strings format is: \x1B0[mode]\x1C[color]

Chapter 10: Configuring for Other Notification Media | 125

To create a usable signboard control string, replace [mode] and [color] with codes from the following table: mode code a b c e f g h i j k l m p q r s effect slow continuous scroll right to left no motion flash scroll up scroll down scroll right to center scroll left to center wipe up wipe down wipe left wipe right scroll up with pauses split message and scroll in from sides split message and scroll out from center split message and wipe in from sides split message and wipe out from center color code 1 2 3 color red gree n ambe r

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 ...

126 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Chapter 10: Configuring for Other Notification Media | 127

10.5

Alternative Signboard Setup (DeviceSubtype=1)

The previous section focused on installations in which TelAlert controls signboard message display. In this section, well 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 TelAlerts control of signboard message display and are ignored when DeviceSubtype=1.) Note that when

128 | TelAlert 6e Administrator Guide - Version 6.1.29

DeviceSubtype=2, TelAlert will not give you an error message if you provide the wrong Mailbox value.
After youve 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 signboards 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 signboards 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 TelAlerts [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)

Chapter 10: Configuring for Other Notification Media | 129

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 TelAlerts [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 strings 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

130 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 10: Configuring for Other Notification Media | 131

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"

132 | TelAlert 6e Administrator Guide - Version 6.1.29

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 persons 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 emailbased. For instructions on using Readmail, refer to the end of this section.

Chapter 10: Configuring for Other Notification Media | 133

10.6.1 Email [Port] Definition


Under [Port], be sure that there is an {Internet} entry, that one of the values listed for Types is Email. For example:

Activeis set to True, and that

[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=telalert@domain.com


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 telalert@domain.com 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.

134 | TelAlert 6e Administrator Guide - Version 6.1.29

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 persons complete email address:

[Destinations] ... {CynthiaEmail} FullName=Cynthia Jasper Configuration=Email To=cynthia@domain.com


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 persons pager (for instance) to go also to this persons 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.

Chapter 10: Configuring for Other Notification Media | 135

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 Readmails 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
ActiveDetermines whether the definition is active. You must set this to

True to use Readmail.

ShellThe shell to which TelAlert should pass the specified Command value. The value should be a fully qualified reference, as the users 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. CommandThe 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).

136 | TelAlert 6e Administrator Guide - Version 6.1.29

Readmail 1.13, build 20021014 or later, includes an used in conjunction with -response. Without

-ignore command line option that is to be

-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, StopThese 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 parameters on the readmail command line:

-file and -back

[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 ...

Chapter 10: Configuring for Other Notification Media | 137

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: %m: %d: %H: %M:

4-digit 2-digit 2-digit 2-dight 2-digit

year month (01-12) day of month hour, 24 hour clock 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 its 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).

138 | TelAlert 6e Administrator Guide - Version 6.1.29

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 messages 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 TelAlerts configured maximum message length) will be used as the message text. After processing such a message, Readmail deletes it. Acting on Outstanding SendsReadmail 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 MessagesReadmail 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 RequestsReadmail 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 emails 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.

Chapter 10: Configuring for Other Notification Media | 139

10.7

Setting Up SpectraLink LCD Notification

SpectraLinks 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) Gatewaya modem-like boxto 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 gateways [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

140 | TelAlert 6e Administrator Guide - Version 6.1.29

10.7.3 SpectraLink LCD [Destinations] Definitions


The [Destinations] definitions provide TelAlert with the mailbox addresses of the handsets LCD displays. A handsets 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 handsets 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 notifications 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}

Chapter 10: Configuring for Other Notification Media | 141

Here,

Command specifies:
the path to the Windows Media Player additional instructions for this applicationso 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 notifications 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, TelAlerts 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 destinationthus providing the help desk coordinator with an audible update of the alerts 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.

142 | TelAlert 6e Administrator Guide - Version 6.1.29

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 "Heres a popup" telalertc -i GeorgeWinpop -m "Heres 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 and later, Type=TextPager is required instead.

Protocol=WINPOP; in 5.1

Chapter 10: Configuring for Other Notification Media | 143

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 protocoli.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.

144 | TelAlert 6e Administrator Guide - Version 6.1.29

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 clienttypically, 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/cgibin/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 recipients browser. The ReplyTo value is the URL to which the recipients 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 telephones 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 clients interactions with microbrowsers, and with browsers of all kinds, refer to Setting up the TelAlert Web Clients in Chapter 17.

Chapter 10: Configuring for Other Notification Media | 145

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 Nextels 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 From=telalert@yourcompany.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 twoway 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.

146 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 10: Configuring for Other Notification Media | 147

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. 2. 3. A [Port] definition of Model=DirectModem A [Configuration] definition of Type=TextPager, Protocol=Chat 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.

148 | TelAlert 6e Administrator Guide - Version 6.1.29

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 shouldnt 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.

Chapter 10: Configuring for Other Notification Media | 149

10.14.4 Samples for Both Techniques

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 customers values, such as

Dev=<<dev>>
will not import as-is. There are two choices: 1. 2. Edit these lines before copying to the clipboard. The import function will give errors for lines that cant be imported; make a note of these lines and set the appropriate keyword values via the main TelAdmin panel.

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 150 | TelAlert 6e Administrator Guide - Version 6.1.29

#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 modems 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

Chapter 10: Configuring for Other Notification Media | 151

-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 definitions.

Speed= value in one of your [Port] section

-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} 152 | TelAlert 6e Administrator Guide - Version 6.1.29

#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 # wont 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 isnt any O in Reply2=Nak NumReplies=4 Acked=1 AckedHold=3 NotAcked=2 Released=4 Reply1=Ack Reply2=Nak Reply3=Hold Reply4=Release

Chapter 10: Configuring for Other Notification Media | 153

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 Type=Fax. The The

Model=FaxModem and

FaxFSI keyword has been added to the [Configuration] section. 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 Identifier) to the remote fax machine.

-subject will be sent as the TTI (Transmitting Terminal

154 | TelAlert 6e Administrator Guide - Version 6.1.29

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 files 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 telalertes 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. 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.

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

Chapter 10: Configuring for Other Notification Media | 155

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 arent 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 programs output directly, without first having to write the message to a file and then send the files 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.

156 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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.

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.

Chapter 10: Configuring for Other Notification Media | 157

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 customers 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

158 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Note: For Service=http, TelAlert looks up http in the servers 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. The following describes the differences in TelAlerts processing when using one or the other of the above configurations: Non-Proxy access: 1. 2. Connect to wctp.arch.com:http Send "POST /wctp HTTP/1.1"

Proxy access: 1. 2. Connect to 10.11.10.99:8085 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 - its not necessary to blank out the HTTPProxyHost/Service values, or remove those keywords.

Chapter 10: Configuring for Other Notification Media | 159

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 destinations 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.

11.3

A Simple Filter

11.3.1 The Scenario


David is the sole support technician for a small company. For simplicitys sake, the companys 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

162 | TelAlert 6e Administrator Guide - Version 6.1.29

The relevant line in the [Destinations] definition is the values in the [Filter] definition is as follows: ActiveSet to

Filter=DavidFilter. The significance of

True, this makes the [Filter] definition available for use by TelAlert.

RequiresFullMatchSet 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. ExclusiveThis 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 includei.e., will deem valida matching destination while excluding all non-matching destinations. When this is set to True, TelAlert will excludei.e., will not send toa matching destination while sending to all non-matching destinations. TagsThe 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 lineserver, 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] definitions 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] definitions 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

Chapter 11: Applying Filtering Techniques | 163

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] definitions 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] definitions 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}.

164 | TelAlert 6e Administrator Guide - Version 6.1.29

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 unique effect and thus serves a relatively specific purpose.

Exclusive provides a

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 Web, Mail, and Internet

include three tags in your [Filter] definition:

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)

Chapter 11: Applying Filtering Techniques | 165

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 serversnot routers, and not Windows servers. To accomplish this, you would: use the

True-False combination Down, Server, and UNIX

include three tags in your [Filter] definition:

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 Workstation, HP, and UNIX

include three tags in your [Filter] definition:

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 destinations are used.

True, matching destinations are discarded and non-matching

166 | TelAlert 6e Administrator Guide - Version 6.1.29

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)

Chapter 11: Applying Filtering Techniques | 167

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.

168 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 11: Applying Filtering Techniques | 169

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 groups [Filter] definition, TelAlert finds that the group is valid, it evaluates the subgroups [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 destinationi.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}
170 | TelAlert 6e Administrator Guide - Version 6.1.29

... 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 messages 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 covered in Chapter 12: Setting Up and Applying Schedules.

priority) is

Chapter 11: Applying Filtering Techniques | 171

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 Davids 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 rangee.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.

172 | TelAlert 6e Administrator Guide - Version 6.1.29

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 messages 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.

Chapter 11: Applying Filtering Techniques | 173

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.

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

174 | TelAlert 6e Administrator Guide - Version 6.1.29

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).

Chapter 11: Applying Filtering Techniques | 175

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 commands -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 applications name for the device, and you will use the controlling applications device-name variable to plug the name into the commands it sends TelAlert. The [Limits] sections 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.)

176 | TelAlert 6e Administrator Guide - Version 6.1.29

11.8.1 Suppressing Orphan Up Messages


When you use the -filterschedule option, after a devices 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 devices 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"

Chapter 11: Applying Filtering Techniques | 177

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 matching messages.

telalert.alert, causing TelAlert to begin discarding

telalert -delete -source NetworkMonitor


This deletes the -source string from matching messages.

telalert.alert, causing TelAlert to stop discarding

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.

178 | TelAlert 6e Administrator Guide - Version 6.1.29

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.4s 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 option provides much more flexibility:

-checkpe

telalert -i foo -m foo -checkpe mdefault "printer.*down"


This command checks for messages that contain the string characters followed by the string down.

printer followed by zero or more

Chapter 11: Applying Filtering Techniques | 179

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, its 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 more characters, sky, 0 or more characters".

".*Sky.*", meaning "0 or

To use this to show active sends to SkyTel (assuming that all SkyTel Configurations names contain "Sky"), use:

telalert -show -selectpattern confsky

180 | TelAlert 6e Administrator Guide - Version 6.1.29

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"

Chapter 11: Applying Filtering Techniques | 181

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 destinationconditions 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 destinationtimes determined by the associated schedule and optionallythe 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 schedules hours for messages of a certain degree of importance; you can also ensure that extremely urgent messages are sent, without regard for any schedule.

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.

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 owners devices. Other users 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.

184 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users 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.

Chapter 12: Setting Up and Applying Schedules | 185

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 Users 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.

186 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Users 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 systems default setting of 24x7, always on duty is explicitly applied.

Figure 26. Edit Device Schedule page allows user to assign a default device schedule.

Chapter 12: Setting Up and Applying Schedules | 187

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--Johns phone-during certain hours and to a different device--Johns 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 devices 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.

188 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users 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.

Chapter 12: Setting Up and Applying Schedules | 189

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. 7. To create a new device schedule select the Add a New Schedule button. 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. Indicate the Repeat Pattern and On Duty Hours Pattern and select the Next button.

9.

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.

190 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users 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 members 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 members date should be switched to reflect as on duty and the start dates can be readjusted upon the missing members return.

Figure 27. The Manage Schedule page allows supervisors and administrators to view existing schedules.

Chapter 12: Setting Up and Applying Schedules | 191

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 Users 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 members schedule. If a group member schedule is not assigned, the device schedule will determine the group members 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.

192 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 12: Setting Up and Applying Schedules | 193

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 members 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 Filtering Techniques.

[Filter] definitions, refer to Chapter 10: Applying

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.

194 | TelAlert 6e Administrator Guide - Version 6.1.29

12.5.5 Schedules and Message Priority


The keyword discussed hereOverrideSchedulePriorityis 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 messages 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.

Chapter 12: Setting Up and Applying Schedules | 195

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 alla 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 TelAlerts 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 destinations validity in light of the messages 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.

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 users 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.

198 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Users 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.

Chapter 13: Representing Users | 199

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 users 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.

200 | TelAlert 6e Administrator Guide - Version 6.1.29

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. Lets 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.

Chapter 13: Representing Users | 201

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.

202 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 13: Representing Users | 203

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.

204 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 13: Representing Users | 205

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.

206 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users role--staff, supervisor, or administrator? What is the users 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.

Chapter 13: Representing Users | 207

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.

208 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 13: Representing Users | 209

Field Active

Description 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 users devices can be added to a group, but the users 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.

210 | TelAlert 6e Administrator Guide - Version 6.1.29

2.

Click the icon next to the user record in the Manage Users list.

3. 4.

On the Edit User page, modify the Active field. Click the Save button.

Chapter 13: Representing Users | 211

To modify an existing users information, do the following: 1. 2. Click the User tab. The Manage Users page appears. Click the Edit User icon next to the user record in the Manage Users list. The Edit User Details page appears. Edit the necessary fields, and then click. For help completing the fields, see Table 18: User Fields. Note: Changing a users 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 users information.

3.

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. 5. Click the User tab. The Manage Users page appears. Click the Remove User icon next to the name of the user you want to delete.

212 | TelAlert 6e Administrator Guide - Version 6.1.29

13.5

Creating a [User] definition: Essentials


telalert.sects file

It common to set all passwords to be encrypted before being written to the by setting EncryptPasswords=True.

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 touchtone telephone keypad, TelAlert will issue a warning.

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

Chapter 13: Representing Users | 213

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
214 | TelAlert 6e Administrator Guide - Version 6.1.29

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 TelAlerts 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 TelAlerts 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 control TelAlerts dial-in/dial-out behavior for that user: Active DialInMaxMessages DialInMenuAccess DialOutMaxMessages DialOutMenuAccess Menu ModemDialbackAreaCode ModemDialbackConfiguration ModemDialbackNumber Password VoiceDialbackAreaCode VoiceDialbackConfiguration VoiceDialbackNumber

[User] definition in order to

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:

Chapter 13: Representing Users | 215

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 issue this command: telalertc -list users -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:

[User] definitions. To do this,

telalertc -list sectionname


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. If ListDisplay is set to False, however, neither a [User] definitions name nor its FullName value will be displayed when you tell TelAlert to list all users. The default for this value is True. 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.

2.

3.

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.

216 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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. 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. 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.

4.

5.

218 | TelAlert 6e Administrator Guide - Version 6.1.29

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 configurations 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). Click the Save button 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.

8. 9.

10. To define additional device parameters, select the Edit this device link and click on the tab.

Chapter 14: Representing Devices | 219

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 selfdocumenting. The device name can be up to 20 characters long. 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. 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. 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.

Owner

Device Type/ Configuration

Comments/Description

Table 9. Common fields in the Devices form

Field

Input/Select

To

Enter the SMTP e-mail address of the device (mailbox). The email address must be valid or an error message will be 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. 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.

ReplyTo

Subject

Table 10. Email options in the Devices form

220 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Number

Enter the area code up to 6 digits. 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 This is used to hide the device when manually sending alerts. The device will still be visible to external systems. Recipients Page

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

Chapter 14: Representing Devices | 221

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 systems default setting of 24x7, always on duty applies.

222 | TelAlert 6e Administrator Guide - Version 6.1.29

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--Johns phone-during certain hours and to a different device--Johns 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 devices 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.

Chapter 14: Representing Devices | 223

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 users 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.

224 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 2. To create a new device schedule select the Add a New Schedule button. 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. Indicate the Repeat Pattern and On Duty Hours Pattern and select the Next button. Enter the times and days of the week that the device will be on duty and available to receive alerts.

4. 5.

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.

Chapter 14: Representing Devices | 225

14.3.2 Removing Your Devices


To remove your devices, do the following: 1. 2. Click the Devices tab. In the list of devices, click the icon to the left of each device you want to remove.

Removing a users 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, c l ic k O K to delete the device, or click Cancel if you do not want to delete the device.

226 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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


[Response]. These are ready for

TelAlert ships with two sets of pre-defined responses under 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. .

228 | TelAlert 6e Administrator Guide - Version 6.1.29

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"
Chapter 15: Enabling Responses | 229

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 TelAlerts [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 defined as InteractiveTextPager.

Type is

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 TelAlerts 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.

230 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Chapter 15: Enabling Responses | 231

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 pings 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.

232 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 15: Enabling Responses | 233

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.

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. In the Name field, enter a name for the group. The group name cannot exceed 20 characters and cannot include special characters. In the Comments/Description text box, enter a brief description of the group (by function, department, or other logical component of your organization). In the Public section, select Yes if you want to allow users to be able to add and remove themselves from the group. 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.

4.

5.

6.

7.

236 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 4.

Modify the Active field. Click the Save button.

Chapter 16: Broadcasting to Groups and Creating Escalations | 237

16.2.4 Modifying a Group


To modify an existing groups information, do the following: 1. 2. Click the Groups tab. The Manage Groups page displays. Click the Edit Group icon next to the group record in the Manage Groups list. The Edit Group page appears. Use the tabs--Details, Members, Escalation, Schedule, and Advanced--to make your changes.

3.

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.

238 | TelAlert 6e Administrator Guide - Version 6.1.29

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: dropdown menu. The Add Members window displays the first ten of all eligible devices, users or groups. Select the entries you want to add to the group by selecting the checkbox next to each recipient.

6. 7.

Chapter 16: Broadcasting to Groups and Creating Escalations | 239

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. 2. Click the Groups tab. The Manage Groups page displays. 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. Click the Schedule tab. The Edit Group Schedules page displays.

3.

240 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users device schedules. To see the group members default schedule, select the Override the Default Schedule radio button. The name of the default schedule will appear in the Schedule drop-down menu.

Chapter 16: Broadcasting to Groups and Creating Escalations | 241

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. 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.

7.

8.

In the Regular Schedule section, enter a schedule Start Date. This date should be todays 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 todays 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 groups status or the group members status to inactive (dont forget to change it back to active later). If you change the groups 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.

242 | TelAlert 6e Administrator Guide - Version 6.1.29

Note: Since Weekly schedules start on a Sunday, the date you enter will be changed to the prior Sunday if necessary. If the schedules 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.

Chapter 16: Broadcasting to Groups and Creating Escalations | 243

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.

244 | TelAlert 6e Administrator Guide - Version 6.1.29

16.3.2 Removing Group Members


1. 2. Click the Groups tab. The Manage Groups page displays. Choose the group you want to manage by selecting the Edit Group icon to the left of the group name. Select the Members tab. This shows the current membership. Select the members you want to remove by checking the boxes and clicking the Remove Selected button.

3. 4.

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. 6. Click the Groups tab. The Manage Groups page displays. Choose the group you want to manage by selecting the Edit Group icon to the left of the group name. Select the Members tab. This shows the current membership. 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.

7. 8.

Chapter 16: Broadcasting to Groups and Creating Escalations | 245

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 groupbut ultimately TelAlert must be able to resolve these references in terms of actual destinations. 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.

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 strategys 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.

246 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Chapter 16: Broadcasting to Groups and Creating Escalations | 247

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 syntax, it's the strategy in the "group_name" definition that is in effect.

-g "group_name"

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.

248 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Sequential

Description 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. 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. In this strategy, the alert is sent to every member of the group simultaneously.

Rotate First Member (Round Robin)

Broadcast

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

Chapter 16: Broadcasting to Groups and Creating Escalations | 249

With this group and this so

[Strategy] definition in place, a message directed to the group, like

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, theres 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 group contains an Escalate value.

[Strategy] definition invoked by the

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.

250 | TelAlert 6e Administrator Guide - Version 6.1.29

ackwait The key to escalation is the -ackwait numberm/h parameter used at the command lineor, 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.

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

Chapter 16: Broadcasting to Groups and Creating Escalations | 251

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.)

Ackedsends that have been successfully sent and acknowledged by the receiver NotAckedsends that have been negatively acknowledged Sentsends that have been successfully sent to their destination Failedsends 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)

Clearedsends that have been cleared using the -clear option on the command line Incompletesends 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

OffDutysends 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 numerical value assigned to it represents a number of minutes.)

Escalate value. (The

Timethe 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.

252 | TelAlert 6e Administrator Guide - Version 6.1.29

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 subgroups destinations were included directly in the supergroup. For instance, a group containing this

Destinations setting

Destinations=SG1,SG2,SG3

Chapter 16: Broadcasting to Groups and Creating Escalations | 253

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 SubgroupEscalation is set to Truein {Group1}, a message directed to {SupportGroup} would be handled as follows:
Because 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

254 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Subgroup

EscalationApplicable 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.

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 contactedfrom 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.

Chapter 16: Broadcasting to Groups and Creating Escalations | 255

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.

256 | TelAlert 6e Administrator Guide - Version 6.1.29

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 systems 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 scriptif 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.

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)

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 TelAlerts event-handling capabilities are limited by only the work you are willing to invest to devise a script that does what you want.

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 TelAlerts logs rolls over to a new file.

258 | TelAlert 6e Administrator Guide - Version 6.1.29

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 eventhandling 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). 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.

2.

[Analog], [Battery], [Configuration], [Destinations], [Group], [Limits], [Port], [Power], [Relay], [Sensor], or [User] definition(s) you want to trigger the
Associate the [Notification] definition with 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 259

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 TelAlerts 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 traps 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


TelAlerts MIB data is automatically loaded into HP OpenView IT/Operations during TelAlert installation. For instructions on changing the traps 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.

260 | TelAlert 6e Administrator Guide - Version 6.1.29

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 TelAlerts 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 keywords 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 261

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 events 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.
when the

${FIFOFileName} The name of the pipe that the program should read from (used only FIFOFileName keyword specifies the name of this pipe). c:\WINNT), or,

${SystemRoot} The directory in which Windows is installed (typically on UNIX, the root directory (/).
translated into forward slashes.

${SystemRootFS} The same as ${SystemRoot}, but with any backslash characters ${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 translated into forward slashes. ${TelAlertTmp}, but with any backslash characters

262 | TelAlert 6e Administrator Guide - Version 6.1.29

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 multiple commands.

[Notification] definition may refer to a script that performs

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 TelAlerts 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 TelAlerts 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 keywordreferring 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

Chapter 19: Getting Familiar with the TelAlert Monitor | 263

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 TelAlertreplies 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 requesta 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 request processing:

[Configuration] and [Notification] definitions set up for

[Configuration] ... {SkyTelITwoWayTextPager} Type=InteractiveTextPager NoneParity=True


264 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 265

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.

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.

AlertDelayedThe event TelAlert recognizes when an alert is delayed by virtue of a -delay value on the command line. AlertStartedThe event TelAlert recognizes when an alert is started (i.e., when TelAlert receives the command to create the alert and begins processing it). AlertErrorThe 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). AlertNotSupportedThe 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).

AlertOffDutyThe event TelAlert recognizes when an alert cannot be processed


because none of the specified destinations are on duty.

AlertFilterThe event TelAlert recognizes when an alert cannot be processed because every specified destination is filtered according to the terms of a [Filter] definition. AlertClearedThe event TelAlert recognizes when an alert is cleared (i.e., when all remaining processing is stopped by a -clearalert, -cleargroup, -clearall, or -clear command). AlertCompletedThe event TelAlert recognizes when an alert completes by virtue of all
processing having been finished without being cleared.

266 | TelAlert 6e Administrator Guide - Version 6.1.29

AlertReleasedThe 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. AlertCheckThe event TelAlert recognizes when an -insert -check is performed. StartedThe event TelAlert recognizes when a send is started. ErrorThe event TelAlert recognizes when an error occurs in the processing of a send. ErrorLimitThe event TelAlert recognizes when a send reaches a limit defined by DialErrorLimit and DialErrorWindow, or by ConnectErrorLimit and ConnectErrorWindow. NotSupportedThe 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). OffDutyThe event TelAlert recognizes when a send cannot be processed because the
intended destination is not on duty.

FilterThe event TelAlert recognizes when a send cannot be processed because the specified destination is filtered according to the terms of a [Filter] definition. ChangeThe 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).

ReplyChangeThe event TelAlert recognizes when an error occurs in the retrieval of a reply or request. ReplyThe event TelAlert recognizes when a reply is received. BadPasswordThe event TelAlert recognizes when a recipient is prompted for a
password and provides an incorrect one.

or

AcknowledgedThe event TelAlert recognizes when a send is acknowledged using ack -ackall. AcknowledgedHeldThe event TelAlert recognizes when a send is acknowledged and -hold. NotAcknowledgedThe event TelAlert recognizes when a send is negatively acknowledged using nak or -nakall. ClearedThe event TelAlert recognizes when a send is cleared using -clear, -clearall, -clearalert, or -cleargroup. CompletedThe event TelAlert recognizes when a send completes by virtue of all
processing having been finished without being cleared.

held using

ReleasedThe event TelAlert recognizes when a send is released from a held state using -release, -releaseall, or -releasealert.
Chapter 19: Getting Familiar with the TelAlert Monitor | 267

ConnectThe event TelAlert recognizes when a step associated with answering or ending
an inbound call occurs.

SecurityAll 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.

WarningThe event TelAlert recognizes when it sends a message that would have failed had AllowUnsupportedTypeSends been set to False.
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 alertsas 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.

ActivationThe event TelAlert recognizes when a definition is activated or deactivated. EngineThe event TelAlert recognizes when a TelAlert Engine reports a change in its
status.

AnalogThe event TelAlert recognizes when a change in the status of an analog device is
reported.

SensorThe event TelAlert recognizes when a change in the status of a sensor device is
reported.

RelayThe event TelAlert recognizes when a change in the status of a relay device is reported. PowerThe event TelAlert recognizes when a change in the power level of the TelAlert
Engine is reported.

BatteryThe event TelAlert recognizes when a change in the status of the TelAlert
Engine battery is reported.

TalkThe event TelAlert recognizes when a talkload is performed. RequestThe event TelAlert recognizes when a request is received.

268 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 269

${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.

270 | TelAlert 6e Administrator Guide - Version 6.1.29

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 events 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
[Heartbeat]

In the above example, you see all four of the event keywords permitted in the section:

StartThe event TelAlert recognizes upon the starting of any of the TelAlert processes. ExitThe event TelAlert recognizes upon the termination of any of the TelAlert
processes.

ErrorThe event TelAlert recognizes upon the occurrence of an error relating to any of
the TelAlert processes.

UpdateThe event TelAlert recognizes if it detects a TelAlert process is running at the


beginning of a new heartbeat interval.

Chapter 19: Getting Familiar with the TelAlert Monitor | 271

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 Section

[Heartbeat]

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 TelAlerts 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 first example, (that calls the notify.exe program) requires the FIFOFileName and EndOfData keywords. The two subsequent (for script invocation in UNIX and Windows) must have blank FIFOFileName and EndOfData that the values for examples values for

272 | TelAlert 6e Administrator Guide - Version 6.1.29

#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


Chapter 19: Getting Familiar with the TelAlert Monitor | 273

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 keywords 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


telainetde.log files.

The [File] section also handles rollover of the telaconfe.log and 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.inis [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 when TelAdmin is Used


Use the following [File] example to handle backups when using TelAdmin.

telalert.ini file Backups

telalert.sects and telalert.ini file

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.
274 | TelAlert 6e Administrator Guide - Version 6.1.29

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 files name. To disable backup, set NumIniSectsFileBackups to 0.

ReloadAfterSectsFileWritten, when set to True, causes TelAlert to automatically activate changes to telalert.sects whenever:
1. 2. 3. TelAdmin user executes a File / Save Data command;

telalert.sects is saved automatically (see WriteSectsFileInterval); or if WriteSectsFileAfterChanges is set to True,


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
The

[File] Functions

[File] section is also used to specify the NumVoiceFiles value, as follows:

NumVoiceFiles=8

17.8.4 Event Substitution Parameters Supported in the Section

[File]

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.
Chapter 19: Getting Familiar with the TelAlert Monitor | 275

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
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.

At any time, you can stop TelAlert using this command:

telalert stop

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 It will be in the same directory as the telelartc file.

telalert.init.d.

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 clients IP address must be entered in the servers 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: Cant 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.

278 | TelAlert 6e Administrator Guide - Version 6.1.29

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 servers 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 279

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. Double-click the System icon. Click the Environment tab. In the Variable field, type TELALERTHOST. In the Value field, type the hosts 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. Click Set, then click OK.

2. 3. 4.

5.

6.

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 ...

280 | TelAlert 6e Administrator Guide - Version 6.1.29

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 ...

Chapter 19: Getting Familiar with the TelAlert Monitor | 281

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 servers 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 servers 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.

282 | TelAlert 6e Administrator Guide - Version 6.1.29

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 recipients 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 the one you follow when editing telalert.ini.

telalerth.ini. The procedure is similar to

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 HDMLcompliant microbrowsers. The WML serves to specify attributes that should be presented to WMLcompliant microbrowsers. Anything preceding the first section marker applies equally to all browsers.

Chapter 19: Getting Familiar with the TelAlert Monitor | 283

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.

284 | TelAlert 6e Administrator Guide - Version 6.1.29

AckWait
Command-line -ackwait value. Default: 0m

AutoResetMessage
Y/N - Clear message text boxes after a send?
Default:

AutoResetOptions
Y/N - Clear Options screen values after a send?
Default:

AutoResetTargets
Y/N - Clear Destination/Group/Config values after a send?
Default:

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 Chapter 19: Getting Familiar with the TelAlert Monitor | 285

DestGroupOnly
Y/N - Prevent access to Configuration/User screen?
Default:

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 clients IP-address as -security option?
Default:

JavaScript
Script file name.
Default:

none

JavaSupport
Y/N - Support JavaScript functions?
Default:

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:

LockOptions
Y/N - prevent changes/access to Options screen?
Default:

LockPreferences
Y/N - prevent changes/access to Preferences screen?
Default:

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

286 | TelAlert 6e Administrator Guide - Version 6.1.29

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:

MsgSize
Number of rows in message box.
Default:

Priority
Command-line -priority value.
Default:

50

SecurityRequired
Require use of Preferences->Security field?
Default:

Service
Same as -service command-line option.
Default:

25378

StatusWithDate
Y/N - Include Start time in Status displays?
Default:

Verbose
Y/N - Display telalertc equivalent when commands executed?
Default:

Chapter 19: Getting Familiar with the TelAlert Monitor | 287

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.

ShowTable, ShowVTable, ShowDetailHTable, ShowDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows:


Values supported by

AltDial AltHost Calls Conf Dest Dial Group Host PIN Reply Send To Track Update User
Values supported by

Alternate phone number (-an) Alternate host/service (-ahs) e.g., "Connected 1/1, Failed 0/10, Rejected 0/1"

[Configurations] [Destinations]
Primary phone number (-n) Group ID Primary host/service (-hs)

-pin value
Last reply text Send ID -to value Track ID Update time -user value

ShowAlertTable, ShowAlertVTable, ShowAlertDetailHTable, ShowAlertDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows: Recipient Release
To whom was the alert sent? Alert-level release info

288 | TelAlert 6e Administrator Guide - Version 6.1.29

Values supported by all ten of the above keywords are as follows:

Alert Check Client Delay Hold IPCheck Masked Message NodeAddr Priority Remark ReplyTo Response Source Start State Subject ShowTable

Alert ID -check

value

IP address of message issuer -delay -hold

value

-ipcheck value
Masked ticket Message text -nodeaddr -priority -remark

value value

value value value

-replyto

-response -source Start time

value

Message state -subject

value

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

Chapter 19: Getting Familiar with the TelAlert Monitor | 289

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

290 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 1Splits text, causing each word to begin on a separate line. 2Center-aligns text. 4Left-aligns text. 8Right-aligns text. 128Bolds text. 256Italicizes text. 1024Prefixes each value with its name (i.e., Message=Hi there).

ShowWhat
Determines what buttons are shown on the main page; can be set to Show, Show Alert, Both, or None.
Default:

Both

18.6
The

Setting up Logging

[Files] section governs TelAlerts built-in logging behavior.

18.6.1 Default Log Files


By default, TelAlert maintains a variety of log files:

telalert.trailThis is a general record of TelAlert activity. telalerte.logThis 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.logthis is the log file for telaconfe, the TelaConf server.


Other process-specific log filesTelAlert 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 291

18.6.2 Setting Maximum Sizes


Four keywords used in the

[Files] section determine the maximum sizes of these files:

TrailMaxFileSizedetermines the maximum size of telalert.trail EventMaxFileSizedetermines the maximum size of telalerte.log ConfMaxFileSizedetermines the maximum size of telaconfe.log LogMaxFileSizedetermines 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.

292 | TelAlert 6e Administrator Guide - Version 6.1.29

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 like so:

[Heartbeat] sections can be activated or deactivated on the command line,

telalert telalert telalert telalert

-deactivate -files -activate -files -deactivate -heartbeat -activate -heartbeat Active keyword can be activated or deactivated on the

Likewise, any definition that supports an 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 293

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 Users 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. Once you have the XML file, log in again to the TelAlert Web UI. Go to Admin > Batch Tool .

2. 3.

294 | TelAlert 6e Administrator Guide - Version 6.1.29

4. 5. 6.

Click the Add New Import File button. Click the Browse button to locate your batch import file. 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. 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. Click the Process Records button to process the selected records. The status of the records changes to Processed. 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.

7.

8.

9.

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 295

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>llinden@calamp.com</To> </ta_properties> </record> 296 | TelAlert 6e Administrator Guide - Version 6.1.29

- <record> <name>LisaL_Device</name> <owner>LisaL_Super</owner> <typename>Email</typename> - <ta_properties> <Configuration>Email</Configuration> <To>llinden@calamp.com</To> </ta_properties> </record> - <record> <name>TonyB_Device</name> <owner>TonyB_Staff</owner> <typename>Email</typename> - <ta_properties> <Configuration>Email</Configuration> <To>llinden@calamp.com</To> </ta_properties> </record> - <record> <name>System2_Device</name> <owner>system</owner> <typename>Email</typename> - <ta_properties> <Configuration>Email</Configuration> <To>llinden@calamp.com</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>

Chapter 19: Getting Familiar with the TelAlert Monitor | 297

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> <TUE>

<MONDAY>

also supported

<TUESDAY> also supported

<WED> <WEDNESDAY> also supported <THU> <THURSDAY> also supported


also supported

<FRI> <FRIDAY> <SAT> <SUN>

<SATURDAY> also supported <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:0023: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).

298 | TelAlert 6e Administrator Guide - Version 6.1.29

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>johnsmith@somedomain.com</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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 299

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).

300 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 301

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. 2. Go to Admin > Manage Departments . The Manage Departments page appears. Click the Add a New Department button.

302 | TelAlert 6e Administrator Guide - Version 6.1.29

3. 4.

Enter a department name, and then click Sav e . 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. 6. Navigate to Admin > Manage Departments. The Manage Departments page appears. Click the Edit Department icon next to the name of the department that you would like to view. Click on the Users tab to view all users that belong to the department.

7.

Chapter 19: Getting Familiar with the TelAlert Monitor | 303

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. 2. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Edit Department icon next to the name of the department that you would like to edit. Click on the Users tab to view all users that belong to the department. See image of Department Users page above. 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.

3.

4.

304 | TelAlert 6e Administrator Guide - Version 6.1.29

Removing Users from Departments


To remove department members, do the following: 1. 2. 3. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Edit Department icon next to the name of the department that you would like to edit. Click on the Users tab to view all users that belong to the department. See image of Department Users page above. To remove a user from the department click on the name of the user in the Users in Department list and select the button. 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.

4.

5.

Adding Groups to Departments


To add group department members, do the following: 1. 2. 3. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Edit Department icon next to the name of the department that you would like to edit. Click on the Groups tab to view all groups belonging to the department.

Chapter 19: Getting Familiar with the TelAlert Monitor | 305

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. 7. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Edit Department icon next to the name of the department that you would like to edit. Click on the Groups tab to view all groups belonging to the department. See image above of the Department Groups page. 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.

8.

9.

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.

306 | TelAlert 6e Administrator Guide - Version 6.1.29

13. Edit the fields and click S ave .

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. 2. 3. 4. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Add a New Holiday button. Complete the required fields, and then click Save . The holiday is created for the date specified. 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. 6. 7. Navigate to Admin > Manage Departments . The Manage Departments page appears. Click the Edit Holiday icon next to the name of the holiday that you would like to edit. Edit the fields and click S ave .

Deleting Holidays
To delete a holiday, do the following:

Chapter 19: Getting Familiar with the TelAlert Monitor | 307

8. 9.

Navigate to Admin > Manage Departments . The Manage Departments page appears. 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

308 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 2. Obtain a valid SSL certificate from the LDAP server. Copy the certificate to the Java security folder on the TelAlert 6e Tomcat server (i.e. C:\ProgramFiles\TelAlert6e\web\jre\lib\security). Import the certificate into the Java certificate key store and follow the prompts on the screen:

3.

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. Restart the TelAlert 6e Tomcat server.

5.

18.8.7 User Role Configuration


Starting in TelAlert 6e v6.2.0, administrators can add customized user roles and modify the predefined roles. For a complete discussion of this process, see User Roles in Chapter 13.

Chapter 19: Getting Familiar with the TelAlert Monitor | 309

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.

310 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 2. 3. 4. Navigate to Admin > Log Viewer. Select the type of log you would like to view in the View Log drop-down menu. Select a value for the Number of Lines to Display Per Page field. Click on the Previous and Next buttons to navigate through the log file.

Chapter 19: Getting Familiar with the TelAlert Monitor | 311

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.

312 | TelAlert 6e Administrator Guide - Version 6.1.29

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 users 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 313

18.9

Additional Admin Tasks

18.9.1 Changing a Users Role


Only administrators can change the role of any user. To change the role of a user, do the following: 1. 2. 3. 4. 5. Click on the User's tab. The Manage Users page displays. In the list of users, find the user whose role you want to change. Click on the Edit User icon next to the user name. The Edit User page displays. In the Role field, select a role for the user. 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 alerts 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.

314 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 315

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

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 Desktops Host Properties (associated with the particular server).

318 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Desktops 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 Desktops host list. When additional host properties are created, the default registry values will be initialized when the Host properties are saved. 1. Launch TelAlert Desktops Host Properties dialog (select Host Properties from the Desktops Hosts menu). Select the Alert Monitor Tool tab on the Host Properties dialog. Verify that the NotifyServer Service value is set to ntfysrvr. Click the OK button on the Host Properties dialog (accept default values for other properties on the Alert Monitor Tool tab.

2. 3. 4.

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

Chapter 19: Getting Familiar with the TelAlert Monitor | 319

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

320 | TelAlert 6e Administrator Guide - Version 6.1.29

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

Chapter 19: Getting Familiar with the TelAlert Monitor | 321

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 Sends state information. The trees 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

322 | TelAlert 6e Administrator Guide - Version 6.1.29

19.5.2 Icons
This section describes the icons that appear in the AlertTree.

Node Type Icons


Scope (1 level) node when monitoring all events on a particular TelAlert Server Scope (1 level) node when monitoring selected Destinations Scope (1 level) node when monitoring selected Groups Alert (2 Alert (2 Alert (2
nd st st st

level) node when active level) node when not active level) node when information expired, pending deletion from memory and view
rd

nd

nd

Destination (3 level Send) node Email (3 level Send) node Speech/TTS (3 level Send) node
rd rd

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

Chapter 19: Getting Familiar with the TelAlert Monitor | 323

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

324 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

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

Chapter 19: Getting Familiar with the TelAlert Monitor | 325

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 Windows 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 buttons 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

326 | TelAlert 6e Administrator Guide - Version 6.1.29

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 Desktops 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 predefined 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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 327

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).

328 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 19: Getting Familiar with the TelAlert Monitor | 329

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 dialogs Recipients list.

330 | TelAlert 6e Administrator Guide - Version 6.1.29

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)

Chapter 19: Getting Familiar with the TelAlert Monitor | 331

20
Security Features
20.1 Overview
TelAlert is deployed in a wide variety of enterprise environmentsenvironments 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 chapters aim is to familiarize system administrators with TelAlerts security features, and to demonstrate the ways in which these features make TelAlert an exceptionally security-conscious application.

20.2

TelAlerts 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 usersmost 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 TelAlerts heightened securityconsciousness begins with a look at its architecture, which spans four main areas:

Architectural Area

Description The communications hub through which all traffic flows 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). TelAlerts administrative components. These components let an administrator control TelAlerts operation and configuration 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.

telalerte
TelAlert Media Controllers

TelaConf/TelAdmin TelAlert Clients

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 TelAlerts 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. 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.

2.

3.

telalerte communicates via a private protocol. For hackers to spoof network traffic,
they would require a full understanding of the TelAlert binary protocol. As with all TelAlert components, all connection set-ups between are logged.

4.

telalerte and clients

334 | TelAlert 6e Administrator Guide - Version 6.1.29

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. 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. 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.) 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. 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). 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.

2.

3.

4.

5.

6.

Chapter 20: Security Features | 335

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. 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.

8.

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. TelAlerts core processes thus always receive sanitized requests from clients, greatly reducing the risk of rogue clients accessing critical features of the core.

336 | TelAlert 6e Administrator Guide - Version 6.1.29

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 userprovided 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 Johns password in the Web UI as follows:

[User] {John} Password=Giants


typing:

telalert -read user John -hold


shows:

[User] {John} Password=#GeYg0xne


If Johns definition is changed, the compile step wont re-encrypt the password, as its 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 irrespective of the current [Limits] EncryptPasswords value.

.sects file,

As a general rule, passwords specified on the command-line or via Stored Authentication must be plain-text.

Chapter 20: Security Features | 337

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 machines 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 capabilities. Client connections are connections by

telalert, telalerths, and C/Java APIs with admin telalertc and C/Java APIs without admin capabilities. telalerth.

Web client connections are connections by

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]

338 | TelAlert 6e Administrator Guide - Version 6.1.29

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, Again, here is a partial command line:

-loginuser and -loginpassword.

-loginuser Joseph -loginpassword 1k2j345 AdminLoginsRequired is False, admin clients can use this command

Note, too, that where

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.

Chapter 20: Security Features | 339

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 eventmarked as [11]Security/Licenseis 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 dialin 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 thirdparty 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.

340 | TelAlert 6e Administrator Guide - Version 6.1.29

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.

Chapter 20: Security Features | 341

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.

342 | TelAlert 6e Administrator Guide - Version 6.1.29

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 nonSSL 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

Chapter 20: Security Features | 343

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. 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 To test

# DialBackup, simply give the -deactivate -process Stunnel command.

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.

344 | TelAlert 6e Administrator Guide - Version 6.1.29

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 import import import

java.lang.* tanotify.*; taNotObjects.*; 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); ) Thats 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 UserCloseStream UserPostFileEvent UserPostHeartBeatEvent UserPostNotificationEvent

This method must be rewritten to read from a stream This method must be rewritten to close a TCP stream Post file events to the legacy interface Post heartbeat events to the legacy interface Post notification events to the legacy interface

Chapter 20: Security Features | 345

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;

346 | TelAlert 6e Administrator Guide - Version 6.1.29

/** * 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 well just call the base method via super. If not defined * here, the base class methods would be used anyway. * subclass might used an attached database connection, * and use these routines to build and execute insert statements. */ Here a real

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);

Chapter 20: Security Features | 347

public boolean UserAppStart(String[] parm1) { /**@todo: Override this tanotify.User method*/ /** The username and password strings are defined by magic here. /** In real code, youd 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); }

*/

348 | TelAlert 6e Administrator Guide - Version 6.1.29

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 were 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 its 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; } Chapter 20: Security Features | 349

} /** * OVERRIDE : CloseStream * Close the stream opened by OpenStream */ public void CloseStream() {

try { activeSocket.close(); serverSocket.close(); } catch (IOException ioex) { ioex.printStackTrace(); } }

350 | TelAlert 6e Administrator Guide - Version 6.1.29

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, its notification interfaces, and JAVA programming.

21.2
1.
The

Enabling XML Output

TelAlert has two distinct circumstances in which it can produce XML output.

[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}

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="&lt;None&gt;" tanIPCheck="" tanNodeAddr="" tanRemark="" tanReplyTo="" tanSource="" tanSubject="" tanTicket="0" tanMaskedTicket="0" tanClientHost="integrationrd2.telamon.com" tanClientUser="Administrator" tanGroupFullName="&lt;None&gt;" 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 Vyteks 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.

352 | TelAlert 6e Administrator Guide - Version 6.1.29

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]"

Chapter 21: Integrating XML Output | 353

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.

354 | TelAlert 6e Administrator Guide - Version 6.1.29

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

TelAlerts 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 TelAlerts 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.)

Chapter 21: Integrating XML Output | 355

After a notify object, a single object event may follow. TelAlert supports three basic object types:

FileEvent NotificationEvent HeartBeatEvent

Events related to the file system and log files within the server Events indicating various actions inside TelAlert 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>

356 | TelAlert 6e Administrator Guide - Version 6.1.29

21.5

The Parser Toolkit

Given the above XML, some code must be written to perform the following tasks: 1. 2. 3. 4. Open an access port to the XML from some server using the appropriate communications media a socket, a file, a serial port, etc. Create a parser designed to parse that XML into usable objects For each object parsed, pass that object to a third-party interface 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 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. 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. 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.

SAXTools

SaxTools.java

TANotObjects

BasicNotification.java TANotifyFile.java TANotifyHeartBeat.java TANotifyNotification.java

TANotify

Application.java Shell.java User.java DBUser.java

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.

Chapter 21: Integrating XML Output | 357

21.6
On Event

The Event Matrix


In File
Shell

Call Method

Purpose
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 Startup

UserAppStart

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

SaxTools

UserUnknownAttribute

Unknown Elements in XML

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. This routine is called during parsing if invalid XML is found. It may correct or ignore the error, or shutdown the process completely.

Error in XML

Shell SaxTools

UserPostError

358 | TelAlert 6e Administrator Guide - Version 6.1.29

On Event
A FileEvent record has been posted

In File
SaxTools

Call Method

Purpose
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.

UserPostFileEvent

A HeartBeat record has been posted

SaxTools

UserPostHeartBeatEven t

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

UserPostNotificationE vent

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.

Chapter 21: Integrating XML Output | 359

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. 2. 3. Define a new User object, say DBUser which extends the User class. Override the various methods above with application-specific methods. 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. Activate the new object by calling the parsers SetUserObject routine, passing our object.

4.

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 Calling convention Purpose Returns User None The constructor can be used to set up the user objects data Nothing

Method Calling convention Purpose

OpenStream Reader OpenStream (String [] args) 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

360 | TelAlert 6e Administrator Guide - Version 6.1.29

Method Calling convention Purpose

CloseStream void CloseStream () CloseStream is called by the shell to close the input stream created by OpenStream.

Returns Method Calling convention Purpose

Nothing
UserAppStart boolean UserAppStart (String [] args) 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 true if startup was successful, false otherwise. If the method returns false, the shell will exit. UserAppStop boolean UserAppStop () UserAppStop is called by the shell just before shutdown. Returns trueif termination was successful, false otherwise. If the method returns false, the shell will exit.

Returns

Method Calling convention Purpose Returns

Method Calling convention Purpose

UserExit void UserExit () UserExit is called by the shell or parser code when an abort is needed rather than a graceful termination. Nothing

Returns

Chapter 21: Integrating XML Output | 361

Method Calling convention Purpose

UserTick boolean UserTick () 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 true if the shell is to continue on, falseif a shutdown is required.

Returns

Method Calling convention Purpose

UserPostError boolean UserPostError(Exception ex) 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 Calling convention Purpose

UserUnknownAttribute boolean UserUnknownAttribute(String elementName, String attrName) 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 Calling convention Purpose

UserPostFileEvent boolean UserPostFileEvent(taNotifyFile event) 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.

362 | TelAlert 6e Administrator Guide - Version 6.1.29

Method Calling convention Purpose

UserPostHeartBeatEvent boolean UserPostHeartBeatEvent(taNotifyHeartBeat event) 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 true on posting success, false if the shell should terminate.

Returns

Method Calling convention Purpose

UserPostNotificationEvent boolean UserPostNotificationEvent(taNotifyNotification event) 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 true on posting success, false if the shell should terminate.

Returns

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. 2. 3.

taNotifyFile-The object representing [File] events taNotifyHeartBeat-The object representing [HeartBeat] events 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.

Chapter 21: Integrating XML Output | 363

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 import import import

java.lang.* tanotify.*; taNotObjects.*; 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); ) Thats 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 UserCloseStream UserPostFileEvent UserPostHeartBeatEvent UserPostNotificationEvent This method must be rewritten to read from a stream This method must be rewritten to close a TCP stream Post file events to the legacy interface Post heartbeat events to the legacy interface Post notification events to the legacy interface

364 | 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; /** * 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 well 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) { Chapter 21: Integrating XML Output | 365

/**@todo: Override this tanotify.User method*/ /** The Administrator and password strings are defined by magic here. /** In real code, youd 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 were 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 its 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) { 366 | TelAlert 6e Administrator Guide - Version 6.1.29

*/

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(); } } }

Chapter 21: Integrating XML Output | 367