TelAlert UMS Administrator Guide

TelAlert UMS Administrator Guide Version 5.71

Copyrights Copyright 2005-2009, 2010 MIR3, Inc. TelAlert UMS 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: 5.71 07Sep2010 [20100907] Document Revision: 3.0 MIR3, Inc. 3398 Carmel Mountain Road San Diego, CA 92121 Phone: 858.724.1200 Fax: 858.724.1201 Email: support@mir3.com Web Site: http://www.mir3.com

Preface The TelAlert Version 5.71 Administrator Guide describes how to use the TelAlert software. It can run on all major platforms (Sun Solaris, Windows, HP-UX and Linux). The information in this document is accurate regardless of the platform used to support the TelAlert system. This Guide does not include instructions about how to install, configure or integrate the TelAlert system with third-party data sources.

Table of Contents Introduction.. 1 1.1 Overview 1 1.2 TelAlert Overview. 1 1.3 TelAlert Text to Speech (TTS) 3 1.3.1 Full Range of Voice Destinations.. 3 1.3.2 Customizable Vocabulary in Four Languages. 3 1.3.3 Interactive Voice Response (IVR). 3 1.3.4 Dialogic Telephony Card. 3 1.4 TelAlert Integrations. 4 1.4.1 TelAlert Integrations Make it Easy 4 1.4.2 Do-it-Yourself Integrations for In-House Applications.. 4 1.5 Supported Platforms. 5 1.5.1 Server and Client Platforms.. 5 1.5.2 Client Platforms 5 1.5.3 Operating Systems Not Supported for Version 5.71. 7 1.6 Guide Introduction 8 1.6.1 Contents 8 1.6.2 Audience 8 1.6.3 Related Technical Documentation 8 1.7 Product Support Contact Information 8 1.8 TelAlert Solutions from MIR3 8 1.9 Guide Conventions 9 1.9.1 Screen Captures 11 1.9.2 File Locations. 11 Technical Overview. 13 2.1 Overview 13 2.2 How TelAlert Works 13 2.2.1 A Typical Alert.. 14 2.3 TelAlert Programs and Processes 15 2.4 Key TelAlert Files 17 2.5 Key Configuration Concepts. 19 2.5.1 Sections, Definitions, Keywords, and Cross-Referencing.. 20 2.5.2 Configuration. 21 2.5.3 Destination. 21 2.5.4 User. 22 2.5.5 Group.. 22 2.5.6 Schedule. 23 2.5.7 Strategy. 23 2.5.8 Other Configuration File Sections.. 24

Implementation Planning. 27 3.1 Overview. 27 3.2 Your Accomplishments So Far. 27 3.3 Structure of the Administrator Guide. 28 3.3.1 Chapter 1: Introduction.. 28 3.3.2 Chapter 2: Technical Overview.. 28 3.3.3 Chapter 3: Implementation Planning 28 3.3.4 Chapter 4: Configuration Basics 28 3.3.5 Chapter 5: The Role of Ports in TelAlert.. 28 3.3.6 Chapter 6: Dialing the Telephone.. 28 3.3.7 Chapter 7: Configuring for Paging Notification 28 3.3.8 Chapter 8: Configuring for Text to Speech (TTS) Notification. 29 3.3.9 Chapter 9: Configuring for Other Notification Media.. 29 3.3.10 Chapter 10: Applying Filtering Techniques 29 3.3.11 Chapter 11: Setting Up and Applying Schedules.. 30 3.3.12 Chapter 12: Representing Users. 30 3.3.13 Chapter 13: Enabling Responses. 30 3.3.14 Chapter 14: Broadcasting to Groups and Creating Escalations. 30 3.3.15 Chapter 15: Processing Events 31 3.3.16 Chapter 16: Miscellaneous Administrative Tasks. 31 3.3.17 Chapter 17: Security Features. 31 3.3.18 Chapter 18: Integrating XML Output.. 31 3.4 The Alert Timeline.. 31 3.4.1 Send and Release. 31 3.4.2 Send, Wait, and Release. 32 3.4.3 Send, Wait, Hold, and Release.. 33 3.4.4 The Alert Timeline and Escalations 33 3.4.5 Summary 34 3.4.6 Organizational Scenarios. 34 3.4.7 Scenario One: Paging Only Small Organization 35 3.4.8 Scenario Two: Paging, Voice, and Email Small Organization. 40 3.4.9 Scenario Three: A Larger Organization. 43 Configuration Basics 47 4.1 Overview. 47 4.2 TelAlert Configuration Methods: telalert.ini; TADesktop 47 4.2.1 Choosing a Configuration Method.. 49 4.2.2 What Make TelAlert Re-Read its Configuration File Means. 50 4.3 Understanding Configuration Examples. 50 4.3.1 Singular vs. Plural Section Names. 52 4.4 Performing Common Configuration Tasks. 53 The Role of Ports in TelAlert 57 5.1 Overview. 57 5.2 What is a Port? 57 5.3 Basic Port Considerations. 58

5.4 If You Are Using a Terminal Server. 61 5.4.1 Testing Connectivity on a Terminal Server.. 62 5.5 More Advanced Port Considerations 62 5.5.1 Directing Specific Notifications to Specific Ports. 62 5.5.2 Providing Port Backup.. 64 5.5.3 Controlling Port Deactivation Due To Errors 65 5.5.4 What Remote Ports Are Used For.. 66 Dialing the Telephone. 69 6.1 Overview. 69 6.2 What s So Hard About Dialing the Phone?. 69 6.2.1 Local Dialing.. 70 6.2.2 Alternate Numbers 70 6.2.3 Inside and Outside Lines. 70 6.2.4 Special Dialing Scenarios 70 6.2.5 Dialing After the Main Number is Answered 70 6.2.6 Inserting Pauses During Dialing. 70 6.3 Dialing Logic 71 6.3.1 Dialing Components. 71 6.3.2 Dialing Process.. 72 6.4 Local Dialing 72 6.4.1 Normal Local Dialing 72 6.4.2 Ten-Digit Local Dialing. 73 6.4.3 Eleven-Digit Local Dialing 73 6.5 Long Distance Dialing 73 6.5.1 Normal Long Distance Dialing 73 6.5.2 Other Long Distance Dialing 74 6.5.3 Alternate Numbers 74 6.6 Inside and Outside Lines.. 75 6.6.1 Getting an Outside Line.. 75 6.6.2 Getting an Inside Line. 75 6.7 Special Dialing Scenarios.. 76 6.8 Dialing After the Main Number is Answered.. 76 6.8.1 Dialing a Number, Then an Extension.. 76 6.8.2 Dialing a Number, Then Accessing a Mailbox.. 77 6.9 Inserting Pauses During Dialing.. 77 6.10 Specifying Telephone Dialing Components at the Command Line. 78 6.11 Overriding the Need for Dialtone. 78 Configuring for Paging Notification.. 79 7.1 Overview. 79 7.2 Getting Started.. 79 7.2.1 Needed Information. 79 7.2.2 General Considerations 80 7.3 Setting Up Text Paging. 81 7.3.1 Creating a Text Pager [Configurations] Definition.. 81

7.3.2 Pointing to a Modem 82 7.3.3 Creating a Text Pager Destination. 83 7.3.4 Sending a Page by Invoking a Destination.. 83 7.3.5 Sending a Page Without Invoking a Destination. 84 7.3.6 Sending to Text Pagers via [Configurations] Definitions of Type=InteractiveTextPager.. 84 7.3.7 Sending Text Pages via Modem without TAP (Protocol=Chat). 85 7.4 Setting Up Numeric Paging.. 89 7.4.1 Sending Numeric Pages Using the TAP Protocol. 89 7.4.2 Sending Numeric Pages Without TAP 90 7.5 Setting Up Two-Way Paging. 93 7.5.1 Creating a Two-Way Pager [Configurations] Definition. 93 7.5.2 Pointing to a Modem 94 7.5.3 Creating Two-Way Pager Destinations. 95 7.5.4 Enabling Responses. 95 7.5.5 Enabling Polling. 98 7.5.6 Enabling Notifications.. 98 7.6 Setting Up Requests: Unsolicited Messages From Two-Way Pagers. 99 7.6.1 Receiving Requests.. 99 7.6.2 Having Requests Trigger [Notifications] Actions. 99 7.6.3 Simulating Requests for Testing Purposes.. 99 7.7 Setting Up Internet-Based Paging 100 7.7.1 One-Way Internet-Based Paging. 100 7.7.2 Two-Way Internet-Based Paging. 101 7.8 Initiating Pages via Email.. 104 7.8.1 Responses to Two-Way Email-Based Text Pages. 105 7.9 Adding ID Numbers to Pages 105 Configuring for Voice Notification.. 107 8.1 Overview.. 107 8.2 Configuration for Voice Notification now in TelAlert Voice and Hardware Guide 107 Configuring for Other Notification Media. 109 9.1 Overview.. 109 9.2 Getting Started 109 9.2.1 Needed Information.. 109 9.2.2 General Considerations. 111 9.3 Setting up Electronic Signboard Notification.. 112 9.3.1 Signboard Overview.. 112 9.3.2 Initial Signboard Firmware Setup 112 9.4 Standard Signboard Setup (DeviceSubtype=2). 112 9.4.1 TelAlert-Controlled Signboard Message Display 113 9.4.2 Signboard [Port] Definition.. 113 9.4.3 Signboard [Configurations] Definition 114 9.4.4 Signboard [Destinations] Definitions. 116 9.4.5 Sending Messages to the Signboard.. 116

9.4.6 Controlling Signboard Text Color and Effects 117 9.4.7 Configuring Multiple Signboards. 119 9.5 Alternative Signboard Setup (DeviceSubtype=1). 119 9.5.1 Signboard [Port] Definition when DeviceSubtype=1.. 120 9.5.2 Signboard [Configurations] Definition when DeviceSubtype=1. 120 9.5.3 Additional Signboard Firmware Setup when DeviceSubtype=1. 121 9.5.4 Signboard [Destinations] Definitions when DeviceSubtype=1.. 122 9.6 Setting up Email Notification. 125 9.6.1 Email [Port] Definition.. 126 9.6.2 Email [Configurations] Definition 126 9.6.3 Email [Destinations] Definition 127 9.6.4 Using Email as a Backup Notification Medium.. 127 9.6.5 Handling Responses to Email With Readmail 127 9.7 Setting up Command Line Notification 133 9.7.1 Command-Line [Configurations] Definition.. 133 9.7.2 Command-Line [Destinations] Definition.. 133 9.7.3 Applications for Command-Line Notification. 134 9.8 POPUP Message Boxes on Windows. 134 9.9 Sending Messages to Other Systems.. 135 9.9.1 UNIX Syslog Processes. 135 9.9.2 TelaConsole. 136 9.9.3 AS/400s.. 136 9.10 Sending Messages to Web-Enabled Phones 136 9.11 Sending Text Messages to Nextel Cellular Phones 138 9.12 Sending One-Way Text Messages to GSM Cellular Telephones.. 139 9.13 Sending Two-Way Text Messages to SMS Mobile Telephones Via a GSM Wireless Modem.. 140 9.13.1 Set-Up During Installation. 140 9.13.2 New Technique in TelAlert 5.4.. 140 9.13.3 Differences Between the Two Techniques.. 141 9.13.4 Samples for Both Techniques 142 9.14 Sending Messages to a DN400E Fax Modem.. 146 9.15 Sending a File or a Line from stdin as a Message. 147 9.15.1 Sending a File as a Message.. 147 9.15.2 Sending a Line from stdin as a Message. 148 9.16 SMPP.. 149 9.16.1 SMPP Confirmed Delivery Option.. 149 9.16.2 SMPP Sample Configuration.. 149 9.17 WCTP Proxy Configuration. 150 Applying Filtering Techniques.. 152 10.1 Overview.. 152 10.2 Getting Started 152 10.2.1 What is Filtering?. 152 10.2.2 Needed Information 152 10.2.3 Other Considerations.. 153

10.3 A Simple Filter. 153 10.3.1 The Scenario. 153 10.3.2 Procedure.. 153 10.4 Filtering Strategies.. 156 10.4.1 Filtering and Default Logic. 156 10.4.2 RequiresFullMatch and Exclusive Value Combinations.. 157 10.4.3 RequiresClientMatch 159 10.4.4 The MatchKeyword.. 159 10.4.5 Filtering and Groups 160 10.4.6 Filtering and Schedules.. 162 10.4.7 Filtering and Users.. 162 10.5 Filtering by Message Priority. 164 10.5.1 Extended Example.. 165 10.5.2 Default Logic. 166 10.6 Filtering Messages by IP Address. 166 10.7 Filtering out Duplicate and Transient Messages. 167 10.7.1 Filtering Out Duplicate Node Down Messages. 167 10.7.2 Suppressing Transient Messages.. 168 10.8 Suppressing Unwanted Messages During Scheduled Downtime. 169 10.8.1 Suppressing Orphan Up Messages 170 10.8.2 When a Device Does Not Come Back Online as Scheduled.. 170 10.9 Filtering Messages by Source 171 10.10 Pattern Matching. 171 10.10.1 Other Uses.. 172 10.10.2 Pre-Defining Regular Expressions.. 173 Setting Up and Applying Schedules 175 11.1 Overview.. 175 11.2 Getting Started 175 11.2.1 What are Schedules?.. 175 11.2.2 Needed Information 176 11.2.3 Other Considerations.. 176 11.3 A Simple Schedule.. 176 11.3.1 The Scenario. 176 11.3.2 Procedure.. 176 11.4 Scheduling Approaches.. 177 11.4.1 Schedules and Default Logic.. 177 11.4.2 Schedules and Groups 178 11.4.3 Schedules and [Filter] Definitions. 181 11.4.4 Schedules and [User]Definitions.. 181 11.4.5 Vacations and Holidays.. 182 11.4.6 Adding Time to a Schedule: ExtraDuty 182 11.4.7 Including Other Schedules in a Schedule 183 11.4.8 Schedules and Message Priority 184 11.4.9 Schedules Longer or Shorter than Seven Days.. 186

11.4.10 Changing a Rotation Schedule to Account for Unexpected Leave. 192 11.4.11 Reverse Schedules: Exclusive. 192 Representing Users.. 195 12.1 Overview.. 195 12.2 Getting Started 195 12.2.1 What Are Users? What Are They For?.. 195 12.2.2 Needed Information 196 12.2.3 Other Considerations.. 196 12.3 Creating a [User] definition: Essentials.. 197 12.4 Values for Inheritance by Associated Destinations 197 12.4.1 Direct Inheritance 198 12.4.2 Minimum of the [User] Value and the [Destinations] Default. 198 12.4.3 Maximum of the [User] Value and the [Destinations] Default. 198 12.4.4 Maximum of the [User] Value, the [Destinations] Default, and the [Configurations] Value. 199 12.5 Values for Dial-in and Dial-out Access. 199 12.6 User-Based Administrative Techniques 200 12.6.1 Viewing Messages: -show.. 200 12.6.2 Getting Rid of Messages: -clear and -release. 201 12.6.3 Listing Users. 201 Enabling Responses.. 203 13.1 Overview.. 203 13.2 Getting Started 203 13.2.1 What are Responses?. 203 13.2.2 Needed Information 203 13.2.3 Other Considerations.. 204 13.3 Taking Advantage of Pre-Defined Responses. 204 13.3.1 Responding Via the Command Line.. 205 13.4 Creating Custom Responses.. 206 13.5 Two-Way Pager Considerations. 207 13.6 Responses and the [Notifications] Feature.. 207 Broadcasting to Groups and Creating Escalations 211 14.1 Overview.. 211 14.2 Getting Started 211 14.2.1 What Are Groups? What Are They For? 211 14.2.2 Needed Information 211 14.2.3 Other Considerations.. 212 14.3 Group Basics. 212 14.3.1 Building a Group from a List of Destinations.. 212 14.3.2 Building a Group From a List of Other Groups 212 14.3.3 Supported Group Attributes.. 213 14.4 Broadcast Notification. 214 14.4.1 About Group IDs.. 215 14.4.2 Use of -g and -l Compared. 215

14.4.3 Schedules and Broadcast Notifications 215 14.5 Escalation. 216 14.5.1 A Simple Escalation. 216 14.5.2 Other Approaches to Strategy.. 218 14.5.3 Escalations Involving Subgroups.. 219 14.5.4 Balancing Workloads by Rotating the First Destination 222 14.5.5 Schedules and Escalation.. 222 Processing Events. 223 15.1 Overview.. 223 15.2 Getting Started 223 15.2.1 Needed Information 223 15.2.2 Other Considerations.. 224 15.3 Event Processing Defined.. 224 15.3.1 What Is Event Processing?. 224 15.3.2 What Is an Event? 225 15.4 Event Processing Overview 225 15.4.1 About Notification and Related Keywords 226 15.5 Triggering Actions 227 15.5.1 Sending an SNMP Trap 227 15.5.2 Writing to the System Log. 228 15.5.3 Issuing a Command 228 15.5.4 Making One Event Trigger Multiple Actions. 230 15.6 Alert-Related and Miscellaneous Events: The [Notification] Section 231 15.6.1 Event Keywords Supported in the [Notification] Section 233 15.6.2 Event Substitution Parameters Supported in the [Notification] Section. 236 15.7 Process-Related Events: The [Heartbeat] Section.. 238 15.7.1 Event Keywords Supported in the [Heartbeat] Section. 239 15.7.2 Event Substitution Parameters Supported in the [Heartbeat] Section 239 15.8 Logging-Related Events: The [File] Section 240 15.8.1 Handling Rollover of telaconfe.log and telainetde.log. 242 15.8.2 Handling telalert.sects and telalert.ini file Backups when TelAdmin is Used 242 15.8.3 Miscellaneous [File] Functions 243 15.8.4 Event Substitution Parameters Supported in the [File] Section.. 243 Miscellaneous Administrative Tasks.. 245 16.1 Overview.. 245 16.2 Starting, Stopping, and Initializing TelAlert 245 16.3 Configuring TelAlert to Run Automatically.. 246 16.3.1 On Windows.. 246 16.3.2 On UNIX 246 16.4 Installing TelAlert Clients 246 16.4.1 Configuring the Server To Accept Remote Clients. 246 16.4.2 Installing the TelAdmin Client 247

16.4.3 Installing Remote Command-Line Clients on Windows. 247 16.4.4 Installing Remote Command-Line Clients on UNIX 249 16.5 Setting up the TelAlert Web Clients. 250 16.5.1 Installing the Web Clients.. 250 16.5.2 Running Multiple Web Clients on the Same Machine. 250 16.5.3 Using the Web Clients with Web-Enabled Cell Phones.. 251 16.5.4 Installing Online Help for the Web Clients.. 251 16.5.5 Configuring telalerth with telalerth.ini. 251 16.5.6 Other Keywords 256 16.6 Setting up Logging.. 259 16.6.1 Default Log Files.. 259 16.6.2 Setting Maximum Sizes.. 260 16.6.3 WriteExecsToTrail 260 16.6.4 Configuring Additional Logging Behavior. 260 16.7 Miscellaneous Administrative Tasks. 260 16.7.1 Specifying Maximum ID Assignments.. 260 16.7.2 Viewing Listen Sockets 261 Security Features.. 262 17.1 Overview.. 262 17.2 TelAlert s Security-Conscious Architecture. 262 17.2.1 telalerte: The Central Hub of TelAlert. 263 17.2.2 The Media Controllers. 264 17.2.3 TelAlert Desktop.. 265 17.2.4 Client Programs 265 17.3 Password Encryption.. 266 17.4 Scheduling of Client Connections. 267 17.5 Authentication for Admin and Client Connections. 267 17.6 Control Over Remote Connections 268 17.7 Security Event Available in [Notifications] 269 17.8 Control Over IVR Interactions.. 269 17.9 Using SSL with Skytel Devices.. 269 17.9.1 Obtain and Install Wrapper/Proxy Software 270 17.10 Development Example 274 Integrating XML Output.. 280 18.1 Overview.. 280 18.2 Enabling XML Output.. 280 18.3 Defining the Task. 283 18.4 A (Very) Brief Overview of XML 284 18.5 The Parser Toolkit 286 18.6 The Event Matrix. 287 18.7 The User Methods 289 18.8 The Notification Objects. 292 18.9 Development Example 293 18.9.1 Step 1: Create A New User Object 293

1 Introduction 1.1 Overview This chapter includes the following sections: A high-level look at TelAlert and related products. An overview of the TelAlert Administrator Guide and other TelAlert documentation. 1.2 TelAlert Overview TelAlert Mission-Critical Messaging Server is the core of MIR3 Application Mobilization Platform (AMP). The flexibility and reliability of TelAlert make it the Urgent Messaging System used by more than half of the Fortune 500. TelAlert Takes Messages from Any Source TelAlert works with virtually any kind of application, including network monitoring, enterprise management, help desk, and dispatch solutions anything capable of generating event-based messages and issuing user-defined Windows or UNIX commands. Applies Your Business Rules TelAlert lets you exert an unparalleled degree of control over how it processes messages. You can: Define groups for broadcast notifications or person-by-person escalations that ensure someone responds, even if the first addressee is unavailable. Set up rules governing how escalations proceed. Create schedules determining when each support technician is available to receive messages. Process messages based on priority. Create filters to weed out trivial messages and automatically direct important messages to the right people.

Sends Messages to the Right Destinations TelAlert 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 does much more than deliver messages. It also allows recipients to respond to messages a key factor in TelAlert's ability escalate an alert and ensure that someone takes control of the situation. 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. WAP- and SMS-Enabled Cell Phones Recipients can wirelessly acknowledge and manage messages through the TelAlert Web Client. Applet-Based Remote Interactions TelAlert Messaging Services, Inc. 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 TelAlert Administrator Guide - Version 5.7

1.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. 1.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. 1.3.2 Customizable Vocabulary in Four Languages The voice fonts TelAlert TSS are generated by AT&T s Natural Voices. These fonts are available in English, French, German, and Spanish. All languages are available in male and females voices. English is also available in American, UK and Indian Accent. 1.3.3 Interactive Voice Response (IVR) Users can enter keypad input to accept or decline messages when they are delivered by TelAlert over the telephone. Users can also dial in and interact with TelAlert and even the backoffice applications with which it is integrated via customizable IVR menus. This capability is delivered through a Dialogic telephony card. The TelAlert Voice Engine is no longer available. 1.3.4 Dialogic Telephony Card Windows users can choose to plugs a Dialogic telephony card into the machine on which TelAlert is installed or it can be configured on a remote Windows computer. Chapter 1: Introduction 3

1.4 TelAlert Integrations TelAlert is designed to work with other applications to take the messages they generate and, following your business rules, pass them to the right people, using the medium of your choice. 1.4.1 TelAlert Integrations Make it Easy It is easy to make TelAlert 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 1.4.2 Do-it-Yourself Integrations for In-House Applications Even with applications for which no certified integration exists, integration with TelAlert is typically a simple matter, since most TelAlert 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 Windows commands in response to specified events, it can be integrated with TelAlert. If you choose to perform your own integration, you can also use the TelAlert API or Java class. 4 TelAlert Administrator Guide - Version 5.7

1.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. 1.5.1 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) 1.5.2 Client Platforms Client systems have 3 states, supported on the current version, supported with an older version and discontinued. All 5.00 5.70 client versions are compatible with the 5.71 server software. Operating System Status AIX AIX 3.2.5 Supported with TA 5.20 AIX 4.1.3 (and higher) Supported with TA 5.20 AIX 5.2 (and higher) Supported with TA 5.60 Chapter 1: Introduction 5

HP-UX HP-UX PA-RISC 1.0 (9.04 and higher) Supported with TA 5.50 HP-UX PA-RISC 1.1 (9.04 and higher) Supported with TA 5.50 HP-UX PA-RISC 1.1 (10.20 and higher) Supported with TA 5.70 HP-UX PA-RISC 2.0 (10.20 and higher) Supported with TA 5.70 HP-UX PA-RISC 1.1 (11.31 and higher) HP-UX PA-RISC 2.0 (11.31 and higher) HP-UX Itanium2 (11.31 and higher) EXISTING EXISTING EXISTING 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") EXISTING EXISTING EXISTING EXISTING Linux Linux (glibc 2.0) (Intel x86 32bit) Supported with TA 5.70 Linux (glibc 2.1) (Intel x86 32bit) Supported with TA 5.70 Linux (glibc 2.5) (Intel x86 32bit) (Red Hat 5.4) NEW Microsoft Windows (32 bit Server) (4.0/2000/XP Professional) Windows (32 bit Server) (2003) Windows (32 bit Server) (2008) EXISTING EXISTING NEW SGI SGI Irix Supported with TA 5.50 SGI MIPS ABI Supported with TA 5.50 SCO SCO Release 3 Supported with TA 5.50 SCO Release 5 Supported with TA 5.50 6 TelAlert Administrator Guide - Version 5.7

Sun SunOS 4.1.3 (SPARC 32bit) Supported with TA 5.50 Solaris 2.7 (Solaris 7) + (SunOS 5.7+) (SPARC 32/64 bit) Supported with TA 5.70 Solaris 2.9 (Solaris 9) + (SunOS 5.9+) (Intel X86 32/64 bit) 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) NEW NEW NEW NEW Other AT&T GIS (System 3000) Supported with TA 5.50 BSDI 4.1 Supported with TA 5.50 Digital Unix (Tru64 UNIX 5.1A BL4) Supported with TA 5.70 Tandem Guardian & Tandem OSS Supported with TA 4.03 IBM OS/2 Supported with TA 5.10 HP MPE/iX (WRQ format) Supported with TA 5.20 1.5.3 Operating Systems Not Supported for Version 5.71 TelAlert no longer has access to the following platforms, so we cannot build 5.71 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) Chapter 1: Introduction 7

1.6 Guide Introduction Thank you for using the MIR3 TelAlert Administrator Guide, your primary source for information about the use of recipient-related 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.6.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 recipient-directed information, including changing login IDs, passwords, and notification retrieval. 1.6.2 Audience The TelAlert Administrator Guide is designed for use by individuals who configure notifications using the TelAlert system. 1.6.3 Related Technical Documentation There are other sources of information available concerning deployment of 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.7 Product Support Contact Information Refer to Appendix: MIR3 Contact Information for MIR3 customer support. 1.8 TelAlert Solutions from MIR3 TelAlert is a trademark of MIR3, Inc., but is referred to without trademark symbols in the remainder of this document. 8 TelAlert Administrator Guide - Version 5.7

1.9 Guide Conventions This guide is written in Microsoft Word format and converted to PDF format to preserve the formatting. The following information provides you with the key to help you identify information as you navigate through this Guide: Example Purpose Use of Monospaced Fonts telalertc -i DestinationName -m "Message" Italicized text within a command line example represents a variable. In the above example, DestinationName is the invocation of an item in TelAlert s configuration file; message represents the message text to be sent by TelAlert. 2001/03/16 11:50:11>Event [21]Alert Completed (23), Status: [81]Message sent, TelamonTestPage Command line text Text representing information entered by the user at the command line or presented by TelAlert as output is shown in a monospaced font. Click OK. Within procedural (how-to) text, boldface words are characters you type or elements you can click. Within overview or conceptual text, bolded words may simply represent concepts that have been highlighted to emphasize their relative importance. 1. Go to the Add User page. Within procedural text, numbered steps denote actions that should be followed in sequence. Message Formatting In this guide, message text passed on the command line is enclosed in quotation marks. This is not required in all cases, but putting your message text in quotation marks is an excellent habit, as it ensures that neither TelAlert nor any shell you might be using will read the message as anything other than a string of text to be delivered. Chapter 1: Introduction 9

Example "Open telalert.ini and search for " " gives the file a.bak extension and then " {LauraTextPager} Configuration=SkyTelNationalTe xtpager PIN=4850879 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. 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. 2. Go to the Add User page. Within procedural text, numbered steps denote actions that should be followed in sequence. Click Save to save your work. Click Cancel to exit without saving. Within procedural text, bulleted text denotes available options. Within overview or conceptual text, bulleted text also denotes supporting information that is subordinate to the major topic being discussed in the Guide. The light bulb icon denotes a helpful tip. The information icon denotes reference material. The note icon indicates definitions or considerations that help you understand the related task. 10 TelAlert Administrator Guide - Version 5.7

Broken Lines in telalert.ini In telalert.ini excerpts 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.ini entry itself, the line will not actually be broken. Note that telalert(c) does not support breaking command lines. If you want to break a line in telalert.ini so that it continues on the next, you must place an ampersand (&) immediately preceding the line break. Otherwise, TelAlert will treat the continuation as a new line. Note too that if a broken line is to be commented out (using the # character) the continuation lines need to be commented out as well. 1.9.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 Enterprise Access Control (EAC) role-based access functions available in the TelAlert system. 1.9.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:\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. Chapter 1: Introduction 11

2 Technical Overview 2.1 Overview A high-level look at TelAlert from a technical perspective: How it works The programs and processes comprising it Key TelAlert files The concepts underlying TelAlert configuration Some frequently asked questions and their answers 2.2 How TelAlert Works TelAlert follows instructions issued by applications and human users. These instructions fall into three main categories: Notification instructions include a message that TelAlert is to send to some recipient. Administrative instructions relate to starting and stopping TelAlert, modifying the way it works, and checking the status of the work it does. 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. TelAlert can accept instructions via two command line interfaces, telalert and telalertc. In addition, specially integrated applications can call TelAlert API functions or Java methods to interact with TelAlert. The command line interfaces are the most common means of interaction, and so instructions typically take the form of commands. Telalert and telalertc parse command line parameters and pass formatted instructions to the main server process, telalerte. Telalerte validates these instructions against TelAlert configuration information and queues tasks to be performed by other server processes, which in turn are responsible for interactions with specific devices or connections: modem, Dialogic telephony card, electronic signboard, and sockets-based Internet connection.

2.2.1 A Typical Alert A typical scenario has TelAlert 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 compiled version of the telalert.ini configuration file, to find the definition for the recipient, the configuration information for the modem to be used, etc. Next telalerte tells telalertm (TelAlert s modem daemon, the process that actually controls the modem) precisely what to do, providing it with instructions for dialing the specified service provider, the PIN for this particular recipient, and finally the message itself. All the while, telalerte records each step in the process in a file called telalert.trail. It also records this alert as active in the telalert.alert file. 14 TelAlert Administrator Guide - Version 5.7

2.3 TelAlert Programs and Processes TelAlert is comprised primarily of two command line programs and six daemon processes, some of which have been mentioned already in this chapter. Each is described in greater detail below. telaconf telaconf is the database management system that controls and stores information on changes you make to your configuration using TelAdmin, a component of the TelAlert Desktop, the graphical configuration environment for TelAlert. On Windows, telaconf runs as a service; use Control Panel/ Administrative Tools/Services on Windows to make sure the Startup parameter is set to Automatic. However, you should not use the Start button in the Services applet to actually start telaconf; instead, give the telaconf -start command from a command line. On UNIX, telaconf runs as a daemon. To have it start automatically when UNIX boots, look at 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. telalertc telalertc is a command line program used 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. telalertc is a client program designed for end users. It lacks certain administrative commands that control the way TelAlert works. telalert telalert is a command line program 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. Chapter 2: Technical Overview 15

telalert vs. telalertc It is recommended that you use telalertc to issue all TelAlert commands other than the administrative commands unique to telalert even when issuing the command from the machine running the TelAlert server, where telalert is also available. The reason is simple: when you use telalertc, there is never a danger of accidentally stopping, re-starting, or re-initializing TelAlert. telalert is the sole means of issuing still other commands (including -clearall, -releaseall, -ackall, and -nakall) that you would not want to give accidentally. telalerth telalerth is a CGI application that allows a Web server to communicate with telalerte. 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. telalerte telalerte is the TelAlert server, the central nervous system of TelAlert. A continually running daemon process, telalerte takes commands and messages received by telalert and renders them complete, incorporating information referred to in the TelAlert configuration file. It then passes complete instructions to the daemon responsible for carrying out the responsibility at hand. Telalerte tracks all TelAlert activity, recording it in a comprehensive events file called telalert.trail. It maintains a record of all active alerts in telalert.alert. telalerte is also the part of TelAlert that processes responses and requests. If a message recipient dials in and acknowledges receipt of a message using TelAlert s voice menus, this response is passed by telalertd (the daemon handling interactions with the TelAlert 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. telalertm 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. 16 TelAlert Administrator Guide - Version 5.7

telalertr telalertr is the process responsible for controlling electronic signboards and other RS232 devices (excluding modems). telalerts 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. readmail TelAlert comes with an email-reading program (readmail, or readmail.exe for Windows) 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 9 of this manual for more information. 2.4 Key TelAlert Files Below is a description of some of the key files comprising a TelAlert installation. 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 100 K. (The TrailSwitchCmd= line in the [Files] section lets you define an external process for archiving the data in these backup.trail files.) telalert.alert Maintained by telalerte, telalert.alert is a continuously updated file containing all the information TelAlert needs to process all active alerts. 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. Chapter 2: Technical Overview 17

telalert.ini This is TelAlert s configuration file. It contains a variety of information that TelAlert uses to carry out commands. This includes licensing details; information about ports, devices, groups, schedules, and users; and instructions about sending messages to specific destinations and general destination types. 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). The telalert.ini file can be configured directly, using a text editor. The other configuration/administration option is to use TelAdmin, a Windows application, to modify the telalert.sects file (the compiled version of the telalert.ini file; see below). For a more in-depth discussion of these two options, refer to the TelAlert Desktop Guide. telalert.sects This is the compiled version of the telalert.ini file. Strictly speaking, telalerte reads this file, not telalert.ini, in order to process commands. You can control the way TelAlert works by using TelAdmin to modify this file as opposed to editing the telalert.ini file directly. For more information on the two configuration options, refer to the TelAlert Desktop Guide. Figure 2. TelAlert Files, Processes, and Destinations 18 TelAlert Administrator Guide - Version 5.7

2.5 Key Configuration Concepts In order to understand your notification and response objectives, TelAlert relies on two sources of information. The first is the command interface (be it command line, API functions, or Java methods), which may be used by another program or a human user. The second is the TelAlert configuration file telalert.ini or, more directly, its compiled version, telalert.sects. These two sources are heavily dependent on one another. While it is possible to pass varying amounts of information directly on the command line, virtually all commands use configuration keywords to make explicit reference to information stored in the configuration file. For example, to send a message to Bob s text pager, you might use the following command: telalertc -c SkyTelNationalTextPager -pin 1234567 -m "node 2745 down" Here, -c tells TelAlert to understand SkyTelNationalTextPager as a reference to the [Configurations] definition of the same name. This definition contains information on how to use the SkyTel service, but the PIN for the intended individual recipient is passed here on the command line, as is the message itself (the text following -m, which is best enclosed in quotation marks). Alternatively, you could issue a command referring to a specific destination (see below) defined in the configuration file. For instance: telalertc -i BobTextPager -m "node 2745 down" Here, -i tells TelAlert to understand BobTextPager as referring to an individual [Destinations] definition (as opposed to a [Configurations] or [Group] definition, signaled by c and -g, respectively). Typically, {BobTextPager} would include the PIN and, by means of a keyword reference, needed configuration information (that stored in the definition of, for instance, {SkyTelNationalTextPager}). Command-line invocation of configuration data is key to much of TelAlert s flexibility and power most notably, its scheduling, group-send, escalation, and response functionality. The following discussions are intended to acquaint you with the concepts you need to understand to configure TelAlert. Each discussion focuses on the concept at hand but introduces related concepts where necessary to help you develop a sense of the big picture how the various pieces of configuration data combine to deliver some of TelAlert s most valuable benefits. Chapter 2: Technical Overview 19

2.5.1 Sections, Definitions, Keywords, and Cross-Referencing telalert.ini is divided into sections headed by words enclosed in straight [brackets]. Many (but not all) 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 one of the many words TelAlert is programmed to recognize (including but not limited to section names), and value is the value you assign (in some cases an integer; in others, True/ False or a definition name). Generally, a definition represents a specific instance of the concept underlying that section. For instance, an entry under [Configurations] contains configuration information for a specific instance of a general medium type such as a pager type, an email gateway, or an electronic signboard. An entry under [Destinations] contains the information specific to a given destination (e.g., an individual s pager), as well as a keyword-based reference to the general configuration information for that type of pager. A [Destinations] definition might look something like this: {LauraTextPager} Configuration=SkyTelNationalTextPager PIN=4850879 The second line of this definition refers to the entry in the [Configurations] section called {SkyTelNationalTextPager}, which might look something like this: {SkyTelNationalTextPager} Type=TextPager AreaCode=800 Number=6792778 Speed=19200 Cross-references within the telalert.ini file flow from more specific to more general. That is, a very specific entry such as a [Destinations] definition usually contains one or more keyword references to more general entries: a [Configurations] definition, or a user or schedule, for example. This is not the same kind of inheritance at work in object-oriented programming (since a [Destinations] definition inherits only a small, explicitly invoked portion of the information stored under [Configurations]), but the effect and benefits are very similar: telalert.ini cross-referencing permits certain broadly applicable pieces of information to be written once, stored centrally, used in many different contexts, and altered throughout in one simple step. telalert.ini can also contain references to outside resources, including scripts and text files storing additional definitions. 20 TelAlert Administrator Guide - Version 5.7

Sectional Default Values Not all lines in every section belong to a definition. Lines appearing between the section name and the first definition name present default values that are valid for every definition. However, if a given definition contains the same keyword and another value, telalerte overrides the default entry and reads the definition-specific line. 2.5.2 Configuration The [Configurations] section contains entries defining basic configuration information for different media types (e.g., email, a specific kind of pager, or an electronic signboard model). These definitions can be drawn from external files using $include relativepath/filename. TelAlert ships with a telalert.ini file filled with commented-out $includefile references and a set of files containing [Configurations] definitions for a wide range of paging service providers. 2.5.3 Destination The [Destinations] section contains entries defining specific destinations such as a text pager belonging to David, his home telephone number, the email address of Joan, or a specific instance of a certain type of electronic signboard. Typically, some of the information for a [Destinations] definition is drawn from a [Configurations]entry. For instance, {DavidPager} might include a Configuration=TextPager line, where TextPager points to the [Configurations] definition of the same name, which may be shared by many destinations. Some destinations (a signboard, for instance) have nothing to do with any person. Others may make reference to a person by means of a User= line. Since it may be possible for TelAlert to contact a person via several different destinations, this optional line allows TelAlert to recognize destinations in terms of the person they have in common. Such an association may be useful if you want to analyze sent messages in terms of the people to whom (rather than destinations to which) they were sent. Chapter 2: Technical Overview 21

2.5.4 User Users, defined individually in the [User]section and referred to elsewhere in telalert.ini by User= lines, represent the people associated with destinations (some other parts of the telalert.ini file permit association with a user, as well). Generally speaking, this is an optional aspect of TelAlert configuration: most [Destinations] definitions do not have to be associated with a user. Creating such associations, however, is the key to several important techniques: By including a User= line in a [Destinations]definition, you cause it to inherit values contained in the invoked [User] definition: Schedule, Password, etc. This tells TelAlert how to assess the destination s validity (i.e., by referring to the schedule), 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). Moreover, whenever [Destinations] definitions are associated with users, it is possible to track messages in terms of the people to whom they were sent. This is helpful because it may be possible to notify a single person via a number of different destinations. While the user concept can be very helpful, not all organizations use it when implementing TelAlert. Some simply create a general user {Operator} and invoke this user by keyword (User=Operator) wherever necessary. Others may have no need to use this keyword at all. 2.5.5 Group A group is a collection of destinations. Under the [Group] section of telalert.ini, each entry is identified by a name in {braces}, and all of the destinations in that group are invoked by means of a single keyword line. For instance: Destinations=BobHomePhone,LauraTextPager,JohnEmail Sending a message to a group means sending it to all of the destinations comprising that group, either all at once or one at a time, according to specified rules. For instance, if a [Destinations]definition invokes a [Schedule] entry, TelAlert has to evaluate the schedule to see if the destination is valid at that time. The priority of the message may override the schedule for the destination, in which case TelAlert will send to it anyway; otherwise, it may move on to the second destination. Similarly, when TelAlert is instructed to send to one destination and wait for a positive acknowledgment before sending to another, it begins by looking through the list for the first [Destinations] definition that it can use, based on the rules that have been set up. When it succeeds in sending the message, it waits for acknowledgment for a specified time before locating the next valid entry and sending the message to this destination. [Group] definitions are critical to TelAlert s escalation capability (as is the concept of strategy; refer to the Strategy section, below). Only by setting up a [Group] definition and invoking it in a command can you ensure that a message reaches someone who can handle the problem, even if the initial send fails or goes unacknowledged. Alternatively, creating a group comprised of all the destinations associated with one person allows you to send a message to that person without specifying a particular destination. As long as each of these destinations is associated with a schedule, TelAlert will examine them one by one until it finds the right one to use, based upon its schedule. You can refer to one [Group] definition within another simply by listing its name as one of the values in the Destination= line. For this reason, a group should never be given the same name as a destination. 22 TelAlert Administrator Guide - Version 5.7

2.5.6 Schedule A schedule is a list of times during which a destination is considered available, or on duty. A [Destinations] definition can invoke a schedule by means of a keyword referring to an entry in the [Schedule] section. If a destination is linked with a [User] definition, however, this definition may invoke the schedule instead so that the destination refers to a user, which in turn refers to an entry under [Schedule]. Having one [Schedule] definition associated with a [Destinations] definition means that TelAlert will use that schedule to assess that destination and then either send the notification to it or not. But you can include more then one schedule reference in a [Destinations] definition, which allows TelAlert to decide what to do based on the message s priority. For example: {JohnPager} User=John Schedule=RegularSchedule AlternateSchedule=LateShift {RegularSchedule} and {LateShift} appear under [Schedule], with {LateShift} defined so that it includes the hours comprising {RegularSchedule} and additional hours as well. Then you might include the following line as part of the [User] definition representing John: AlternateSchedulePriority=80 Thus, when TelAlert processes a message of priority 80 or higher, it finds it is permitted to send it to {JohnPager}, even if it comes at a time outside of his normal schedule (assuming it falls within the hours of his alternate schedule). 2.5.7 Strategy Entries under [Strategy] are relevant for a message sent to a group and are referred to in [Group] definitions. They determine two things: (1) how TelAlert recognizes an alert as complete and (2) under what conditions it escalates the alert by sending to a subsequent destination. The first is accomplished through a Complete= line. For instance, Complete=acked>0 tells TelAlert to consider the alert complete when it receives positive acknowledgment from any recipient. An Escalate= line tells TelAlert under what conditions to escalate the alert. For example, Escalate=Incomplete=0 tells TelAlert to escalate the alert to the next sub-group when the number of sends in an incomplete state (i.e., those marked Active, Pending, or AckWait) equals zero. Together, these two lines form a commonly used [Strategy] definition called {FirstAcknowledge}. Under the terms of {FirstAcknowledge}, the alert will be escalated until it has been acknowledged once (and thus has been completed); assuming no acknowledgment, it will be escalated until there are no more destinations to which it can be escalated. Chapter 2: Technical Overview 23

If the requirements for completion (set in the Complete= line) are met, TelAlert always ceases escalation, even if the conditions for escalation (set in the Escalate= line) remain unmet. TelAlert allows you to set a higher standard for completion in case you want to keep an alert active (for tracking purposes, say) even after escalation has ceased. A default strategy may be invoked under [Group] using a Strategy= line placed before the first definition. A group may also invoke its own strategy using a Strategy=line; these group-specific strategies override the default. In the absence of a reference to a [Strategy] definition, no escalation occurs; TelAlert sends to all destinations at once. Note that when you send a message to a group that includes one or more other groups, TelAlert uses the strategy defined in the group to which the message is addressed, and ignores any Strategy= lines in the subsidiary groups. 2.5.8 Other Configuration File Sections There are a number of other sections comprising the telalert.ini file. Some of these, like the ones described above, provide a means of controlling the way TelAlert interacts with users. Others pertain to TelAlert s internal functioning or its interaction with various optional components. Each of these is described briefly below. All the behavior governed by these other sections can be modified using TelAdmin, as well. For more information on these two configuration options, refer to the TelAlert Desktop Guide. [Access] Configures the prompts issued by TelAlert in both dial-in and dial-out calls. [Analog] Used to configure certain environmental monitors which connect via the Sensor Interface Unit. (Obsolete - TelAlert Classic Engine only.) [Battery] Specifies the battery charge level range to monitor and the means of notification when this range is exceeded. (Obsolete - TelAlert Classic Engine only.) [CallProgress] Contains values associated with the ability of the Dialogic telephony card to listen for and recognize various telephone rings and voice interaction cues. [Files] Allows you to configure TelAlert s standard logging activity. [Filter] In conjunction with a tags parameter, allows you to have TelAlert send to a select subset of a group of destinations based upon the nature of the message it is to deliver. 24 TelAlert Administrator Guide - Version 5.7

[Heartbeat] Contains values relating to TelAlert s ability to notify other applications or scripts regarding changes in the status of TelAlert. [License] Contains settings related to your TelAlert software license that allow TelAlert to function according to its terms. [Limits] Establishes values for miscellaneous parameters internal to the TelAlert software. [Menu] Specifies how the Dialogic telephony card prompts and receives input from users. [Message] Defines rules for modifying a message so it can be sent to a group of destinations with varying display capabilities. [Modem] Configures numerous modem parameters. [Notifications] Specifies when and how TelAlert should deliver information to the trouble ticketing or other application with which it is integrated. [Patterns] Specifies patterns that can be used to view, manage, and modify alerts in progress. [PhonePrefixes] Specifies the phone prefix information associated with the telephone lines used by TelAlert. [Port] Defines the connections TelAlert uses to send notifications. [Power] Specifies the power level range to be monitored and the means of notification when this range is exceeded. (Obsolete - TelAlert Classic Engine only.) Chapter 2: Technical Overview 25

[Process] Allows you to configure TelAlert s control over helper applications such as Readmail. [Relay] Allows you to configure TelAlert s control over devices connected to the TelAlert Relay Interface Unit. (Obsolete - TelAlert Relay Interface Unit only.) [Response] Defines any responses that recipients may be able to make after receiving a message. [Sensor] Allows you to configure certain environmental monitors, which connect to the TelAlert Sensor Interface Unit. (Obsolete - TelAlert Sensor Interface Unit only.) 26 TelAlert Administrator Guide - Version 5.7

3 Implementation Planning 3.1 Overview An introduction to the work of setting up TelAlert to meet your organization s unique notification needs. 3.2 Your Accomplishments So Far Chapter 1: Introduction and Chapter 2: 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 Chapter 16: Miscellaneous Administrative Tasks and checked your installation by sending a test page. Also, you should have read the integration guide pertaining to any third-party product(s) with which you plan to integrate TelAlert. As you will see, integration accompanies rather than follows general implementation, and, as you move ahead, it will be helpful to understand what kind of integration you need to perform. Integration Assumptions TelAlert is designed to work with a controlling application. Many such applications control TelAlert via the command line either directly, issuing a TelAlert command just as a human user might, or indirectly, invoking a script that builds and issues a TelAlert command. (Some others call TelAlert APIs or Java classes to communicate directly with TelAlert.) Because the command itself is the key to achieving the desired TelAlert behavior, the rest of the Administrator Guide focuses on these commands and associated parameters, ignoring the different ways they might be produced in different integrations. Integrations differ also in that some store a portion of the contact information required for sending notifications in the controlling application s database, while others store all such information in the TelAlert configuration file. In order to give you the most complete picture of TelAlert implementation capabilities, the Administrator Guide assumes the latter scenario.

3.3 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. 3.3.1 Chapter 1: Introduction This chapter presents a general overview of TelAlert from a product perspective. 3.3.2 Chapter 2: Technical Overview This chapter presents a general overview of TelAlert from a technical perspective. 3.3.3 Chapter 3: Implementation Planning The present chapter focuses on familiarizing you with the work you must do to configure TelAlert to meet your organization s specific needs. 3.3.4 Chapter 4: 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. 3.3.5 Chapter 5: 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. 3.3.6 Chapter 6: Dialing the Telephone Many of TelAlert s paging and voice notification capabilities rely on dialing the telephone. This chapter explains all of the configuration settings that control how TelAlert dials the telephone, teaching you to handle a wide variety of special dialing scenarios, from overlapping area codes to special billing codes to inside and outside lines. The things you will learn in this chapter will be relevant to a great deal of the other work you will do while setting up TelAlert. 3.3.7 Chapter 7: 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. 28 TelAlert Administrator Guide - Version 5.7

3.3.8 Chapter 8: 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 TelAlert s voice capability, you should have purchased a TelAlert Dialogic telephony card and installed and tested it following the directions in the TelAlert Voice and Hardware Guide. Once TTS is in place, most of your work will consist of setting up specific [Configurations] and [Destinations] definitions appropriate for voice notifications. One important aspect of this process is determining how TelAlert should behave when a number it calls is answered for instance, whether it should expect to reach a voice mail system or a human user whom it must ask for identification before reading its message. All the information regarding the TelAlert Dialogic telephony card and software configuration for voice functionality is now covered in chapters 2 through 4 of the TelAlert Voice and Hardware Guide. 3.3.9 Chapter 9: 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 Webenabled and text-screen-equipped cellular phones. 3.3.10 Chapter 10: 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. Chapter 3: Implementation Planning 29

3.3.11 Chapter 11: Setting Up and Applying Schedules [Schedule] definitions can be invoked in [Destinations] or [User] definitions. At whatever level you invoke a schedule, TelAlert uses this information to evaluate affected destinations and determine which are valid at the time TelAlert sends a notification. Schedules can play a role in notifications sent to a single destination, but primarily they serve to determine which of a group of destinations are valid at any given time. They are an important part of implementing TelAlert s escalation capabilities, but, even when used solely in conjunction with simple group sends, they allow you to differentiate between on-duty and off-duty destinations so that the right people are notified every time. TelAlert s scheduling feature allows you to do more than simply indicate when a user or destination is to be considered on duty. As explained in this chapter, you can also set an AlternateSchedule and OverrideSchedule value for each, making it possible to extend the hours during which a destination is valid, depending on message priority. 3.3.12 Chapter 12: 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. 3.3.13 Chapter 13: Enabling Responses Recipients of TelAlert messages can respond remotely using two-way pagers or touch-tone telephones; they can also issue a command line response on a machine on which telalertc is installed. The most basic aspects of TelAlert s support for responses require no setup; this chapter covers these but focuses on techniques for creating customized [Response] definitions. These can play a role in escalations; they can also be used in conjunction with [Notifications] definitions to initiate additional actions. 3.3.14 Chapter 14: Broadcasting to Groups and Creating Escalations Groups are collections of destinations. Setting up [Group] definitions is very simple; the principal challenge is looking at your organization and its notification needs and deciding what groups to create. The best way to approach this issue is to consider what groups already exist within your organization implicitly or explicitly among the pool of potential message recipients. You might form groups on the basis of a wide range of traits: e.g., functional area, physical location, shift, or level of responsibility/authority. You can use [Group] definitions to send messages to a number of destinations at once (broadcasting). You use a combination of [Group] and [Strategy] definitions to perform an escalation sending the message either to a series of individual destinations, one at a time, or to all the destinations comprising one subgroup, then to all the destinations comprising the next subgroup, and so on. This chapter covers all the details of creating [Group] and [Strategy] definitions and using them for broadcast notifications and escalations. 30 TelAlert Administrator Guide - Version 5.7

3.3.15 Chapter 15: Processing Events TelAlert is able to recognize a wide range of internal events some relating to notifications, some relating to input from environmental monitors, some relating to logging, and some relating to the state of TelAlert s constituent processes. This chapter explains the procedures for having TelAlert pay attention to designated events and process them according to rules you specify. 3.3.16 Chapter 16: 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. 3.3.17 Chapter 17: 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. 3.3.18 Chapter 18: Integrating XML Output This chapter shows how TelAlert s XML output can be integrated with various third-party applications. 3.4 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. 3.4.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 Chapter 3: Implementation Planning 31

This continues to be true as you add other [Configurations] and [Destinations] definitions to the mix, thus making other notification media available, and even as you begin sending messages to more than one destination and filtering these destinations according to the ones considered on-duty. Whether you are sending a message to one or many destinations, TelAlert s basic procedure is the same: it sends the message to the specified destination or destinations and then lets go of the alert. Note that TelAlert knows nothing about nodes, node numbers, or downtime. It simply takes the text of the message received from the controlling application, and sends it to the destination indicated by the command. 3.4.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. Figure 4. Extended Alert Timeline: -ackwait What does this extension of the timeline accomplish? Since the message is being sent to a single destination, there is no question of any TelAlert-directed escalation taking place as the result of a response or non-response. But, for as long as the message and (as a consequence) the alert remain alive after message delivery (here, ten minutes), TelAlert can accept a response and pass it to a controlling application. Thus, your help desk application (for instance) will know whether the problem is being handled something it could not learn unless the alert were held after the point of delivery. 32 TelAlert Administrator Guide - Version 5.7

3.4.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. 3.4.4 The Alert Timeline and Escalations The introduction of escalations achieved using [Group] and [Strategy] definitions changes the timeline model of a TelAlert alert slightly. Even here, however, the basic idea is the same: unless it is told to do otherwise, TelAlert considers the alert complete when it has finished sending all the messages that comprise it. In an escalation scenario, the main factor governing the life of the alert is the value assigned to the Complete keyword, which is included in the [Strategy] definition. As long as this criterion has not been met, TelAlert keeps the alert alive. An individual message recipient may positively acknowledge having received it and thus cause TelAlert to let go of that particular send (one of the multiple notifications that may result when an alert is sent to multiple destinations). However, if this individual acknowledgment does not meet the completion criterion for the alert, the alert itself remains alive. Likewise, an individual message recipient may acknowledge and hold a message. This affects the state of the alert itself only if the acknowledgment meets the completion criterion; otherwise it affects only the state of the individual send. In this case, TelAlert holds the message but continues to process other sends and responses associated with the alert until the completion criterion is met. When this happens, TelAlert stops processing sends and clears all messages in an ackwait state. It continues to hold the held message, however, and as a result the alert remains alive until the message is released, the ReleaseWait timer expires, or the alert is cleared by the sender or a TelAlert administrator. Chapter 3: Implementation Planning 33

3.4.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. 3.4.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. 34 TelAlert Administrator Guide - Version 5.7

3.4.7 Scenario One: Paging Only Small Organization Some people who implement TelAlert want to use it merely to page the members of a small support group under certain circumstances. The following describes the steps likely to be followed in such a case. 1. Set up [Configurations] Definitions for Paging In a small organization, it is common for everyone to use the same paging service provider, so you might have to create only one [Configurations] definition. Here, though, assume that there are three hands-on support employees with local-coverage paging and a manager who uses a national service from another provider. First, create the definition for the local service based on information found in the appropriate file in the Pagers directory: [Configurations] {ATTWichitaTextPager} Type=TextPager Speed=2400 AreaCode=316 Number=636-4110 Now, go to [PhonePrefixes] and set LocalAreaCode to match the local area code (in this case, 316). This ensures that TelAlert will not dial the area code when it sends notifications using this definition. Next, create the [Configurations] definition for the national paging service. This too should be based on information contained in the file from the Pagers directory. [Configurations] {SkyTelNationalTextPager} 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 7: Configuring for Paging Notification. Chapter 3: Implementation Planning 35

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. [Destinations] {JohnTextPager} Configuration=ATTWichitaTextPager PIN=1234567 {CynthiaTextPager} Configuration=ATTWichitaTextPager PIN=2345678 {DavidTextPager} Configuration=ATTWichitaTextPager PIN=3456789 You can name these definitions anything you like, but including the person s name, along with text and pager, in the name you assign may be helpful later, even if there currently are no other entries with which these might be confused. Next, create the destination for their manager: [Destinations] {RachelNationalTextPager} Configuration=SkyTelNationalTextPager PIN=4567890 For a detailed discussion of these settings, refer to Chapter 7: Configuring for Paging Notification. 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" 36 TelAlert Administrator Guide - Version 5.7

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 14: 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 two entries for each destination one a regular schedule, the other an alternate (i.e., extended) schedule to be used under special circumstances. 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 {CynthiaAltPageSched} AddSchedules= "CynthiaPageSched" Monday=16:00-20:00 Tuesday=16:00-20:00 Wednesday=16:00-20:00 Thursday=16:00-20:00 Friday=16:00-20:00 Next, under each of the four destinations you created, set the following values: Schedule=name_of_schedule AlternateSchedule=name_of_alternate_schedule Chapter 3: Implementation Planning 37

Here, nameofschedule matches the name of the regular schedule you created for this destination under [Schedule]. For the destination {CynthiaTextPager}, name_of_schedule would be {CynthiaPageSched}, and name_of_alternate_schedule would be {CynthiaAltPageSched}.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 or alternate 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. To activate the alternate [Schedule] definitions, set an additional value in each [Destinations] definition: AlternateSchedulePriority=70 This means that alerts with a priority of 70 and higher will be delivered to the destination during both regular and extended duty hours. If you set an additional value OverrideSchedulePriorty=80 alerts of priority 80 and higher will be delivered to the destination at all times. (Of course, you can set whatever threshold you like. The priority of an alert can be determined at the command line.) For a detailed discussion of these settings, refer to Chapter 11: 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 38 TelAlert Administrator Guide - Version 5.7

Once this is in place, you (or the application controlling TelAlert) can invoke this set of responses on the command line when sending a message: telalertc -g Support -m "node 2745 down" -ackwait 1h -response Basic Any recipient of this message could go to a networked computer on which telalertc was installed and issue a reply, like so: telalertc -reply sendid yes Here, sendid is the integer uniquely identifying the message sent to this recipient. (The command telalertc -showalert will display the IDs of active sends.) Even if you do not want to use this set of responses when you send to regular text pager destinations, setting it up now prepares you for the addition of two-way pagers in the future. 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 13: Enabling Responses. 6. Create Strategies The final step in implementing TelAlert in this scenario is setting up [Strategy] definitions that enable alert escalation so that a message is sent first to one destination, then another, then another, until certain conditions are met. In an organization this size, you might need only one. Under [Strategy], create the following entry: [Strategy] {FirstAcknowledge} Complete=Acked>0 Escalate=Incomplete=0 According to this definition, escalation will cease upon the first positive acknowledgment of the message; this is because the first acknowledgment meets the definition of complete found in the [Strategy] definition. As long as no acknowledgment is given, escalation will continue until there are no more valid destinations to which TelAlert can send the message. Once this strategy is in place, it is merely a question of when and how to invoke it. You can do so at the command line (by including -strategy FirstAcknowledge). You can also refer to it within a [Group] definition, so that every message sent to that group is subject to this escalation strategy. Chapter 3: Implementation Planning 39

Perhaps this makes especially good sense for one of the groups you have already created, {SupportAll}. Simply set a Strategyvalue here, like so: [Group] {SupportAll} Destinations= "Support","RachelNationalTextPager" Strategy=FirstAcknowledge Now, any message sent to this group with -response Basicand -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 14: Broadcasting to Groups and Creating Escalations. 3.4.8 Scenario Two: Paging, Voice, and Email Small Organization Assuming an organization of the same size, adding voice and email to the list of notification media is a relatively simple matter. At its most basic, it consists of adding two new [Configurations] definitions and a set of new [Destinations] definitions for each destination to which you anticipate sending messages. Beyond this, you may want to work with your schedules, groups, and strategies to arrive at an overall configuration that allows you to take full advantage of the newly enabled media. This scenario builds on concepts introduced in Scenario One: Paging Only Small Organization, which we recommend you read first. Note that voice notification requires a TelAlert Dialogic telephony card. Set Outbound Voice Configuration First, under [Configurations], create a definition for outbound voice notification (your outbound voice destinations will in turn invoke this entry). The information comprising this definition relates to TelAlert s behavior after the phone is answered: [Configurations] {OutboundVoice} Type=InteractiveTTS ToneConfirmWait=3s AnswerConfirmationRequired=True UserRequired=True PreMsgWait=0.5s PostMsgWait=1s 40 TelAlert Administrator Guide - Version 5.7

When TelAlert attempts to make a voice notification using this [Configurations] definition and the phone is answered, it identifies itself and gives the person on the other end of the line three seconds (ToneConfirmWait=3s) to press the # key. Then, because UserRequired=True, it asks the user to key in his or her password, followed by the # key. Once TelAlert has verified the user s identity, it reads the message and provides a pre-defined set of responses, allowing the user to positively acknowledge, negatively acknowledge, or acknowledge and hold the message. These are built-in responses; they are not related to those made available through invocation of a [Response] definition. Note that the Type setting is what connects this [Configurations] definition to {TTS_Port1}, a definition under [Port]; this is how TelAlert knows to use a TTS port for notifications based on this [Configurations] definition. If you did not set up this [Port] definition when you installed and tested the TelAlert Engine, you will have to do so now. For a detailed discussion of these settings, refer to Chapter 3 of the TelAlert Voice and Hardware Guide. 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 Uservalue. Thus, after 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. Chapter 3: Implementation Planning 41

Apply Group, Schedule, and Strategy Definitions Once the voice [Configurations]and [Destinations] definitions are in place, you (or the application controlling TelAlert) can send a voice notification using a command such as this: telalertc -i JohnHome -m "node 2745 down" To send voice notifications to groups, invoke schedules, and perform escalations, you will have to do some more work, using techniques similar to those you used when setting up paging: 1. First, refer to these new voice destinations in [Group] definitions. One option you have is to set up voice-only groups that parallel existing groups of pagers. Alternatively, you can form groups comprised of different kinds of destinations. For instance, you could construct a group out of {DavidTextPager}and {RachelCellPhone} and use it so that any page not acknowledged by David within a certain time would result in a call to Rachel s mobile phone. 2. Second, create [Schedule] definitions for these destinations. You can do this by defining new regular and extended entries under [Schedule] and referring to them by setting Schedule and AlternateSchedule 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. A third possibility is to refer to regular and extended schedules in each [User] definition and let them be brought into play through the destination s User setting. 3. Third, set a Strategy value for each of the [Group] definitions you create. For a detailed discussion of these settings, refer to Chapter 14: Broadcasting to Groups and Creating Escalations and Chapter 11: Setting Up and Applying Schedules. Set [Configurations] Definitions for Email With email, the same model applies. First create the [Configurations] definition that will be used to send email notifications: [Configurations] {Email} Type=Email Model=Internet Host=server.domain.com Service=smtp From= telalert@domain.com Together, Type=Email and Model=Internet point to the {Internet} definition under [Port], which you should set up now, if you have not done so already. 42 TelAlert Administrator Guide - Version 5.7

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 creating a series of groups, each pairing a paging and a matching email destination. You can then use these to build larger groups. For a detailed discussion of these settings, refer to Chapter 9: Configuring for Other Notification Media. 3.4.9 Scenario Three: A Larger Organization When implementing TelAlert in a considerably larger organization than the one just described, the main two additional challenges concern the work s increased volume and complexity. Higher Volume There are a number of reasons for the increased volume of work: You will very likely be creating more [Configurations] definitions, and you will certainly be creating many more destinations. For each destination, you may be creating one or two unique schedules, and for every human user you may decide to create a separate [User] definition and then associate each with the appropriate destinations. There will be more groups to create, and some of these may be comprised of a large number of destinations. Even if you opt to use only one [Response] and one [Strategy] definition, tending to the other parts of this implementation will demand considerably more effort than in a small organization. Chapter 3: Implementation Planning 43

Greater Complexity The greater complexity is partly the consequence of the greater volume. For instance: More destinations means more choices as to how to set up your groups. Likewise, the fact that significant numbers of destinations will be on duty at precisely the same times may lead you to set up a system of shared schedules something that, though rather complicated, will save on maintenance in the long run. At the same time, a larger organization is more likely to have needs that can be met only through more complex techniques: In order to achieve certain escalation effects, you may have to develop your [Group] and [Strategy]definitions at the same time, or you may need to return to your originally created groups and add to or modify them based on what you want to accomplish. As mentioned earlier, you might create several otherwise identical versions of a group, associating each with a different [Strategy] definition. You may find that there are times when you want a message to go to a particular person, via a destination that TelAlert chooses based on scheduling. This requires creating a set of groups, each referring to all of the destinations linked to each person. Once you have done this, you will have to decide if and when these groups should comprise larger ones and what escalation strategies, if any, should be applied. 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. First, create all your [Configurations] and [Destinations] definitions. Next, create [Schedule] definitions and associate these with the destinations in as hierarchical a way as possible (i.e., by sharing identical schedules whenever possible). Finally, set up a system of [User] definitions that makes sense for what you want to do. You may not need to create any such entries, but if you want TelAlert to require a password on outbound voice notifications, you must at least set up a standard [User] definition ({Operator}, for instance) and set this value in all appropriate destinations. Keep in mind that some additional functionality depends on defining destinations in terms of unique human users (i.e., User=John, User=Cynthia, etc.), and doing this now may make certain tasks easier down the road. 44 TelAlert Administrator Guide - Version 5.7

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? What response options will be provided? What responses can affect the processing of the alert? How would you like an urgent alert handled in a worst-case scenario for instance, if no support personnel could be contacted? Will a response from a message recipient be used to control an external application? Chapter 3: Implementation Planning 45

Work Towards an Economical Configuration Whether you are building your foundation or have begun erecting [Group] and [Strategy] definitions on top of it, it is a good idea to work towards as economical a configuration as possible i.e., one that does not needlessly repeat information but instead uses cross-references and inheritance to make single entries broadly available. Doing so means less work up front and easier maintenance down the road. This principle is mentioned above, with regard to representing work schedules. If everyone is on one of three work schedules, there is no point in creating more than three corresponding [Schedule] definitions. Even if work schedules are more varied, you can avoid entering one for every single destination. For instance, if you are setting up more than one destination for each human user, it may make sense to associate schedules with [User] definitions and include the relevant User value in each [Destinations] definition. There are several other common opportunities for creating an economical configuration. Below are some methods to keep in mind: If you want to include the members of one group in a larger one, include them as a subgroup. You can do this even if you want these destinations treated as if they had been listed individually by setting SubgroupEscalation=True in the larger [Group] definition. If you will be using the same strategy in most or all of your escalations, specify it under [Group] by setting a default Strategy value. Then include a Strategy setting in the definitions of only those groups for which you want another strategy to apply (this group-level strategy specification overrides the default). 46 TelAlert Administrator Guide - Version 5.7

4 Configuration Basics 4.1 Overview An overview of the concepts you will use to configure TelAlert How it works, including a comparison of all of the different tools for performing configuration tasks in Classic TelAlert TADesktop 4.2 TelAlert Configuration Methods: telalert.ini; TADesktop When the telalerte server daemon starts up, it creates a memory-cached copy of the disk binary file telalert.sects, and uses the 'Section' configuration data in the memory-cached telalert.sects copy for all operations. To change the configuration, you must update the disk telalert.sects copy, and then either command telalerte to 'reload' its cache from disk, or stop and restart telalerte. When TelAlert was installed, the first version of the binary telalert.sects file was '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 compliation process.) All subsequent configuration changes must be made by either changing telalert.ini and recompiling telalert.sects; or by directly changing telalert.sects. Here are your options: Editing telalert.ini with a text editor (not a word processor) of your choice -- this is the original method, and is still a popular option with TelAlert. Users that have chosen to use the TADesktop GUI, should NOT edit telalert.ini; in fact, we recommend TADesktop users remove all telalert.ini files to reduce the risk of inconsistent configuration specifications. Using the TADesktop GUI to modify telalert.sects. TelAdmin is used to edit all configuration Sections. The TADesktop Wizards can also be used to modify TelAlert s telalert.sects file.

Figure 6. TADesktop TelAdmin is a graphical configuration tool for Windows similar in design to Windows Registry Editor. TelAdmin is part of the TelAlert Desktop graphical configuration environment. Though TelAdmin runs only on Windows platforms (refer to the Release Notes for supported versions), it may be used to configure TelAlert installations running on UNIX by installing TA Desktop on a Windows machine and pointing it to the TelAlert server. 48 TelAlert Administrator Guide - Version 5.7

Figure 7. TelAlert Desktop Host Configuration The TelAlert Desktop also offers other features that make configuration of your TelAlert installation easier. Please refer to the TelAlert Desktop User s Guide for information on working with TelAdmin, on the differences between the two configuration methods, and on switching between configuration methods. 4.2.1 Choosing a Configuration Method A small TelAlert installation with a single administrator may use the administrator s personal preference to choose between editing telalert.ini and using TADesktop. Refer to the TelAlert Desktop User s Guide for notes on factors such as automatic file backups; physical proximity to the TelAlert server; etc., that should be considered when making your decision. A multi-administrator TelAlert installation, or an installation with multiple roles (user, supervisor, administrator) should probably use TelAdmin. TelAdmin is not a simple graphical configuration-file editor, but rather a front end for a TelAlert-proprietary multiuser transactional database system (the telaconfe server daemon). Using TelAdmin, multiple personnel may simultaneously update the configuration, and a record-locking system ensures that they do not accidentally overwrite each other s changes. Personnel can also manage multiple TelAlert servers from a single instance of TelAdmin. Finally, by implementing the optional [Owner] section and assigning the proper Owner keyword values in other Sections and object definitions, the system administrator may define access rights that control which other Administrators/supervisors/users may access which TelAlert Sections and definitions within TelAdmin. It is possible to implement roles/permissions without TADesktop by splitting telalert.ini into a large number of individual.ini files, each with separate OS access rights, but it s easier to use TADesktop. Chapter 4: Configuration Basics 49

4.2.2 What Make TelAlert Re-Read its Configuration File Means From time to time, this Administrator Guide reminds you that you must make TelAlert re-read its configuration file before your changes will take effect. As mentioned above, this means that you must make the telalerte server daemon reread its memory-cached copy of telalert.sects. How you do this depends on how you configure TelAlert: If you are editing telalert.ini directly, this means issuing a telalert -compile command followed by a telalert -reload command, or by issuing a telalert -init command (which implicitly does a -compile and -reload). Note that if the -compile step encounters errors, the disk copy of telalert.sects will not be updated, and the -reload will either be skipped, or will simply refresh the memory-cached copy with the same data it previously contained. Also note that if you made changes to either the [License], [Port] or [Process] section, you should do a telalert -stop and a telalert -start -init, since these changes affect the number of child processes managed by telalerte. If you are using TADesktop, after selecting the appropriate Configuratation section a window will appear allowing you to enter in the appropriate configuration data. After completing the data you click the Save button and the telalert.sects is updated. See "Configuring TelAdmin s Save and Backup Options" in the TelAlert Desktop User Guide for more details. Note: You may need to stop and restart the TelAlert service after certain configuration sections are updated. 4.3 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 2: Technical Overview for detailed discussion of these terms.) Consider the following example: [Configurations] {OutboundVoiceLive} Type=InteractiveTTS AnswerConfirmationRequired=True ToneConfirmWait=15 UserRequired=True 50 TelAlert Administrator Guide - Version 5.7

This text example s information can be applied to all of the configuration methods: If you are editing.ini files, find the [Configurations] section. Find the existing {OutboundVoiceLive} definition; if there isn t an existing definition with that name, create a new definition. Make sure the new definition begins AFTER any Section default keyword-value entries at the beginning of the section; it may be best to add the new definition at the END of the section, immediately preceding the [Section] header for the subsequent section. See <Emphasis>Modifying a Section s Defaults on page 4-5 If you are editing telalert.ini, the first line tells you that this is an entry to be made in the [Configurations] section. The second line ( ) indicates that there may be other lines, including other definitions, between the start of the section and this entry. (Never actually enter as a line in the file; it will cause an error when you perform the -init.) The rest is the entry to be made that is, to be typed, verbatim, at this point in the file. If you are using TelAdmin, the line [Configurations] tells you to expand the Configuration heading in the tree in TelAdmin s left pane. The line Type=InteractiveTTS tells you to select the InteractiveTTS subtree under Configuration in TelAdmin s left pane. The line enclosed in curly brackets tells you to select (or create) a definition named OutboundVoiceLive in the TelAdmin s right pane. The other lines tell you which keywords to modify, and what values to enter in each. For example, UserRequired=True tells you to choose True from the UserRequired dropdown list. See the TelAlert Desktop User Guide for further information. Figure 8. TADesktop Configuration section Chapter 4: Configuration Basics 51

Figure 9. TADesktop Configuration screen 4.3.1 Singular vs. Plural Section Names To simplify editing telalert.ini, many section names can be headed with either a singular or plural version of their name. Below is the complete list of sections that can take either a singular or plural name: Analog or Analogs Configuration or Configurations Destination or Destinations File or Files Filter or Filters Group or Groups Menu or Menus Message or Messages Notification or Notifications Owner or Owners Pattern or Patterns 52 TelAlert Administrator Guide - Version 5.7

PhonePrefix or PhonePrefixes Port or Ports Process or Processes Relay or Relays Response or Responses Schedule or Schedules Sensor or Sensors Strategy or Strategies User or Users 4.4 Performing Common Configuration Tasks In this section we will provide brief step-by-step guides to performing basic TelAlert configuration tasks. Instructions are provided for those who wish to use the traditional text-editor method: To perform common configuration tasks using TelAdmin, please refer to the TelAlert Desktop Guide. Activating Changes After performing any of the following tasks, you must enter the command telalert -init to make TelAlert recompile telalert.ini to telalert.sects. (If you have modified the [License] section, you must instead stop TelAlert with the command telalert -stop, then restart and initialize it with telalert -start -init.) Modifying a Definition Search telalert.ini for the relevant section name, in square brackets (e.g. [User]), then find the definition name, in curly brackets (e.g. {Bob}). For example: Change or delete the values of the keywords immediately below the definition name, or add new keywords. [User] DialInMaxMessages=0 Menu=MenuAck {Bob} Active=True Password=giants {Jane} Active=True Password=giants Chapter 4: Configuration Basics 53

Be careful to keep your changes between the definition name and the next definition or section name (which marks the end of the definition you are editing). When you are through, save the file and follow the instructions in Activating Changes, above. The [Access], [Battery], [CallProgress], [Files], [Heartbeat], [License], [Limits], [Modem], [PhonePrefixes], and [Power] sections do not use definitions. Modifying a Section s Defaults Only sections that use definitions have defaults. Search telalert.ini for the relevant section name, in square brackets (e.g. [User]). Any keywords that appear after the section name and before the first definition name (in curly brackets, e.g. {Bob}) are default values for the section. For example: {Bob} Active=True Password=giants Modify or delete the keyword values in this area, or add new keywords. When you are through, save the file and follow the instructions in Activating Changes, above. Creating a New Definition Search telalert.ini for the relevant section name, in square brackets (e.g. [Destinations]). Then scroll down until you find the next section name (e.g. [Files]). Immediately above the second section name, type the new definition. Be sure to put blank lines above and below the definition. When you are through, save the file and follow the instructions in Activating Changes, above. Note on Use of Special Characters We strongly discourage using spaces in TelAlert definition names; particularly for [Destinations] and [Groups], but also for [Configurations], [Users], etc. Much of TelAlert's power comes from the ability to invoke Korn or Perl scripts, and these scripts are often passed definition names as parameters. It can be difficult to have these scripts properly parse definition names that contain spaces. We recommend that TelAlert users avoid spaces in definition names from the very beginning. For clarity, we suggest using underscores where you would have used spaces (John_Doe instead of John Doe). 54 TelAlert Administrator Guide - Version 5.7

Creating a New Definition Based on an Existing One Select all the lines that comprise the existing definition, copy, and paste immediately after the existing definition. Be sure the old and new definitions are separated by blank lines, and that the copy is followed by a blank line. Modify or delete the keyword values in the copy, or add new keywords. When you are through, save the file and follow the instructions in Activating Changes, above. Modifying a Section without Definitions Search telalert.ini for the relevant section name, in square brackets (e.g. [User]). Modify or delete the keyword values immediately below the section name, or add new keywords, just as if you were editing default values for a section that uses definitions. [User] DialInMaxMessages=0 Menu=MenuAck {Bob} Active=True Password=giants Be careful to keep your changes between the section name and the next section name, (e.g.between [Modem] and [Modem.Engine]). When you are through, save the file and follow the instructions in Activating Changes, above. Chapter 4: Configuration Basics 55

5 The Role of Ports in TelAlert 5.1 Overview An introduction to the "port" concept in TelAlert and instructions for configuring [Port]definitions to achieve the desired notification behavior. 5.2 What is a Port? Port can refer to the physical connection between the computer on which TelAlert is running and a device (e.g., a modem, electronic signboard, TelAlert Engine) or network. It can also refer to the computer s software-based representation of this connection: the file (e.g., COM2, tty00) that controls it. Within TelAlert, however, port refers to the entry under [Port] in the TelAlert configuration file that identifies a connection as available for sending notifications. This definition also provides TelAlert with the information it needs to use the connected device. For TelAlert to work properly, all required ports must be set up correctly in all three senses of the term. The physical connection between device and computer must be correct. The file associated with the port at the operating system level must be set up correctly. The [Port] definition in the TelAlert configuration file must point to the correct port and accurately and completely describe its properties, and those of the connected device. The first two issues are covered in the Quick Start Guide. This chapter covers the third: the issues you must take into account when setting up, within TelAlert, the ports you need for the kinds of notifications you want to carry out.

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 port s definition, or understand how a port figures in TelAlert notifications. Note that port changes may require a new Key value (under [License]). Additional charges may apply. 5.3 Basic Port Considerations The key element common to all [Port] definitions is Model, which identifies the kind of device connected to the port and allows TelAlert to determine the kinds of notifications for which the port may be used. There are eight supported Model values: Modem for a port to which a modem is connected. DirectModem for a port to which a modem hooked to a leased line is connected. FaxModem for a port to which a DN400E fax modem is connected to send text messages to fax machines. TTS for a port to which a Dialogic telephony card is connected using Text to Speech (TTS). Internet for the computer s Internet connection. Device for a port to which a device of any kind not explicitly supported by the other models is connected (electronic signboards, most commonly). Remote for another installation of TelAlert with which the installation on the local machine is to communicate. Gateway for another installation of a TelAlert server that is behind a firewall. Obsolete Model values: Voice for a port to which a Dialogic telephony card is connected using prerecorded words. (Obsolete) EngineMini for a port to which a TelAlert Voice Engine is connected. (Obsolete) Engine for a port to which a TelAlert Classic Engine is connected. (Obsolete) EngineSensor for a port to which a TelAlert Sensor Interface Unit is connected. (Obsolete) EngineRelay for a port to which a TelAlert Relay Interface Unit is connected. (Obsolete) EngineAnalog for a port to which certain environmental monitors which connect via the Sensor Interface Unit is connected. (Obsolete) 58 TelAlert Administrator Guide - Version 5.7

The other most essential [Port] components vary according to the Model value set. These are discussed below. Modem A [Port] definition of Model=Modem requires Dev, Speed, Modem, and PhonePrefixes values. Dev The name of the file associated with the physical port to which the modem is connected (e.g., COM2,tty00). Speed The speed at which you want to communicate with the modem. Modem The name of the [Modem]section corresponding to the model of the modem. PhonePrefixes The name of the [PhonePrefixes] section describing the attributes of the telephone line to which the modem is attached. For information on these settings, refer to Chapter 6: Dialing the Telephone, and the TelAlert Keyword and Command Reference. DirectModem A [Port] definition of Model=DirectModem requires Dev and Speed values. No Modem value is needed: because the modem will not be used to dial, TelAlert does not need to know the special command set associated with the modem s model. Dev The name of the file associated with the physical port to which the modem is connected (e.g., COM2, tty00). Speed The speed at which you want to communicate with the modem. FaxModem A [Port] definition of Model=FaxModem requires Dev, Speed, Modem, and PhonePrefixes values. Dev The name of the file associated with the physical port to which the modem is connected (e.g., COM2,tty00). Speed The speed at which you want to communicate with the modem. Modem The name of the [Modem]section corresponding to the model of the modem. PhonePrefixes The name of the [PhonePrefixes] section describing the attributes of the telephone line to which the modem is attached. For information on these settings, refer to Chapter 6: Dialing the Telephone, and the TelAlert Keyword and Command Reference. Chapter 5: The Role of Ports in TelAlert 59

TTS A [Port] definition of Model=TTS requires VoiceLine and PhonePrefixesvalues. VoiceLine A single Dialogic telephony card can support a number of telephone lines. A separate [Port] definition is required for each. The telephone line to which a given [Port] definition pertains is indicated by the value it assigns VoiceLine: e.g., 1, 2, 3, etc. The proper value is determined by the number of the jack on the card into which the line is plugged. PhonePrefixes The name of the [PhonePrefixes] section describing the attributes of the telephone line to which the card is attached. For information on these settings, refer to Chapter 6: Dialing the Telephone, and the TelAlert Keyword and Command Reference. Internet A [Port] definition of Model=Internet requires no additional values. Device A [Port] definition of Model=Device requires Dev and Speed values. If the device is a signboard, the definition also requires a value for DeviceSubType and (if DeviceSubtype is set to 2) AlphaAddresses. Dev The name of the file associated with the physical port to which the device is connected (e.g., COM2, tty00). Referring to Physical Ports on Windows On Windows, TelAlert now allows the Dev value under [Port] to be entered in either of two formats Dev=COMn Dev=COMn: where n is the number of the port. Speed The speed at which you want to communicate with the device. DeviceSubtype The type of device. 0 is generic; 1 is a signboard to be managed outside of TelAlert; 2 is a signboard to be managed by TelAlert; 3 is a SpectraLink telephone system. AlphaAddresses A range list that provides the addresses of each of a series of daisy-chained signboards (used only when DeviceSubtype=2). 60 TelAlert Administrator Guide - Version 5.7

Remote A [Port] definition of Model=Remote requires Host and Service values. Host The host name (or IP address) of the remote machine on which TelAlert is installed. Service The name or number of the port on which the remote installation of TelAlert runs. Gateway A [Port] definition of Model=Gateway requires Host and Service values. Host The host name (or IP address) of the gateway machine on which TelAlert is installed. Service The name or number of the port on which the gateway installation of TelAlert runs. 5.4 If You Are Using a Terminal Server If you are connecting a device to a terminal server rather than a port on the machine on which TelAlert is installed, the [Port] definition must be set up differently. It will contain no Dev or Speed value. It may contain other components in addition to the following, but these are the ones specific to terminal servers: DeviceHost The host name (or IP address) of the terminal server. DeviceService The name or number of the port on the terminal server to which the device is connected. NetDevice Set to True. SoftwareParity Set to True if the device to which you are connecting is a modem; False otherwise. You also must modify the configuration of the terminal server itself: Its speed setting must match the speed of the device. Its parity setting must be 8/none except where Model=Device. In this case, the terminal server s parity setting is determined by the DeviceSubtype value: 0 whatever value is needed to match the device s parity setting 1 7/even 2 7/even 3 7/even Chapter 5: The Role of Ports in TelAlert 61

5.4.1 Testing Connectivity on a Terminal Server TelAlert comes with two programs: termserv.exe and testcomm.exe. These programs have a.exe suffix on Windows, but no suffix on UNIX. The termserv program cannot be used to test connectivity to a real terminal server. The purpose of termserv is to make a PC with an attached modem act like a terminal server if you do not have a real terminal server. MIR3 recommends using testcomm to test your real terminal server. Please note that using testcomm with a terminal server is different from using testcomm with a standard modem. Use the following syntax with testcomm for testing your real terminal server: testcomm nm server_name_or_ip server_port if a standard modem is attached to the terminal server, or: testcomm nmg server_name_or_ip server_port if a GSM wireless modem is attached to the terminal server. For example: testcomm nm 1.2.3.4 4001 testcomm nmg lantronix 3001 5.5 More Advanced Port Considerations 5.5.1 Directing Specific Notifications to Specific Ports Type/Types How does TelAlert know to use a given port for a given notification? All notifications are carried out using a [Configurations] entry, which always contains a Type value. Similarly, all [Port] definitions contain, implicitly or explicitly, a Types value (note that this keyword is plural). If the [Configurations] definition s Type value matches one of the items listed as part of the [Port] definition s Types value, that port is considered to be appropriate for notifications based on that [Configurations] definition. Consider these examples: [Port] {Engine1} Active=True Model=Engine Types=Speaker,Display,NumericPager,TextPager,InteractiveTextPager,Mode m,interactivemodem,voice,interactivevoice,relay Dev=/dev/com/2 Speed=19200 Modem=[Modem.EngineCermetek] [Configurations] {TelamonTestPage} Type=TextPager Speed=19200 AreaCode=800 Number=679-2778 62 TelAlert Administrator Guide - Version 5.7

Here, TelAlert recognizes {Engine1} as an appropriate port for processing notifications based on {TelamonTestPage} because TextPager is one of the types listed in the port s definition. If you also had a [Port] definition of Model=Modem, it would (by virtue of its default settings) also have a Types value containing TextPager. Thus, TelAlert could use either port to deliver notifications based on this [Configurations] definition. Which one it would actually use in any given case is determined by (1) the order in which they are listed (in telalert.ini) or the order in which they were created (if you are using 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 Typesvalue for all [Port] definitions of a given model. For instance, the Types value shown above is the default for [Port] definitions of Model=Engine and would hold even if this value were not explicitly assigned in the configuration file. This default value cannot be expanded; it consists of all the types that a given model is capable of supporting. But it can be pared down so that a given [Port] definition will not be used to process notifications of an excluded type. Why would you want to do this? If you use TelAlert to send both text and numeric pages and have both a Voice Engine and a modem at your disposal, you might want to make sure that numeric pages go out through the Engine only (since an Engine s listening abilities make it easier to send numeric pages), while allowing text pages to be sent using whichever was available. By modifying the [Port] definition associated with the modem so that the Types value no longer included NumericPager, you could ensure that TelAlert never used the modem to send numeric pages. Assuming the Voice Engine was the only other appropriate mechanism, TelAlert would always use it instead. Class The Class keyword gives you an additional degree of control over which ports are used for which notifications. By assigning a Class value (an arbitrary integer) to a [Configurations] definition, you can tie that definition to any [Port] definition(s) to which you assign a matching Class value. Almost exclusively, Class is used to ensure that pages sent over a leased line (Model=DirectModem) use the appropriate [Port] definition. For instance, perhaps you send pages using two paging service providers. One you connect to via dial-up, the other via a leased line. To achieve this, you would assign a Class value of 1 to the [Configuration] definition that should use the leased line and the same Class value to the corresponding [Port] definition. In both the dial-up [Configuration] definition and the corresponding [Port] definition, you would allow the Class value to default to 0 (i.e., by not setting a Class value). Sometimes Class is Required There are scenarios in which you might use Class to achieve a desired but optional behavior. A scenario in which you use a leased line and a regular line to send pages via different service providers, however, would require some form of Class-based exclusion. Otherwise, TelAlert would try to use the leased-line port to send other notifications, and these pages would not go through. Chapter 5: The Role of Ports in TelAlert 63

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}. 5.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.) 64 TelAlert Administrator Guide - Version 5.7

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. 5.5.3 Controlling Port Deactivation Due To Errors Ports can encounter errors, such as no dial tone, or IP socket connection failure. For dialup phone line based ports (Engine, EngineMini, FaxModem, Modem, TTS, and Voice), TelAlert can track both Dialing errors at the server end (no response to AT commands, no dial tone, etc.) which block use of the port with ALL service providers; and Connect errors at the provider end (busy signals, no answering modem handshake tone, etc.) which block use of the port with a SINGLE service provider. Generally, TelAlert customers ignore dialup phone line based Connect errors at the [Port] level, tracking them instead at the [Configuration] level. For other ports (Device, DirectModem, Internet, and Remote) TelAlert tracks only Connect errors, since it cannot distinguish between an error at the server end (an unplugged cable) and an error at the service provider end of the connection. Generally, TelAlert customers track these Connect errors at the [Port] level. (Note that the special-purpose EngineAnalog, EngineRelay, and EngineSensor ports do not track either Dialing or Connect errors.) In general, if a customer has multiple interchangeable ports of a particular type that are being used in a rotation (for instance, 3 Modem ports), it is useful to deactivate a port that is encountering consistent Dialing errors, because messages will go out faster if they are not delayed by repeated error retry cycles on the bad port. However, if a customer only has a single port of a particular type, it s more likely that the customer will want to report the errors for follow up, but keep the port active in the hope the problem will be resolved. Chapter 5: The Role of Ports in TelAlert 65

When a port is deactivated for either Dialing or Connect errors, TelAlert will execute [Heartbeat] Error and [Notification] Activation events, if any are defined. TelAlert will then attempt to reactivate the port, if its MaxAutoActivates keyword has a value > 0. It will wait for the time specified by the AutoActivateWait keyword before attempting the reactivation. Once the number of reactivation attempts has reached the value specified by MaxAutoActivates, TelAlert will wait for 60 minutes (regardless of the AutoActivateWait setting), reset its activation attempt counter to zero, and start another cycle of activation attempts up to the MaxAutoActivates limit. For Dialing errors, the keywords DialingErrorLimit, DialingErrorWindow, and DialingErrorLimitDeactivation are used. If both DialingErrorLimit and DialingErrorWindow are zero, errors will not be tracked for port deactivation purposes. Otherwise, DialingErrorWindow is a sliding window of the immediately preceding dialing attempts, and if the number of dialing errors in that sliding window reaches the DialingErrorLimit value, then the port deactivation process will be initiated. Whether or not the port is ACTUALLY deactivated depends on the setting of DialingErrorLimitDeactivation; if False, the [Heartbeat]Error and [Notification] Activation events, if any, will be executed for warning and tracking purposes, but the dialing error counter will be reset to zero rather than deactivating the port (MaxAutoActivatesand AutoActivateWait will not come into consideration.) For example, if DialingErrorLimit=2 and DialingErrorWindow=100, port deactivation will be initiated if just a couple of errors occur; while if DialingErrorLimit=30and DialingErrorWindow=30, then port deactivation will only be initiated if it s become clear that no messages are getting through at all. For Connect errors, there s a similar set of keywords ConnectErrorLimit, ConnectErrorWindow, and ConnectErrorLimitDeactivation. 5.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. 66 TelAlert Administrator Guide - Version 5.7

However, using a remote port, you can have the New York installation pass the notification along to the San Francisco installation, which can in turn page the employee by making a local call. To do this, you must first configure both machines so they agree as to the socket number over which they will communicate. You do this by adding the following line to the operating system s services file: telaremt 25376/tcp # TelAlert Remote (In Windows, services is in the directory %windir%\system32\drivers\etc\services; in UNIX, it is in the directory \etc.) You can specify any socket number, as long as the two machines agree and no other service is using that socket. Likewise, you can call the service anything you like, as long as you use the same name in both places and refer to it correctly in the TelAlert configuration file. After this step, the only required configuration changes are changes to the New York installation s configuration file. You must create a new [Port] definition and add a value to the [Configurations] definition that had been used to page the San Francisco employee. [Port] {SanFranciscoRemote} Active=True Model=Remote Service=telaremt Host=Name/IP Address of SF Machine [Configurations] {SanFranciscoServiceProvider} Type=TextPager Speed=2400 AreaCode=415 Number=5551212 Remote=SanFranciscoRemote LocalIfRemoteDown=True Here, the Remote value in {SanFranciscoServiceProvider} causes notifications originating in New York and based on this [Configurations] definition to be processed using the {SanFranciscoRemote} port definition, which gives the New York TelAlert installation the information it needs to contact the San Francisco installation and have it process the notification. Further, by setting LocalIfRemoteDown to True in {SanFranciscoServiceProvider}, you can ensure that the New York installation will use a local port to send the notification if it cannot make contact with the San Francisco installation. Chapter 5: The Role of Ports in TelAlert 67

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. 68 TelAlert Administrator Guide - Version 5.7

6 6.1 Overview Dialing the Telephone 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. 6.2 What s So Hard About Dialing the Phone? The most common types of TelAlert notifications involve dialing the telephone. In some cases, pages can be initiated over the Internet, either via email or the Web, but in the usual paging scenario, TelAlert uses an external modem to dial the telephone number of the paging service provider s system. Similarly, the usual scenario requires that TelAlert dial a telephone number in order to speak the message, either live to the intended person or into a voice mail system. At its simplest, correctly dialing the phone is effortless: TelAlert simply dials the Number value that you have provided in the [Destinations] or [Configurations] definition. But your situation may require that you take other factors into account to get TelAlert to dial properly. These factors are listed below and explained in greater detail on subsequent pages. TelAlert Does Not Use Windows s Modem Settings In Windows, TelAlert controls the modem directly. It ignores any settings in the Modem and Telephony control panel applets.

6.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. 6.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. 6.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. 6.2.4 Special Dialing Scenarios Aside from the typical local vs. long distance and inside vs. outside considerations, you may find that some scenarios call for special dialing for instance, international calling. There are several keywords you can use to accommodate special dialing needs. 6.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. 6.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 (,). 70 TelAlert Administrator Guide - Version 5.7

6.3 Dialing Logic 6.3.1 Dialing Components The complete number that TelAlert dials for a given notification is usually constructed out of parts. Some of these are typically included in the [Destinations] or [Configurations] definition used to process the notification: Number AreaCode Two other parts may be found here as well. Note that these are not dialed as part of the main number. Extension Mailbox Other parts are typically found in the set of [PhonePrefixes] settings associated with the telephone line (via the relevant [Port] definition) that will be used to send the notification. (There can be more than one [PhonePrefixes] section. A given [Port] definition is linked to a given [PhonePrefixes]section through the former s use of the PhonePrefixes keyword.) When used, the following are dialed before the beginning of the main number (or before the area code, if one is used): LocalAccess LongDistAccess AlternateLongDistAccess InsideAccess SpecialAccess The following are dialed after the main number, to provide billing code information if it is required by your PBX system: LongDistBillingCode AlternateLongDistBillingCode SpecialBillingCode In addition, other values typically set in [PhonePrefixes] allow TelAlert to determine how to proceed when asked to dial a number: InsideDigitCount SpecialDigitCount LocalAreaCode AlternateLocalAreaCodes AlternateLongDistanceAreaCodes Chapter 6: Dialing the Telephone 71

6.3.2 Dialing Process Based on values in the [Configurations] and/or [Destinations] definition, and settings under [PhonePrefixes], telephone dialing proceeds as follows: If the Number value is comprised of a number of digits equal to or less than InsideDigitCount, then TelAlert dials the InsideAccess value (if any), then the Number value. If the Number value is comprised of a number of digits equal to or greater than SpecialDigitCount, then TelAlert dials the SpecialAccess value (if any), then the Numbervalue, and then the SpecialBillingCode value (if any). In these instances, AreaCode is ignored and not dialed. If the Number value is comprised of a number of digits neither less than or equal to InsideDigitCount nor greater than or equal to SpecialDigitCount, then If AreaCode is blank or matches LocalAreaCode, TelAlert dials the LocalAccess value (if any), then the Number value. If AreaCode matches AlternateLocalAreaCode, TelAlert dials the LocalAccess value (if any), then the AreaCodevalue, 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). 6.4 Local Dialing 6.4.1 Normal Local Dialing Normal local dialing i.e., seven-digit dialing is very simple. 1. Set AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual. 2. In the appropriate [PhonePrefixes] section, set the LocalAreaCode value to the local area code. 3. If you have not already done so, set LocalAccess under [PhonePrefixes]. This is the value TelAlert must dial (if any) to get an outside line on which to make a local call. Because the area code matches LocalAreaCode, TelAlert simply dials the LocalAccess value (if any) and the number. 72 TelAlert Administrator Guide - Version 5.7

6.4.2 Ten-Digit Local Dialing In some areas, you must dial the area code for some or all local numbers. This involves some special settings. 1. Set AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual. 2. In the [PhonePrefixes] section: If you use seven-digit dialing for numbers in your own area code, but ten-digit dialing for local numbers in other area codes, enter your area code in LocalAreaCode, and the other local area codes in AlternateLocalAreaCodes. If you use ten-digit dialing for all local calls, leave LocalAreaCode blank, and enter all local area codes, including your own, in AlternateLocalAreaCodes. 3. If you have not already done so, set LocalAccess under [PhonePrefixes]. This is the value TelAlert must dial (if any) to get an outside line on which to make a local call. Here, if the area code matches one of those listed in AlternateLocalAreaCodes, TelAlert dials the LocalAccess value, the AreaCodevalue, and the Number value. 6.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. 6.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. 6.5.1 Normal Long Distance Dialing This is the setup for most long distance dialing that TelAlert is asked to do. Set the Number and AreaCodevalues in either the [Configurations] or the [Destinations] definition. As a general rule, if you dial the same number to reach different people (as in the case of a number that gives you access to a voice mail system, or the number for a paging service provider s system), it makes sense to put these values in the [Configurations] definition. If they are unique to a given person, they belong in the [Destinations] definition. (It is a good idea always to provide an AreaCode, even for local numbers.) You must also make sure that your local area code (LocalAreaCode) is set in the [PhonePrefixes] section associated with the telephone line to be used. Before dialing, TelAlert compares the AreaCode involved in the notification against this value. If they do not match, it knows to dial the area code. Chapter 6: Dialing the Telephone 73

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. 6.5.2 Other Long Distance Dialing The above description covers most long distance dialing that TelAlert will be asked to do. There are related keywords designed to accommodate other scenarios. For instance, your PBX may require you to dial 8 to access a line for calling long distance, but it may treat 800 or 888 calls as local, requiring you to dial the 9 that gives you access to a local outside line and then a 1. Similarly, there are areas in which certain calls require a 1 and an area code but incur no charges and thus are treated by the PBX as local calls. 1. Provide AreaCode and Number values in the [Configurations] or [Destinations] definition, as usual. 2. Enter the relevant area code(s) (e.g., 800, 888, or others) in the list of AlternateLongDistAreaCodes under the appropriate [PhonePrefixes] section. 3. Finally, set AlternateLongDistAccess and AlternateLongDistBillingCode. AlternateLongDistAccess is the value TelAlert must enter to access a line on which this type of call can be placed; it may be the same value required to access an outside line for local calls, followed by 1(e.g., 91). AlternateLongDistBillingCode is a value your organization may use to ensure proper billing or tracking of long distance calls. For instance, each person or each department may have a special billing code. It may be that no such code is required for calls of this type. When TelAlert sees that the area code provided does not match the LocalAreaCode value, it checks the value against those listed for AlternateLongDistAreaCodes. When it finds it listed there, it uses the AlternateLongDistAccess and AlternateLongDistBillingCode values, instead of LongDistAccess and LongDistBillingCode. 6.5.3 Alternate Numbers When appropriate, you can specify an alternate number for TelAlert to dial when it is unable to deliver the message to the primary number. To use this feature, simply specify a value for AlternateNumber in the same definition as Number. When using AlternateNumber, TelAlert uses AlternateAreaCode and AlternateExtension, so if those numbers are needed be sure to specify them as well, even if the values are identical to those for AreaCode and Extension. These alternate numbers are subject to all the same digit-counting and area code logic as Number and AreaCode. 74 TelAlert Administrator Guide - Version 5.7

6.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. 6.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. 6.6.2 Getting an Inside Line Depending on how your organization s PBX is set up, TelAlert may not need to do anything special to dial an inside extension; it may be a matter of simply picking up the line and dialing. Here, you would list the extension as the Numbervalue and set InsideDigitCount to the number of digits comprising your extensions. With these settings in place, TelAlert sees that the Number value is equal to or less than InsideDigitCount and simply dials the number, without worrying about area code. If your PBX requires that some special value be entered before dialing an internal extension, however, you will also need to set an InsideAccess value. Thus, when the InsideDigitCount criterion is met, TelAlert will dial the InsideAccessvalue first, then the Numbervalue. Chapter 6: Dialing the Telephone 75

6.7 Special Dialing Scenarios You may find that some scenarios call for special dialing, aside from the typical local vs. long distance and inside vs. outside considerations. A common example is international calling. There are several keywords you can use to accommodate international calling and other special dialing needs. SpecialDigitCount SpecialAccess SpecialBillingCode SpecialDigitCount works much like InsideDigitCount. You use it to indicate what kinds of numbers TelAlert should treat specially i.e., by ignoring area code considerations and dialing the SpecialAccess value, the SpecialBillingCode value (if any), and then the Number value. A number is treated in this way if it is comprised of a number of digits equal to or greater than SpecialDigitCount (whereas a number is treated according to the rules of inside access if it is comprised of a number of digits equal to or less than InsideDigitCount). If you are in the United States and want TelAlert to dial an international number, typically you would assign SpecialAccess a value of 011 and SpecialDigitCount a value of 9. SpecialBillingCode is optional; whether you assign a value here depends on whether your phone system requires such a billing code to be entered. If you are using a PBX and must dial a number to get an outside line, you would include this number as part of the SpecialAccess value making it 9011, for instance. 6.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. 6.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. 76 TelAlert Administrator Guide - Version 5.7

6.8.2 Dialing a Number, Then Accessing a Mailbox Typically, you use Mailbox when you need TelAlert to dial a number and then, having reached the desired destination, enter other values that allow it to navigate the telephone system in some specific way to access a voice mailbox, for instance, so it can leave a message. For instance, you might use Mailbox if you want TelAlert to dial a number that, once answered, offers the caller the option of pressing 1 and leaving a voice mail message. If an extension were required to reach this destination, you would use both Extension and Mailbox values; in this case, Mailbox would come into play only after the second answer (the answering of the extension). Mailbox can be present in both the [Configurations] and the [Destinations] definition. If values are assigned in both places, both will be used together, without separation, in that order. MailboxWait can be specified in the [Configurations] definition; this tells TelAlert how long to wait after the call has been answered before entering the first of the Mailbox values. For notifications processed using a [Configurations] definition of Type=InteractiveTTS, the presence of a Mailbox value also serves to tell TelAlert that it should leave a message if it does not reach a live person. Where this is the desired behavior, at least some Mailbox value (a comma, for instance) is required by TelAlert, even if the phone system does not require one. 6.9 Inserting Pauses During Dialing You may find that you need to have TelAlert pause at one or more points in the dialing process. When dialing a modem, you can achieve this using a comma (,). You should never include a comma in any part of a number to be dialed by a Dialogic telephony card. When asked to process a notification that involves dialing the phone, TelAlert assembles the number from the relevant components and dials it in its entirety, without any pauses. For instance, it might piece the number together out of 81(LongDistAccess), 800(AreaCode), 555-1212(Number), and 77 (LongDistBillingCode), and then dial 81800555121277, all in a single motion. If you found that your PBX had trouble processing the number when dialed in this way, you could insert pauses to separate the various components. For instance, you might define LongDistAccess as 81, and LongDistBillingCodeas 77. Typically, no pauses would be necessary between AreaCode and Number. The length of the pause created by a single comma is set by the modem s S8 register. In most modems, the factory default is two seconds. To read the register s current value, control the modem with a terminal emulator, and enter the command: ats8? To change the register s setting, use the following command, where n is the length of the pause in seconds: ats8=n Various keywords associated with Extension and Mailbox (ExtensionWait, ExtensionListenDelay, MailboxWait) also provide means of inserting pauses into certain types of voice-based notifications. For more information, refer to Chapter 3 of the TelAlert Voice and Hardware Guide. Chapter 6: Dialing the Telephone 77

6.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 ### AlternateExtension (AlternateAreaCode)AlternateNumber Extension Mailbox -n (###)###-#### (AreaCode)Number Note that you can use these options only to supply missing values. Any values set with keywords will override those specified at the command line. See the TelAlert Keyword and Command Reference for detailed instructions. 6.11 Overriding the Need for Dialtone Some PBXs either do not provide a dialtone at all, or provide an unusual dialtone the modem/dialogic telephony card does not recognize. In such cases it is necessary to customize the appropriate modem.setups file so that the modem or Dialogic telephony card will skip the dialtone check and "blind dial" instead. In this situation, change the modem AT setup commands to skip dial tone detection. While you should check the particular modem s documentation, this is usually done by changing X4 to X3. Normally TelAlert has X4 in the Setup0 string of the modem.setups file. If you use X3, you may also need to change the length of time that the modem pauses between when it goes "off-hook" and when it starts to blind dial. Again, check the particular modem s documentation, but usually this is done by adding a S6=4 to one of the Setup strings (in this case, we re setting a pause of 4 seconds). 78 TelAlert Administrator Guide - Version 5.7

7 7.1 Overview Configuring for Paging Notification 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. 7.2 Getting Started 7.2.1 Needed Information As suggested in Implementation Planning, before proceeding with the work described in this chapter you should gather complete information on each of your organization s paging services. This will be used in setting up [Configurations] definitions for paging. name of service service type (text, numeric, or two-way; dial-up or Internet-based) coverage (local or national) connect speed (needed for dial-up service only) Internet name or IP address for service provider s host machine (needed for 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) 7.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 not uniquely related to TelAlert s paging functionality. Nonetheless, you may wish to set up [User] definitions and refer to one in some or all of your destinations by setting a User value in each. There are a number of reasons for doing this. For instance, you may want to track sent messages aggregately in terms of the users to which destinations belong. If each destination contains a User value, you can do this using the -show command in conjunction with the -user keyword and a valid user name: telalertc -show -user Administrator When given this command, TelAlert displays all active messages associated with the specified user. Another possibility is that you want TelAlert to require users to provide a user ID and password when acknowledging a message on the command line. This is an effect of sending a message to a destination associated with a user (if no password is set in the [User] definition, TelAlert requires only the user ID). You can also use a User setting to link your destinations to other information referred to in your [User] definitions (e.g., schedules). For complete information on creating and invoking [User] definitions, refer to Chapter 12: 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. TelAdmin vs. telalert.ini File Configuration To set up paging notifications, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation. Thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. 80 TelAlert Administrator Guide - Version 5.7

Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 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 6: Dialing the Telephone. Reaching an Outside Line and Other Special Dialing Techniques For any notification method that requires dialing, there are a number of special techniques you may need to employ in order to take into account particular aspects of your organization s phone system or policies: techniques for getting an outside line, for initiating a long-distance call, for dialing when a dialtone is not present etc. For complete coverage of these topics, refer to Chapter 6: Dialing the Telephone. 7.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. 7.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 Vytek Messaging Services, Inc. (/usr/telalert/pagers is the default location for these files). Under [Configurations], create a definition for your paging service, either by hand or by using TelAlert s include function to insert the contents of the appropriate file. 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. Chapter 7: Configuring for Paging Notification 81

7.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: [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=TextPagerand Model=Modem settings would be able to use only the external modem. 82 TelAlert Administrator Guide - Version 5.7

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 some port flexibility while removing some ports completely from its list of options. 7.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, create a separate entry under [Destinations], like so: [Destinations] {JohnTextPager} Configuration=ATTWichitaTextPager PIN=1234567 Note that a text pager destination is typically comprised of: 1. A name that uniquely identifies it within the context of TelAlert. 2. A reference to an existing [Configurations] definition. 3. A PIN that uniquely identifies the pager within the context of the paging service. A destination 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. Note too that you can use the new Wireless Destination Wizard to quickly and easily create new Destinations. Refer to the TelAlert Desktop Guide for information on using the Wizard. 7.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. Chapter 7: Configuring for Paging Notification 83

7.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. 7.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. 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. 84 TelAlert Administrator Guide - Version 5.7

7.3.7 Sending Text Pages via Modem without TAP (Protocol=Chat) Some European text paging services, including Orange GSM/SMS Cellular Phone & Hutchinson Paging, VodaPage Premier Text Paging Service, and Vodaphone GSM/SMS Cellular Phone do not support TAP. Their modem interfaces are designed to interact with an actual human being using a terminal-emulation program. To send pages to such a system, use TelAlert s Chat protocol, which is a variation on the protocol used in UUCP chat scripts. The keywords ChatLogon, ChatScript, and ChatLogoff allow you to define simple scripts that watch for the host to send certain strings, such as Please enter pager number or Send a message, and send other strings, such as 5551212 or node 5213 is down, in return. The Chat keywords values are chat scripts, strings containing pairs of expect and send parameters. An expect parameter defines a string that the paging system will send to TelAlert (such as pager number ); the send parameter that follows defines the string that TelAlert will send in response (such as the pager number associated with the destination or passed with the pin option at the command line). In addition to text, the expect and send parameters may contain the following codes: Codes used in both expect and send parameters Codes used in send parameters only \W## set timeout to ## seconds \E echo check on \ - (hyphen) \e echo check off \b bell \c suppress carriage return at end of send \n line feed \d pause 1 second \r carriage return \p pause.25 seconds \s space \P the pager number (from PIN keyword or pin option) \t tab \A the password (from Access keyword) \\ backslash \M the message text \x## hex character number ## \### octal character number ### If you do not set a timeout with \W##, TelAlert uses the one set by the TextPagerWait keyword, which has a default value of 10 seconds. Turning on echo check in a send parameter will cause the chat script to fail if the paging service does not echo back all of the sent text. 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 - Chapter 7: Configuring for Paging Notification 85

After the user enters the pager number, VodaPage prompts for the message: Please Enter Alpha-numeric Message (up to 80 characters) - After the user enters the message, VodaPage returns to the first prompt, where the user may either enter another pager number or simply hang up to complete the session. An appropriate set of [Configurations] keywords for this service would include: [Configurations] {VodaPagePremierTextPager} Type=TextPager Parity=None Protocol=Chat ChatLogon= Number\s\-\s ChatScript= "" \P characters)\s\-\r\n \M Number\s\-\s ChatLogoff= MaxMessagesPerCall=10 MaxMessageLength=80 After the call is connected, TelAlert executes the chat script defined by ChatLogon. First it waits to see the string Number - (Number\ s\-\s). If the paging service sends that string within the timeout, since there is no send parameter, TelAlert simply moves on to the script defined by ChatScript; otherwise, it fails and goes on to ChatLogoff. If TelAlert gets to the ChatScript string at all, the first thing it needs to do is send the pager number. This script contains three expect/send pairs: 1. The script starts with an empty expect parameter ("") followed by \P, which tells TelAlert to send the value of the ${PIN} variable (that is, the pager number associated with this destination by the PIN keyword or passed at the command line by the -pin option) immediately. 2. After sending the pager number, TelAlert waits for the string characters) - followed by a carriage return (\r) and line feed (\n). If it receives the string before the timeout, it sends the value of the ${Message} variable (that is, the message text); otherwise, it fails and goes on to ChatLogoff. 3. If TelAlert sends the message successfully, it waits for the string Number - (just as it did in the ChatLogon script). If TelAlert (1) receives that string before the timeout, (2) has another message to send to this service, and (3) has not yet sent the maximum number of messages indicated by the MaxMessagesPerCall keyword, TelAlert starts ChatScript over at step 1. Otherwise that is, if If TelAlert has no more messages to send, or it does not receive the string within the timeout it goes on to ChatLogoff. One way or another, TelAlert will eventually get to the ChatLogoff script. Since in this case it is empty (""), TelAlert continues processing the event, normally by hanging up and putting the message(s) in the sent state. 86 TelAlert Administrator Guide - Version 5.7

Detecting Invalid PIN Numbers The example configuration above does not take into account the possibility that you may send VodaPage the wrong pager number, in which case the service will return the error message, Invalid Pager Number. You can handle that possibility by adding the ChatRejected keyword: [Configurations] {VodaPagePremierTextPager} ChatRejected= Invalid With this setting, if the paging service sends the word Invalid while ChatScript is active, TelAlert will assume the PIN number is bad, hang up, and put the message into the message rejected state. If it has other messages to send the service, it will redial the service and continue with the next message. Chat Protocol Example #2: Orange For another example, consider the Orange GSM/SMS Cellular Phone & Hutchinson Paging Terminal Interface. This service presents a user dialing in with a terminal emulation program with the following menu: Please choose an option (do not press return) : S :- Send a message H :- Help E :- Exit If the user presses s, this prompt appears: Enter destination Orange or Hutchison Pager number and press return: After entering the pager number after the colon, the user sees this prompt: Type your message (160 characters max) and press return to send: After the user enters the message after the colon, the system again displays the send/help/exit menu. An appropriate set of [Configurations] keywords for this service would be: Type=TextPager Parity=None Protocol=Chat ChatLogon= Exit\r\n ChatScript= "" S\c return\r\n\r\n: \E\P send\r\n\r\n: \M Exit\r\n ChatLogoff= "" E\c MaxMessagesPerCall=10 MaxMessageLength=160 ChatLogon waits for the last part of the menu (the string Exit followed by a carriage return and line feed). Since the send parameter is missing, TelAlert goes directly to ChatScript when it detects the string, or directly to ChatLogoff if the timeout expires first. Chapter 7: Configuring for Paging Notification 87

ChatScript contains four expect/send parameter pairs: 1. This pair has a blank expect, so it immediately sends an S followed by a carriage return. 2. Waits for the colon after the pager-number prompt, then sends the ${PIN} value. The \E means that TelAlert will check to make sure the paging service echoes back the PIN correctly. 3. Waits for the colon after the message prompt, then sends the ${Message} value. 4. Waits for the menu to appear again, then starts ChatScript over or moves on to ChatLogoff, as discussed in the previous example. If the timeout expires on any of the expect parameters, TelAlert moves on to ChatLogoff. Since ChatLogoff has a blank expect parameter, TelAlert immediately sends an E followed by a carriage return, telling the paging system that it is exiting. TelAlert then continues processing the event, normally by hanging up and putting the message(s) in the sent state. Summary and Additional Information on Chat Scripts To summarize, when you use the Chat protocol, TelAlert performs the following steps: 1. Connects to text paging service by modem. 2. Runs ChatLogon. If the script fails, TelAlert goes to step 4. 3. Runs ChatScript repeatedly, once for each message. If the script fails or TelAlert hits the limit set by MaxMessagesPerCall, it goes to step 4. If TelAlert receives the ChatRejected string, it hangs up, puts the current message into the message rejected state, and goes to step 5. 4. Runs ChatLogoff. 5. If TelAlert has additional messages for the service, it starts over with step 1. TelAlert s chat scripts take the form of pairs of expect and send parameters, separated by spaces. For example, here are four pairs: If an expect parameter is not followed by a send parameter, as in the last of the sections outlined above, when TelAlert detects the expect string it goes on to the next expect parameter or, if as in this case it is at the end of the script, considers the script complete. 88 TelAlert Administrator Guide - Version 5.7

7.4 Setting Up Numeric Paging Setting up numeric paging is similar to setting up text paging in that both involve creating a [Configurations] definition for each service provider and (optionally) a [Destinations] definition for each pager. One difference is that a typical numeric pager is associated with its own unique phone number, so the Number setting (as in phone number) usually appears as part of the destination, not the [Configurations] definition. A more fundamental difference rests with the challenge of getting your modem to communicate with the numeric paging service. When you use TelAlert to send a text page, you call a line reserved for modem-to-modem communication. Your modem whether in the Engine or an external one already understands how to participate in the handshaking process required to communicate with the service provider; no special settings are required to instruct the modem what to do, or when to do it. Some numeric paging services also provide special lines for modem-to-modem communications. If that method is available, we strongly recommend you use it, as described below in Sending Numeric Pages Using the TAP Protocol. Other numeric paging services require TelAlert to dial the same number used by human users. In that case, follow the instructions in Sending Numeric Pages Without TAP. 7.4.1 Sending Numeric Pages Using the TAP Protocol The better of the two alternatives is to send the numeric page using the service provider s 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. Chapter 7: Configuring for Paging Notification 89

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 Typesetting 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 provider s standard numeric paging dial-up number. 7.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. 90 TelAlert Administrator Guide - Version 5.7

Sending Numeric Pages Without TAP, Using a Conventional Modem If you cannot use TAP, and do not have a TelAlert Engine (or have one but are reserving it for voice applications), you will send your numeric pages using a conventional modem. This is problematic, since a standard modem cannot detect the tone or silence that indicates it is time to send the page: it can recognize a busy signal but nothing more. Thus, instead of telling it what to listen for and under what conditions to respond, you are limited to telling it how long to wait before delivering the message, before ending the call, etc. In other words, the modem does much of its work blind. For that reason, the crucial keyword in such configurations is called BlindAnswerWait. 1. Under [Configurations], create an entry for the numeric paging service based on the appropriate configuration information found in the file called numeric in the Pagers subdirectory. For example: [Configurations] {NumericPager} Type=NumericPager Model=Modem BlindAnswerWait=10s PINRequired=False Terminator=# PostMsgWait=2s 2. Make necessary changes to this [Configurations] definition, as detailed below: First, be sure the definition points exclusively to the TelAlert modem port. If you also have an Engine port configured and both list NumericPager among their types, having Type=NumericPager in the [Configurations] definition is not sufficient. Above, Model has been set to Modem; this, in combination with the Type value, should uniquely identify the modem port. Second, set PINRequired to False if your numeric paging service does not require a PIN (typically, local numeric paging services assign each pager a unique local phone number that serves to identify it). Third, examine the settings related to the timing of TelAlert s delivery of the message. Remember, your modem cannot listen for or respond to a tone; here, it is simply a matter of coming up with a blind timing pattern that allows it to deliver the message at the right time, relative to what takes place at the other end of the line. You will have to experiment with these settings to find the combination that works best with your service. These settings are: BlindAnswerWait 10s specifies how long after the completion of dialing TelAlert will wait before blindly delivering its message. If this is set too low, TelAlert may deliver the message when the phone is still ringing. If it is set too high, the service may hang up on TelAlert before it delivers the message. To determine what value to assign here, call the numeric paging service and count the seconds that elapse from the time you finish dialing until you hear the tones. Repeat this procedure until you are confident of the consistency of this timing. To accommodate each additional ring, you will need to add a full six seconds to the BlindAnswerWait value, since a standard ring cycle is six seconds. You must make sure that this additional time does not cause the service to time out on occasions when the line is answered more quickly. Chapter 7: Configuring for Paging Notification 91

Terminator This is the tone that TelAlert issues to signal the end of message transmission. Most services ask callers to press the pound (#) key after entering the numeric message. After issuing this tone, TelAlert waits the amount of time specified by PostMsgWait and hangs up. PostMsgWait 2s specifies how long after message transmission (which includes the issuing of the terminator tone) TelAlert should wait before hanging up. This is needed in cases where the service provider issues a fake busy signal after it hears the terminator tone; if you permit the modem to detect this, it will report that it received a busy signal and you will not know whether the message was actually delivered. Tone Recognition Settings Not Needed Some of the configuration settings used for sending numeric pages via the Engine s modem are not needed here (e.g., ToneWait, AnswerToneOnly, ToneRepeats, MinToneOn, MaxToneOn, MinToneOff, MaxToneOff, and PreMsgWait). If you model your standard numeric paging [Configurations] definition on a definition that contains these settings, you can either delete them or leave them intact. Assigning a value to BlindAnswerWait causes TelAlert to ignore all settings related to tone recognition. 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 92 TelAlert Administrator Guide - Version 5.7

7.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. 7.5.1 Creating a Two-Way Pager [Configurations] Definition To enable two-way paging with TelAlert, you must set up at least one two-way pager [Configurations] definition. You should be able to find the information you need in one of the pager configuration files provided by MIR3 (telalert/pagers is the default location for these files). Under [Configurations], create an entry for your two-way paging service, based on the information you find in the appropriate pagers file. This definition will look something like this: [Configurations] {SkyTelITwoWayTextPager} Type=InteractiveTextPager Protocol=TMEX Parity=None MaxMessagesPerCall=100 Speed=19200 AreaCode=800 Number=679-2778 Note the type, InteractiveTextPager, and the I (for interactive ) in the name: SkyTelITwoWayTextPager. Other [Configurations] definition names may refer to two-way paging, but only if Typeequals InteractiveTextPager will the definition support two-way paging (some other two-way [Configurations] definitions, of Type=TextPager, are for sending regular text pages to two-way pagers). The Protocol keyword refers to the protocol used to send information back and forth from the pager. The pagers that TelAlert supports use many different protocols: refer to Chapter 2 of the TelAlert Keyword and Command Reference for details on the Protocol keyword. Above, Parity=None is a setting required by the protocol used for two-way paging, TMEX (Telocator Message Entry). MaxMessagesPerCall is a limit specified by your service provider; the number entered here must not exceed this limit. The Speed setting should be correct for the service provider, assuming you are using configuration information from the Pagers directory. Chapter 7: Configuring for Paging Notification 93

7.5.2 Pointing to a Modem TelAlert can use either an external modem or the modem in the TelAlert Voice Engine (assuming an Engine is installed) to send two-way pages. TelAlert determines which one to use by reading keywords in each of the [Port] definitions and matching these values to the values assigned to corresponding keywords found in the relevant [Configurations] definition. For instance, the sample [Configurations] definition presented above contains a setting Type=InteractiveTextPager. Assuming you have made no changes to the [Port] definitions labeled {Modem}, you will find in each a Type setting in which InteractiveTextPager is one of a series of listed items. Under such a setup, both ports can be used for sending pages to destinations that invoke this [Configurations] definition; TelAlert goes through the list of matching [Port] definitions in the order in which they appear under [Port], choosing the first one that is not currently in use. A [Configurations] definition can also be tied to a particular port by including a Model setting and matching its value to the value assigned this keyword in the desired [Port] definition. Class=anyinteger is yet another setting that can be used in this way. Why is there more than one keyword for associating a [Configurations] definition with a port? If two are used in a given [Configurations] definition, TelAlert will use a port only if both values match those assigned to the corresponding keywords in the [Port] definition. If three are used, all three must match. Consider the following: [Port] {EngineMini} Active=True Model=EngineMini Types=Speaker,Display,NumericPager,TextPager,InteractiveTextPage r,& Modem,InteractiveModem,Voice,InteractiveVoice,Relay Dev=/dev/tty00 Speed=19200 Modem=EngineMini {Modem} Active=True Model=Modem Types=NumericPager,TextPager,InteractiveTextPager,Modem,Interact ivemodem Dev=/dev/tty00 Speed=19200 Modem=Hayes1200 Given these settings, a [Configurations] definition that contained a Type=InteractiveTextPager setting could use either port. By contrast, a [Configurations] definition containing Type=InteractiveTextPagerand Model=Modem settings would be able to use only the external modem. 94 TelAlert Administrator Guide - Version 5.7

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. 7.5.3 Creating Two-Way Pager Destinations For each pager to which you want to send two-way pages, create an entry under [Destinations], like so: [Destinations] {JohnTwoWayTextPager} Configuration=SkyTelITwoWayTextPager PIN=1234567 Note that a two-way pager destination is typically comprised of: 1. A name that uniquely identifies it within the context of TelAlert. 2. A reference to an existing [Configurations] definition. 3. A PIN that uniquely identifies the pager within the context of the paging service. A [Destinations] definition may contain other settings as well, including User and Schedule. For a complete list, refer to Chapter 2: Keyword Reference, in the TelAlert Keyword and Command Reference. Though recommended, setting up destinations is optional. As explained below, at the beginning of Enabling Responses, you can invoke a [Configurations] definition and provide destinationrelated information on the command line. 7.5.4 Enabling Responses You can send a message by invoking a destination in a command like this: telalertc -i JohnTwoWayTextPager -m "this is a test" You can also send a message using the [Configurations] definition only, passing destination-related information on the command line: telalertc -c SkyTelITwoWayTextPager -pin 1234567 -m "this is a test" Chapter 7: Configuring for Paging Notification 95

Unless you attach a menu of responses to the messages you send, you cannot take advantage of the medium s two-way functionality. To do this, follow these steps. 1. Examine the response entries found under [Response]. These are ready for you to refer to on the command line. For example: [Response] {Basic} NumReplies=6 Acked=1 AckedHold=3,4,6 NotAcked=2 Released=5 Reply1=Yes Reply2=No Reply3=Hold Reply4=Info #Reply4 means the user will be sending additional info #(requires use of a special notification script) Reply5=Release Reply6=Ping #Reply6 runs a script that pings a node and reports the result #to the user (requires use of a special notification script) You can invoke any existing [Response]definition when sending a message to a two-way pager using an interactive [Configurations] definition: telalertc -i JohnTwoWayTextPager -m "this is a test" -response Basic -ackwait 15m In this example, these responses will show up on the pager, in the form of a menu of choices: Yes, No, Hold, Info, Release, Ping. Each response maps to a TelAlert command by way of the Acked, AckedHold, NotAcked, and Released settings in the [Response] definition, so that Yes positively acknowledges the message, No negatively acknowledges it, and so on. -ackwait is Essential to Responses The -ackwait parameter is essential anytime you want to make it possible for the message recipient to respond: without it, TelAlert would not hold on to the message after delivery and thus would not be in a position to accept a response. 96 TelAlert Administrator Guide - Version 5.7

2. Modify the existing [Response] definitions, or create new ones, as necessary. For instance, you might want to make the above set of responses even more basic by removing Info and Ping, so that there is a one-to-one correspondence between menu items and TelAlert commands. Or you might want to add more responses that map to Acked, AckedHold, NotAcked, or Released, so that these responses carry out the corresponding action within TelAlert while providing more detailed information. For example: [Response] {DetailedReplies} NumReplies=8 Acked=1,2 AckedHold=5,6 NotAcked=3,4 Released=7,8 Reply1= Yes<1Hour #Reply1 means yes, in less than one hour Reply2= Yes>1Hour #Reply2 means yes, in more than one hour Reply3=NoBusy #Reply3 means no, I am busy Reply4=NoOffDuty #Reply4 means no, I am off duty Reply5=HoldWillHandle #Reply5 means hold, I will handle it Reply6=HoldWillDelegate #Reply6 means hold, I will assign this to someone else Reply7=ReleaseFixed #Reply7 means release, this is fixed Reply8=ReleaseNotFixed #Reply8 means release, but this is not fixed Here, two responses map to each command, allowing the respondent to positively acknowledge the message in two ways, negatively acknowledge the message two ways, and so on. (The intended meaning of each response is explained in a comment line.) The text of the response will be available in the telalert.trail file. You can make much better use of this sort of response-related information when using TelAlert s notification feature. For more information, refer to Enabling Notifications below. Chapter 7: Configuring for Paging Notification 97

7.5.5 Enabling Polling Polling is the means by which TelAlert retrieves the responses returned by message recipients. Polling is necessary because a response to a two-way page is not automatically delivered to the originator of the page; rather, the service provider holds it until contacted by the originator, at which point it hands it over. TelAlert knows to poll for responses whenever it sends a page that meets three conditions: The page must use a [Configurations] definition in which Type is set to InteractiveTextPager. The command generating the alert must specify an -ackwait value. The command generating the alert must specify a set of responses. In addition, the message must still be active: it must be in either an ackwaitor ackheld state. Otherwise, from TelAlert s point of view, the message no longer exists and there is no reason for TelAlert to poll for a response. The only aspect of polling that it is possible to control is the frequency with which TelAlert dials in to check for responses. You can do this by changing the CheckITPRepliesInterval setting under [Limits]. The default is 5m. Note that this single setting is used by all [Configurations] definitions of Type=InteractiveTextPager. You may find that a value of less than 5m interferes with TelAlert s attempts to deliver messages, since it will cause TelAlert to spend more time polling for responses. At the same time, this value must be less than any -ackwait value you assign; otherwise, messages will always expire before TelAlert has a chance to dial in and check for a response. 7.5.6 Enabling Notifications Responses are useful because they allow message recipients to affect message status by remotely issuing a TelAlert command. Customized responses are useful because they allow message recipients to provide extra information information in addition to the information implied by an -ack, -nak, -hold, or -release. Customized responses become considerably more powerful when used in conjunction with TelAlert s notification feature, which allows the text of a response to be passed to an external target a log file or TelAlert s controlling application, for example. This makes it much easier to track the information returned with a response. It also greatly extends the user s ability to carry out procedures remotely, since responses can be set up to trigger highly customizable scripts. Because the notification feature has a wide range of applications many unrelated to two-way paging complete information on setting it up is provided elsewhere in this guide. For detailed instructions, refer to Chapter 15: Processing Events. 98 TelAlert Administrator Guide - Version 5.7

7.6 Setting Up Requests: Unsolicited Messages From Two-Way Pagers 7.6.1 Receiving Requests SkyTel and Bell South Wireless Data (BSWD) offer two-way paging services that support unsolicited messages. In other words, a person with one of these pagers can use it to initiate a message also called a request that is not a response to any page. The person or program dialing in to the paging provider s system to check for messages can ask for messages that have come in response to a specific page, or for all unsolicited messages. To enable this feature, set PollRequests to True in the relevant [Configurations]. This setting will cause TelAlert to poll for unsolicited messages at the interval specified in [Limits] by the CheckITPRepliesInterval keyword. (This value applies to all polling for all configurations and paging services.) Any configuration in which PollRequests is set to True also requires ServerPIN and Access values. ServerPIN is the identifier that tells the service who is asking for the messages. Access is the security code or password associated with the account. For BSWD, ServerPIN is the DAS account Administrator. Note that BSWD requires ServerPIN and Access values for both regular two-way polling and unsolicited polling. SkyTel does not require them for regular two-way polling, but they will be used if you provide them. 7.6.2 Having Requests Trigger [Notifications] Actions A reply received in response to a two-way page can trigger an action defined in [Notifications]. The key to this is the NotificationReply keyword in the configuration, which points to the correct [Notifications] definition. To have unsolicited messages i.e., requests retrieved by TelAlert trigger an action, use the NotificationRequest and Request keywords. The first goes in the relevant [Configurations] definition and points to a [Notifications] definition, which in turn specifies a Request value. For detailed information on using this feature, refer to Chapter 15: Processing Events. 7.6.3 Simulating Requests for Testing Purposes You can use the -request command option to submit simulated requests to TelAlert at the command line: telalert -request string The request will be processed using the [Notifications] definition specified by the NotificationRequest keyword in the [Limits] section. This setting can be made to determine what [Notifications] definition is used in other circumstances, as well. For example, you could create a voice menu script that offers a "place a request" option to users who call and identify themselves to the TelAlert Voice Engine. This script could then process the user-provided input by creating and executing a TelAlert command that includes -request input. In such a case, the [Notifications] definition referred to by the [Limits] section s NotificationRequest keyword will be used to process this command. Chapter 7: Configuring for Paging Notification 99

7.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. 7.7.1 One-Way Internet-Based Paging One of the one-way Internet protocols supported by TelAlert is SNPP, Simple Network Paging Protocol. Using SNPP, TelAlert can pass a message (along with information identifying the intended destination) to an application the service provider maintains on a machine accessible over the Internet. This application then takes the information and sends the page. 1. To send pages via SNPP, first create an Internet entry under [Port]: [Port] {Internet} Active=True Model=Internet Types=Email,TextPager,InteractiveTextPager Active means that the port is active and available to be used by TelAlert. Model and Types are keywords that form the association between this [Port] definition and the [Configurations] definition(s) in which these values match. 2. Next, set up a [Configurations] definition that uses the [Port] definition of Model=Internet. Use the information you find for your service provider in the appropriate pagers file. On Windows systems, these files will be in %TELALERTCFG%\Pagers; on UNIX systems they will be in ${TELALERTCFG:-/usr/telalert}/Pagers. If you cannot find the pager configuration you need in this directory and are having trouble creating one, please contact our Technical Support staff. We may have already written the configuration you want. The [Configurations] definition will look something like this: [Configurations] {PagemartSNPPTextPager} Type=TextPager Protocol=SNPP Model=Internet MaxMessagesPerCall=100 Host=pagemart.net #Host=198.78.254.130 Service=444 TextPagerWait=30s Type and Model determine which port this [Configurations] definition uses; both the values assigned here must match the values set in the [Port] definition for that port to be used. Since this is an Internet transmission for one-way paging, it will use Protocol=SNPP. MaxMessagesPerCall is a limit determined by the service provider; the number you enter here must not exceed the provider s limit. Host is the Internet name or IP address of the machine running the paging application (you may need to contact your service provider to learn the correct value). Service is the Internet port or service name used by SNPP; the default, as defined by this standard, is 444. 100 TelAlert Administrator Guide - Version 5.7

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" 7.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 their telalert.ini file. [Port] Definition The [Configurations] definition you are going to select or create will use the Internet port represented by the following definition. If this definition is not already in place, it may mean that your license does not support an Internet port. In this case, you should contact your MIR3 sales representative. [Port] {Internet} Active=True Model=Internet Types=Email,TextPager,InteractiveTextPager This [Port] definition is associated with particular [Configurations] definitions by means of the Model and Types lines. Active=True means that the port is available for use by TelAlert. Chapter 7: Configuring for Paging Notification 101

[Configurations] Definition Next, choose and set up a [Configurations] definition. Use the information you find for your service provider in the appropriate pagers file. On Windows systems, these files are located in %TELALERTCFG%\Pagers; on UNIX systems they are located in ${TELALERTCFG:-/usr/ telalert}/pagers. Your configuration will look something like this: [Configurations] {SkyTelInetTwoWayTextPager} Type=InteractiveTextPager Protocol=TMEX Model=Internet MaxMessagesPerCall=100 ServerPIN=serverpin Access=password PollRequests=False Host=skysock.skytel.com Service=2502 DialBackup=5 Parity=None Speed=19200 AreaCode=800 Number=679-2778 The values assigned to Type and Model tie this [Configurations] definition to one of your [Port] definitions (in this case, {Internet}). The communication protocol is TMEX. MaxMessagesPerCall is a limit determined by your service provider; the number you enter here must not exceed this limit. ServerPIN and Access will usually be needed,; contact your service provider if you do not have the correct values for these. Host is the Internet name or IP address of the machine running the paging application (you may need to contact your service provider to learn the correct value). Service is the Internet port or service name used by TMEX; the default, as defined by this standard, is 2502. The last five settings in this entry, beginning with DialBackup, are optional. Taken together, they permit pages to be sent via dial-up if TelAlert encounters (in this case) five connect failures in the course of attempting to send a page using this [Configurations] definition. In the current example, as soon as TelAlert encounters the fifth connection error in attempting to send a page, it dials the number you provide here and, still using the TMEX protocol, transmits the message to the service provider. Parity=None is the correct value relating to all dial-up TMEX paging, as is the Speed setting presented here. Connecting to BSWD via the Internet Bell South s two-way paging service allows you to initiate pages via the Internet. To take advantage of this capability, TelAlert has been modified to support the associated protocol. Thus, in the relevant [Configurations] definition, Protocol should be set to XSOCKET. This [Configurations] definition also requires ServerPIN (DAS account Administrator) and Access(password) values. 102 TelAlert Administrator Guide - Version 5.7

Connecting to Sprint via the Internet Sprint no longer allows pre-formatted responses via SNPP. By setting the [Configurations] keyword AddResponseToMessage to true, TelAlert will add the Response list to the messages that are being sent. The User of the device must reply with the full text of the response, no menu will be available. The response could be in the form of: ${SendID} yes, where ${SendID} is the SendID of the message, if the ${SendID} is 7612, the User would reply with 7612 yes. The following parameter settings are different than the standard settings: ProtocolMask=0x0011 AddResponseToMessage=True An example [Configurations] paragraph for Sprint SNPP follows. [Configuruations] {SprintSNPPTwoWay} Comment=Sprint SNPP service for Two-Way messaging Active=True Type=InteractiveTextPager Model=Internet Host=snpp.telemessage.com Service=444 PagerType=2 Protocol=SNPP ProtocolMask=0x0011 AddResponseToMessage=True InternetSubtype=0 ModemSubtype=0 DialBackup=0 DialBackupClass=0 DialBackupProtocol=TAP # DialBackupProtocolMask: DialBackupProtocolMask=0 DialBackupServiceMaxMessageLength=238 DialBackupServiceSupportsMultiBlocks=False PollRequests=False ServerPIN=*UserNameProvidedBySprint* Access=*PassCodeProvidedBySprint* From='telalert@*yourdomain.com* ReplyTo='' To='' [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. Chapter 7: Configuring for Paging Notification 103

Polling Polling is the means by which TelAlert checks for responses to two-way pages it has sent. When it polls, TelAlert uses the same [Configurations] definition that it used to send the original page. If you send a two-way page via the Internet, TelAlert attempts to retrieve a response by the same medium. If DialBackup is specified and TelAlert encounters the specified number of connect errors in attempting to poll, it will use the DialBackup information to poll by dial-up. For more detailed information, refer to the discussion of polling in the preceding section on regular (i.e., non- Internet-based) two-way polling. [Notifications] Definition As discussed under Setting Up Two-Way Paging, response functionality can be significantly expanded using TelAlert s notification feature, which allows you to pass customized responses to a log file or another application. Thus, you can enable a response that will update a trouble ticket in the controlling application with which you have integrated TelAlert; likewise, you can enable a response that, by triggering a script, will carry out a diagnostic or administrative operation. Because the notification feature has many uses that are not specifically related to paging, it is covered elsewhere. For detailed instructions, refer to Chapter 15: Processing Events. 7.8 Initiating Pages via Email Some paging service providers allow you to initiate pages by sending email to an account linked to a pager. Normally, the practice is to address such messages with the recipient s PIN and the provider s domain, for instance, 1234567@pagingprovider.com. To set up TelAlert to use this method, use the To keyword in a [Configurations] definition of Type=Email to define the provider s domain, and the PIN keyword in associated [Destinations] definitions to provide the rest of the address. For example: [Configurations] {EmailPage} Type=Email 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 configuration s To value, and use that as the address for the email message. The more important application of this feature, however, is for users who store PINs outside of TelAlert and pass them on the command line, bypassing any references to destinations in the configuration file. Here, as long as the invoked [Configurations] definition contains the correct To value (see above), the command line need not contain any email-related information. For instance: 104 TelAlert Administrator Guide - Version 5.7

telalertc -c EmailPage -pin 1234567 2345678 3456789 -m "this is a test" 7.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. 7.9 Adding ID Numbers to Pages It is often useful to add TelAlert s internal tracking numbers to pager messages. (For an overview of TelAlert s ID numbers, refer to Command Line Options Following a Send in Chapter 3 of the TelAlert Keyword and Command Reference.) Note that you can add ID numbers when using any notification medium. The techniques are covered here simply because they are more useful with pagers than with other media. Adding Send IDs to Pages Adding the send ID gives one-way pager users the information they need to respond to pages via the command-line or Web client, or by dialing into a TelAlert Voice Engine. You can make TelAlert add the send ID automatically to all messages sent using a particular [Configurations] or [Destinations] definition by including the following line: AddSendIDtoMessage=True With this setting, messages sent using this configuration or destination will be preceded by the send ID number and a colon. For example: 6488:node 5681 down Alternatively, you can add the send ID to the message manually by including the ${SendID} substitution parameter at the command line. For example: telalertc -i BobNumericPager -m "\${SendID}:node 5681 down" -ackwait 1h Adding Track IDs to Pages Most paging services have no way of tracking whether a pager has actually received a message or not. With such services, you can easily miss a message and never know it. TelAlert s track ID feature deals with this potential problem by automatically numbering each message sent to a particular destination. With this option enabled, users can tell if a page is missing by the gap in sequence. For example, consider this series of pager messages: 145:node 1250 down 146:node 5206 down 148:node 9864 down In this case, the user would know to contact TelAlert (through the Web, command-line client, or dialing in to a TelAlert Voice Engine) to check for a message with track ID 147. Chapter 7: Configuring for Paging Notification 105

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 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 When you set AddTrackIDtoMessage to True, you may also wish to set an AcknowledgeWait value in the same definition to ensure that messages sent without an - ackwait will be active long enough to be recovered in the event they are not delivered to the pager. 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 106 TelAlert Administrator Guide - Version 5.7

8 8.1 Overview Configuring for Voice Notification Information on software configuration for voice functionality has been moved to the TelAlert Voice and Hardware Guide. 8.2 Configuration for Voice Notification now in TelAlert Voice and Hardware Guide Information on Configuring for Voice Notification is now in the TelAlert Voice and Hardware Guide Since TelAlert voice functionality requires a Dialogic telephony card, the information on software and hardware configuration for voice functionality now resides in the TelAlert Voice and Hardware Guide. Voice is the second most commonly used notification medium supported by TelAlert. If you plan to use TelAlert s voice capability, you should have purchased a Dialogic telephony card and installed and tested it following the directions in the TelAlert Voice and Hardware Guide. Once the Dialogic telephony card is in place, most of your work will consist of setting up specific [Configurations] and [Destinations] definitions appropriate for voice notifications. All the information regarding the Dialogic telephony card and software configuration for voice functionality is now covered in the TelAlert Voice and Hardware Guide.

9 9.1 Overview Configuring for Other Notification Media 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 DEVICES (in TelAlert 6e) [Destinations] definitions (in core TelAlert) for these media and using these definitions and the TelAlert command line to send messages. Note: For users of TelAlert 6e, Destinations are refered to as Devices in the TelAlert 6e web interface. 9.2 Getting Started 9.2.1 Needed Information For electronic signboard notification setup, you need to know: the name of the physical port to which it is connected, or if it is connected to a terminal server, the servers s IP address and the number of the appropriate TCP port For email notification setup, you need to know: the names and email addresses for all the people to whom you want to be able to send messages the Internet name or IP address of the mail server TelAlert will use to send email the address you want to appear in the From field on every email For SpectraLink LCD notification setup, you need to know: the extension numbers of all the SpectraLink telephones to which you want to be able to send messages the address of the serial port to which the Open Applications Interface Gateway is connected

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 carrier s server the exact TelAlert Web client URL to which recipients should go to retrieve their messages To set up TelAlert to send two-way messages to Nextel cellular phones equipped with text screens, you need to know: the host name of the Nextel server the PIN for any phones to which you will be sending messages an email address within your organization s domain to which responses can be sent 110 TelAlert Administrator Guide - Version 5.7

9.2.2 General Considerations 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]. [User] Definitions Strictly speaking, a [User] definition can be used in conjunction with any destination (or any [Configurations] definition, for that matter). However, a [User] definition has few clear-cut applications in the case of electronic signboard and command line notifications, since these are typically not associated with human users. In the case of email notifications, the concept of user has the same general relevance as for most other notification media: by including a User setting in each of your email destinations and creating corresponding [User] definitions, you can: require message recipients to provide a password when responding to a message via the command line track messages in terms of the people associated with the destinations to which they are sent link these destinations to information (e.g., on-duty schedules) referred to in the [User] definitions You may want to include a User setting in most or all your destinations to take advantage of one or more of these features. For complete information on creating and invoking [User] definitions, refer to Chapter 12: Representing Users. TelAdmin vs. telalert.ini File Configuration To set up the notifications covered in this chapter, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation: thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. Chapter 10: Applying Filtering Techniques 111

9.3 Setting up Electronic Signboard Notification 9.3.1 Signboard Overview There are two basic approaches to setting up Alpha electronic signboards to display TelAlert messages. (Alpha is the only brand of signboard TelAlert supports directly.) The standard and easier method is to let TelAlert control message display (DeviceSubType=2 in the signboard s [Port] definition). You set the maximum number of messages to rotate among, whether to drop older messages to make room for new ones, and a few other simple options, and TelAlert handles the details. Alternatively, you can configure TelAlert to let another application control message display (DeviceSubType=1 in the signboard s [Port] definition). This option is popular among call-center users and others who want their signboards to display a fixed number of continuously updated messages displaying such current information as the number of calls waiting and the average hold time. Whichever approach you choose, the basic elements comprising a signboard setup are the same: a [Port] definition and a [Configurations] definition. A [Destinations] definition is another common piece of the configuration, though it is not always required. 9.3.2 Initial Signboard Firmware Setup If you have more than one signboard, you will need to set each to use a different serial address (the number portion of the Mailbox keyword value, discussed below). Depending on the model, you may perform this task using buttons on the signboard, its remote control, or bundled software. The default value is usually 01, so if you have only one signboard this step is probably unnecessary. If your signboard does not work, check to make sure the serial address is set to 01. Note that this serial address has nothing to do with your computer s serial port number. It is simply an arbitrary hexadecimal number that allows you to control multiple signboards individually. Choose addresses that use the digits 0 through 9 only; do not use A through F. If you have many signboards, you may wish to group them by assigning serial addresses with the same first or last digit, for example 01, 02, and 03, or 10, 20, and 30. Using Mailbox wildcards (discussed below), you can then use a single TelAlert send to display the same message on all signboards in a group. For example, if you configured the signboards in your help-desk offices to use 01, 11, and 21, and those in network managers offices to use 02, 12, and 22, you could use commands like the following to send messages to the two groups: telalertc -c signboard -mailbox?1 -m "hello help desk office" -ackwait 10m telalertc -c signboard -mailbox?2 -m "hello network managers" -ackwait 10m 9.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. 112 TelAlert Administrator Guide - Version 5.7

9.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. 9.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 A signboard connected to a terminal server does NOT have a dev= value. Instead, it includes the following keyword values: {SignboardPort} NetDevice=True DeviceHost=192.168.168.140 DeviceService=3001 Chapter 10: Applying Filtering Techniques 113

Model This keyword identifies the kind of device connected to the port and allows TelAlert to determine the kinds of notifications for which the port may be used. In [Port] definitions relating to signboards, it must be set to Device. Types Not relevant to signboards. Where Model=Device, Types must also be Device. DeviceSubtype Set to 2 if you want TelAlert to control message display; set to 1 if you want TelAlert to let another application control message display. SoftwareParity Not relevant to signboards. Leave blank or set at default value of False. Dev The name of the physical port to which the signboard is connected. Speed For signboards, must be set to 9600. AlphaAddresses A list of the serial addresses (discussed under Initial Signboard Firmware Setup above) of daisy-chained signboards sharing this port, expressed as two-digit decimal numbers separated by commas: for example, 1-3,11-13,21-23. For a single signboard, normally left blank or set at default value of 1. (This keyword is ignored when DeviceSubtype=1.) NetDevice Set to its default value of False if the signboard is connected to serial port of the computer running telalerte. Set to True if the signboard is connected to a terminal server. DeviceHost The IP address or network name of the terminal server to which the signboard is connected. DeviceService The number of the TCP port TelAlert is to use to communicate with the terminal server to which the signboard is connected. 9.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 TextFilesEmptyMessage= \x1b m \x1c3\x13 Type With signboards, always set Type=Device (to match the setting in the [Port] definition). DeviceSubtype Must be set to match the setting in the [Port] definition. 114 TelAlert Administrator Guide - Version 5.7

Parity For signboards, must be set to Even. Mailbox This keyword uniquely identifies the signboard with which this [Configurations] definition is associated. Mailbox values are comprised of (1) a letter indicating type (one-line vs. two-line, for instance) and (2) a two-digit hexadecimal number (01 to FF) corresponding to the signboard s serial address (discussed under Initial Signboard Firmware Setup above). Mailbox should normally be set to Z in the [Configurations] definition. (The Z type will work with all models.) Set the serial address in the [Destinations] definitions, and TelAlert will combine the type and serial address values when sending messages to the destinations. With this setup, you can also specify the serial address on the command line, for example: telalertc -c signconfigst2 -mailbox 02 -m "this is a test" -ackwait 10m Terminator Not relevant to signboards. Leave blank. ServiceMaxMessageLength Not relevant to signboards. Leave blank or set at default value of 960. MaxTextFiles The maximum number of messages you want the signboard to be able to hold and cycle among. (This keyword is ignored when DeviceSubtype=1.) TextFilesFIFO First in, first out. When this value is set to False, TelAlert will count as failed any message sent to the signboard when it is already holding the maximum number of active messages. When this value is set to True and a message is sent to a signboard already holding the maximum number of active messages, TelAlert will eliminate the oldest such message to make room for the new one. (This keyword is ignored when DeviceSubtype=1.) TextFilesFIFOMinDisplayTime When TextFilesFIFO=True, the minimum amount of time TelAlert will display a message on the signboard. (This keyword is ignored when DeviceSubtype=1.) FailWait Controls how many minutes TelAlert will wait before trying to send the message again after finding that the signboard is full. You should set this to a shorter length of time than that set by TextFileFIFOMinDisplayTime. TextFilesEmptyMessage Controls what is displayed on a signboard controlled by TelAlert when there are no active messages. The default value (\x1b b \x1c1\x13) displays the current time. (This keyword is ignored when DeviceSubtype=1.) Chapter 10: Applying Filtering Techniques 115

9.4.4 Signboard [Destinations] Definitions Though it is not always necessary to create a [Destinations] definition for a signboard, doing so may offer certain advantages. For instance, the application with which you integrate TelAlert may be set up to begin all message-generating commands as if sending to a destination, that is, when using the -i option. Creating a signboard [Destinations] definition lets you avoid making an exception to this general procedure. The following definition assumes the Mailbox type has been set in the indicated configuration: [Destinations] {Sign} Configuration=SignConfigST2 Mailbox=01 Configuration This keyword simply points to the [Configurations] definition you want TelAlert to use when processing alerts directed to this signboard. Mailbox Set the signboard s serial address here. If you have multiple signboards, this keyword will control which will display messages sent with this [Destinations] definition. See the discussion of Mailbox in Signboard [Configurations] Definition, above. 9.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. 116 TelAlert Administrator Guide - Version 5.7

9.4.6 Controlling Signboard Text Color and Effects The display effect and color of a TelAlert signboard message is determined by an 11-character string of signboard control codes, which as discussed below can be specified either in the signboard s [Destinations] definition, or at the command line with -mi. The control string s format is: \x1b0[mode]\x1c[color] To create a usable signboard control string, replace [mode] and [color] with codes from the following table: mode code effect color code color a slow continuous scroll 1 red right to left b no motion 2 gree n c flash 3 ambe e f scroll up scroll down r g h i j k l m p q r s 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 Chapter 10: Applying Filtering Techniques 117

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 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" 118 TelAlert Administrator Guide - Version 5.7

9.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 9.5 Alternative Signboard Setup (DeviceSubtype=1) The previous section focused on installations in which TelAlert controls signboard message display. In this section, we ll discuss configuring TelAlert to let another application control the signboard. With this alternative setup, the signboard will display a fixed number of continuously updated messages from the controlling application. Typically this approach is used in call centers to display status messages, such as current hold time, number of calls waiting, and number of calls in progress. As with the standard signboard setup, you must define [Port] and [Configurations] definitions. Then you will use TelAlert to perform some additional firmware initialization. Finally, you can either create a separate [Destinations] definition for each message, or configure the controlling application to include the necessary signboard control codes in the message. Chapter 10: Applying Filtering Techniques 119

9.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 9.5.2 Signboard [Configurations] Definition when DeviceSubtype=1 As with a standard signboard setup, normally you will create only one [Configurations] definition for each signboard [Port] definition. Multiple signboards that share the same port can share the same [Configurations] definition by referencing it in individual [Destinations] definitions. For a DeviceSubtype=1signboard, you need only the following keywords: Configuration {SignConfigST1} Type=Device DeviceSubtype=1 Mailbox= Device and DeviceSubtype should be set as shown. See the Signboard [Configurations] Definition section of Standard Signboard Setup (DeviceSubtype=2) above for instructions on setting the Mailbox value. (The keywords MaxTextFiles, TextFilesFIFO, TextFilesFIFOMinDisplayTime, and TextFilesEmptyMessagerelate only to TelAlert s control of signboard message display and are ignored when DeviceSubtype=1.) Note that when DeviceSubtype=2, TelAlert will not give you an error message if you provide the wrong Mailbox value. After you ve saved this new definition, activate it by making TelAlert re-read its configuration file. You must activate the new definition before you can perform the following instructions. 120 TelAlert Administrator Guide - Version 5.7

9.5.3 Additional Signboard Firmware Setup when DeviceSubtype=1 With an alternative signboard setup, the next step is to create a separate virtual file in the signboard s memory for each of the continuously-updated messages you want it to display. You must perform this step after creating the port and configuration definitions, as you will use them to send a special file-initialization message to the signboard. As with setting the signboard s serial address, you should only need to do this once. (If you reconfigure the signboard to use DeviceType=2, you will need to perform this step again to switch back to DeviceType=1.) First, make sure that the {AlphaAllocateTextFiles} definition exists and is set active in TelAlert s [Message] section. If not, create it, as follows: [Message] {AlphaAllocateTextFiles} Device= E\x24${Parm1} The next step is to send a special message to the configuration you just created that contains the control codes necessary to set up the virtual files. The syntax is: telalertc -c signconfigst1 -mailbox?? -mi AlphaAllocateTextFiles control_codes Programming control codes is a tedious process, but assuming you need to rotate no more than six messages of no more than 255 characters each, you can use the following command: telalertc -c signconfigst1 -mailbox?? -mi AlphaAllocateTextFiles AAL00FFFFFEBAL00FFFFFECAL00FFFFFEDAL00FFFFFEEAL00FFFFFEFAL00FFFFFE That last bit is a run-together series of six 11-character control strings, each of which creates a virtual file. The first letter of each control string is the name of the virtual file, so the six virtual files this command creates are named A through F. (Instead of retyping this cumbersome string, you can simply copy it from the PDF version of this manual.) If you need more or longer messages, you will need to write your own custom control-code string. Here is the syntax: character 1: single-letter virtual file name character 2: A (tells signboard you are defining a text file) character 3: L (disables remote control; replace with U to enable) characters 4-7: hexadecimal number indicating file size in bytes (00FF = 255) characters 8-11: FFFE (tells signboard not to control display with its internal clock) 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.) Chapter 10: Applying Filtering Techniques 121

By default, the signboard displays each file for an equal length of time. If you do not use all six files, you can use the AlphaTextFileSequence [Message] definition to change the display. First, make sure that the AlphaAllocateTextFilesdefinition exists and is set active in TelAlert s [Message] section. If not, create it, as follows: [Message] {AlphaTextFileSequence} Device= E.SL${Parm1} Then use the following command to tell the signboard which files to display: telalertc -c signconfigst1 -mailbox?? -mi AlphaTextFileSequence list_of_file_names For example, if you use only files A, B, and C, use the following command: telalertc -c signconfigst1 -mailbox?? -mi AlphaTextFileSequence ABC You can also use AlphaTextFileSequence to make some messages display longer than others. For example, to make message A display twice as long as B and C: telalertc -c signconfigst1 -mailbox?? -mi AlphaTextFileSequence AABC 9.5.4 Signboard [Destinations] Definitions when DeviceSubtype=1 See the Signboard [Destinations] Definitions section of Standard Signboard Setup (DeviceSubtype=2) above for general instructions on creating signboard [Destinations] definitions. The only difference when DeviceSubtype=1 is that you may wish to specify the virtual-file control codes discussed in the preceding section in the MessagePrefix keyword value. Which virtual file a TelAlert message is loaded into is determined by a two-character string of signboard control codes. The control string s format is: A[file_name] file_name is the single-letter name of the virtual file you want to hold the message. Thus, to put a message into virtual file A, and have the signboard scroll it in red, you would use the following string: AA To put a message into virtual file B, you would use: AB 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. 122 TelAlert Administrator Guide - Version 5.7

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: Applying Filtering Techniques 123

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" 124 TelAlert Administrator Guide - Version 5.7

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" 9.6 Setting up Email Notification Because the Internet is sometimes subject to delays, and because not everyone checks for new email messages with the same frequency, email is not the most efficient or reliable notification medium. It can be very useful, however, for low-priority messages. Also, some organizations set up TelAlert so that every message sent via pager also is sent to the person s email address. Used in this way, email can serve as an effective means for backing up other media or for creating records of messages that individual users may find valuable. Setting up email notification involves creating a [Configurations] definition and one or more destinations. The [Port] definition that will be referred to by the [Configurations] definition probably already exists in your TelAlert configuration file. You can have TelAlert use a provided helper application, called Readmail, to process responses to email notifications. This is also useful in the case of two-way text paging services that are emailbased. For instructions on using Readmail, refer to the end of this section. Chapter 10: Applying Filtering Techniques 125

9.6.1 Email [Port] Definition Under [Port], be sure that there is an {Internet} entry, that Activeis set to True, and that one of the values listed for Types is Email. For example: [Port] {Internet} Active=True Model=Internet Types=Email,TextPager,InteractiveTextPager Model=Internet provides an additional link matching the [Configurations] definition, below, to this [Port] definition. It also tells TelAlert which process to use in processing notifications that invoke this [Port] definition. 9.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= validemailaddr@yoursite.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. 126 TelAlert Administrator Guide - Version 5.7

9.6.3 Email [Destinations] Definition An email destination must point to the [Configurations] definition you create for sending email notifications. In addition, it contains the name of the recipient and that person s complete email address: [Destinations] {CynthiaEmail} FullName= Cynthia Jasper Configuration=Email To= 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" 9.6.4 Using Email as a Backup Notification Medium If you want all messages that you send to a person s pager (for instance) to go also to this person s email address, you must combine the email destination and the pager destination in a group and direct messages to this group, instead of an individual destination. For instance: [Group] {Cynthia} Destinations= "CynthiaTextPager","CynthiaEmail" By issuing the following command telalertc -g Cynthia -m "this is a test" -ackwait 15m you could send a message to {CynthiaTextPager} and {CynthiaEmail} simultaneously. By associating the pager destination with a schedule and assigning no schedule to the email destination, you could ensure that Cynthia would receive a record of all relevant alerts, even those that occurred when, according to her pager schedule, she was off-duty. 9.6.5 Handling Responses to Email With Readmail TelAlert comes with an email-reading utility (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. Chapter 10: Applying Filtering Techniques 127

To use Readmail, you must activate and edit the {POPClient} definition found in a new section, called [Process], in the telalert.ini file. This definition is responsible for starting Readmail whenever TelAlert is started, and for setting the parameters that govern Readmail s behavior. {POPClient} Settings Following is the version of the {POPClient} definition found in the template telalert.ini file that ships with TelAlert 5.1. [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 options <Option Bit Mask> Start=${TimeStamp} Start Reset=${TimeStamp} Reset Status=${TimeStamp} Status Control=${TimeStamp} Control ${Message} Switch=${TimeStamp} Switch Stop=${TimeStamp} Stop Active Determines whether the definition is active. You must set this to True to use Readmail. Shell The shell to which TelAlert should pass the specified Command value. The value should be a fully qualified reference, as the user s PATH will not be used. When the Command value is not a shell command (as is normally the case in Windows), the Shell value should be blank. Command The command TelAlert should issue whenever 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 is the DNS name or IP address of your E-mailserver. -service -user is the TCP port, 110 for POP mail. is the user E-mail user name without the domain, for example, for linda@mir3.com only use user=linda. -password is the email password for the user to connect to the email server. -options is a hexadecimal bit mask that turns on one or more readmail options. For example (0x0002) (0x0008) (use Heat formatting and Don t trust Octets) would be passed as options 0x000A The available hex values are as follows: 128 TelAlert Administrator Guide - Version 5.7

OM_Heat (0x00000001) "Heat" system messages have the SendID embedded in the body of the message, in the form "SendID=nnn", and the Ticket as "Ticket=xxx". Option can also be specified by setting '-heat' on the readmail command line. OM_List (0x00000002) Send POP LIST command OM_NoOctets (0x00000008) Don t trust octet counts OM_NoSubject (0x00000010) Message body is <sendid> text OM_NoUIDL (0x00000020) Don t issue UIDL command OM_SecondLine (0x00000040) Ignore first non-blank line, using second as text OM_SendIDinBody (0x00000001) Ignore subject line if doesn t contain anything recognizable, including re:<blank> ; parse body for <sendid> and text. 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) based on the content of the subject line or the body of the message. Details of these options are decussed below. Chapter 10: Applying Filtering Techniques 129

Readmail 1.13, build 20021014 or later, includes an -ignore command line option that is to be used in conjunction with -response. Without -ignore: -response expects the Subject line to be in the format: Re: <SendId> <Reply> where <Reply> will be string-matched against the list of replies contained in the -response definition specified in the original command (the command that initiated SendID). If <Reply> is null on the Subject line, then the first line of the message body will be taken as <Reply> and stringmatched instead. With -ignore: -response expects the Subject line to be in the format Re: <SendId> <whatever> and the first line of the message body to be: <Reply> The <Reply> will be string-matched against the list of replies contained in the -response definition and will always be taken from the first line of the message body. Any text that follows <SendId> on the Subject line will be ignored. Start, Reset, Status, Control, Switch, Stop These keywords allow you to specify the commands to be passed to Readmail whenever the associated keyword is used on the command line. Readmail understands a set of commands identical to this set of keywords (i.e., start, reset, status, control, switch, and stop), but they still must be set explicitly. Note that only one of these, Control, is designed to allow you to pass more than just a command: to the value of Control you can append data, either explicitly or using a substitution parameter. (In the case of other helper applications, these keywords may be assigned other values, depending on the commands these applications have been designed to accept.) Readmail Logfile and Rollover Logfile The names of the readmail logfile and rollover logfile are controlled by the -file and -back parameters on the readmail command line: [Process] {POPClient} Command=${TelAlertBin}/readmail ${EventData} -name ${Paragraph} -file POPClient.log & -back POPClient.%Y%m%d%H%M -size 50000 -time 01:00 -dayofweek 0 130 TelAlert Administrator Guide - Version 5.7

If file or -back are not specified, the built-in defaults are those shown above. In the example for the -back filename, the % parameters are replaced at file creation time as follows: %Y: 4-digit year %m: 2-digit month (01-12) %d: 2-digit day of month %H: 2-dight hour, 24 hour clock %M: 2-digit minute A rollover filename will look like: POPClient.200211260915 This allows keeping each rollover file separate, instead of having the rollover files overwrite each other. However, there is a need to adopt some plan to archive off old rollover files. If you use -back POPClient.bak, then the rollover files will overwrite each other. You may include a file path in file or -back, but the file path is relative to the path given by telalertdir. (Also note that it s telalertdir, not telalertbin/cfg/tmp). For example, if you have -file /logfiles/popclient.log, and telalertdir is /var/opt/telalert, then the fully-qualified file location will be /var/opt/telalert/logfiles/popclient.log. Regarding the other logfile-related parameters: -size -50000 means that when the logfile reaches 50,000 bytes, it will be renamed to the -back filename and a new logfile created with -name. To disable switching on logfile size, omit the size keyword (do not use -size 0). -time -01:00 means that the logfile will roll over to -back at 1AM. Whether it rolls over daily or weekly depends on the value of -dayofweek. If the -time keyword is omitted, the logfile will not roll over based on time of day. -dayofweek -if this keyword is specified, the logfile will roll over weekly at -time; if it is not specified, the logfile will roll over daily at -time. The value following -dayofweek indicates which day the weekly rollover will occur; 0=Sunday, 1=Monday, 6=Saturday. MIR3 does not recommend omitting both size and -time. If you do, then the logfile continues to grow until the disk runs out of space. If you decide to specify both size and -time, MIR3 recommends setting -size to a fairly high value, so that most rollovers will occur due to -time, but if you get a sudden influx of log entries, the -size will prevent the logfile from growing to excess size. Readmail in Action If the [Process] definition governing it is set to Active=True, Readmail runs when TelAlert is started. Based on the settings found in the above example, Readmail will check mail at the designated email address every thirty seconds. It will process emails that have been formatted to ack, nak, or reply to TelAlert notifications. It will also process emails that have been formatted to send notifications through TelAlert or to submit requests (refer to the discussion of requests in Chapter 7: Configuring for Paging Notification). Chapter 10: Applying Filtering Techniques 131

Readmail recognizes emails that it should process by parsing the subject line. Based on what it finds there, it generates and executes an appropriate TelAlert command. Details regarding the recognition and processing of particular kinds of emails are presented below. In most cases, users must understand what kind of subject line Readmail looks for, in order to send an email that is formatted appropriately. Sending Messages Readmail recognizes an email intended to generate a TelAlert send by the presence (in the first line of the message s subject line) the name of a TelAlert [Destinations] or [Group] definition. The subject line should take the form: destination_name or, in the case of sends to a group: group: group_name The body of the email message (up to TelAlert s configured maximum message length) will be used as the message text. After processing such a message, Readmail deletes it. Acting on Outstanding Sends Readmail recognizes an email intended to act on a TelAlert notification by the presence of certain magic words in the subject line: Ack N AckHold N Nak N Clear N Release N In each case, N is the numeric send ID of the message to be acted upon. The body of the email message is ignored. After processing such a message, Readmail deletes it. Replying to Messages Readmail recognizes emails intended to provide a canned reply to a TelAlert notification based on the presence of Re: SendID in the subject line, where SendID is the numeric send ID of the message to be replied to. The body of the email provides the data that Readmail passes as the reply. It does so using this command: telalert -reply SendID Data After processing such a message, Readmail deletes it. Submitting Requests Readmail recognizes emails intended to generate a request based on the presence of Request: Name in the subject line, where Name is the name of the [Notifications] definition that should be used to process the request. The body of the email provides the data that Readmail passes as part of the request. The email s From information is used to return a response to the original sender; it is passed to TelAlert using the -replyto command line option. The entire TelAlert command takes this form: telalert -request "Name Data" -replyto "From_Info" After processing such a message, Readmail deletes it. 132 TelAlert Administrator Guide - Version 5.7

9.7 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. 9.7.1 Command-Line [Configurations] Definition The [Configurations] definition serves primarily to identify the notification s Type, which is different from all other Type values in that it does not link to a port. If you want to use a shell to run the command, you can specify it here. [Configurations] {Sound} Comment= No Shell - typical for Windows Type=Command Shell="" {shcommand} Comment= Shell specified - typical for Unix Type=Command Shell="bin/sh -c" 9.7.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} Here, Command specifies: the path to the Windows Media Player additional instructions for this application so that it closes after executing the command the path to the.wav file that the application is to play Note that the actual.wav file is not specified. This command destination is set up so that the file can be supplied on the command line as the notification s message, like so: telalertc -i sound -m ding.wav TelAlert replaces ${Message} with the command line string following the -m. If you wanted the same sound to be played for every message, you could specify the file directly in the destination, in Chapter 10: Applying Filtering Techniques 133

place of ${Message}. If you do this, you still must provide some message value on the command line. For example: telalertc -i sound -m, 9.7.3 Applications for Command-Line Notification Obviously, TelAlert s command line notification feature has a wide range of applications, ranging from the very simple (as shown by the above example) to much more sophisticated solutions involving customized scripts and/or third-party programs. For instance, if a process running on a machine on your network occasionally dies and requires restarting, and if you have a means for getting word of its death to TelAlert, you could set up a command line notification that would enable TelAlert to restart the process on its own. If successfully restarting the process involved a series of commands, you could create a script that TelAlert would invoke, passing all needed information in the command line message. Perhaps you want TelAlert to restart the process but also to notify a support employee that the process died. In this case, you could create a group consisting of the {Restart} destination and a pager destination. The recipient of the page would know that TelAlert had issued the command to restart the process; he or she could then take whatever steps necessary to make sure that the process was in fact up and running. Even the simple example of having TelAlert play a sound can be the core of a sophisticated notification strategy. Imagine that, in a send to a group involving escalation, you want TelAlert to play a sound each time the message is sent to another destination thus providing the help desk coordinator with an audible update of the alert s progress. To do this, you would group each pager destination with a suitable sound destination and build your main group out of these subgroups, like so: [Group] {MainSupport} Destinations= "DavidPager,DavidSound","JohnPager,JohnSound", "CynthiaPager,CynthiaSound" In this example, three different sound destinations are being invoked, each associated with a different sound file. These could be files you build yourself to read aloud messages corresponding to each user: e.g., David is being paged, John is being paged, etc. 9.8 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} 134 TelAlert Administrator Guide - Version 5.7

Configuration=Winpop To=GeorgeDesktop telalertc -c Winpop -To GeorgeDesktop -m "Here s a popup" telalertc -i GeorgeWinpop -m "Here s another popup" Note that when using -c Winpop, you use -to, not -PIN. Also notice that the To/-to value must be a DNS name; it cannot be an IP address. Also notice that From= is supported and is included in the text displayed in the popup. TelAlert does not support an equivalent to this popup functionality on UNIX, because of the variety of window managers and networking protocols. If you know that a particular utility providing this functionality is installed at your site, a Command Configuration can be used. The following is an example if the smbclient utility is installed: [Configuration] {smbclientpop} Type=Command Shell="bin/sh -c" Command="smbclient -M ${PIN} -U TelAlert" Acked=252 PINRequired=True WriteExecsToTrail=False telalertc -c smbclientpop -PIN GeorgeDesktop -m "UNIX popup" This UNIX Command Configuration example should be crossreferenced from the topic on command configurations, since otherwise all of the command configuration examples are for Windows. In TelAlert release 5.0 and earlier, Type=Email was required with Protocol=WINPOP; in 5.1 and later, Type=TextPager is required instead. NOTE: We are not aware of any way to send a "two-step" popup, where first it would pop up a request for username and password, and only if the proper username and password was given would the second step pop up the actual message. Winpop is based on the Windows "net send" command. "net send" allows sending to either a machine name, or a user name. Messages sent to a machine name will be delivered to all users cuurently logged into that machine. To have a message delivered only to authenticated, logged on users, address it to a user name. 9.9 Sending 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. 9.9.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 Chapter 10: Applying Filtering Techniques 135

facilitycode.priority, where facilitycode is a number between 0 and 127, inclusive, and priority is a number between 0 and 7, inclusive. 9.9.2 TelaConsole To send messages to TelaConsole, you also use a [Configurations] definition of Type=TextPager. Here, Protocol should be set to TelaConsole. Service and Host should also be set appropriately. If you choose, you can provide "Facility code" and "priority" information just as with the Syslog protocol i.e., passed as the PIN value, typically either on the command line (using -pin) orin a [Destinations] definition (using the PIN keyword). The format for this information is facilitycode.priority, where facilitycode is a number between 0 and 127, inclusive, and priority is a number between 0 and 7, inclusive. 9.9.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. 9.10 Sending Messages to Web-Enabled Phones You can send messages to cellular telephones equipped with a Phone.com microbrowser. The information TelAlert first passes to the telephone is the URL for the TelAlert Web client typically, a qualified URL (expressed using ${SendID}) where the recipient can go to read the actual message. A typical [Configurations] definition looks like this: {NextelUPNotify} Type=TextPager Protocol=UPNOTIFY Host=atlsnup2.adc.nexteldata.net Service=4445 Subject=ALERT-${SendID} ReplyTo=http://www.company.com/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 recipient s browser. The ReplyTo value is the URL to which the recipient s browser will be directed when the recipient reads the message from TelAlert. A [Destinations] definition simply points to the [Configurations] definition and provides a PIN, which is the telephone s subscriber ID, not the telephone number: {NextelUPN} Configuration=NextelUPNotify PIN=123456789-09876 136 TelAlert Administrator Guide - Version 5.7

Microbrowser-equipped telephones can also initiate interactions with TelAlert by browsing to the URL of the TelAlert Web client. The Web client (telalerth) that ships with TelAlert will automatically recognize microbrowsers and present information in a form they can handle. For information on customizing the Web client s interactions with microbrowsers, and with browsers of all kinds, refer to Setting up the TelAlert Web Clients in Chapter 16. Chapter 10: Applying Filtering Techniques 137

9.11 Sending Text Messages to Nextel Cellular Phones TelAlert supports two-way text messaging with Nextel cellular telephones equipped with text screens. This messaging is email-based. Sending notifications requires a [Configurations] definition of Type=InteractiveTextPager where Protocol=SMTP. A special keyword must be used: ProtocolMask=4. This ensures that all reply options attached to the send are formatted according to Nextel s requirements. Finally, you should set AddSendIDtoMessage to True. This allows replies to the message to be linked to the original send and processed properly. Here is a typical [Configurations] definition: {NextelSMTPTwoWay} Type=InteractiveTextPager Protocol=SMTP Host=messaging.nextel.com Service=smtp ProtocolMask=4 To=${PIN}@messaging.nextel.com From=<ValidEmailADDR>@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 two-way messaging as well. There is generally little reason to send messages to two-way pagers by this means, but it can be done, as described above. The ProtocolMask value must be set appropriately, based on the requirements of each of these service providers. For PageNet, WebLink Wireless, and Verizon, use a value of 1. 138 TelAlert Administrator Guide - Version 5.7

9.12 Sending One-Way Text Messages to GSM Cellular Telephones 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: Applying Filtering Techniques 139

9.13 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. 9.13.1 Set-Up During Installation TelAlert has two techniques for handling GSM wireless modems. The first technique was introduced in TelAlert 5.2. A combination of existing core program options provided functionality to send messages using GSM wireless modems (the existing options were Protocol=Chat, etc.) To handle receiving GSM messages, a helper program, GSMPoll, was added; GSMPoll does have specific GSM support. This technique uses three TelAlert definitions: 1. A [Port] definition of Model=DirectModem 2. A [Configuration] definition of Type=TextPager,Protocol=Chat 3. A [Process] definition invoking the GSMPoll helper program. One-way pages, and the outgoing part of two-way pages, are sent out via the [Port] and [Configuration]. Responses to two-way pages come back via the [Process]; if only one-way paging is used, the [Process] is not required. For simplicity, in the sample definitions, the name {GSMModem} is used for the [Port] and [Configuration], and the name {GSMPoll} was used for the [Process]. These specific names are not required; any names can be used, as long as all references to the names are properly updated. 9.13.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. 140 TelAlert Administrator Guide - Version 5.7

9.13.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: or Option SendID SendID Option where Option is one of Ack, Nak, Hold, Clear, Release. The newer technique requires that a custom [Response] list be specified on the command line. The newer technique's SMS replies must be in the form SendID response where response must be one of the responses specified on the original command (for instance, if the original command contained the specification -response basic then response must be one of Yes, No, Hold, Info, Release, or Ping). Note that these basic responses are not the same as the options for the older technique. To facilitate upgrading, a new set of responses has been created -- refer to {GSMResponse} below. However, even with these responses, the newer technique requires SendID before the response; the older technique would accept SendID either before or after the option. Also, there isn't any newer response equivalent for the older clear option; this shouldn t be a problem because clear is normally used when nobody has responded, rather than as a response option in itself. These new responses would be invoked by including -response GSMResponse on the telalert(c) command line. Chapter 10: Applying Filtering Techniques 141

9.13.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 customer s values, such as Dev=<<dev>> will not import as-is. There are two choices: 1. Edit these lines before copying to the clipboard. 2. The import function will give errors for lines that can t be imported; make a note of these lines and set the appropriate keyword values via the main TelAdmin panel. 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 142 TelAlert Administrator Guide - Version 5.7

#ChatLogon= "" \EAT+CMGF=1 OK #ChatScript= "" \EAT+CMGS="\P" > \M\x1A\c OK #ChatLogon= "" \EAT+CMGF=0 OK ChatLogon="" ChatScript= "" \EAT+CMGF=1 OK \EAT+CMGS="\P" > \M\x1A\c OK ChatLogoff="" Class=1 [Process] {GSMPoll} # See notes for details on the Command= line Active=True Shell="" Command=${TelAlertBin}/gsmpoll "${EventData}" -name ${Paragraph} & -file gsmpoll.log -back gsmpoll.%y%m%d%h%m -size 50000 & -dev COM6 -speed 9600 -parity none & -sleep 30 -debug 0 Start=${TimeStamp} Start Reset=${TimeStamp} Reset Status=${TimeStamp} Status Stop=${TimeStamp} Stop Set Speed= to the modem s correct speed setting (9600 for most GSM modems; because the trailing 0 is optional, 960 is equivalent to 9600). To determine the speed of the modem (and check the availability of the port), use testcomm, a utility included with TelAlert. Use this command line: testcomm mg device speed Substitute the port name for device. For speed, begin with 9600 and try other speeds (1200, 2400, 19200, 38400)as necessary. Both values must be correct to get a response from the modem. When finished, save and implement your changes. This definition is now ready for you to use, either with or without a [Destinations] definition pointing to it. The following comments describe the Command= line options in [Process] {GSMPoll}: The client polls the directly-connected GSM modem for incoming SMS messages. The command line options are: -file Name The log file will be named Name. Default value is readmail.log -back Name The backup log file will be named Name. Default value is readmail.%y%m%d%h%m. Both Names are passed through strftime (). Common substitutions are: %Y: 4-digit year %m: 2-digit month (1-12) %d: 2-digit day of month %H: 2-dight hour, 24 hour clock %M: 2-digit minute Chapter 10: Applying Filtering Techniques 143

-size n When the log file reaches n bytes, the backup log file is removed, the log file is renamed to the backup log file and a new log file is created. By default, the log file is not switched based on size. -time hh:mm When the time passes hh:mm (24 hour clock), the backup log file is removed, the log file is renamed to the backup log file and a new log file is created. By default, the log file is not switched based on time. -dev <device> This is the Device where your GSM modem has been connected. This should match the Dev= value in one of your [Port] section definitions. The [Port] definition with this device specification must have Share=True set. -speed <speed> The speed of the GSM modem. This should match the Speed= value in one of your [Port] section definitions. -sleep N The number of seconds between poll checks. The default value is 30. -debug N Debug level. Set to 1024 to have modem interaction written to log file (-file) Example definitions for the new technique: [Port] {GSMModem} #A. Model=Modem and ModemSubtype=2 to invoke new core code that # is specific to GSM wireless modems; ModemSubtype=2 also links # to [Configuration] {GSMModem} #B. Modem=xxx_GSM required when Model=Modem #C. Share=True not required since GSMPoll no longer used #D. Class=1 no longer needed; [Configuration] {GSMModem} linked # by ModemSubtype=2 Active=True Model=Modem ModemSubtype=2 Types=TextPager,InteractiveTextPager Modem=<<[Modem.xxx_GSM]>> Dev=<<dev>> Speed=<<speed; some modems are 9600-only, others are 19200-only>> [Configuration] {GSMModem} 144 TelAlert Administrator Guide - Version 5.7

#A. Set Type=TextPager for one-way, InteractiveTextPager for two-way #B. Protocol=GSM enables hard-coded GSM AT modem commands in telalertm #C. ModemSubtype=2 links to [Port] {GSMModem} #D. ProtocolMask setting depends on service provider; try 0 first, then 1, then 2 #E. Set AddSendIDToMessage True for two-way, either True or False for one-way {GSMModem} Active=True Type=InteractiveTextPager Protocol=GSM Speed=<<speed; some modems are 9600-only, others are 19200-only>> ModemSubtype=2 MaxMessagesPerCall=1 PINRequired=True PollRequests=False # ProtocolMask::= 1 -> Send in Text Mode; 0 -> PDU mode # ProtocolMask::= 2 -> Send as Flash Message; 0 -> Normal Message # Note: Flash messages must be sent in PDU mode - e.g. a value of 3 # won t work. ProtocolMask=0 AddSendIDToMessage=True [Response] {GSMResponse} # Used to have the newer 5.4 GSM two-way responses look similar to the # older 5.2 GSM two-way responses. The older clear response is # not supported in the newer method. # TelAlert matches on case-insensitive leading substring. For instance, since # Reply2=Nak, then the following will match: N, NA, nak, and NAK. But # NO will NOT match because there isn t any O in Reply2=Nak NumReplies=4 Acked=1 AckedHold=3 NotAcked=2 Released=4 Reply1=Ack Reply2=Nak Reply3=Hold Reply4=Release Chapter 10: Applying Filtering Techniques 145

9.14 Sending Messages to a DN400E Fax Modem TelAlert now supports the DN400E fax modem. Using the supported DN400E fax modem, you can now use TelAlert to send text messages to fax machines. (Note that only the DN400E fax modem is supported at this time. Contact the ACM Group for more information on obtaining this fax modem: ACM Group (Advanced Communications Methods), 103 Bullet Hole Rd, Carmel, NY 10512; (845) 228-0527.) In the [Port] and [Configuration] sections you can now specify Model=FaxModem and Type=Fax. The FaxFSI keyword has been added to the [Configuration] section. The FaxCSI keyword has been added to the [Destination] section. Typical definitions follow: [Port] {FaxModem1} Model=FaxModem Types=Fax Dev=COM3 Speed=19200 Modem=DN400E [Configuration] {Fax} Type=Fax Model=FaxModem FaxFSI=AAA-BBB-CCCC [Destination] {FaxZZZZ} Configuration=Fax AreaCode=AAA Number=XXX-YYYY FaxCSI=ZZZZ FaxFSI (the Fax Subscriber Identifier) is the string sent by TelAlert to the remote fax machine to indicate the source of the fax. FaxFSI can be up to 20 characters. FaxCSI (Called Subscriber Identifier), is the string returned by the fax machine at (AAA)XXX-YYYY to identify itself to TelAlert. If FaxCSI is specified, the value returned by the fax machine must match FaxCSI exactly, otherwise the fax is not sent. If FaxCSI is not specified or blank, no checking is performed. FaxCSI can be up to 20 characters. In addition, the command line option: -faxcsi string can be used to specify, but not replace, the FaxCSI string from a [Configuration] or [Destination]. The first 32 characters of Subject= or -subject will be sent as the TTI (Transmitting Terminal Identifier) to the remote fax machine. 146 TelAlert Administrator Guide - Version 5.7

9.15 Sending a File or a Line from stdin as a Message 9.15.1 Sending a File as a Message It is possible to send the contents of a file as a message. This is particularly useful if the destination is of type Email, Modem or InteractiveModem. A file s contents may be used as the message text. e.g.: telalertc -i BostonModem -m ~file /tmp/salesrpt.txt The message file is processed differently depending on the destination type. If the destination type is anything other than Email, Modem or InteractiveModem, the file is read when the alert is initiated, and the message text is kept in telalerte s internal tables. Thus, the text to be sent may not be larger than MaxMessageLength, as specified in the [Configuration] or [Destination] sections. MaxMessageLength itself has an upper limit of 960 characters if being sent through an Engine, 1920 otherwise. If the file contains references to TelAlert variables, such as ~batteryvolts, the substitutions will be made subject to the following limitations. If the destination (BostonModem) is of type Email or Modem or InteractiveModem, the message will be sent with variable substitution only if the message is shorter than MaxMessageLength. If the destination type is Modem or InteractiveModem and the message is longer than MaxMessageLength, the message will be sent without variable substitution. If the destination is type Email, then the message file is not processed until telalerte's telalerts child process actually connects to the smtp mail server. This may be a concern if the message file is dynamically produced, and a new event may overwrite the existing message file before it has been read and sent. 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 Bourne/Korn Chapter 10: Applying Filtering Techniques 147

shell such as the MKS toolkit that can provide both command substitution ( command ) and the "cat" command: telalertc -host 1.2.3.4 -i destination -m cat msgfile The second workaround uses telalertc's "~stdin" syntax (discussed below) instead of the "~file" syntax. In other words, if the message is in a file named msgfile, use a command like this on Windows or UNIX: telalertc -host 1.2.3.4 -i destination -m ~stdin < msgfile or like this on UNIX (or on Windows with MKS): cat msgfile telalertc -host 1.2.3.4 -i destination -m ~stdin Note that when using the "~stdin" syntax, only the first logical line of msgfile will be read. To have the entire file treated as a single logical line, make sure there aren t any imbedded <CR> or EOL characters in msgfile. If msgfile is created by an external application that embeds <CR> and/or EOLs, then pass msgfile through a filter to remove them. 9.15.2 Sending a Line from stdin as a Message It is also possible to have TelAlert read a single line from stdin and put it in a message. This is useful if you want TelAlert to send a one-line result of a program as the message. For example, if you have a program that outputs a one-line message, you can send the program s output directly, without first having to write the message to a file and then send the file s contents. e.g. makeamessage telalertc -i JackTextPager -mp ~stdin This is simpler than: makeamessage > tmpfile telalertc -i JackTextPager -mp ~file tmpfile rm tmpfile Note that stdin is read by the telalert(c) command-line program, and thus this technique will work whether telalert(c) is being run on the TelAlert server, or on a client machine. 148 TelAlert Administrator Guide - Version 5.7

9.16 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. 9.16.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. 9.16.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: Applying Filtering Techniques 149

9.17 WCTP Proxy Configuration By default, the WCTP protocol uses the same TCP/IP port/socket as the HTTP protocol (port 80). Due to security concerns, more and more companies are installing HTTP Proxy Servers to control the HTTP traffic through their firewall. These HTTP Proxy Servers can interfere with the WCTP traffic using the same port. TelAlert 5.6 now includes three optional [Configuration] keywords for use with a HTTP Proxy Server, so that TelAlert can modify its WCTP processing to correctly route messages through the Proxy Server. The boolean HTTPProxyRequired keyword (default False) indicates if a Proxy Server exists. The HTTPProxyHost and HTTPProxyService keywords define how TelAlert should connect to the company's Proxy Server. The Host and Service keywords continue to define the connection to the messaging service provider (which is now made through the Proxy Server instead of directly by TelAlert). This new WCTP/HTTP-specific proxy support is in addition to the generic SOCKS proxy for which TelAlert has continued to provide support. The new options to enable the use of an HTTP proxy server are reflected in three new [Configuration] variables: HTTPProxyRequired A True/False variable indicating whether the Proxy mechanism is to be used (True) or not (False.) HTTPProxyHost The IP address of the HTTP Proxy server. This is typically an address within the customer s network domain. HTTPProxyService The TCP/IP port value for the HTTP Proxy server. The default text value is "webcache"; the default numeric value is 8080. As an example, the Arch Wireless WCTP [Configuration] looks like: {ArchWCTP} Comment=Arch WCTP service for Two-Way messaging. Type=InteractiveTextPager Protocol=WCTP Host=wctp.arch.com Service=http # For one-way paging, set ServerPIN to yourname.yourdomain and # Access="", and un-comment both lines. # For two-way paging, you'll need to get an account set up with # Arch. Use the senderid/securitycode provided by Arch, and # un-comment both lines. # ServerPIN=<your senderid> # Access=<your securitycode> PollRequests=False TextPagerWait=30s ProtocolMask=32 150 TelAlert Administrator Guide - Version 5.7

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 server s etc/hosts file, and uses the numeric value found there (normally 80). It is legal to use Service=80, which allows TelAlert to skip the etc/hosts lookup step. The following describes the differences in TelAlert s processing when using one or the other of the above configurations: Non-Proxy access: 1. Connect to wctp.arch.com:http 2. Send "POST /wctp HTTP/1.1" Proxy access: 1. Connect to 10.11.10.99:8085 2. Send "POST http://wctp.arch.com:80/wctp HTTP/1.1" Note that the numeric Service value is substituted in the POST directive, rather than "wctp". Simply changing HTTPProxyRequired to False will cause the Configuration to revert back to non- Proxy mode - it s not necessary to blank out the HTTPProxyHost/Service values, or remove those keywords. Chapter 10: Applying Filtering Techniques 151

10 Applying Filtering Techniques 10.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. 10.2 Getting Started 10.2.1 What is Filtering? Filtering is a means of specifying rules TelAlert is to follow in order to qualify a destination s validity when it prepares to send a message. You can set up filtering so that TelAlert sends the message to no destinations except those meeting specified criteria (inclusive filtering), or so that TelAlert sends the message to all destinations except those meeting specified criteria (exclusive filtering). At its most basic, filtering involves associating a [Filter] definition with a destination and letting TelAlert send or not send to the destination according to whether tags specified on the command line match tags included in the [Filter] definition. Commonly, filtering is used in conjunction with groups, schedules, and users. In the case of groups, it is used to qualify the destinations comprising a group, so that some are used and some are discarded. In the case of schedules, it provides a means of qualification in addition to a schedule, so that the destination must be on duty and meet the filtering criteria for it to be used. In the case of users, a [Filter] definition is associated with one or more destinations by referring to it in a [User] definition and then invoking the user in the relevant destinations. 10.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. 152 TelAlert Administrator Guide - Version 5.7

10.2.3 Other Considerations TelAdmin vs. telalert.ini File Configuration To set up filtering, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation. Thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 10.3 A Simple Filter 10.3.1 The Scenario David is the sole support technician for a small company. For simplicity s sake, the company s network monitoring application is set up to generate a TelAlert alert for every network event it detects. David wants to tell TelAlert how to determine which ones it should send to him and which ones it should suppress. He is interested in receiving a page only when there is an event pertaining to a server or router. 10.3.2 Procedure To set up this simple filter, David first creates the following [Filter] definition and refers to it in his destination: [Filter] {DavidFilter} Active=True RequiresFullMatch=False Exclusive=False Tags=Router,Server [Destinations] {DavidTextPager} Configuration=ATTWichitaTextPager PIN=3456789 Filter=DavidFilter Chapter 10: Applying Filtering Techniques 153

The relevant line in the [Destinations] definition is Filter=DavidFilter. The significance of the values in the [Filter] definition is as follows: Active Set to True, this makes the [Filter] definition available for use by TelAlert. RequiresFullMatch Set to False, this means that a minimum of one tag specified in the [Filter] definition must be matched by a tag specified on the command line for the destination to be deemed a match. Set to True, this means that all tags specified in the [Filter] definition must be matched by those on the command line. How a match is treated is determined by the Exclusive setting. Exclusive This determines how TelAlert treats a destination that it, on the basis of the tags specified and the RequiresFullMatch value, views as a match. When this is set to False, TelAlert will include i.e., will deem valid a matching destination while excluding all non-matching destinations. When this is set to True, TelAlert will exclude i.e., will not send to a matching destination while sending to all non-matching destinations. For example: {ExclusiveFilter} Comment=Tags that you do not want to receive Active=True Exclusive=True RequiresFullMatch=False Tags=Death,Taxes {InclusiveFilter} Comment=Tags that you want to receive Active=True Exclusive=False RequiresFullMatch=False Tags=Love,Money Tags The values entered here serve solely as a means for determining a match or non-match between a command and a destination. Even though TelAlert understands a tag only as a string of characters to compare against another string of characters, you should name your tags so that you can understand what they refer to. Having created this [Filter] definition and added this line to {DavidTextPager}, David then modifies the network monitoring application so that, in passing news of an event to TelAlert, it specifies a tag on the command line server, router, modem, printer, etc. so that the complete command looks like this: telalertc -i DavidTextPager -m "node down" -tags router Here, the message is sent because (1) the destination is a match (since one tag matches and a full match is not required); and (2) Exclusive is set to False (meaning that matching destinations, and only matching destinations, are included). Note that: If he changed the Exclusive setting to True, the [Filter] definition would operate exclusively: i.e., the message would not be sent because TelAlert would exclude it, along with any other matching destinations. If he changed RequiresFullMatch to True and left Exclusive set to False, the message would not be sent. The destination is not a match because not all of the [Filter] definition s tags appear on the command line. As a non-match, the destination is excluded, since the Exclusive setting specifies that only matching destinations are to be included. 154 TelAlert Administrator Guide - Version 5.7

If he changed RequiresFullMatch to True and Exclusive to True, the message would be sent. The destination is not a match because not all of the [Filter] definition s tags appear on the command line. As a non-match, the destination is included, since the Exclusive setting specifies that only matching destinations will be excluded. Now, in light of the original settings presented above, consider this command: telalertc -i DavidTextPager -m "node down" -tags printer Chapter 10: Applying Filtering Techniques 155

Here, the message is not sent because (1) the destination is a non-match (since the tag specified here does not match any specified in the [Filter] definition); and (2) Exclusive is set to False (meaning that matching destinations, and only matching destinations, are included). Note that: If he changed the Exclusive setting to True, the [Filter] definition would operate exclusively, but here the message would be sent because TelAlert excludes only matching destinations and includes all non-matches. If he changed RequiresFullMatch to True and left Exclusive set to False, the message would not be sent. The destination is not a match because none of the [Filter] definition s tags appear on the command line. As a non-match, the destination is excluded, since the Exclusive setting specifies that only matching destinations are to be sent to. If he changed RequiresFullMatch to True and Exclusive to True, the message would be sent. The destination is not a match because none of the [Filter] definition s tags appear on the command line. As a non-match, the destination is included, since the Exclusive setting specifies that only matching destinations will be excluded. In the case of events that David wanted to be informed of no matter what, he would set up the network monitoring application to issue appropriate commands without a -tags value: telalertc -i DavidTextPager -m "power outage" Without a -tags value on the command line, the [Filter] definition linked to the destination does not come into play at all. 10.4 Filtering Strategies 10.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}. 156 TelAlert Administrator Guide - Version 5.7

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}. 10.4.2 RequiresFullMatch and Exclusive Value Combinations In the above scenario, David wants TelAlert to suppress all messages except those meeting either of two conditions. He achieves this by setting both RequiresFullMatch and Exclusive to False. Each of the four possible combinations of RequiresFullMatch and Exclusive provides a unique effect and thus serves a relatively specific purpose. RequiresFullMatch=False, Exclusive=False Generally speaking, this combination is useful when you want all of the messages directed to a destination to be filtered (and thus not sent) unless they meet specified criteria. It differs from the True-False combination, however, in that it allows you to specify a set of criteria and have the destination be considered valid if it matches in a single respect. In the example provided, this combination is appropriate because David wants to filter all messages other than those specified. At the same time, he wants to be able to provide a fairly loose specification: either messages tagged with Router or messages tagged with Server. RequiresFullMatch=False, Exclusive=True Generally speaking, this combination is useful when you want all of the messages directed to a destination to be sent unless they meet specified criteria (in which case you want TelAlert to discard them). It differs from the True-True combination, however, in that it allows you to specify a set of criteria and have the destination be excluded if it matches in any respect. Under what circumstances might this be the appropriate combination? Perhaps you want a certain destination to receive any message directed to it unless the message falls into one of three classes: those relating to Web servers, those relating to mail servers, and those relating to Internet gateways. To accomplish this, you would: use the False-True combination include three tags in your [Filter] definition: Web, Mail, and Internet configure your monitoring software so that, each time it generates a TelAlert command, it provides the information necessary to create these tags on the command line (where appropriate) Chapter 10: Applying Filtering Techniques 157

RequiresFullMatch=True, Exclusive=False Generally speaking, this combination is useful when you want all of the messages directed to a destination to be filtered (and thus not sent) unless they meet specified criteria. It differs from the False-False combination, however, in that it allows you to specify a set of criteria and have the destination be considered valid only if it matches in every respect. Under what circumstances might this be the appropriate combination? Perhaps you want a certain destination to receive only a very narrow set of messages. For instance, your network monitoring application may be able to generate notifications about a number of different status changes and node types, but in this case you want to receive node down messages only, and only those pertaining to downed UNIX servers not routers, and not Windows servers. To accomplish this, you would: use the True-False combination include three tags in your [Filter] definition: Down, Server, and UNIX configure your monitoring software so that, each time it generates a TelAlert command, it provides the information necessary to create these tags on the command line (where appropriate) RequiresFullMatch=True, Exclusive=True Generally speaking, this combination is useful when you want all of the messages directed to a destination to be sent unless they meet specified criteria (in which case you want TelAlert to discard them). It differs from the False-True combination, however, in that it allows you to specify a set of criteria and have the destination be excluded only if it matches in every respect. Under what circumstances might this be the appropriate combination? Perhaps you want a certain destination to receive any message directed to it unless the message has all of three special characteristics: it pertains to a (1) workstation (2) manufactured by Hewlett-Packard and (3) running UNIX. To accomplish this, you would: use the True-True combination include three tags in your [Filter] definition: Workstation, HP, and UNIX configure your monitoring software so that, each time it generates a TelAlert command, it provides the information necessary to create these tags on the command line (where appropriate) Interaction Between Exclusive and RequiresFullMatch RequiresFullMatch works in conjunction with the tags specified in the filter and on the command line to determine whether a destination is a match. Exclusive tells TelAlert what to do with matches and, implicitly, with non-matches. With Exclusive set to False, matching destinations are used and non-matching destinations are discarded. With Exclusive set to True, matching destinations are discarded and non-matching destinations are used. 158 TelAlert Administrator Guide - Version 5.7

10.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. 10.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 10: Applying Filtering Techniques 159

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. 10.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 14: 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. 160 TelAlert Administrator Guide - Version 5.7

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 10: Applying Filtering Techniques 161

A group can be associated with one [Filter] definition, a subgroup within that group with another, and each of the individual destinations with still others. If, after evaluating the group s [Filter] definition, TelAlert finds that the group is valid, it evaluates the subgroup s [Filter] definition. If this too is valid, it looks at the [Filter] definitions invoked at the destination level. In such a case, the message will be sent to a destination only if all three [Filter] definitions permit it. 10.4.6 Filtering and Schedules A [Filter] definition is one way of qualifying a destination i.e., of setting rules for determining whether the destination is valid for a given message. A schedule is another means of destination qualification. Whereas a [Filter] definition determines whether a destination is valid based on the tag or tags accompanying the message, a schedule determines whether a destination is valid based on the time the message is to be sent. You do not have to do anything special to make [Filter] definitions and schedules work together. If a destination is associated with a [Filter]definition and a [Schedule] definition, TelAlert will send it a message that is accompanied by a -tag value only if it finds that the destination is both on duty and valid according to the terms of the [Filter] definition. For information on setting up and using schedules, refer to Chapter 11: Setting Up and Applying Schedules. 10.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} 162 TelAlert Administrator Guide - Version 5.7

Chapter 10: Applying Filtering Techniques 163

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. 10.5 Filtering by Message Priority There is another filtering technique that lets you determine whether a message directed to a given destination is actually sent to that destination. This involves assigning the message a priority on the command line and including MinFilterPriority and MaxFilterPriority values in the [Destinations] definition. If the message s priority is less than MinFilterPriority or greater than MaxFilterPriority, it is not sent. Consider this destination: [Destinations] {CynthiaTextPager} MinFilterPriority=50 MaxFilterPriority=80 And consider the following three commands: telalertc -i CynthiaTextPager -m "this is a test" -priority 40 telalertc -i CynthiaTextPager -m "this is a test" -priority 80 telalertc -i CynthiaTextPager -m "this is a test" -priority 90 Here, the first message would not be sent, because its priority is less than the MinFilterPriority assigned in the destination. The second message would be sent, because its priority is neither less than the MinFilterPriority nor greater than the MaxFilterPriority. The third message would not be sent, because its priority is greater than MaxFilterPriority. Schedule-Based Filtering Schedule-based filtering (including schedule-based filtering using priority) is covered in Chapter 11: Setting Up and Applying Schedules. 164 TelAlert Administrator Guide - Version 5.7

10.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 14: Broadcasting to Groups and Creating Escalations. Imagine that David can be sent notifications any of three ways: by telephone, pager, and email. He wants his least important messages to be delivered by email, the most important messages to be delivered by pager, and those of moderate importance to be delivered by telephone. He could achieve this by setting MinFilterPriority and MaxFilterPriority in each destination, like so: [Destinations] {DavidEmail} MinFilterPriority=1 MaxFilterPriority=40 {DavidVoiceMail} MinFilterPriority=40 MaxFilterPriority=80 {DavidTextPager} MinFilterPriority=80 MaxFilterPriority=100 With these values in place, he could then create a group pointing to these destinations: [Group] {David} Destinations=DavidEmail,DavidVoiceMail,DavidTextPager A message directed to this group and specifying a priority would then go to whichever destination met the filtering requirements. For instance, this message telalertc -g David -m "this is a test" -priority 50 would be sent to David s voice mail because its priority falls within the range (inclusive) specified in the definition of {DavidVoiceMail}. Keep in Mind MinFilterPriority and MaxFilterPriority do not have to be used so that they create a middle range e.g., from 50 to 80. You can set MinFilterPriority to 60, for example, and MaxFilterPriority to 100; this means that all messages of priority 60 or higher will be sent to the destination. Likewise, you can set MinFilterPriority to 0 and MaxFilterPriority to 60; this means that all messages of priority 60 and lower will be sent to the destination. Chapter 10: Applying Filtering Techniques 165

10.5.2 Default Logic The default value for MinFilterPriority is 1, and the default value for MaxFilterPriority is 100 thus, by default, no messages are ever filtered on the basis of priority. These values can be set for all destinations, all users, or all groups. They also can be set for individual destinations, users, and groups. Values assigned within a specific destination override values set elsewhere. If a destination does not specify these values directly, it inherits either the settings assigned to all destinations or the settings assigned to an associated user (regardless of whether these are specified directly in the [User] definition or for all [User] definitions). If these values have been set both for all destinations and for the user, TelAlert works with the lesser of the MinFilterPriority values and the greater of the MaxFilterPriority values. MinFilterPriority and MaxFilterPriorityin Groups If MinFilterPriority and MaxFilterPriority are set for a group, a message will not be sent to any of the destinations comprising the group unless its priority falls between these minimum and maximum values, inclusive. If individual destinations within the group also specify these values, either directly or by inheritance, the message s priority must fall within these minimum and maximum values as well for the destination to be considered valid. 10.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. 166 TelAlert Administrator Guide - Version 5.7

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. 10.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. 10.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 Chapter 10: Applying Filtering Techniques 167

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. 10.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). 168 TelAlert Administrator Guide - Version 5.7

Use a command similar to the following for node down messages: telalertc -i RachelPager -m "node 123 down" -check "node 123 down" -delay 6m Use a command similar to this one for node up messages: telalertc -i RachelPager -m "node 123 up" -cancel "node 123 down" When the network management application sends the first node down command, TelAlert does nothing immediately. Instead, it waits for six minutes (-delay 6). If on the next ping the network management application finds the node is up, it issues the second node up command. Since its -cancel string matches the delayed command s -check string, TelAlert sends neither message. If, instead, on the next ping the node is still down, the network management application does nothing. A minute later the delay timer expires and TelAlert sends the node down message. When the node comes back online and the network management application issues the second node up command, TelAlert will send the node up message, since there is no delayed node down message to cancel. 10.8 Suppressing Unwanted Messages During Scheduled Downtime The filterschedule command-line option treats a schedule as a filter. For example, TelAlert will execute the following command only if the referenced {Node144} schedule is on duty: telalert -g support -filterschedule node144 -m "this is a test" The typical use of this technique is to associate a schedule with a device (rather than a destination), in order to filter out messages that are sent during scheduled downtime, or at times when unexpected downtime does not demand the immediate attention of support staff. Normally the filter name will be the controlling application s name for the device, and you will use the controlling application s device-name variable to plug the name into the commands it sends TelAlert. The [Limits] section s ValidateFilterSchedule keyword determines how TelAlert handles commands that include invalid filter names in the -filterschedule device_name option. If set to True (the default), such commands fail with a [Filter] {device_name} not found error. If set to False, TelAlert processes the command as if the -filterschedule option had not been used. Setting ValidateFilterSchedule=False allows you to configure your controlling application to include -filterschedule device_name in all commands it sends to TelAlert. If a device_name schedule exists, TelAlert will check it and discard the alert only if the machine is currently scheduled to be down. If there is no device_name schedule, TelAlert will simply ignore the filter and process the alert. This approach allows you to create schedules as needed only for those devices that require them. (Otherwise, to avoid error messages and consequent failed alerts you would have to create schedules for all devices.) Chapter 10: Applying Filtering Techniques 169

10.8.1 Suppressing Orphan Up Messages When you use the -filterschedule option, after a device s scheduled downtime is up, the controlling application may cause TelAlert to send an up message for which the preceding down message was filtered out. You can suppress such up orphan messages by using -cancelnc, a special variation of the -cancel option. Configure the controlling application to include -delay and -check options in the commands that generate the down messages, and -cancelnc options in the commands that generate the up messages. For example: telalertc -g support -m "node 2302 is down" -filterschedule SystemUp -check "node 2302 is down" -delay 5m telalertc -g support -m "node 2302 is up" -filterschedule SystemUp -cancelnc "node 2302 is down" With those commands, TelAlert will send the up message only if its -cancelnc string matches the -check string of a message that is not in a delayed state, for example, one that has been responded to with an ackhold. If TelAlert does not find such a match, it does not send the up message, and also deletes any delayed messages that match the cancelnc string. In other words, TelAlert sends an up message only when a down message has been sent and has not yet been cleared. 10.8.2 When a Device Does Not Come Back Online as Scheduled But what if the device does not come back online after the scheduled downtime? Your network monitoring program thinks it has already sent at least one down message, and it may not send another as soon as you would like. For prompt notification of a device s failure to come back up from scheduled downtime, add a -delay option to the command: telalert -g support -m "node 2302 is down" -delay 5m -filterschedule SystemUp -check "node 2302 is down" When you use -delay in combination with -filterschedule, TelAlert does not discard messages during downtime. Instead, it delays them until the scheduled uptime, plus the number of minutes specified in -delay. Send your up messages with the following command, and the down messages will be sent only if the machine does not come back online within five minutes of the scheduled time: telalert -g support -m "node 2302 is up" -filterschedule SystemUp -cancel "node 2302 is down" 170 TelAlert Administrator Guide - Version 5.7

10.9 Filtering Messages by Source The telalert.alert file can contain, among other things, certain filtering information referred to by TelAlert in determining whether or not it should process each notification it receives. For instance, as discussed above, there are ways (both automatic and manual) to load a -check value into this file, so that any messages to which a matching -check string is affixed are discarded. It is also possible to load a -source value into telalert.alert, so that TelAlert discards all subsequent messages with matching source strings. This lets you ensure that no messages from a specified source are processed. All operations related to -source filtering must be carried out manually; they cannot be performed as part of a send. For example: telalert -insert -source NetworkMonitor This inserts the -source string into telalert.alert, causing TelAlert to begin discarding matching messages. telalert -delete -source NetworkMonitor This deletes the -source string from telalert.alert, causing TelAlert to stop discarding matching messages. telalert -verify -source This causes TelAlert to list the source strings currently stored in telalert.alert. 10.10 Pattern Matching TelAlert has long included various administrative commands that can be used to view, manage, and modify alerts in progress. These include -show, -clear, -nak, and -ack, just to name a few. These commands can be used with an Alert ID to act on a specific alert, or they can be used with various command line options to act on alerts that meet specified criteria. For example, you can use these command telalert -show -source remedy telalert -show -source openview to specify that the command be executed against only those alerts that have a particular source string associated with them. Beginning with TelAlert 5.4, you have much greater flexibility in specifying what alerts are acted on by administrative commands. This flexibility is based on an entirely new section, called [Patterns], which has been added to the configuration file. Chapter 10: Applying Filtering Techniques 171

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. 10.10.1 Other Uses There are several other command-line options available as part of TelAlert 5.4 s pattern-matching functionality. These are designed to allow you to use it with the elimination of duplicate messages, filtering, and the automatic cancellation of unwanted messages. -checkpe The checkpe operator is used to compare a new message against messages already in the TelAlert queue. Where previously, you might have used: telalert -i foo -m foo -check printer is down to prevent duplicate messages being issued with the exact check sequence specified, the -checkpe option provides much more flexibility: telalert -i foo -m foo -checkpe mdefault "printer.*down" This command checks for messages that contain the string printer followed by zero or more characters followed by the string down. 172 TelAlert Administrator Guide - Version 5.7

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. 10.10.2 Pre-Defining Regular Expressions Since compilation of regular expressions (RE) can be expensive, and the possible combination of options can be complex, it s possible to predefine them in the [Patterns] section. A simple pattern to match entries with Configuration names containing "Sky" (case-insensitive) could be: {ConfSky} PEConfiguration= Sky Match=PEConfiguration A simple string like this is treated as though it had been specified as ".*Sky.*", meaning "0 or more characters, sky, 0 or more characters". To use this to show active sends to SkyTel (assuming that all SkyTel Configurations names contain "Sky"), use: telalert -show -selectpattern confsky Chapter 10: Applying Filtering Techniques 173

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: and: telalert -show -selectpe configuration "sky" telalert -show -selectpe configuration "sky" \-selectpe user "ross" \-selectpm "configuration &!user" 174 TelAlert Administrator Guide - Version 5.7

11 Setting Up and Applying Schedules 11.1 Overview Instructions for using [Schedule] definitions to specify the times when destinations are valid for sending notifications. 11.2 Getting Started 11.2.1 What are Schedules? [Schedule] definitions, like [Filter] definitions, are a means of qualifying destinations. If a destination is associated with a [Filter] definition, TelAlert understands the conditions under which it can and cannot send a message to this destination conditions determined by the tags accompanying the message and the rules comprising the [Filter] definition. Similarly, if a destination is associated with a schedule, TelAlert understands the times during which it can and cannot send a message to this destination times determined by the associated schedule and optionally the priority of the message. At its most basic, deploying a schedule involves associating a [Schedule] definition with a destination and letting TelAlert send or not send to the destination according to whether the destination is on duty at the time. Commonly, however, schedules are used in conjunction with groups or users, as well as with priority settings assigned to individual messages. In the first case, a schedule might be used to qualify the destinations comprising a group, so that those that are on duty are automatically distinguished from those that are not. In the second, a schedule is associated with one or more destinations by referring to it in a [User] definition and then invoking the [User] definition in the relevant destinations. Priority settings allow you to invoke alternate [Schedule] definitions that extend a regular schedule s hours for messages of a certain degree of importance; you can also ensure that extremely urgent messages are sent, without regard for any schedule.

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. 11.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. 11.2.3 Other Considerations TelAdmin vs. telalert.ini File Configuration To set up scheduling, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation: thus, the instructions offered here apply equally to all methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. 11.3 A Simple Schedule 11.3.1 The Scenario Rachel is a support technician for a company that uses a network monitoring application integrated with TelAlert. When she is on duty, she tracks problems on an electronic signboard in her office. Thus, she needs to receive TelAlert pages only when she is not at work. However, she does not want to receive any pages after midnight, or before six in the morning. 11.3.2 Procedure To achieve this effect, Rachel creates the following [Schedule] definition and then refers to it in her destination: [Schedule] {RachelPager} Sunday=06:00-23:59 Monday=06:00-07:59,18:00-23:59 Tuesday=06:00-07:59,18:00-23:59 Wednesday=06:00-07:59,18:00-23:59 Thursday=06:00-07:59,18:00-23:59 Friday=06:00-07:59,18:00-23:59 Saturday=06:00-23:59 176 TelAlert Administrator Guide - Version 5.7

[Destinations] {RachelTextPager} Configuration=ATTWichitaTextPager PIN=3456789 Schedule=RachelPager With this setup in place, any message TelAlert is told to send to Rachel s pager during work hours will be suppressed. Likewise, any message TelAlert is told to send to Rachel s pager between the hours of midnight and 6:00 a.m. will be suppressed. Messages directed to her during all other hours will be sent. If instead of suppressing messages you wish to hold them until the recipient is on duty, set an OnDutyWait value in the appropriate [Configurations], [Destinations], [Group], and/or [User] sections, or use the -ondutywait command-line option. 11.4 Scheduling Approaches 11.4.1 Schedules and Default Logic Which Schedule is in Effect? The way scheduling works in 5.71 is that the first schedule wins. This means that if a schedule is applied on the command line, that schedule will be implemented and no others will be considered. If there is no schedule in the command line but one at the top group level, this schedule will be used. If there are subgroups with schedules applied and none at the prior top levels this schedule will be used. Finally if the destination has a schedule and none of the other top levels this schedule will be used. The simplest and most common approach is to associate a schedule directly with a destination, but (as explained below) a schedule can also be associated with a group or a user. Moreover, a default schedule can be specified that applies to all destinations, all users, or all groups. Such a default holds only for those individual destinations, users, or groups that do not themselves specify a schedule. A schedule associated with a [User] definition whether directly or by default and thus linked to a destination invoking that user always overrides any schedule associated merely by default with that destination. By contrast, a schedule associated directly with a destination always takes precedence over a schedule associated with the destination only indirectly through an invoked [User] definition. A schedule specified either directly or by default for a group applies to all destinations comprising it but only when those destinations come into play as part of an alert involving that group. Chapter 11: Setting Up and Applying Schedules 177

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 2010/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. This is particularly handy when a definition is linked to several schedules through the use of the AddSchedule keyword. For instance: telalertc -checkonduty destination testdest or telalertc -checkonduty group testgroup Schedule Default Values The only default value that can be assigned for all schedules is Active (which can be set to True or False). This allows you to deactivate all schedules by changing a single value. If you explicitly assign an Active value in an individual [Schedule] definition, however, this setting overrides any Active value you have assigned to all schedules. (By default, a schedule is active unless Active is set to False, either in its definition or for all [Schedule] definitions.) Note that setting a schedule s Active keyword to False has the same effect as editing it so that it is on duty 24 hours a day, seven days a week. Hence you will likely want to use that value only in emergencies. 11.4.2 Schedules and Groups The following discussion concerns two points of intersection between schedules and groups. For information on setting up and using [Group] definitions, refer to Chapter 14: Broadcasting to Groups and Creating Escalations. Using Schedules to Choose the Appropriate Destinations From a Group 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 send a message to the group. For instance, three members of a support department might each be responsible for an exclusive eight-hour period every day of the week: Cynthia from 8:00 a.m. to 4:00 p.m., John from 4:00 p.m. to midnight, and David from midnight to 8:00 a.m. Here, you would set up these [Schedule] definitions: 178 TelAlert Administrator Guide - Version 5.7

[Schedule] {CynthiaSchedule} Sunday=08:00-15:59 Monday=08:00-15:59 Tuesday=08:00-15:59 Wednesday=08:00-15:59 Thursday=08:00-15:59 Friday=08:00-15:59 Saturday=08:00-15:59 {JohnSchedule} Sunday=16:00-23:59 Monday=16:00-23:59 Tuesday=16:00-23:59 Wednesday=16:00-23:59 Thursday=16:00-23:59 Friday=16:00-23:59 Saturday=16:00-23:59 {DavidSchedule} Sunday=00:00-07:59 Monday=00:00-07:59 Tuesday=00:00-07:59 Wednesday=00:00-07:59 Thursday=00:00-07:59 Friday=00:00-07:59 Saturday=00:00-07:59 Next, you would associate each with the appropriate [Destinations] definition: [Destinations] {CynthiaPager} Schedule=CynthiaSchedule {JohnPager} Chapter 11: Setting Up and Applying Schedules 179

Schedule=JohnSchedule {DavidPager} Schedule=DavidSchedule If the relevant [Group] definition is set up like this [Group] {Support} Destinations=CynthiaPager,JohnPager,DavidPager then you can give the following command to TelAlert at 4:17 p.m., for instance, and TelAlert will page John: telalertc -g Support -m "this is a test" Associating a Schedule with a Group A schedule associated with a group applies to all the destinations comprising the group and overrides any schedule associated with any of the destinations individually. This includes destinations that are part of the group by virtue of their membership in subgroups included by name in the supergroup. Likewise, the schedule associated with the supergroup overrides any assigned to any of the subgroups that comprise it. You may want to associate a schedule with a group in order to specify a special time during which all the destinations comprising the group when considered explicitly as its members, rather than individually are considered on duty. For instance, you might set up a group called {EmergencySupport} and assign it an around-the-clock schedule. When a message is directed to this group, all destinations comprising it are considered eligible to be sent the message. By contrast, if the same message were directed to any one of these destinations individually, the destination s validity would depend on its own schedule, if any. Typically, you would specify a schedule for a group within the [Group] definition itself, but you may specify a default schedule for all groups instead. This default will not apply to any group that specifies its own schedule, however. 180 TelAlert Administrator Guide - Version 5.7

11.4.3 Schedules and [Filter] Definitions A schedule, like a [Filter] definition, is a means of destination qualification. Whereas a [Filter] definition determines whether a destination is valid based on the tag or tags accompanying the message, a schedule determines whether a destination is valid based on the time the message is to be sent. You do not have to do anything special to make schedules and [Filter] definitions work together. If a destination is associated with a schedule and a [Filter] definition, TelAlert will send it a message only if it finds that the destination is both on duty and valid according to the terms of the [Filter] definition. For information on setting up and using [Filter] definitions, refer to Chapter 10: Applying Filtering Techniques. 11.4.4 Schedules and [User]Definitions [User] definitions offer another means of associating schedules with destinations. You can create a [User] definition, refer to a schedule in it, and then refer to the [User] definition in the [Destinations] definition. The schedule will operate as if it were specified there directly. (If a schedule is specified directly in the destination, however, it will override the one specified at the user level.) This is an especially effective way of linking a schedule with one or more destinations when several destinations belong to the same human user and you want the same schedule to apply in all cases. For instance: [Schedule] {JohnSchedule} Sunday=16:00-23:59 Monday=16:00-23:59 Tuesday=16:00-23:59 Wednesday=16:00-23:59 Thursday=16:00-23:59 Friday=16:00-23:59 Saturday=16:00-23:59 [User] {John} Schedule=JohnSchedule [Destinations] {JohnTextPager} User=John {JohnCellPhone} Chapter 11: Setting Up and Applying Schedules 181

User=John {JohnHomePhone} User=John Here, {JohnSchedule} will apply whenever a message is directed to a destination linked to {John}. You may find that tying schedules to destinations via [User] definitions is valuable whenever the schedules at work in an organization are connected with people, as opposed to the destinations 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 [User] definitions for some other purpose (to link [Filter] definitions to destinations, for instance), this method makes even more sense, since the [User] definitions can be made to serve two purposes. 11.4.5 Vacations and Holidays TelAlert schedules allow you to specify time during which the destination is off-duty, independent of the terms of the main Sunday-through-Saturday schedule. You do this using the Vacation and Holidays keywords, and you set their values simply by listing dates, in yyyy/mm/dd format, separated by commas. You can record consecutive days off using a date range. You can also include hour and minute values in a date range. For example: Vacation=2010/4/2@17:00-2010/4/12@8:00 Vacation and Holiday each operate according to the same logic; they exist as separate keywords simply as a convenience, so you can record days off under two different categories. 11.4.6 Adding Time to a Schedule: ExtraDuty Vacation and Holidays allow you to create exceptions to the on-duty time explicitly specified in a schedule. Similarly, ExtraDuty lets you create an exception to the off-duty time the schedule implies (i.e., all times not specified as on-duty). You express an ExtraDuty value as a date range, just as with Vacation or Holidays. During the time specified, the destination will be considered valid, even if according to the main schedule it would otherwise be off-duty. This is useful in a case where a person works a normal weekly schedule and also is assigned once a month, perhaps a day of extra duty. 182 TelAlert Administrator Guide - Version 5.7

11.4.7 Including Other Schedules in a Schedule Using AddSchedules A schedule can refer to other schedules using the AddSchedules keyword. This allows you to create a schedule out of only those components that you want to apply to all destinations and then invoke it in the schedule definitions you create for individual destinations. For instance, you might create a schedule called {CompanyHolidays} that does nothing more than list your company s holidays using the Holidays keyword. By referring to this schedule in all individual [Schedule] definitions using AddSchedules, you can make these holidays apply to all destinations associated with a schedule. For example: [Schedule] {CompanyHolidays} Holidays=2010/1/1,2010/1/18,2010/2/15,2010/5/24,2010/7/5,20010/9/6,2010/11/25, 2010/11/26,2010/12/24 {DavidSchedule} Sunday=08:00-15:59 Monday=08:00-15:59 Tuesday=08:00-15:59 Wednesday=08:00-15:59 Thursday=08:00-15:59 Friday=08:00-15:59 Saturday=08:00-15:59 AddSchedules=CompanyHolidays In the above example, July 4 falls on a Sunday, and the day off is assigned to the following Monday. If your company decided to make the preceding Friday a day off instead, you could make this change in a single step. Using Schedule Using a Schedule reference in a [Schedule] definition to refer to another schedule, you can set default values for the schedule containing the Schedule reference. Consider the following example: [Schedule] {DavidSchedule} Monday=08:00-17:00 Tuesday=08:00-17:00 Wednesday=08:00-17:00 Thursday=08:00-17:00 Friday=08:00-17:00 Schedule=WeekendSchedule {WeekendSchedule} Sunday=12:00-16:00 Saturday=12:00-16:00 Chapter 11: Setting Up and Applying Schedules 183

Here, {DavidSchedule} inherits the Saturdayand Sunday values in WeekendSchedule, as would any other schedule that referred to {Weekend} using the Schedule keyword. If {DavidSchedule} contained its own Saturday and Sunday values, these values would override those in {Weekend}. The Difference Between AddSchedulesand Schedule Values contained in a [Schedule] definition invoked using AddSchedules are used in addition to the values contained in the schedule that makes the AddSchedules reference. If both schedules contain the same keyword (Monday, for instance) and different values for each (08:00-16:00 in one and 16:00-24:00 in the other, for instance), these values are combined (so that in this example Monday would have a value of 08:00-24:00). By contrast, values contained in a [Schedule] definition invoked using Schedule are used only if the schedule that makes the Schedule reference does not contain corresponding keyword values. If it does, these values override those in the invoked schedule. 11.4.8 Schedules and Message Priority The keywords discussed here AlternateSchedule, AlternateSchedulePriority, and OverrideSchedulePriority are usually used to enable TelAlert to look to other, less restrictive schedules in determining how to handle messages of a certain specified urgency. AlternateSchedule and AlternateSchedulePriority Under normal circumstances, TelAlert will not send a message to a destination that is off duty according to the terms of its schedule. But you can associate an alternate schedule with a destination (or group or user) and specify a priority threshold that a message must meet for the alternate schedule to come into play. For instance, perhaps David wants to be paged about routine events only during his regular work hours, as represented in {DavidSchedule}: [Schedule] {DavidSchedule} Sunday= Monday=08:00-18:00 Tuesday=08:00-18:00 Wednesday=08:00-18:00 Thursday=08:00-18:00 Friday=08:00-18:00 Saturday= However, in the case of more severe events, he wants to be paged on the weekend as well, during these same hours. To allow for this, he creates another schedule, like so: {DavidExtendedSchedule} AddSchedules=DavidSchedule Sunday=08:00-18:00 Saturday=08:00-18:00 184 TelAlert Administrator Guide - Version 5.7

His pager destination then invokes both of these schedules and sets a threshold at which the alternate schedule takes effect: {DavidPager} Schedule=DavidSchedule AlternateSchedule=DavidExtendedSchedule AlternateSchedulePriority=70 With this setup, both of the following two commands cause TelAlert to use David s regular schedule in evaluating the validity of his pager destination: telalertc -i DavidPager -m "this is a test" telalertc -i DavidPager -m "this is a test" -priority 60 These messages will be sent only if it comes at a time covered by {DavidSchedule}. Note that a command issued without a -priority value will never invoke an alternate schedule. As soon as the priority assigned to the alert is 70 or higher, however telalertc -i DavidPager -m "this is a test" -priority 70 telalertc -i DavidPager -m "this is a test" -priority 80 TelAlert will send the message to David if it comes at a time covered by {DavidExtendedSchedule}, which here is defined as a more open schedule: David s regular hours plus additional weekend hours. OverrideSchedulePriority You can take special treatment of high-priority messages a step further using OverrideSchedulePriority in a destination, a group, or a [User] definition. When a message s priority meets or exceeds this threshold, TelAlert will send it, completely disregarding all questions of schedule. Simply add the OverrideSchedulePriority setting, where appropriate. For example: [Destinations] {DavidPager} AlternateSchedule=DavidExtendedSchedule AlternateSchedulePriority=70 OverrideSchedulePriority=90 There is no schedule that corresponds to OverrideSchedulePriority, as there is with AlternateSchedulePriority, since this keyword overrides all schedules rather than invoking an alternate one. Chapter 11: Setting Up and Applying Schedules 185

11.4.9 Schedules Longer or Shorter than Seven Days TelAlert s Schedule feature assumes a Sunday-through-Saturday schedule that repeats every seven days. Sometimes, however, you may want to represent a schedule that repeats according to some other interval: perhaps a support technician is on call around the clock every third day, or perhaps she is on call twelve hours a day every day for a week, then has a week off. TelAlert offers two means of setting up schedules that repeat according to non-weekly intervals. One is ideal for multiple-week intervals i.e., for intervals of fourteen days, twenty-one days, twenty-eight days, etc. The other is better suited for intervals of less than seven days, and for longer intervals comprised of a number of days not divisible by seven. RotationSchedules RotationSchedules is ideal for setting up a schedule comprised of a multiple-week interval. It allows you to bolt together two or more weekly schedules (up to 13), so that each Sundaythrough-Saturday period specifies its own unique set of on-duty hours. It should be mentioned that this first example uses an example where the duty rollover from one tech to the next tech exactly matches the internal TelAlert definition of a week (which start at 12:00AM Sunday morning and end at 11:59PM Saturday night). Example 1 To use this feature, follow these directions. 1. Create one Sunday-through-Saturday [Schedule] definition for each unique weekly schedule. Here, the scenario is that mentioned above: Cynthia is on call twelve hours a day for one week, then not on call at all the week following. [Schedule] {WeekOn} Sunday=08:00-20:00 Monday=08:00-20:00 Tuesday=08:00-20:00 Wednesday=08:00-20:00 Thursday=08:00-20:00 Friday=08:00-20:00 Saturday=08:00-20:00 {WeekOff} Sunday= Monday= Tuesday= Wednesday= Thursday= Friday= Saturday= 186 TelAlert Administrator Guide - Version 5.7

2. Use the RotationSchedules keyword to refer to these schedules in the schedule of the relevant person/destination, and use RotationStart to specify the date on which you want the rotation to begin: {CynthiaOnCallSchedule} RotationSchedules=WeekOn,WeekOff RotationStart=2010/1/3 3. If there is someone who will be on duty during the week Cynthia is off, you can use the same weekly schedules as part of that person s schedule, and add that definition to the [Schedule] section. Here you would set RotationStart for David one week later than for Cynthia: {DavidOnCallSchedule} RotationSchedules=WeekOn,WeekOff RotationStart=2010/1/10 Note: You should set RotationStart to the date of the Sunday on which you want this two-weeklong rotation to begin. This can be any Sunday past, present, or future. If you specify a date in the future, the rotation will not begin until that Sunday arrives. Note that in the interim until the rotation start date arrives there will be no rotation associated with the recipient, and TelAlert will assume that person is on-duty 24 hours a day, 7 days a week. Thus, if you want the rotation to take effect immediately, you should specify a date in the past. Specifying a date in the past causes the rotation to begin immediately, picking up with the day of the week in the first weekly schedule corresponding to today (that is, if you specify a past Sunday and today is a Wednesday, the rotation picks up with the hours set for Wednesday in the first weekly schedule). More Than One RotationSchedules Reference Leads to an Error A [Schedule] definition must not contain more than one RotationSchedules reference, either directly or indirectly through AddSchedules (of course, as in the examples above, this one reference will point to more than one schedule). For instance, if you set a RotationSchedules value and use AddSchedules to refer to another schedule that contains a RotationSchedules value, initialization will fail. Chapter 11: Setting Up and Applying Schedules 187

Example 2 It may also be useful to start the rollover at a different point during the week. There may be an occasion where one person is going off duty can talk to the person coming on duty to transfer any work-in-process. In this case it would be usual to have the rollover at 8AM Monday morning, or sometime Friday afternoon. The following is an example that illustrates this case. Assume 4 people on the team; Bob, Carol, Ted, and Alice. Each person is on-duty from noon on one Friday, continuously until noon on the following Friday. They are then off for 3 weeks. There are two methods to set up the schedules. The first method combines sets of 7-day weekly schedules. The second method uses a single 28-day (4 x 7) schedule. The methods are effectively equivalent. However, some people may be able to visualize one method more readily than the other method. First method: [Schedule] {PartialOnStartWeek} Sunday= Monday= Tuesday= Wednesday= Thursday= Friday=12:00-23:59 Saturday=00:00-23:59 {PartialOnEndWeek} Sunday=00:00-23:59 Monday=00:00-23:59 Tuesday=00:00-23:59 Wednesday=00:00-23:59 Thursday=00:00-23:59 Friday=00:00-11:59 Saturday= {FullOffWeek} Sunday= Monday= Tuesday= Wednesday= Thursday= Friday= Saturday= {CompleteRotation} RotationSchedules=PartialOnStartWeek,PartialOnEndWeek,FullOffWeek,Full offweek 188 TelAlert Administrator Guide - Version 5.7

## RotationStart must be a Sunday, by definition, when using weekly schedules {BobSchedule} Schedule=CompleteRotation RotationStart=20030126 {CarolSchedule} Schedule=CompleteRotation RotationStart=20030202 {TedSchedule} Schedule=CompleteRotation RotationStart=20030209 {AliceSchedule} Schedule=CompleteRotation RotationStart=20030216 ============================================================= Second method: [Schedule] {CompleteRotation} Day1=12:00-23:59 Day2=00:00-23:59 Day3=00:00-23:59 Day4=00:00-23:59 Day5=00:00-23:59 Day6=00:00-23:59 Day7=00:00-23:59 Day8=00:00-11:59 DefaultDay= RotationDays=28 ## Instead of "DefaultDay=", could have specified ## Day9= ## Day10= ## ## Day28= Chapter 11: Setting Up and Applying Schedules 189

## RotationStart is a Friday per this customer s policies {BobSchedule} Schedule=CompleteRotation RotationStart=20030131 {CarolSchedule} Schedule=CompleteRotation RotationStart=20030207 {TedSchedule} Schedule=CompleteRotation RotationStart=20030214 {AliceSchedule} Schedule=CompleteRotation RotationStart=20030221 ============================================================= Perhaps a fifth person (let s say George) needs to be added to the rotation. In the first method, you would make this change in {CompleteRotation}: RotationSchedules=PartialOnStartWeek,PartialOnEndWeek,FullOffWeek, FullOffWeek,FullOffWeek and add this new schedule: {GeorgeSchedule} Schedule=CompleteRotation RotationStart=20030223 In the second method, you would make this change in {CompleteRotation}: RotationDays=35 and add this new schedule: {GeorgeSchedule} Schedule=CompleteRotation RotationStart=20030228 You may test these schedules from the command line by specifying which schedule you want to test and the date/ time to compare to the schedule. You will get a response that indicates if the specified date/time is on duty or off duty for that schedule: telalert -checkonduty schedule BobSchedule -datetime 2003/01/31@11:59 telalert -checkonduty schedule BobSchedule -datetime 2003/02/07@12:00 190 TelAlert Administrator Guide - Version 5.7

will both return off duty, while: telalert -checkonduty schedule BobSchedule -datetime 2003/01/31@12:00 telalert -checkonduty schedule BobSchedule -datetime 2003/02/07@11:59 will both return on duty. If you check: telalert -checkonduty schedule BobSchedule -datetime 2003/01/30 you will get on-duty. The reason for this is that the date is prior to the RotationStart date in BobSchedule, and so the schedule is not in effect at all. A schedule that isn't in effect is different from a schedule that is in effect and is indicating off-duty. In TelAlert, if no schedule is in effect, you are on-duty. This allows TelAlert to function with those TelAlert customers that do not use schedules at all. RotationDays RotationDays is better suited for intervals of less than seven days, and for longer intervals comprised of a number of days not divisible by seven. It allows you to specify on-duty hours for a series of days (up to 98) and have TelAlert repeat the sequence each time it reaches the end. The following example takes up the scenario already mentioned, in which a technician is on call twentyfour hours a day every third day. [Schedule] {JohnThreeDaySchedule} Day1=00:00-23:59 Day2= Day3= RotationDays=3 RotationStart=2000/1/10 RotationStart sets the rotation s Day1. TelAlert equates Day1 with 2000/1/10 and begins cycling through the rotation beginning on January 1, 2000, and begins with Day1. The number assigned to RotationDays should match the total number of Days (Day1, Day2, etc.) you have defined as part of the rotation. Note that, if you assign a non-zero value to this keyword, this schedule must not contain any regular day references (Monday, Tuesday, etc.). If more than one person will be using this rotation, you can put it in a [Schedule] definition of its own and refer to it in other schedules using AddSchedules. For instance, if John, Rachel, and David each are on call all day every third day, John the first day, Rachel the second, and David the third, you could set up a rotation like this: Chapter 11: Setting Up and Applying Schedules 191

[Schedule] {ThreeDayRotation} Day1=00:00-23:59 Day2= Day3= RotationDays=3 {John} AddSchedules=ThreeDayRotation RotationStart=2000/1/3 {Rachel} AddSchedules=ThreeDayRotation RotationStart=2000/1/4 {David} AddSchedules=ThreeDayRotation RotationStart=2000/1/5 Here, assigning each individual schedule a different RotationStart date makes each person s Day1 a different day, enabling a rotation in which each person is on duty on the day when the other two are off. Mixing RotationSchedules and RotationDaysLeads to an Error If a schedule contains a RotationDays value, it must not (directly or through reference) contain any regular day of the week values (i.e., Sunday, Monday, etc.). Likewise, if a schedule contains a RotationSchedules value, it must not (directly or through reference) contain any numbered day values (i.e., Day1, Day2, etc.). Finally, a schedule must not contain both a RotationSchedules and a RotationDays value. 11.4.10 Changing a Rotation Schedule to Account for Unexpected Leave Suppose one of your employees is on leave, and you need to substitute another one for those shifts during the leave period. Change the RotationStart date of the person who will "cover" for the employee who is missing; make it match the date of the missing employee. When the missing employee returns from leave, you can return the other employee to their old schedule. 11.4.11 Reverse Schedules: Exclusive Adding the Exclusive keyword to a schedule reverses its effect, making hours that would normally be on duty off duty, and vice versa. This option is useful when it is easier to specify the hours when someone is not available. For example, say a high-level supervisor is on call for emergencies 24 hours a day, 7 days a week, except when on vacation. 192 TelAlert Administrator Guide - Version 5.7

The following definition is an easy way to implement such a schedule: {David} Exclusive=True ExtraDuty=2010/4/6@17:00-2010/4/16@8:00 With the above schedule, David is off duty only during the period specified by ExtraDuty (which, since the schedule has been reversed, is equivalent to Vacation in a normal schedule). Without the Exclusive keyword, the schedule would be considerably more complex: {David} Exclusive=False Sunday=00:00-23:59 Monday=00:00-23:59 Tuesday=00:00-23:59 Wednesday=00:00-23:59 Thursday=00:00-23:59 Friday=00:00-23:59 Saturday=00:00-23:59 Vacation=2010/4/6@17:00-2010/4/16@8:00 Chapter 11: Setting Up and Applying Schedules 193

12 Representing Users 12.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. 12.2 Getting Started 12.2.1 What Are Users? What Are They For? In TelAlert, it is important not to confuse destinations with people: a destination such as a pager may be one of several ways a given individual can be contacted, or a destination may not be associated with a unique individual or with any people at all a single pager may be carried by a different person each shift, for instance, and an electronic signboard is often used to deliver messages to a roomful of people. [User] definitions offer a way of introducing the notion of people into TelAlert s view of the world. Their uses fall into three main categories. 1. Values for Inheritance by Associated Destinations By referring to a [User] definition in a destination, you can cause the destination to inherit its values: Schedule, AlternateSchedule, Password, MinFilterPriority and MaxFilterPriority, etc. Thus, TelAlert knows how to assess the destination s validity in light of the message s priority or -filter tags, or how to determine the identity of someone with whom it is interacting (i.e., by asking for a password when the person attempts to respond to a notification). 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, whenever 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. 12.2.2 Needed Information [User] definitions must be used in conjunction with destinations that invoke [Configurations] definitions of Type=InteractiveVoice or InteractiveTTS. 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. 12.2.3 Other Considerations TelAdmin vs. telalert.ini File Configuration To represent users, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation. The instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 196 TelAlert Administrator Guide - Version 5.7

12.3 Creating a [User] definition: Essentials The most basic [User] definition consists of a user name and password, like so: [User] {John} Password=123 This definition could contain another value, Active=True, but it is unnecessary. By default, all [User] definitions are active unless they are set to Active=False, or unless this has been set as the default value for all users. Some organizations need [User] definitions only insofar as they are required by TelAlert s voice menus and dial-in access functionality. Thus, they sometimes set up a single [User] definition like the one above {Operator}, for instance and refer to it in every required instance. In this case, every person would use the same password to demonstrate his or her authorization to receive and respond to messages. More commonly, security policy requires unique passwords for each [User]. In this case, create [User] entries for each [User] with separate passwords for each. In such an environment, it also common to set all passwords to be encrypted before being written to the telalert.sects file 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 such a definition by editing telalert.ini, initialization (telalert init or telalert -start -init) will fail. 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.. 12.4 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. Chapter 12: Representing Users 197

12.4.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 12.4.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 12.4.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 198 TelAlert Administrator Guide - Version 5.7

12.4.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 12.5 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=123 DialInMenuAccess=True DialOutMenuAccess=True Menu=MenuAck These settings have very little to do with the destinations associated with {Rachel}. The one connection is a general one: Rachel will be able to use TelAlert s dial-in and dial-out capabilities to access only those messages sent to destinations with which she is associated as user. However, neither the fact that she has dial-in/dial-out access nor the Menu setting affects TelAlert s processing of the messages sent to these destinations. In this sense, these settings are distinct from those discussed under Values for Inheritance by Associated Destinations, located earlier in this chapter. Chapter 12: Representing Users 199

Below is a list of the keywords that can be assigned values in a [User] definition in order to control TelAlert s dial-in/dial-out behavior for that user: Active DialInMaxMessages DialInMenuAccess DialOutMaxMessages DialOutMenuAccess Menu ModemDialbackAreaCode ModemDialbackConfiguration ModemDialbackNumber Password VoiceDialbackAreaCode VoiceDialbackConfiguration VoiceDialbackNumber 12.6 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. 12.6.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: telalert -show -user Administrator 200 TelAlert Administrator Guide - Version 5.7

12.6.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 12.6.3 Listing Users Another administrative function allows you to generate a list of [User] definitions. To do this, 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: telalertc -list sectionname There are three variations on the basic -list users technique: 1. For those [User] definitions containing a FullName value, the list you generate will show this value instead of the name of the definition. This allows you to give your [User] definitions a simple name (one that is easy to refer to on the command line, in destination definitions, etc.) and still be able to determine at a glance the person to whom it belongs. 2. If ListDisplay is set to False, however, neither a [User] definition s name nor its FullName value will be displayed when you tell TelAlert to list all users. The default for this value is True. 3. Finally, if you include ListFilter in your [User] definitions and assign this keyword a value pointing to a [Filter]entry, you can impose additional restrictions on what [User] definitions are displayed when you tell TelAlert to list them. This filtering works just as the filtering described in the first part of Chapter 10: Applying Filtering Techniques. Simply use a -tags value when you give the list command, and TelAlert will display [User] definitions according to the filtering rules you have created. For instance, you could set up a [Filter] definition such that specifying a certain tag with the command causes all [User] definitions pointing to that [Filter] definition to be displayed. Having done this, you would issue a command like this to see a list of those [User] definitions: telalertc -list users -tags RouterSupport Alternatively, you could set up a [Filter] definition such that specifying a certain tag with the command causes all [User] definitions pointing to that [Filter] definition not to be displayed. The difference hinges on the Exclusive setting in the [Filter] definition. For more information, refer to Chapter 10: Applying Filtering Techniques. Chapter 12: Representing Users 201

13 Enabling Responses 13.1 Overview 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. 13.2 Getting Started 13.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 a destination with 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. 13.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.

13.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 AcknowledgeWait=value 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.) TelAdmin vs. telalert.ini File Configuration To set up [Response] definitions, you can use TelAdmin (now a component of the TelAlert desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation. Thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 13.3 Taking Advantage of Pre-Defined Responses TelAlert ships with two sets of pre-defined responses under [Response]. These are ready for you to refer to on the command line. For example: [Response] {Basic} NumReplies=6 Acked=1 AckedHold=3,4,6 NotAcked=2 Released=5 Reply1=Yes Reply2=No Reply3=Hold Reply4=Info Reply5=Release Reply6=Ping Here, Reply4 is intended to offer a means by which the user can send additional info (this requires the use of a script invoked using a [Notifications] definition). Reply6 is intended to allow the user to run a script that pings a node and reports the result to the user (this, too, requires the use of a script invoked using a [Notifications] definition). 204 TelAlert Administrator Guide - Version 5.7

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.. 13.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 Chapter 13: Enabling Responses 205

13.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" Reply4=NoOffDuty #Reply4 means "no, I am off duty" Reply5=HoldWillHandle #Reply5 means "hold, I will handle it" Reply6=HoldWillDelegate #Reply6 means "hold, I will assign this to someone else" Reply7=ReleaseFixed #Reply7 means "release, this is fixed" Reply8=ReleaseNotFixed #Reply8 means "release, but this is not fixed" Here, two responses map to each command, allowing the respondent to positively acknowledge the message in two ways, negatively acknowledge the message in two ways, and so on. (The intended meaning of each response is explained in a comment line.) The text of the response will be available in the telalert.trail file. You can take greater advantage of this sort of response-related information using TelAlert s [Notifications] feature. For more information, refer to Responses and the [Notifications] Feature below. Once you have the desired set of responses in place, you can send pages by invoking the destination in a command such as this: telalertc -i DavidTwoWayInternetPager -m "this is a test" -response Detailed -ackwait 15m 206 TelAlert Administrator Guide - Version 5.7

13.5 Two-Way Pager Considerations Because invocation of a set of responses is handled more or less seamlessly in sends to two-way pager destinations (i.e., the responses are presented straightforwardly as a menu of choices, without additional effort on your part), the only detail unique to two-way pagers with which you need to concern yourself is polling. Polling is the means by which TelAlert checks for responses to two-way pages it has sent. TelAlert knows to poll for responses whenever it sends a page that meets three conditions: The page must use a [Configurations] definition (or a destination) in which Type is defined as InteractiveTextPager. The command generating the alert must specify an ackwait value (or an AcknowledgeWait value must be in effect via some other mechanism). The command generating the alert must specify a set of responses. In addition, the message must still be active: it must be in either an ackwait or ackheld state. Otherwise, from TelAlert s point of view, the message no longer exists and there is no reason for TelAlert to poll for a response. When it polls, TelAlert uses the same [Configurations] definition that it used to send the original page. If you send a two-way page via the Internet, TelAlert attempts to retrieve a response by the same medium. If DialBackup is specified and TelAlert encounters the specified number of connect errors in attempting to poll, it will use the DialBackup information to poll by dial-up. 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. 13.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. Chapter 13: Enabling Responses 207

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 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},${PI N},& ${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. 208 TelAlert Administrator Guide - Version 5.7

But, because the destination contains a NotificationReply value, TelAlert also executes reply.sh (or, in Windows, reply.ksh), the script specified in the [Notifications] definition named {BasicReply}. reply.sh (or.ksh), 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.ksh is designed to interpret the value following -remarkas a node address or name.) The script then passes the result of the ping to TelAlert as the message part of a command that generates another page to {DavidTwoWayInternetPager}. By this means, David learns the ping s result. The template reply.sh(or.ksh), in the form provided by Vytek Messaging Services, Inc., 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 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.ksh) 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, 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. 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 13: Enabling Responses 209

14 Broadcasting to Groups and Creating Escalations 14.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. 14.2 Getting Started 14.2.1 What Are Groups? What Are They For? Groups are collections of destinations and \or subgroups. When you issue a command that tells TelAlert to send a message, you can specify a group rather than an individual destination, and TelAlert will send the message either to all of the destinations at once or to each of the destinations singly, in sequence, according to rules and Strategies you specify. The first technique, broadcast group notification, which is the default for newly created Groups, is useful for getting a piece of information out to a number of people at once. The second, called escalation, is useful for ensuring that a message reaches at least one of a number of people qualified to handle the problem. 14.2.2 Needed Information To set up [Group] definitions, you will need to know the names of the Destinations or Groups out of which you want to construct your groups. You should also think about how you will use the groups you set up e.g., whether you will use them for broadcast or escalation, whether you want escalation to proceed destination by destination or subgroup by subgroup, and what conditions must be met before TelAlert is to consider an escalation complete.

14.2.3 Other Considerations TelAdmin vs. telalert.ini File Configuration To set up groups, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide methodneutral documentation. Thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 14.3 Group Basics 14.3.1 Building a Group from a List of Destinations At its most basic, a [Group]definition is simply a list of destination names: [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. 14.3.2 Building a Group From a List of Other Groups A group can also be a list of other groups (or subgroups ). For example: [Group] {Support} Destinations=DayShift,NightShift {DayShift} Destinations=DavidTextPager,RachelTextPager {NightShift} Destinations=CynthiaTextPager,JohnTextPager 212 TelAlert Administrator Guide - Version 5.7

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: [Group] {Support} Destinations=DayShift,NightShift,JaneTextPager Fundamentally, nothing distinguishes groups from subgroups; a subgroup is simply a group that is listed as a destination in another group. It is permissible to create a group that refers to another group that in turn refers to yet another group but ultimately TelAlert must be able to resolve these references in terms of actual destinations. 14.3.3 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 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. If you have must have Destinations and Groups names the same, you can configure TelAlert to know which one to use first by changing the parameter GroupFirstInIGandL=False in the [Limits] section, False indicates Destination first, True indicates Group messaging first. Strategy points to a [Strategy] definition. If you assign a value here, a send directed to the group will be considered complete only when the strategy s completion criterion is met. If the strategy is also given an Escalate value, 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. Schedule, AlternateSchedule, AlternateSchedulePriority, OverrideSchedulePriority A schedule set for a group determines the on-duty hours for the group as a whole; any schedules set for the destinations or subgroups comprising the group are ignored if a schedule is set for the group as a whole, (Group schedules override destination schedules). Schedule-related keywords apply here just as they do for destinations. For more information, refer to Chapter 11: Setting Up and Applying Schedules. Chapter 14: Broadcasting to Groups and Creating Escalations 213

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. Note: Performing an init or a save in TADesktop resets the order back to A-B-C. 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. 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. 14.4 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 214 TelAlert Administrator Guide - Version 5.7

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. 14.4.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. 14.4.2 Use of -g and -l Compared It is also possible to send to group using the -l syntax, as follows: telalertc -l JohnTextPager,CynthiaTextPager,RouterSupportGroup -m "this is a test" For a given alert, only one escalation strategy can be in effect. If you use the -g "group_name" syntax, it's the strategy in the "group_name" definition that is in effect. If you use the -l syntax, you are essentially creating, on-the-fly, a one-time-use "supergroup". (If you are logging, you can assign a name to this one-time-use group with the -name parameter.) Regardless of whether you use -name, if you want this one-time-use group to use a strategy, you must specify the -strategy parameter; 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 to fully define the onetime-use group you are creating on-the-fly. 14.4.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 11: 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. Chapter 14: Broadcasting to Groups and Creating Escalations 215

14.5 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. 14.5.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 With this group and this [Strategy] definition in place, a message directed to the group, like so telalertc -g Support -m "this is a test" -ackwait 10m will be sent first to David. If after ten minutes TelAlert has not received an acknowledgment from David, it will send the message to Rachel. If after ten minutes TelAlert has not received an acknowledgment from Rachel, it will send the message to Cynthia. If after ten minutes TelAlert has not received an acknowledgment from Cynthia, it will send the message to John. If David acknowledges the message during the initial ten-minute ackwait period (for an explanation, see the following note), escalation stops and the message is not sent to anyone else. If escalation continues, it does so only until an acknowledgment is received from one of the recipients. This permits the fewest possible people to be contacted while at the same time ensuring that the problem is handled. Note that you can also have command destinations, i.e., destinations associated only with [Configurations] definitions of Type=Command. Since there is no human at a "command" destination, there s no human to acknowledge the alert. Instead, the keyword Acked in the definition of the "command" destination determines whether TelAlert considers the "command" destination to have acknowledged the alert. 216 TelAlert Administrator Guide - Version 5.7

In this example, there are several things to understand about strategies in general, and the strategy called FirstAcknowledge in particular: The send is treated as an escalation because the [Strategy] definition invoked by the group contains an Escalate value. Complete specifies the conditions under which TelAlert will consider the alert complete. Here, Complete=Acked>0 means that a send in which this strategy is invoked will be considered complete when at least one person has positively acknowledged it (i.e., when the number of messages acked is greater then zero). If the Complete criterion is met, TelAlert ends the escalation. Escalate specifies the conditions under which TelAlert will escalate the alert, assuming the Complete criterion has not yet been met. In this example, Escalate=Incomplete=0 means that TelAlert will send the message to the next destination when the current send ceases to be in an incomplete state (i.e., when the number of sends in an incomplete state equals zero). TelAlert treats escalation differently when the group is comprised of subgroups. For more information, refer to Escalations Involving Subgroups later in this chapter. ackwait The key to escalation is the -ackwait numberm/h parameter used at the command line or, alternatively, the AcknowledgeWait=numberm/h line that can be used in defining a group or destination. These entries tell TelAlert how long to wait but before doing what? If there is a [Strategy] definition for TelAlert to refer to, it sends to the first destination and waits this amount of time before following its escalation procedure. If there is no [Strategy] definition, it sends to all destinations and waits this amount of time before releasing the alert. Without the -ackwait parameter or AcknowledgeWait= line, any escalation procedure specified in a [Strategy] definition becomes meaningless, since TelAlert will not know how long to wait before escalating the alert. In such cases, TelAlert sends to all destinations at once. -ackwait at the command line overrides an AcknowledgeWait value in telalert.ini. TelAlert ignores any AcknowledgeWait value given as part of a [Destinations] definition when that definition is invoked as part of a group. Note: The AcknowledgeWait time is started after a successful Send, not the time the alert was issued. Chapter 14: Broadcasting to Groups and Creating Escalations 217

14.5.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 The supported relational operators are: = equal to > greater than >= greater than or equal to < less than <= less than or equal to <> not equal to Send states that can be referred to in [Strategy] definitions are as follows. (The numerical values assigned to these keywords always represent the percentage of the total number of sends that are in this state.) Acked sends that have been successfully sent and acknowledged by the receiver NotAcked sends that have been negatively acknowledged Sent sends that have been successfully sent to their destination Failed sends that could not be successfully sent to their destination and for which the maximum number of attempts have been made (as determined by the MaxFailCalls value for that configuration) 218 TelAlert Administrator Guide - Version 5.7

Cleared sends that have been cleared using the -clear option on the command line Incomplete sends that are still in progress. A send is incomplete if TelAlert has not yet made an attempt to send to a destination, or if TelAlert is trying to send the message but has not yet succeeded OffDuty sends that will never be sent because the destination is not currently on-duty There is one other keyword that can be used in setting a Complete or Escalate value. (The numerical value assigned to it represents a number of minutes.) Time the number of minutes since TelAlert began issuing sends to the current destination or subgroup. Typical Escalate Value Escalate=Incomplete=0 is the appropriate value in almost all instances. Rarely will you need to use another setting. 14.5.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 Chapter 14: Broadcasting to Groups and Creating Escalations 219

Here, a message directed to {Support}, like so telalertc -g Support -m "this is a test" -ackwait 10m will first be sent to Pager1, Pager2, and Pager3, all at once. If none of these recipients acknowledges the message within ten minutes, it will be sent to Pager4,Pager5, and Pager6, all at once. If none of these recipients acknowledges the message within ten minutes, it will be sent to Pager7, Pager8, and Pager9, all at once. If none of these recipients acknowledges the message within ten minutes, the alert is marked as finished but not as complete, since the Complete criterion was not met. Sending to Subgroup Members Individually: SubgroupEscalation The way TelAlert processes an escalated send to a group comprised of subgroups is changed significantly by the use of the SubgroupEscalation keyword. TelAlert treats any group containing a subgroup in which SubgroupEscalation is set to True as if the subgroup s destinations were included directly in the supergroup. For instance, a group containing this Destinations setting Destinations=SG1,SG2,SG3 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 220 TelAlert Administrator Guide - Version 5.7

Because SubgroupEscalation is set to True in {Group1}, a message directed to {SupportGroup} would be handled as follows: TelAlert sends the message to Pager1. If this recipient does not acknowledge the message within ten minutes, TelAlert sends the message to Pager2. If this recipient does not acknowledge the message within ten minutes, TelAlert sends the message to Pager3. If this recipient does not acknowledge the message within ten minutes, TelAlert sends the message to Pager4, Pager5, and Pager6, all at once. If none of these recipients acknowledges the message within ten minutes, TelAlert sends the message to Pager7, Pager8, and Pager9, all at once. If none of these recipients acknowledges the message within ten minutes, the alert is marked as "finished" but not as "complete," since the Complete criterion was not met. Under what circumstances would you want to use SubgroupEscalation? Assume that you have three groups of support technicians. Any member of any of the groups is qualified to handle a node down message, but it is most appropriate to assign a member of one particular group whenever possible. This much is achieved simply by listing this most appropriate group first, since TelAlert sends to the destinations in the order in which they are listed. But perhaps you also want to avoid paging all the members of this first group each time a node down message is generated. By setting SubgroupEscalation to True in the definition of this group, you cause TelAlert to send the 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 Escalation Applicable Only to Subgroups SubgroupEscalation=True has 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. Chapter 14: Broadcasting to Groups and Creating Escalations 221

14.5.4 Balancing Workloads by Rotating the First Destination Because TelAlert, when processing escalations, sends to destinations in the order in which they are listed, you may find that some people are being assigned a heavier workload than others. For instance, if JohnPager is the first destination listed in a group called {Support} that invokes a strategy containing an Escalate value, John (when on duty) will always be the first person to receive a page whenever a message is directed to that group. You can address this problem using RotateFirstDestination. Set this to True in the [Group] definition, and TelAlert will begin with a different destination each time it processes a send directed to this group: A-B-C, then B-C-A, then C-A-B, for example. You can use RotateFirstDestination in a group comprised of subgroups to have TelAlert rotate the order in which it sends to the subgroups. If SubgroupEscalation is True for one of these subgroups, its destinations become part of the rotation. Likewise, in a group comprised of a mixture of destinations and subgroups, rotation is applied to all of these entities equally. Note that it is not common to use RotateFirstDestination to rotate the order in which TelAlert sends to subgroups, since typically the purpose of defining a group in terms of subgroups is to arrange personnel in the order in which you want them to be contacted from most to least appropriate, for example, or from least to most expert. You can invoke destination rotation at the command line using the -rotatefirstdest option. For example: telalert -g support -rotatefirstdest -m "this is a test" -ackwait 10m If the support group includes LucyPager, RickyPager, and EthelPager, and this is the first message sent using -rotatefirstdest, the first send will go to RickyPager. If the next message sent to the group also includes -rotatefirstdest, its first send will go to EthelPager. If it does not include -rotatefirstdest, the first send will go to RickyPageragain. 14.5.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 11: 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. 222 TelAlert Administrator Guide - Version 5.7

15 Processing Events 15.1 Overview Instructions for setting up TelAlert to respond automatically to specified events by issuing commands to itself or other applications, sending SNMP traps, or writing to the operating system s log. 15.2 Getting Started 15.2.1 Needed Information The information you may need to gather and the preparations you may need to make in order to apply the techniques described in this chapter can vary tremendously, depending on your purpose. For instance: If you want TelAlert to log certain send-related information to a file, you will need to know the name of this file and its location. You will need to know what information you want logged and whether you want this information logged for all sends or sends of a certain type only. You will also need to know what command you want TelAlert to use to carry out this operation. Depending on the complexity of the action you want TelAlert to carry out, you may need to devise a customized script if you want the information to be given a special format or entered in a database, for example. If you want TelAlert to send SNMP traps, you will need to know the name of the SNMP host(s). In some cases, you may have to provide an SNMP community name as well. You may also need to know the host service name or port number. If you want TelAlert to update another application when it receives a reply to a message, you will need to know what information must be passed, the proper format, and the correct command for carrying out the interaction. This, too, may require a script. If you want TelAlert to send a message when an environmental monitor connected to a TelAlert Engine detects an event, you will need to know the correct destination (or group of destinations) and make all customary decisions about the behavior of the send (i.e., regarding strategy, replies, and so on). You will also need to know what message you want to deliver. If you want to be notified when process-related events occur, you will need to know what event you want to be informed of, the information you want to be passed, and the notification mechanism you want TelAlert to use. 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.

15.2.2 Other Considerations TelAdmin Versus telalert.ini File Configuration To configure TelAlert to process events in the ways described in this chapter, you can use TelAdmin (now a component of the TelAlert Desktop) or edit the telalert.ini file directly. As a rule, the Administrator Guide seeks to provide method-neutral documentation. Thus, the instructions offered here apply equally to both methods. For detailed information on these two configuration options, including important differences between the two, refer to the TelAlert Desktop User Guide. Making TelAlert Re-Read its Configuration File Only when TelAlert re-reads its configuration file will your configuration changes take place. How you make it do this depends on your configuration method. For information on the two configuration methods, including different methods for re-loading configuration information, refer to Chapter 4: Configuration Basics. 15.3 Event Processing Defined 15.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 TelAlert s event-handling capabilities are limited by only the work you are willing to invest to devise a script that does what you want. 224 TelAlert Administrator Guide - Version 5.7

15.3.2 What Is an Event? In this chapter, event refers to an occurrence internal to TelAlert. For example, when an alert is initiated by a telalertc command, that is an event. When a user acknowledges the alert, that is another event. There are several basic types of events, which can be grouped into three categories based on which configuration file section defines how TelAlert will process them: Alert-related and miscellaneous events ([Notification] section): An alert or send changes state (i.e., is started, held, acked, etc.) TelAlert receives an unsolicited request from a two-way paging service. TelAlert receives or hangs up an incoming call. A definition is activated or deactivated. Process-related events ([Heartbeat] section): TelAlert process (daemon) starts, stops, or issues an error message. TelAlert process is running at the beginning of a new heartbeat interval. Logging-related events ([File] section): One of TelAlert s logs rolls over to a new file. Most logging-related functionality is covered in Chapter 16: 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. 15.4 Event Processing Overview Configuring TelAlert to process a particular event takes at least three steps, and usually four. Here is a brief overview of the process: 1. Select the type of event you want TelAlert to process by choosing one of the event keywords (AlertStarted, Acknowledged, Start, Error, and so on) and adding it to either the [Heartbeat] section (for process-related events), the [File] section (for logging-related events), or a [Notification] definition (for alert-related and miscellaneous events). 2. Define what information you want TelAlert to pass with the command or SNMP trap, or to write to the log, in the event keyword value. Normally this string will include a number of substitution parameters (variables) that TelAlert will replace with information about the specific event. Event keywords and related substitution parameters are described in detail later in this chapter. 3. Define the action you want TelAlert to take by adding one of the following keywords to the same definition or section: Chapter 15: Processing Events 225

Command: TelAlert will issue the specified command. Typically the command will include the ${EventData} replaceable parameter, for which TelAlert will substitute the event keyword value, with any replaceable parameters it contains expanded. See Issuing a Command, below, for detailed instructions on setting this and related keyword values. SNMPHosts: TelAlert will send an SNMP trap, which will include the expanded event keyword value and various other information, to the specified host. See Sending an SNMP Trap, below, for instructions on setting this keyword value and a discussion of what other information is passed to the host. WriteSysEventLog: When this keyword is set to True, TelAlert will write the event keyword value (with any replaceable parameters it contains expanded) to syslog(in UNIX) or the Application Event Log (in Windows). See Writing to the System Log, below, for instructions on setting this keyword value. The inclusion of the event keyword value in the command, SNMP trap, or log entry allows you to add multiple event keywords in a single definition or section (that is, to perform steps 1 and 2 above repeatedly, with different event keywords), and have each generate a different command, SNMP trap, or log entry. A fourth step is necessary for notification-related events only: 4. Associate the [Notification] definition with the [Analog], [Battery], [Configuration], [Destinations], [Group], [Limits], [Port], [Power], [Relay], [Sensor], or [User] definition(s) you want to trigger the action by including a keyword value for Notification or one of the related keywords. Alternatively, you can invoke a [Notification] definition using the notification (or notificationreply or -notificationrequest) command line option. 15.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. 226 TelAlert Administrator Guide - Version 5.7

15.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. 15.5.1 Sending an SNMP Trap The following discussion assumes a familiarity with SNMP terminology and configuration. See the documentation for the application receiving the SNMP traps for further information. To configure TelAlert to send an SNMP trap when a particular event occurs, add the matching event keyword and the SNMPHosts keyword to the appropriate definition or section. For example: [Heartbeat] SNMPHosts=192.168.168.168 Error=${TimeStamp} Error ${Name} ${PID}, ${StatusData} With this configuration, whenever an error occurs in one of TelAlert s processes, TelAlert will send an SNMP trap to the host at IP address 192.168.168.168, using the standard service name snmp-trap. The trap s first variable contains the Errorevent keyword value with its replaceable parameters expanded. (The replaceable parameters are explained in Event Keywords Supported in the [Heartbeat] Section, below.) The first variable is followed by additional variables containing the current values of each of the other replaceable parameters that are allowed in the [Heartbeat] section. Notes for SNMP Administrators TelAlert s MIB data is automatically loaded into HP OpenView IT/Operations during TelAlert installation. For instructions on changing the trap s community name, or using a nonstandard service name or port, refer to the SNMPHosts entry in the [Heartbeat] section of Chapter 2 of the TelAlert Keyword and Command Reference. Chapter 15: Processing Events 227

15.5.2 Writing to the System Log To configure TelAlert to write to the system log (syslog in UNIX, the Application Event Log in Windows) when a particular event occurs, add the matching event keyword and WriteSysEventLog=True to the appropriate definition or section. For example: [Heartbeat] WriteSysEventLog=True Error=${TimeStamp} Error ${Name} ${PID}, ${StatusData} With this configuration, whenever an error occurs in one of TelAlert s processes, TelAlert will write the string defined by the Error event keyword value, with its replaceable parameters expanded, to the system log. 15.5.3 Issuing a Command Configuring TelAlert to respond to an event by sending an SNMP trap or writing to the operating system log is straightforward. You simply add SNMPHost=hostname or WriteSysEventLog=True to the relevant definition. Configuring it to respond to an event by sending a command is more complicated. There are four keywords you may use: Command, Shell, FIFOFileName, and WriteExecsToTrail: Command: Typically, this keyword s value contains the command string you want TelAlert to issue at the command line, enclosed in double quotes. The string usually contains a number of substitution parameters, especially ${EventData}, which TelAlert will expand with their current values before issuing the command. Shell: This specifies the shell you want to be involved in carrying out this action; the default value is /bin/ sh -c. You are required to specify a Shell value only if (1) you want TelAlert to run a script to process the event and (2) the script does not contain a marker that lets your system know what shell to use to run it. When the Command value is not a shell command (as is normally the case in Windows), the Shell value should be blank. As far as TelAlert is concerned, Shell can contain both a shell reference (if one is needed) and the command you want to be executed. Likewise, Command can contain the command you want to be executed, preceded by a shell reference (if one is required). Thus, you are free to combine the Shell and Command values and place the result entirely on one or the other of these lines. Likewise, as long as you maintain the proper order, you are free to split their combined value across both lines at any natural point. The program you are asking TelAlert to run, however, may prefer a specific arrangement. 228 TelAlert Administrator Guide - Version 5.7

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. FIFOFileName: Assuming the program you are invoking in Shell and/or Command supports such behavior, FIFOFileName allows you to run this program once (at the event s first occurrence) and write both initial and subsequent event data to a specified file that the program can then continuously read. The value you assign FIFOFileName is the name of the file from which you want your program to read. If you do assign it a value, you should make sure that ${FIFOFileName} appears at the point in your Command or Shell value where you want the name of the file to be passed to the program. WriteExecsToTrail: If you set this keyword to True, TelAlert will write the results of each attempted execution of the command to the telalert.trail file. This can be useful when debugging a command that does not work as expected. Event Substitution Parameters Supported in Command and Shell Keyword Values Shell and Command support a limited number of TelAlert substitution parameters. Most of these are used to point to various directories in which components of TelAlert are installed. Another is ${EventData}, which is especially important. Include this substitution parameter as part of either Shell or Command if TelAlert is to pass information from the event (as defined by the value assigned to the event keyword) to the specified program or script. Following is a complete list of substitutions supported in Shell and Command: ${Definition} The name of the telalert.ini definition in which the Command keyword appears. When Command appears at the section level, the section name is passed instead. ${EventData} The string formed based on the value assigned to the event keyword. ${FIFOFileName} The name of the pipe that the program should read from (used only when the FIFOFileName keyword specifies the name of this pipe). ${SystemRoot} The directory in which Windows is installed (typically c:\winnt), or, on UNIX, the root directory (/). ${SystemRootFS} The same as ${SystemRoot}, but with any backslash characters translated into forward slashes. Chapter 15: Processing Events 229

${TelAlertBin} The value of the TelAlertBin environment variable. ${TelAlertBinFS} The same as ${TelAlertBin}, but with any backslash characters translated into forward slashes. ${TelAlertCfg} The value of the TelAlertCfg environment variable. ${TelAlertCfgFS} The same as ${TelAlertCfg}, but with any backslash characters translated into forward slashes. ${TelAlertDir} The value of the TelAlertDir environment variable. ${TelAlertDirFS} The same as ${TelAlertDir}, but with any backslash characters translated into forward slashes. ${TelAlertTmp} The value of the TelAlertTmp environment variable. ${TelAlertTmpFS} The same as ${TelAlertTmp}, but with any backslash characters translated into forward slashes. 15.5.4 Making One Event Trigger Multiple Actions You can configure TelAlert to trigger multiple actions in response to a single event. There are several ways to do this: You may trigger a command, an SNMP trap, and a write to the system log by including Notification, SNMPHosts, and WriteSysEventLogin the same section or definition. You may refer to multiple [Notification] definitions by including two or more of the keywords discussed in About Notificationand Related Keywords, above, in the same definition. Note that each referenced [Notification] definition may (and usually will) include a different set of event keywords. The Command value in a [Notification] definition may refer to a script that performs multiple commands. The SNMPHosts keyword value may contain multiple host names or IP addresses, separated by commas. These methods are not mutually exclusive. You may use all of them to process the same event. 230 TelAlert Administrator Guide - Version 5.7

15.6 Alert-Related and Miscellaneous Events: The [Notification] Section The event processing supported by the [Notification] section is by far TelAlert s most flexible and wide-ranging. You can use it to process replies received in response to TelAlert notifications, requests sent by two-way pagers capable of initiating sends, and environmental changes detected by a TelAlert Sensor Engine. You can also use it to process a broad spectrum of other events. To do this, you must first understand the general principles at work in TelAlert s event-processing capabilities, as explained in the previous sections. The following discusses the techniques specific to the [Notification] section and lists the events and substitution parameters it supports. [Notification] Section Basics All TelAlert notifications are based on a [Configuration] definition, and in any such definition you can point to a [Notification] definition using the Notification keyword (or one of the other keywords discussed in About Notification and Related Keywords, above). Any event relating to a notification processed by this [Configuration] definition and specified in the [Notification] definition will trigger the action represented by the combined values assigned to Shell, Command, and the event keyword. For instance, perhaps you have a service level agreement with your paging service provider, and this SLA stipulates that you will not encounter more than a certain number of busy signals per 100 attempts. To monitor this, you might have your [Configuration] definition invoke a [Notification] definition called {MonitorDialing}, and this definition might contain the Change keyword referring to the generic dialing event that includes dialing failures such as busy, no dial tone, no answer, and so on. Whenever TelAlert attempts to send a notification using this [Configuration] definition and encounters a dialing problem included under Change, {MonitorDialing} is invoked and the specified event data (${State}, for instance) is passed to the script or program you have indicated by the values assigned to Shell and/or Command. For purposes of monitoring the performance of your paging service provider, you would want to pass this data to a program capable of parsing it and reporting in real time on any failures exceeding the threshold permitted by the SLA. Replies Any TelAlert notification that invokes a [Response] definition can be replied to by the message recipient. Depending on the medium used to send the message, this reply can come via two-way pager, touch-tone telephone, email or the command line. If TelAlert receives a reply and the [Configuration] definition originally used to send the message points to a [Notification] entry containing the Reply event keyword, TelAlert processes the reply according to the terms of this [Notification] entry. Thus, a reply can be made to trigger a script or program, and the information contained in the reply can be passed to this script or program in order to have TelAlert execute an action desired by the person replying. It is best to configure reply events using the NotificationReply keyword (discussed in About Notification and Related Keywords, above). This approach leaves the Notification keyword free for other purposes. Note that some basic replies that can be specified in a [Response] definition (including ack, nak, etc.) can be processed directly by TelAlert, without any action being defined under [Notification]. Conversely, you can create other reply options that have nothing to do with TelAlert replies designed only to trigger and be processed by the appropriate [Notification] definition. Chapter 15: Processing Events 231

Requests Certain two-way paging services permit users to use their two-way paging devices to initiate a request a message that is not a response to any received page. TelAlert polls for requests if PollRequests is set to True in a [Configuration] definition representing a paging service that supports requests. (Any [Configuration] definition in which PollRequests is set to True also requires ServerPIN and Access values. ServerPIN is the identifier that tells the service who is asking for the messages. Access is the security code or password associated with the account. For BSWD, ServerPIN is the DAS account Administrator. Note that BSWD requires ServerPIN and Access values for both regular two-way polling and unsolicited polling. SkyTel does not require them for regular two-way polling, but they will be used if you provide them.) To have TelAlert treat the retrieval of a request as an event, use the keyword NotificationRequest (discussed in About Notification and Related Keywords, above) to invoke a [Notification] definition. Thus, a request can trigger a script or program, and the information contained in the request can be passed to this script or program so that TelAlert executes an action desired by the person initiating the request. Consider this example of [Configuration] and [Notification] definitions set up for request processing: [Configuration] {SkyTelITwoWayTextPager} Type=InteractiveTextPager NoneParity=True MaxMessagesPerCall=100 Speed=19200 AreaCode=800 Number=679-2778 NotificationReply=ReplyAction NotificationRequest=RequestAction [Notification] {RequestAction} Active=True Shell="" 232 TelAlert Administrator Guide - Version 5.7

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. 15.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. Chapter 15: Processing Events 233

AlertDelayed The event TelAlert recognizes when an alert is delayed by virtue of a -delay value on the command line. AlertStarted The event TelAlert recognizes when an alert is started (i.e., when TelAlert receives the command to create the alert and begins processing it). AlertError The event TelAlert recognizes when an error occurs in the processing of an alert owing to erroneous information being passed on the command line (typically, one or more invalid definition names). AlertNotSupported The event TelAlert recognizes when no destination involved in an alert is supported by TelAlert (owing typically to the absence of appropriate resources for processing the sends). AlertOffDuty The event TelAlert recognizes when an alert cannot be processed because none of the specified destinations are on duty. AlertFilter The event TelAlert recognizes when an alert cannot be processed because every specified destination is filtered according to the terms of a [Filter] definition. AlertCleared The event TelAlert recognizes when an alert is cleared (i.e., when all remaining processing is stopped by a -clearalert, -cleargroup, -clearall, or -clear command). AlertCompleted The event TelAlert recognizes when an alert completes by virtue of all processing having been finished without being cleared. AlertReleased The event TelAlert recognizes when an alert is released from a held state thanks to the release of all held sends using release or releaseall or the alert itself using -releasealert. AlertCheck The event TelAlert recognizes when an -insert -check is performed. Started The event TelAlert recognizes when a send is started. Error The event TelAlert recognizes when an error occurs in the processing of a send. ErrorLimit The event TelAlert recognizes when a send reaches a limit defined by DialErrorLimit and DialErrorWindow, or by ConnectErrorLimit and ConnectErrorWindow. NotSupported The event TelAlert recognizes when the destination involved in a send is not supported by TelAlert (owing typically to the absence of appropriate resources for processing the send). OffDuty The event TelAlert recognizes when a send cannot be processed because the intended destination is not on duty. Filter The event TelAlert recognizes when a send cannot be processed because the specified destination is filtered according to the terms of a [Filter] definition. Change The event TelAlert recognizes when a send is comprised of multiple processing steps and one of these steps has been completed (this can occur because the send is set up to take multiple steps, or because of a dialing or other error). 234 TelAlert Administrator Guide - Version 5.7

ReplyChange The event TelAlert recognizes when an error occurs in the retrieval of a reply or request. Reply The event TelAlert recognizes when a reply is received. BadPassword The event TelAlert recognizes when a recipient is prompted for a password and provides an incorrect one. Acknowledged The event TelAlert recognizes when a send is acknowledged using ack or -ackall. AcknowledgedHeld The event TelAlert recognizes when a send is acknowledged and held using -hold. NotAcknowledged The event TelAlert recognizes when a send is negatively acknowledged using nak or -nakall. Cleared The event TelAlert recognizes when a send is cleared using -clear, -clearall, -clearalert, or -cleargroup. Completed The event TelAlert recognizes when a send completes by virtue of all processing having been finished without being cleared. Released The event TelAlert recognizes when a send is released from a held state using -release, -releaseall, or -releasealert. Connect The event TelAlert recognizes when a step associated with answering or ending an inbound call occurs. Security All remote connects and disconnects are sent to this keyword. The [Notification] paragraphs referenced by [Limits] Notification, NotificationLog, NotificationTrap and NotificationITV are invoked for each event. Warning The event TelAlert recognizes when it sends a message that would have failed had AllowUnsupportedTypeSends been set to False. Non-Alert Events in the [Notification] Section While events defined in the [Notification] section are typically triggered by [Configuration], [Destination], [Group], or [User] definitions that is, by alerts as discussed below they may also be triggered by the following events relating to [Port], 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. Activation The event TelAlert recognizes when a definition is activated or deactivated. Chapter 15: Processing Events 235

Request The event TelAlert recognizes when a request is received. 15.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. 236 TelAlert Administrator Guide - Version 5.7

${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. ${ReplyTo} The ReplyTo value associated with the send. ${Request} The full text of the request. ${RequestID} The ID assigned to the request by the service provider. ${RequestName} The text preceding the first vertical bar ( ) in the request, up to sixteen characters (if no vertical bar is present, this parameter is assigned the same value as ${Request}). ${RequestPIN} The PIN or email address of the device that originated the request. ${SendID} The ID associated with the send. ${ServerHost} The name of the host on which TelAlert is running. ${Source} The -source value provided at the origination of the send. ${StartTime} The time that the processing of the send or alert was begun. ${State} The current send state: ${StatusData} plus additional state information. ${StatusData} The state number and associated description of this event. ${StateNum} The state number of this event. ${Subgroup} The name of the lowest-level subgroup to which the message was addressed (if the message was not addressed to a group, the value is <none>) ${Subject} The -subject value provided at the origination of the send. ${Ticket} The -ticket value provided at the origination of the send. ${TimeStamp} The time that the event occurred. ${To} The To value used in processing the send. ${TrackID} The tracking ID assigned to the send by TelAlert (part of a sequence specific to each destination). ${Type} The Type value of the [Configuration] definition used to process the send. ${User} The User value used in processing the send. ${Value} The value reported from an analog, sensor, relay, battery, or power event. Chapter 15: Processing Events 237

15.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} 238 TelAlert Administrator Guide - Version 5.7

In this example, a script called notify.sh (or, in Windows, notify.ksh) is invoked as part of the Command value whenever one of the four specified events occurs. The data specified in the event s definition is passed to and processed by this script. Interval refers to the interval at which TelAlert should issue a status update (assuming Update has been assigned a value). Other keywords are covered below. notify.sh is provided with TelAlert. You can customize it or invoke instead a script or program of your choice. 15.7.1 Event Keywords Supported in the [Heartbeat] Section In the above example, you see all four of the event keywords permitted in the [Heartbeat] section: Start The event TelAlert recognizes upon the starting of any of the TelAlert processes. Exit The event TelAlert recognizes upon the termination of any of the TelAlert processes. Error The event TelAlert recognizes upon the occurrence of an error relating to any of the TelAlert processes. Update The event TelAlert recognizes if it detects a TelAlert process is running at the beginning of a new heartbeat interval. 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. 15.7.2 Event Substitution Parameters Supported in the [Heartbeat] Section Comprising the value assigned to each event keyword, you see all five of the substitution parameters supported for event definitions in the [Heartbeat] section: ${Name} The name of the process associated with the event. ${PID} The daemon process ID associated with the event. ${ServerHost} The name of the host on which TelAlert is running. ${StatusData} The state number and associated description of this event. ${TimeStamp} The time of the event. Chapter 15: Processing Events 239

15.8 Logging-Related Events: The [File] Section One feature of the [File] section is that it allows you to tell TelAlert whether you would like to be informed when TelAlert s default log files reach their maximum size and, if so, the means by which it should do so. Here, Command, Shell, and one or more event-related keywords combine to form the string that will be passed on the command line when an event matching one of those event keywords takes place. Consider the following example: [File] # Note that [File] is only invoked for BUILT-IN TelAlert files. # Events associated with log files used with helper programs # (such as readmail and gsmpoll # in [Process], or notify in # [Notification], [Heartbeat], etc.) do NOT invoke this section. Comment=TelAlert sample [File] Section Active=True AttemptWait=5m MaxAttempts=1 SNMPHosts="" WriteExecsToTrail=False WriteSysEventLog=False WriteTrapsToTrail=False Shell="" # Use only ONE of the following three Command= examples. Note that the # first example, (that calls the notify.exe program) requires values for # the FIFOFileName and EndOfData keywords. The two subsequent examples # (for script invocation in UNIX and Windows) must have blank values for # FIFOFileName and EndOfData #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="" # 240 TelAlert Administrator Guide - Version 5.7

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 With some of these configurations, a program called notify.exe is invoked as part of the Command value whenever one of the three specified events occurs. The data specified in the event keyword s value is passed to and processed by this program. notify.exe is provided with TelAlert. You can invoke instead a program or script of your choice. The notify executable is best for high-volume logging to a flat file. The notify scripts are best for low-volume transfer of selected events to a custom script that takes special action on the events. The example scripts simply log the events to a flat file; unless you customize the scripts, they have little advantage over the executable, and have the disadvantage of additional operating-system overhead compared to the executable. Note that you should not have multiple invocations of the notifyexecutable with the same FIFOFilename=value and/or the same -file filename in the Command=line. Chapter 15: Processing Events 241

15.8.1 Handling Rollover of telaconfe.log and telainetde.log The [File] section also handles rollover of the telaconfe.log and telainetde.log files. The following is a sample [File] section for handling of these files: # TelaConf and TelaInetD do not have their own.ini or.sects # files, so the parameters relating to their log file rollover # are kept in telalert.ini s [File] section. Unlike telalerte, # telaconfe and telainetde do not have functionality to execute # operating system commands, so these keywords do NOT exist: # ConfSwitchCmd, ConfErrorCmd, InetdSwitchCmd, InetdErrorCmd # For telaconfe.log ConfMaxFileSize=50000 ConfSwitchTime=-1 ConfSwitchDayOfWeek=-1 ConfErrorExit=False # For telainetde.log InetdMaxFileSize=100000 InetdSwitchTime=-1 InetdSwitchDayOfWeek=-1 InetdErrorExit=False 15.8.2 Handling telalert.sects and telalert.ini file Backups when TelAdmin is Used Use the following [File] example to handle telalert.sects and telalert.ini file backups when using TelAdmin. BackupIniFile="" NumIniSectsFileBackups=2 ReloadAfterSectsFileWritten=True WriteSectsFileAfterChanges=True WriteSectsFileInterval=0s NumIniSectsFileBackups is the maximum number of backup copies of telalert.ini and telalert.sects TelAlert will maintain. The backup files are named telalert.sects. followed by a date-time stamp in the format YYYYMMDDHHMMSS (Year/Month/Day/Hour/Minute/Seconds). If a file with that name already exists, TelAlert will append a three-digit number to the end of the new file s name. To disable backup, set NumIniSectsFileBackups to 0. ReloadAfterSectsFileWritten, when set to True, causes TelAlert to automatically activate changes to telalert.sects whenever: 1. TelAdmin user executes a File / Save Data command; 2. telalert.sects is saved automatically (see WriteSectsFileInterval); or if WriteSectsFileAfterChanges is set to True, 3. TelAdmin user presses an Update button. 242 TelAlert Administrator Guide - Version 5.7

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. 15.8.3 Miscellaneous [File] Functions The [File] section is also used to specify the NumVoiceFiles value, as follows: NumVoiceFiles=8 15.8.4 Event Substitution Parameters Supported in the [File] Section These are the substitution parameters that are allowed as part of the event keyword value in your [File] section: ${Base} The name of the original log file. ${BaseFS} The same as ${Base}, but with any backslash characters translated into forward slashes. ${Error} The error code from the failure of a system function (if any). ${File} The name of the file to which the log was switched. ${FileFS} The same as ${File}, but with any backslash characters translated into forward slashes. ${Function} The function that failed (if any). ${Name} The name of the process associated with the event. ${PID} The daemon process ID associated with the event. ${ServerHost} The name of the host on which TelAlert is running. ${TimeStamp} The time of the event. Chapter 15: Processing Events 243

16.1 Overview 16 Miscellaneous Administrative Tasks 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. 16.2 Starting, Stopping, and Initializing 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. If while TelAlert was stopped you modified its configuration by editing the telalert.ini file, you must also do an -init, which compiles the telalert.ini file to telalert.sects. The command for this is: telalert -start init 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

16.3 Configuring TelAlert to Run Automatically 16.3.1 On Windows When you install TelAlert on Windows, the installation application automatically configures it as a service, but it sets it up as a service that must be run manually i.e., TelAlert appears as an option in the Control Panel but will not, by default, be started each time the machine is re-started. To change this, open the Control Panel, select TelAlert, click Startup, and change the Startup Type setting to Automatic. 16.3.2 On UNIX System V-Compliant Systems On the machine on which the TelAlert server is installed, find the file called telalert.init.d. It will be in the same directory as the telelart.ini file. Copy this file to the directory on the same machine that holds the start-up scripts. Change the name of the file to telalert. In the appropriate run-level status directory (rc<n>.d), create a link to this file. Non-System V-Compliant Systems Follow the standard procedure for the system on which the TelAlert server is installed. In most cases, this involves adding telalert start to the system start-up script. 16.4 Installing TelAlert Clients 16.4.1 Configuring the Server To Accept Remote Clients You must do two things before remote systems running TelAlert clients (telalertc, the Web client, or TelAdmin) can connect to a TelAlert server: 1. Each client s IP address must be entered in the server s telalert.hosts file. This is simply a list of IP addresses; edit it with any text editor and add the necessary addresses. This step is not relevant for Web clients. List entries may use wildcards, for example 192.168.*.* (any address beginning with 192.168), or may be a range of addresses, such as 192.168.168.38-144. Alternatively, you can temporarily or permanently modify this list of permitted hosts using various commands. For more information, refer to Command Line Options for Modifying Filter Files in Chapter 3 of the TelAlert Keyword and Command Reference. 2. You must have purchased licenses sufficient to handle as many clients as you wish to be able to connect simultaneously. Contact the MIR3 Sales Department if you need additional licenses, or licenses for different operating systems. If either of these conditions is not met, the client will fail with an error message, usually this one: Exit *telalert, error 7: Can t connect to any host 246 TelAlert Administrator Guide - Version 5.7

Client Licenses in Evaluation Versions The demonstration version of TelAlert supports remote clients. So, with any unexpired demonstration 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. 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 16.4.2 Installing the TelAdmin Client TelAdmin runs only on Windows. When you install TelAlert on a Windows system, the setup utility will automatically install a copy of TelAdmin in the in the telalert\gui directory. To install TelAdmin on other systems running Windows, unzip the file TelAdmin.zip from the TelAlert CD to any directory. To run TelAdmin, double-click TelAlert.exe, or create a shortcut and add it to your Start menu. The first time you run TelAdmin, you must enter the TelAlert server s IP address. Right-click the TelAlert Hosts icon, choose Add New, enter the IP address in the TelAlert Host field, and click OK. 16.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 The file can be found on your TelAlert CD. Open the Clients directory, then the directory called Win95nt. The correct file is clients.zip. You can also 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. Chapter 16: Miscellaneous Administrative Tasks 247

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. 1. From the Start menu, choose Settings / Control Panel. 2. Double-click the System icon. 3. Click the Environment tab. 4. In the Variable field, type TELALERTHOST. 5. In the Value field, type the host s IP address. If you have one or more backup hosts and wish the client to roll over automatically when the primary host is down, add their IP addresses or host names, separated by spaces. 6. Click Set, then click OK. Two, you can use the -host option each time you use this client to access the server: telalertc -i speaker -m "this is a test" -host primary_host_ip_address 1st_backup_host_IP_address 2nd_backup_host_IP_address telalertc -i speaker -m "this is a test" -host primary_host_name 1st_backup_host_name 2nd_backup_host_name 248 TelAlert Administrator Guide - Version 5.7

16.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 The file can be found on your TelAlert CD. Open the appropriate directory for your platform and find the file called clients.tar.z. You can also 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 16: Miscellaneous Administrative Tasks 249

16.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. 16.5.1 Installing the Web Clients To install either client, do the following: Copy the program to a Web server s CGI directory. In Windows, that directory is usually called scripts; with most UNIX Web servers, it is cgi-bin. Any Web server that supports CGI scripts should work, including the Web Server that Microsoft distributes with Windows servers. By default, these clients assume they are running on the same computer that runs the TelAlert server. To change that, in the same directory as the clients create a file called telalerth.ini that contains the following line: Host = [name or IP address of TelAlert server] To run one of these clients, just point your browser to the program. For example: http://www.myserver.com/scripts/telalerth.exe http://www.myserver.com/cgi-bin/telalerth You can also point to the server s IP address. For example, when working at the server itself, you could use one of these URLs: http://127.0.0.1/scripts/telalerths.exe http://127.0.0.1/cgi-bin/telalerths 16.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. 250 TelAlert Administrator Guide - Version 5.7

16.5.3 Using the Web Clients with Web-Enabled Cell Phones Cellular telephones equipped with microbrowsers can access the TelAlert Web client. The Web client will automatically recognize a supported microbrowser and present it with information in a suitable format. Thus, by going to the TelAlert Web client's URL, users with these devices can view, acknowledge, hold, negatively acknowledge, release, clear, and reply to messages, much as if they were visiting the Web page from a networked computer. One approach for Web-enabled phones is to send notifications that do not actually contain the message that TelAlert has been asked to convey. Rather, they are comprised of a subject line and a URL the recipient should visit in order to retrieve the message. A recipient s phone indicates that a message has arrived; when the recipient selects and "reads" the message, the microbrowser follows the provided URL (which has the send ID appended) and connects to the TelAlert Web client. For instructions on setting up TelAlert to send messages to Web-enabled telephones, refer to Sending Messages to Web-Enabled Phones in Chapter 9. 16.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. 16.5.5 Configuring telalerth with telalerth.ini You can configure the Web clients by adding lines to telalerth.ini. The procedure is similar to the one you follow when editing telalert.ini. telalerth.ini Sections telalerth.ini can contain "sections" that allow it to present different options under different circumstances. Three such sections are automatically created using these markers: [html] [hdml] [wml] The HTML section serves to specify attributes that should be presented to traditional Web browsers. The HDML section serves to specify attributes that should be presented to 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 16: Miscellaneous Administrative Tasks 251

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. 252 TelAlert Administrator Guide - Version 5.7

AckWait Command-line -ackwait value. Default: 0m AutoResetMessage Y/N - Clear message text boxes after a send? Default: N AutoResetOptions Y/N - Clear Options screen values after a send? Default: N AutoResetTargets Y/N - Clear Destination/Group/Config values after a send? Default: N BodyBackground Sets HTML attribute. Default: none BodyColorALINK Sets HTML attribute. Default: none BodyColorBGCOLOR Sets HTML attribute. Default: none BodyColorLINK Sets HTML attribute. Default: none BodyColorTEXT Sets HTML attribute. Default: none BodyColorVLINK Sets HTML attribute. Default: none ConnectPause Overrides ConnectPause configuration keyword value. Default: 2 ConnectTimer Overrides ConnectTimer configuration keyword value. Default: 10 ConnectTries Overrides ConnectTries configuration keyword value. Default: 5 ConnectWait Overrides ConnectWait configuration keyword value. Default: 30 Delay Command-line -delay value. Default: 0m Chapter 16: Miscellaneous Administrative Tasks 253

DestGroupOnly Y/N - Prevent access to Configuration/User screen? Default: N DNS Y/N - Convert numeric IP address to name form? Default: Y HelpURL URL for Web client online help Default: none Host Same as -host command-line option Default: 127.0.0.1 IPSecurity Y/N - Add client s IP-address as -security option? Default: N JavaScript Script file name. Default: none JavaSupport Y/N - Support JavaScript functions? Default: Y ListSize Vertical height of Dest/Group lists. Default: 10 ListTags Same as -tags command-line option. Default: none LockConfig Y N - prevent changes/access to Config screen? Default: N LockOptions Y/N - prevent changes/access to Options screen? Default: N LockPreferences Y/N - prevent changes/access to Preferences screen? Default: N LogFile UNIX log file; Windows log file Default: /tmp/telalerth.log; C:\TEMP\TELALERTH.LOG Logfile Logo file name. Default: none LogoHeight Logo height. Default: 80 254 TelAlert Administrator Guide - Version 5.7

MetaRefresh Set to a value n to cause the message sent screen to automatically go back to the main screen n seconds after the send has been issued. If the value is set to 0 (the default), the client will stay on the message sent screen until you click one of the buttons. Default: 0 MsgSize Number of rows in message box. Default: 5 Priority Command-line -priority value. Default: 50 SecurityRequired Require use of Preferences->Security field? Default: N Service Same as -service command-line option. Default: 25378 StatusWithDate Y/N - Include Start time in Status displays? Default: Y Verbose Y/N - Display telalertc equivalent when commands executed? Default: Y Chapter 16: Miscellaneous Administrative Tasks 255

16.5.6 Other Keywords Most of these keywords determine what send- and alert-related information is shown on the Show Send, Send Detail, Show Alert, and Alert Detail screens. Values supported by ShowTable, ShowVTable, ShowDetailHTable, ShowDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows: AltDial AltHost Alternate phone number (-an) Alternate host/service (-ahs) Calls e.g., "Connected 1/1, Failed 0/10, Rejected 0/1" Conf Dest Dial Group Host PIN Reply Send To Track Update User [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 Values supported by ShowAlertTable, ShowAlertVTable, ShowAlertDetailHTable, ShowAlertDetailVTable, ShowWAPTable, and ShowWAPDetail are as follows: Recipient Release To whom was the alert sent? Alert-level release info 256 TelAlert Administrator Guide - Version 5.7

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 Alert ID -check value IP address of message issuer -delay value -hold -ipcheck value Masked ticket Message text -nodeaddr value -priority value -remark value -replyto value -response value -source value Start time Message state -subject value ShowTable Governs Show Send page appearance. Determines what information is displayed for each send, horizontally from left to right. Default: Send,Start,User,Dest,State?128,Message ShowVTable Governs Show Send page appearance. Determines what information is shown for each send in one or more rows beneath the initial row of horizontally-arranged send information. Default: Message ShowDetailHTable Governs Send Detail page appearance. Determines what information is displayed for each send, horizontally from left to right. Default: Send,Alert,User,Dest,Conf,Source,Priority,Ticket,Masked ShowDetailVTable Governs Send Detail page appearance. Determines what information is shown for each send in one or more rows, from top to bottom, beneath the initial row of horizontally-arranged send information. Default: Start,Update,Client,State?128,Calls,Remark,Message,Reply Chapter 16: Miscellaneous Administrative Tasks 257

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 258 TelAlert Administrator Guide - Version 5.7

Special Display Options for Microbrowsers Values assigned to ShowWAPTableand ShowWAPDetail can be further specified using these flags, each preceded by a question mark. For example, Send?128, Message shows the send ID in bold text, followed by the message in plain text. 1 Splits text, causing each word to begin on a separate line. 2 Center-aligns text. 4 Left-aligns text. 8 Right-aligns text. 128 Bolds text. 256 Italicizes text. 1024 Prefixes each value with its name (i.e., Message=Hi there). ShowWhat Determines what buttons are shown on the main page; can be set to Show, Show Alert, Both, or None. Default: Both 16.6 Setting up Logging The [Files] section governs TelAlert s built-in logging behavior. 16.6.1 Default Log Files By default, TelAlert maintains a variety of log files: telalert.trail This is a general record of TelAlert activity. telalerte.log This is the log file for telalerte, the TelAlert server. It contains all the information TelAlert needs to process all active alerts. Media Controller log files -- To allow parallel processing, the telalerte server daemon creates a separate child Media Controller process for each Active [Port] definition. Each child process maintains its own log file; the names reflect the Media type: telalerts#.log for Internet Socket ports, telalertm#.log formodem ports, etc. The # is replaced by a digit (telalertv3.log, for instance) since there can be multiple child processes for a particular Media type. telaconfe.log this is the log file for telaconfe, the TelaConf server. Other process-specific log files TelAlert maintains one log file for each of the other TelAlert processes: telalerth.log for telalerth, telalertd.log for telalertd, etc. The contents vary according to the type of process. Chapter 16: Miscellaneous Administrative Tasks 259

16.6.2 Setting Maximum Sizes Four keywords used in the [Files] section determine the maximum sizes of these files: TrailMaxFileSize determines the maximum size of telalert.trail EventMaxFileSize determines the maximum size of telalerte.log ConfMaxFileSize determines the maximum size of telaconfe.log LogMaxFileSize determines the maximum size of each of the process-specific log files (this value applies to all of these files) When these limits are reached, TelAlert (1) deletes the existing backup file; (2) renames the existing log file, giving it a.bak extension; and (3) starts a new log file. You can set any of these keywords to 0 to prevent this procedure from being carried out. Note that doing so will cause the file to continue to grow indefinitely, unless you manually initiate the procedure using the -switch command (discussed in the "Administrative Command Line Options" section of Chapter 3 of the TelAlert Keyword and Command Reference). 16.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. 16.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. 16.7 Miscellaneous Administrative Tasks 16.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, 1 billion being 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. 260 TelAlert Administrator Guide - Version 5.7

16.7.2 Viewing Listen Sockets telalert -status shows you a wide range of information about your implementation of TelAlert, including facts pertaining to your ports, Internet set-up, and license. This command also displays your active listen sockets, as specified in your TelAlert environment variables or by command line options. Activating and Deactivating Sections and Definitions The [Files] and [Heartbeat] sections can be activated or deactivated on the command line, like so: telalert -deactivate -files telalert -activate -files telalert -deactivate -heartbeat telalert -activate -heartbeat Likewise, any definition that supports an Active keyword can be activated or deactivated on the command line. For instance: telalert -deactivate -user John telalert -activate -user John Chapter 16: Miscellaneous Administrative Tasks 261

17 Security Features 17.1 Overview TelAlert is deployed in a wide variety of enterprise environments environments that, for all their diversity, share the same pressing need for network security. This chapter describes the key features with which TelAlert has been equipped in order to ensure a high degree of security when deployed as part of an enterprise network. This chapter s aim is to familiarize system administrators with TelAlert s security features, and to demonstrate the ways in which these features make TelAlert an exceptionally security-conscious application. 17.2 TelAlert s Security-Conscious Architecture Any good site administrator is concerned with security and knows that each new product added may carry security risks that jeopardize applications, data, or the network as a whole.telalert addresses these concerns by adopting engineering approaches which insure that potentially troublesome areas (modem connections to the outside world, for instance) are secured. TelAlert has been developed within the enterprise model and with years of guidance from our users most of whom run enterprise sites. Thanks to this heritage, TelAlert is able to address these and other points of risk and offer a strong level of security. Understanding TelAlert s heightened securityconsciousness begins with a look at its architecture, which spans four main areas:

Architectural Area telalerte TelAlert Media Controllers TelaConf/TelAdmin TelAlert Clients 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). TelAlert s administrative components. These components let an administrator control TelAlert s 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. Potential risks associated with each area are anticipated by safeguards that are built in to TelAlert. TelAlert allows administrators who want maximum security to enable number of security features. The following sections take a look at the security features of each area of TelAlert s architecture. 17.2.1 telalerte: The Central Hub of TelAlert Most important are the security measures taken by the telalerte process, which, thanks to its central role, offers a hacker the opportunity to do the greatest damage. To guard against a breach, telalerte takes the following precautions: 1. All traffic into telalerte from clients (such as telalertc) must originate from hosts defined in the telalert.hosts file. If the host address is not present in this file, telalerte will not allow communication from the client. For example, for a site network on subnet 206.169.153.*, TelAlert will assume that it can accept client connections from its local interface only (127.*.*.*) unless the telalert.hosts file is modified to allow for other connections. For TelAlert to accept a connection from another host, the site administrator must explicitly add its hostname or IP address to telalert.hosts. 2. TelAlert creates a port before creating the child process that will communicate using the port. This port is only usable by telalerte and the child process - no third process can gain access to the conversation. 3. telalerte communicates via a private protocol. For hackers to spoof network traffic, they would require a full understanding of the TelAlert binary protocol. 4. As with all TelAlert components, all connection set-ups between telalerte and clients are logged. Chapter 17: Security Features 263

17.2.2 The Media Controllers Media controllers allow TelAlert to connect to external services such as paging gateways, mail systems, modems, etc. When telalerte wants to send a message to a given destination (e.g., a SkyTel two-way text pager), it passes the message to the media controller process bound to SkyTel (telalerts). telalerte itself does not know how to speak to SkyTel; the media-controller is the only process that knows how to speak to a given carrier over a given protocol. Media controllers are, in effect, the translation gateways between telalerte and the real world of messaging. Because media controllers are points of external access and thus potential security risks, TelAlert imposes several default security measures that must be explicitly disabled if a lower level of security is desired: 1. TelAlert media controllers are started by telalerte. Because only telalerte knows which network port will be used, it is very difficult to write a rogue media controller capable of spoofing the connection. 2. Media controllers, like all connections with TelAlert, are bound to a single socket session. This prevents rogue processes from joining an existing conversation that has been opened by telalerte. 3. Media controller connections are set up dynamically. telalerte takes great care to avoid persistent connections that might be vulnerable to traffic sniffing and/or network spoofing. (Note, however, that some kinds of connections between the media controller and the outside world are determined by the protocols used by the service: For example, leased-line telalertm is persistent; dialup telalertm is not. Internet telalerts using the ARDIS protocol is persistent; the SNPP protocol is not.) 4. The media controller command set as it relates to telalerte is an internal, proprietary command set that cannot easily be managed outside of telalerte, and this binary protocol is of little use to non-telalert components. Again, it important to note that connections between the media controller and the outside world frequently rely on standard public protocols. 5. To secure media controllers that manage external devices such as modems, TelAlert places these devices in a non-auto-answer state and, by default, requests exclusive use of the device. Unless the administrator places a getty program on a modem and explicitly tells TelAlert that the device is shared, TelAlert is the only application with access to the device (and even TelAlert is limited to access in an outbound fashion). 6. TelAlert does not provide any form of Remote Access Service (RAS). Typically, RAS services (such as the UNIX gettyprocess) provide users with a login prompt. Since TelAlert does not include the software that would provide this access, there is no way to gain system access inbound from a modem controlled by TelAlert: its modems do not answer calls, and, and no command processor/login session exists behind the modem to process incoming data. The TelAlert Engine supports dial-in access, but dial-in is not required to send voice messages, and dial-in can easily be disabled. Even if dial-in access to TelAlert is enabled, the Engine is listening for DTMF tones only (the tones emitted when a touch-tone telephone keypad is pressed). Further, a password is required before callers are allowed access to the voice menu. 264 TelAlert Administrator Guide - Version 5.7

Circumventing all of these measures still would not give an intruder access to the host platform. For this to be possible via an external interface such as a modem, the system must have software listen on the port and pass incoming data to a special process (such as a login process). TelAlert does not provide this capability. If an intruder were to gain access to a TelAlert port and bypass TelAlert, he or she would be met with the datacom equivalent of dead air. 7. TelAlert can be configured so that telalerte requires a special password be provided each time a message is initiated, thus preventing a client from sending unauthorized messages through a gateway. 8. Clients such as telalert take great care to check every packet to prevent buffer overrun. This makes it difficult for a rogue client to force access to TelAlert or the system underneath it via traditional intrusion methods. It is worth noting that the activity of media controller processes, like that of all TelAlert components, can be logged to the various log files (for example telalertm1.log, telalerts2.log, telalert.trail, etc.) The level of detail for logging is configurable. See the [Files] section in Chapter 2 of the TelAlert Keyword and Command Reference and Chapter 15 of this manual for information on configuring log file features. 17.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. 17.2.4 Client Programs TelAlert client programs such as telalert and TelAdmin also do their part to ensure system security. Each client accepts external requests, whether from a user or external application, and performs several consistency checks on the data before actually transmitting it to the TelAlert core. Because they parse user input directly, rather than sending it to the core for parsing, commands are never sent to the core without first having their credentials checked. Each client program also checks for potential security problems such as buffer overrun and illegal option values. TelAlert s core processes thus always receive sanitized requests from clients, greatly reducing the risk of rogue clients accessing critical features of the core. Chapter 17: Security Features 265

17.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, with telalert.ini containing: [Limits] EncryptPasswords=True and: [User] {Operator} Password=Giants after a telalert -init, typing: telalert -read user operator -hold shows: [User] {Operator} Password= #GeYg0xne If the.ini file is changed to contain the encrypted value (#GeYg0xne), the compile step won t re-encrypt the password, as it s already encrypted (determined by the leading "#"). When EncryptPasswords is reset to False, passwords are unchanged during compile operations. Only when the [User] or [Owner] section entries are re-compiled are the Encryption functions performed. Any password already encrypted will remain encrypted, regardless of the EncryptPasswords value. Only non-encrypted passwords will be encrypted when EncryptPasswords is True. As a result, the testing of passwords is done based on the values found in the.sects file, irrespective of the current [Limits] EncryptPasswords value. As a general rule, passwords specified on the command-line or via Stored Authentication must be plain-text. 266 TelAlert Administrator Guide - Version 5.7

17.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. With TelAlert 5.4, the ability of a client machine to connect can be governed by a schedule. To do this, you alter telalert.hosts so that each machine is identified by a name in curly brackets. To the keyword Address, assign the machine s IP address or hostname. To the keyword Schedule, assign a value matching the name of a TelAlert-defined schedule. For example: {Name} Comment=Customer Service Department Schedule=NineToFive Address=1.2.3.4-20 The telalert.hosts file can contain information presented in this form (where a list of IP addresses are shown on one line), the old form (an IP address or hostname per line), or a combination of both forms. See Chapter 11: 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. 17.5 Authentication for Admin and Client Connections TelAlert can require clients to log in before passing information to the server. The Administrator and password provided by the client on the command line are checked against the values specified in [User] definitions (and not in [Owner] definitions). If a match is found, the command is allowed. Admin connections are connections by telalert, telalerths, and C/Java APIs with admin capabilities. Client connections are connections by telalertc and C/Java APIs without admin capabilities. Web client connections are connections by telalerth. This is accomplished using new keywords added to the [Limits] section: AdminLoginsRequired, ClientLoginsRequired, and WebClientLoginsRequired. The default value for these variables is False; if set to True, logins are required. There are two approaches to passing the Administrator and password on the command line. If you are using host to specify multiple TelAlert servers to which clients should attempt to connect, you must provide the appropriate Administrator and password following each specified host. Consider this partial command line: -host 1.2.3.4[user1:pass1] 5.6.7.8[user2:pass2] Chapter 17: Security Features 267

If you have only one TelAlert server to which clients can connect, you can begin using -host and this associated method of providing Administrator and password. Note that there must not be any space between the final character of the host specification and the opening bracket of the Administrator/password combination. Alternatively, you can use two new command line options, -loginuser and -loginpassword. Again, here is a partial command line: -loginuser Joseph -loginpassword 1k2j345 Note, too, that where AdminLoginsRequired is False, admin clients can use this command telalert -validate -loginuser Foo -loginpassword Bar to check the validity of a login. Note that requiring login passwords, and enabling password encryption, are separate and distinct options. You can enable encrypted passwords without requiring logins (in this case, the encryption would apply to passwords used for other purposes, like Voice IVR menu access). Or, you can require logins without encrypting the login passwords. 17.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 5: Setting Up a Remote Port for more information on working with remote connections. 268 TelAlert Administrator Guide - Version 5.7

17.7 Security Event Available in [Notifications] A new keyword, Security, can be used in the [Notifications] section to trigger specified actions in response to security-related state changes within TelAlert. A single security event marked as [11]Security/License is comprised of a number of new state changes: [107]No Web Clients [108]License Expired [109]License Limit Exceeded [110]Admin Unacceptable [111]Client Unacceptable [112]Master Unacceptable [113]Remote Unacceptable [114]Invalid Admin Login [115]Invalid Client Login [116]Invalid Master Login [117]Invalid Remote Login [118]Not A Gateway [119]Master Already Connected 17.8 Control Over IVR Interactions [Configurations] definitions of Type=InteractiveModem and Type=InteractiveTTS now support two new keywords. NoUserValidation suppresses the password prompt presented to dial-in users, and NoMessageResponse suppresses the acknowledge prompt. 17.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. Chapter 17: Security Features 269

17.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. 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. http://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. 270 TelAlert Administrator Guide - Version 5.7

Ensure that Stunnel will always be running, with the proper parameters, whenever TelAlert is running. If you have installed stunnel on the TelAlert server, you can use a [Process] definition; a sample is given below. This sample has TelAlert run the ExecProc utility, which then runs Stunnel, instead of having TelAlert directly run stunnel. ExecProc adds features to more smoothly integrate Stunnel with TelAlert; for instance, ExecProc will report to TelAlert if stunnel dies, and will cleanly terminate stunnel on command from TelAlert during a TelAlert shutdown. ExecProc is a new program in the 5.4 release of TelAlert. Parameters that may need to be customized in the following [Process]{Stunnel} definition: MaxAutoActivates controls how many times TelAlert should automatically restart Stunnel if Stunnel dies. Increase this value if observation shows that the Stunnel connection to Skytel often times out. The following are subparameters in the Command= line: -debug 0 is the debug flag for ExecProc, not for Stunnel. Use 1 instead of 0 to activate debugging. Debugging information is written to execproc.log. -cfg and exec are ExecProc parms indicating the (-exec) executable file name, and (-cfg) directory path where the file is located, for the program that ExecProc is to create as a child process. Not shown in the above example are the TelAlert [Process] standard -file, -back, and -size parameters relating to the execproc.logfile, so the defaults are being used. The -parms string is passed unchanged from ExecProc to the child stunnel process, so the values in parms are more fully documented in the Stunnel documentation. Briefly: "-d 7778" is the socket that Stunnel will use to communicate with TelAlert "-r secure-apps.skytel.com:7778" is the DNS name/ip address socket that Stunnel will use to communicate with Skytel. (If the your DNS server does not resolve secure-apps.skytel.com, use IP addresses 204.153.80.31 or 204.153.81.31) "-c" indicates that stunnel will run in client mode "-o stunnel.log" is Stunnel's logfile name Not shown in this example is "-D 5", which is the default control for the level of debugging information Stunnel writes. To increase the level of information, use -D 6 or -D 7. Chapter 17: Security Features 271

Note that the -d socket value must match the TelAlert {SkytelxxxxSSL} definition's Service value, and the -r socket value must match one that Skytel actually monitors, but the d and -r socket values do not need to be identical - it's simply a convenience. [Process] {Stunnel} Active=True WriteExecsToTrail=True MaxAutoActivates=3 Shell="" Command=${TelAlertBin}/ExecProc ${Message} -debug 0 -cfg ${TelAlertBin} -exec stunnel -parms "-d 7778 -r secure-apps.skytel.com:7778 -c o stunnel.log" Start=${TimeStamp} Start Reset=${TimeStamp} Reset Status=${TimeStamp} Status #Control=${TimeStamp} Control ${Message} #Switch=${TimeStamp} Switch Stop=${TimeStamp} Stop If you install stunnel on a machine other than the TelAlert server, starting or stopping Stunnel, and providing the proper parameters, is your responsibility. Stunnel can be run under an "inetd"-type arrangement on a UNIX "gateway" machine; refer to the Stunnel documentation. In this situation, the [Process]{Stunnel} definition is not used. Set up SSL-aware Skytel configuration(s) in TelAlert The following is a completely new TelAlert Skytel configuration that uses SSL. Using this configuration, you could have some destinations refer to the non-ssl connection using an existing configuration like SkyTelSNPPTextPager, and other destinations refer to this new SSL connection. This is useful for testing. Alternatively, you could change the existing Skytel configuration to match this one; doing this means that no changes are required to switch existing Destination entries from their existing non- SSL Skytel configuration to the new SSL-aware Skytel configuration, which may save a lot of editing. {SkyTelSNPPSSL} # SkyTel National SNPP Text Paging System for Interactive TwoWay Pagers # Uses SSL over the Internet # Dial Backup does NOT use SSL Type=InteractiveTextPager Protocol=SNPP # ProtocolMask sets special protocol options: # 1 - PIN is included in command replies, non-standard # 2 - SkyTel time format which is non-standard ProtocolMask=3 Model=Internet 272 TelAlert Administrator Guide - Version 5.7

MaxMessagesPerCall=100 # Host=127.0.0.1 connects to Stunnel running on the TelAlert server. # If Stunnel is on a gateway machine, adjust accordingly Host=127.0.0.1 # Connects to Stunnel using the same socket Stunnel is listening on; # by convention, this is one of the two sockets that Skytel is # listening on (7778 and 8889), but if necessary TelAlert and Stunnel # can use ANY socket that is not otherwise in use on this server. # This must match the Stunnel -d parameter Service=7777 TextPagerWait=30s # To enable dial backup, set DialBackup to a value > 0. To test # DialBackup, simply give the -deactivate -process Stunnel command. DialBackup=0 # May need to have Parity=Even instead of Parity=None to have SkyTel # recognize the protocol properly when we failover to the modem DialBackupProtocol=TMEX Parity=None Speed=19200 AreaCode=800 Number=679-2778 After the TelAlert configuration changes have been made (either via TelAdmin, or by editing telalert.ini), make sure to stop and start TelAlert to put them into full effect, particularly since the changes involve creating new child processes (ExecProc and stunnel). Finally, the new SSL-aware configuration should be tested. Chapter 17: Security Features 273

17.10 Development Example Returning to the development example, the code needs to read input from a stream socket and send the parsed data to a legacy system through a defined Legacy interface object. With the information above, one can now consider the code required to accomplish this task: Step 1: Create A New User Object Before one can override the base behavior, one must first define the new object to implement it. In JAVA, this is done by creating a new object which extends the base class. Define a new java source file with a new public class LegacyInterface which extends the User class: import java.lang.* import tanotify.*; import tanotobjects.*; import LegacyMagic.*; // LegacyMagic is the packet that // contains the legacy adapter. public class LegacyInterface extends User {} The first four imports bring in standard objects, the objects that define the shell and event objects, and the interface to the Legacy backend. Next, the class is defined, including its references to the base User class. Now, in the Shell.java file, find the line that reads: User myuser = new User This is where the Shell defines the reference to the base User class. Add the import for our new class, and change the line to read: LegacyInterface myuser = new LegacyInterface() This step brings in the legacy interface object. To actually use this object, find the line which calls the SetUserObject method and pass this object. (Example: parser.setuserobject(myuser); ) That s all there is to it. The shell will now use the new user object in place of the base class. Since the new object is derived from the base class, all methods defined in the base User object are still there and will be called if needed. Stopping here will create a shell which works identically to the standard toolkit. To change behavior, one must override specific methods. In this case, the stream source has changed from a file to a TCP socket and posting methods must be extended. Therefore, one must override the following methods: UserOpenStream 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 274 TelAlert Administrator Guide - Version 5.7

In addition, one should redefine UserAppStart and UserAppStop to support opening and closing access to the legacy system itself. In a true production environment, one would also redefine error handlers, etc. In this example, we will assume everything works as expected. Consider the following JAVA code; with the exception of the legacy interface, this JAVA code meets the requirements defined earlier in this document. package tanotify; /** * This class provides an example for those wishing to write their * own User subclass. While this class does nothing useful, developers */ * can use this class as a model for a subclass that might work with * a database or legacy system. /** * First, import the IO package AND our object definitions */ import java.io.reader; import tanotobjects.*; /** * Get normal JAVA language components */ import java.lang.*; import java.net.*; import java.io.*; /** * First, subclass the user class and reference THIS class in the shell * THIS IS HOW ONE WOULD CREATE THEIR OWN USER OBJECT */ public class DBUser extends User { /** * Create a Legacy object here */ Legacy mylegacy; Chapter 17: Security Features 275

/** * In this example, the class gets its input from a socket not a * file, Therefore, this class must override the OpenStream and * CloseStream methods to start. Create the necessary objects for * the socket. */ ServerSocket serversocket; Socket activesocket; InputStreamReader inputreader; /** * Our local constructor does nothing */ public DBUser() { } /** */ * The post routines do nothing different from the base class * so we ll just call the base method via super. If not defined * here, the base class methods would be used anyway. Here a real * subclass might used an attached database connection, * and use these routines to build and execute insert statements. public boolean UserPostFileEvent(taNotifyFile event) { /**@todo: Override this tanotify.user method*/ return super.userpostfileevent( event); } public boolean UserUnknownAttribute(String elementname, String attrname, String attrvalue) { /** Here we would override this method to handle unknown attributes 276 TelAlert Administrator Guide - Version 5.7

*/ /**@todo: Override this tanotify.user method*/ return super.userunknownattribute( elementname, attrname, attrvalue); } public boolean UserAppStart(String[] parm1) { } /**@todo: Override this tanotify.user method*/ /** The username and password strings are defined by magic here. */ /** In real code, you d need to define the logic */ mylegacy.openlegacy(usernameref, passwordref); return super.userappstart( parm1); public void UserExit() { /**@todo: Override this tanotify.user method*/ mylegacy.closelegacy(); super.userexit(); } public boolean UserPostNotificationEvent( tanotifynotification event) { /**@todo: Override this tanotify.user method*/ /** and Here one should serialize the object into a collection of strings */ 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*/ /** and Here one should serialize the object into a collection of strings */ place them into a vector (data) Vector data = /* Get strings out of event */ return mylegacy.postevent( HeartBeatEvent, data) Chapter 17: Security Features 277

} public boolean UserPostError(Exception ex) { /**@todo: Override this tanotify.user method*/ return super.userposterror( ex); } public boolean UserAppStop() { /**@todo: Override this tanotify.user method*/ return super.userappstop(); } public boolean UserTick() { /**@todo: Override this tanotify.user method*/ return super.usertick(); } /** */ * OVERRIDE : OpenStream * This new method gets input from a socket, not a file. public Reader OpenStream(String[] parm1) { /** * Get the port number for the server socket we re listening on */ String listenportstring = parm1[0]; Integer ivalue = new Integer(listenPortString); int portnum = ivalue.intvalue(); try { /** * Set up the socket and get Reader and Writer interfaces from it * once it s active. */ serversocket = new ServerSocket(portNum); activesocket = serversocket.accept();inputreader = new InputStreamReader(activeSocket.getInputStream()); PrintWriter outputwriter = new 278 TelAlert Administrator Guide - Version 5.7

PrintWriter(activeSocket.getOutputStream()); outputwriter.println("xml Parser ready"); return inputreader; } } /** } catch (IOException ioex) { 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 17: Security Features 279

18 Integrating XML Output 18.1 Overview TelAlert 5.3 and beyond now supports notifications in XML format. This new interface allows developers to post notifications to third-party systems with minimal effort. In addition, developers can use this interface to provide customer database and legacy system support. This chapter describes the steps needed to integrate a TelAlert installation into a third-party backend. Note that this chapter assumes the reader is familiar with TelAlert, it s notification interfaces, and JAVA 1.2 programming. 18.2 Enabling XML Output TelAlert has two distinct circumstances in which it can produce XML output. 1. The [File] section; the [Heartbeat] section; and definitions in the [Notification] sections can specify XML format for the event data they produce. All three of these sections provide event-driven output, triggered by internal TelAlert events in the alert lifecycle. TelAlert includes a DTD (tanote.dtd) that defines the XML output for these events. TelAlert also includes some documentation of an example application that receives and processes this XML event data stream. 2. The telalert show and showalert commands have been enhanced to produce XML-like output. This is somewhat of a curiosity; no DTD is provided, and no method of passing the output to another application is implemented (other than the standard >> redirection of command output to a file on both Windows and UNIX, and the " "piping of command output on UNIX.) To have [File], [Heartbeat], or [Notification] produce XML output, simply include [XML in the appropriate event keyword definitions. For example, a [Notification] definition that includes the keyword-value pair AlertStarted= ${TimeStamp} Alert Started ${AlertID} ${Destination} ${Ticket} ${State} 280 TelAlert Administrator Guide - Version 5.7

would produce output looking like this: 2002/03/18 16:31:44 Alert Started 41 Display 0 [20]Alert Started, Display while a definition that includes the keyword-value pair AlertStarted= [XML] would produce output looking like this: <Notify><NotificationEvent><AlertStarted tantimestamp="2002-03-19t00:31:44+00:00" tanserverhost="integrationrd2.telamon.com" taneventnum="20" tanstatenum="20" tanstatusdata="[20]alert Started" tanstate="[20]alert Started, Display" tanparagraph="notifylogxml" tandefinition="notifylogxml" tanalertid="41" tandestination="display" tanmessage="test" tanpriority="50" tanuser="" tancheck="" tangroup="<none>" tanipcheck="" tannodeaddr="" tanremark="" tanreplyto="" tansource="" tansubject="" tanticket="0" tanmaskedticket="0" tanclienthost="integrationrd2.telamon.com" tanclientuser="administrator" tangroupfullname="<none>" tancmndid="342"/></notificationevent></notify> Among other differences, notice that the timestamp in the first example is in "local" time according to the server clock (PST in this case), while the timestamp in the second example is in UTC (Greenwich) time. For certain variables like ${TimeStamp}whose value according to XML standards differs from older TelAlert defaults, it is now possible to define event keyword-value definitions that use TelAlert ${variablenames}and XML standards; the definition AlertStarted= ${TimeStamp,XML} Alert Started ${AlertID} ${Destination} ${Ticket} ${State} would produce output looking like this: 2002-03-19T00:31:44+00:00 Alert Started 41 Display 0 [20]Alert Started, Display [File], [Heartbeat] and [Notification] can direct their XML-formatted output to all of the same places they can direct their legacy-formatted output: appended to text files; sent to UNIX syslog or Windows Application Event Log; etc. In addition, the "helper" application tconntfy, which is normally used to send event data to Vytek s TelaConsole product, can also be used to direct XML-formatted output to another application listening on a TCP/IP socket, such as the sample JAVA application discussed later in this chapter. The [Limits] section has a NotificationITV keyword that enables a [Notification] definition to be invoked for every TelAlert event (most [Limits] Notificationxxx keywords are only invoked for a specific subset of events). This keyword is useful for creating an XML data stream containing all events. Chapter 17: Security Features 281

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]" 282 TelAlert Administrator Guide - Version 5.7

Progress="[xml]" Cmnd="[xml]" GroupStarted="[xml]" GroupOffDuty="[xml]" GroupCleared="[xml]" GroupCompleted="[xml]" Server="[xml]" Security="[xml]" 18.3 Defining the Task In this example, assume the TelAlert administrator has a running TelAlert server, and that the server has been configured to emit notifications via XML (consult the TelAlert documentation for details on XML output). Furthermore, for simplicity, assume that the administrator has chosen to have notifications carry all possible attributes. Finally, assume these notifications are being broadcast on a socket connection to our new backend process. We will assume this backend process will listen to TCP port 8819, hostname backend. (The toolkit can easily be extended to support any interface, but TCP/IP sockets are convenient mechanisms and require minimal setup.) In our backend process, once data is available, we want it to be posted to a legacy system. This system could be a database, a proprietary controller or a set of disk files. In this document, we will not discuss the legacy interface. Rather, we will assume that a JAVA package for the legacy interface is already available to the developer with the following class object. public class LegacyMigration extends Legacy { public boolean OpenLegacy(String account, String password); public boolean CloseLegacy(); public boolean PostEvent(String recordtype, Vector data); } The manual page for this class reads: The legacy class must be extended by the developer to provide three basic interfaces. boolean OpenLegacy(String account, String password) This method will be called when applications wish to open a session with the legacy system. It expects a valid account name and password pass as strings. It will attempt to log into the legacy system. On success, it returns true. On failure, it returns false and generates an error in the system log. boolean CloseLegacy() This interface closes the active session with the legacy system. On success, it returns true, false on failure. Chapter 17: Security Features 283

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. 18.4 A (Very) Brief Overview of XML TelAlert s XML stream, like all XML, consists of a text stream describing data. To debunk an old myth, XML does not have meaning, it is simply a representation of the data. Applications require a definition document to describe that data to describe to them what a given block of data means in terms of objects. Simply having XML does not give you interoperability. This document, also supplied with TelAlert, is the data-type-document or DTD. A DTD describes the structure of an XML document what is allowed where and how often. While meaning is still absent, applications can at least trust that their content is syntactically correct. As an analogy, a JAVA class contains data in various objects. Any application can access that class and its data akin to the XML document and DTD - but the meaning of the sub-objects is still left to the developer. A string is a string, is a string In TelAlert s XML streams, objects begin with the <Notify> tag. This tag signals the start of an event. The event will end when a </Notify> tag is received. One and only one event will be encapsulated within these tags. <Notify> event data </Notify> <Notify> event data </Notify> XML purists will note the lack of a DOCTYPE statement. Technically, XML documents require a DOCTYPE statement to tell the parser what DTD is bound to that document. Unfortunately, most parsers will insist on parsing the DTD each and every time a DOCTYPE object is read. This may be fine for web pages, but for streaming data, it creates a very significant performance penalty. Therefore, TelAlert uses a non-validating SAX parser one which will accept, and ignore any DOCTYPE references. While this speeds up parsing, it means that invalid XML will be silently discarded. One can use a DOM-style parser, but this would increase the memory footprint, and often the financial footprint, by orders of magnitude. (For reference, our toolkit uses the Apache Xerces JAVA SAX parser.) 284 TelAlert Administrator Guide - Version 5.7

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> Chapter 17: Security Features 285

18.5 The Parser Toolkit Given the above XML, some code must be written to perform the following tasks: 1. Open an access port to the XML from some server using the appropriate communications media a socket, a file, a serial port, etc. 2. Create a parser designed to parse that XML into usable objects 3. For each object parsed, pass that object to a third-party interface 4. When done, close the third-party interface and access stream Fortunately, our XML parser toolkit has written much of the basic skeleton already. Using this kit, a developer will most likely need to change only one class. Overall, the toolkit consists of three JAVA packages, only one of which requires development effort. (Source code for the entire package is provided for those who wish to extend the package.) Package Files Purpose SAXTools TANotObjects SaxTools.java BasicNotification.java TANotifyFile.java TANotifyHeartBeat.java TANotifyNotification.java This is the parser framework. It is the XML-aware code in the toolkit. Once started, it drives the parsing and calls appropriate publish routines. Normally, developers will not need to change this package. This package defines the JAVA objects that hold processed notifications. Unless a developer wishes to add an entirely new type of notification, this package can be considered read only. TANotify Application.java Shell.java User.java DBUser.java The shell for the parser. A developer calls this package to start the application and to interface his special methods into the parser. Typically, only two files will require work. Since the majority of these files require no changes, this document will not discuss the files BasicNotification.java, SAXTools.java, and Application.java. The reader may consult the source code for details in these sections. Furthermore, the entire project is written using the Xerces SAX Parser specification (http:// www.apache.or/xml). This specification assumes the reader is familiar with JAVA event-based programming. For those unfamiliar with event-based programming, rather than having a standard code module that calls procedures as they occur, event programs register with a dispatcher. During startup, the program requests that, on an event X the dispatcher should call function funcx. This is how SAX works. Simply reading the code might confuse the reader - there is no obvious code flow. Looking deeper into SAXTools however, one finds that the constructor registers functions on various XML events. When an element starts or ends, or during an unknown attribute, our parser events are called by the dispatcher. Therefore, rather than drawing a typical code diagram, this document will use an event response matrix. This matrix can be read as When event X occurs, call funcx. 286 TelAlert Administrator Guide - Version 5.7

18.6 The Event Matrix On Event In File Call Method Purpose Application Startup Shell UserAppStart This method in the user object is called when the application first starts. Developers may use this method to set up any special structures and/or threads. Application Shutdown Shell UserAppStop Called just before shutdown. Developers may use this method to perform any final cleanup. Internal Error Shell & SaxTools UserExit When called, it means that a shell or parser component found an error it is not prepared to handle. This method is called to perform a quick, abort-style shutdown. Unknown Attributes in XML Unknown Elements in XML SaxTools UserUnknownAttribute This method is called by the parser when it finds an attribute or element not in its dictionary. This routine can simply ignore or correct the error, or shut the system down completely. Shell wants to open the input stream Shell UserOpenStream The shell calls this routine when the shell wants the user class to open the input stream. Shell wants to close the input stream Shell UserCloseStream Called by the shell when it wants to close the input stream. Error in XML Shell SaxTools UserPostError This routine is called during parsing if invalid XML is found. It may correct or ignore the error, or shutdown the process completely. Chapter 17: Security Features 287

On Event In File Call Method Purpose A FileEvent record has been posted SaxTools UserPostFileEvent This method is called during normal processing. Once the XML parser has completely parsed a file event, it passes the JAVA file class to this routine for post-processing. A HeartBeat record has been posted SaxTools 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. 288 TelAlert Administrator Guide - Version 5.7

All of these events are managed by the JAVA User object. This base class (in User.java) does little more than read records from a file and print diagnostic data to the system console. In a real application, one needs to override this object and its methods. This is most often performed by two steps: 1. Define a new User object, say DBUser which extends the User class. 2. Override the various methods above with application-specific methods. 3. Edit the shell code, looking for the line that says User userobject = new User. This is the line that needs to change. The new line should become something like DBUser userobject = new DBUser(). Since DBUser has extended User, all internal routines will work, but our override methods will now take effect. 4. Activate the new object by calling the parsers SetUserObject routine, passing our object. 18.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 object s 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 Chapter 17: Security Features 289

Method CloseStream Calling convention void CloseStream () Purpose Returns CloseStream is called by the shell to close the input stream created by OpenStream. Nothing Method Calling convention Purpose Returns 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. Method UserAppStop Calling convention boolean UserAppStop () Purpose Returns 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. Method UserExit Calling convention void UserExit () Purpose Returns UserExit is called by the shell or parser code when an abort is needed rather than a graceful termination. Nothing 290 TelAlert Administrator Guide - Version 5.7

Method UserTick Calling convention boolean UserTick () Purpose Returns 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. 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. Chapter 17: Security Features 291

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 Returns true on posting success, false if the shell should terminate. Method Calling convention Purpose Returns 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. 18.8 The Notification Objects Given the user object, one can now pass data objects to backend systems. The current codekit defines three objects: 1. tanotifyfile-the object representing [File] events 2. tanotifyheartbeat-the object representing [HeartBeat] events 3. tanotifynotification-the object representing [Notification] events All three of these objects are implemented as JAVA beans. As with all JAVA beans, the actual variables for various components are marked private. Code accesses the contents of a bean via its getx methods. For example, a [File] event has an attribute ServerHost. Rather than accessing the value of this attribute with code such as String value = tanotifyfile.serverhost, standard JAVA beans suggest something closer to String value = tanotify.getserverhost(); This isolates the developer from the actual value of ServerHost. The method will return it as a string regardless of its internal representation. For all notifications, consult TelAlert documentation for the appropriate attribute list. For each attribute X, each object has a getx method. 292 TelAlert Administrator Guide - Version 5.7

18.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: 18.9.1 Step 1: Create A New User Object Before one can override the base behavior, one must first define the new object to implement it. In JAVA, this is done by creating a new object which extends the base class. Define a new java source file with a new public class LegacyInterface which extends the User class: import java.lang.* import tanotify.*; import tanotobjects.*; import LegacyMagic.*; // LegacyMagic is the packet that // contains the legacy adapter. public class LegacyInterface extends User {} The first four imports bring in standard objects, the objects that define the shell and event objects, and the interface to the Legacy backend. Next, the class is defined, including its references to the base User class. Now, in the Shell.java file, find the line that reads: User myuser = new User This is where the Shell defines the reference to the base User class. Add the import for our new class, and change the line to read: LegacyInterface myuser = new LegacyInterface() This step brings in the legacy interface object. To actually use this object, find the line which calls the SetUserObject method and pass this object. (Example: parser.setuserobject(myuser); ) That s all there is to it. The shell will now use the new user object in place of the base class. Since the new object is derived from the base class, all methods defined in the base User object are still there and will be called if needed. Stopping here will create a shell which works identically to the standard toolkit. To change behavior, one must override specific methods. In this case, the stream source has changed from a file to a TCP socket and posting methods must be extended. Therefore, one must override the following methods: UserOpenStream 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 17: Security Features 293

In addition, one should redefine UserAppStart and UserAppStop to support opening and closing access to the legacy system itself. In a true production environment, one would also redefine error handlers, etc. In this example, we will assume everything works as expected. Consider the following JAVA code; with the exception of the legacy interface, this JAVA code meets the requirements defined earlier in this document. package tanotify; /** * This class provides an example for those wishing to write their * own User subclass. While this class does nothing useful, developers * can use this class as a model for a subclass that might work with * a database or legacy system. */ /** * First, import the IO package AND our object definitions */ import java.io.reader; import tanotobjects.*; /** * Get normal JAVA language components */ import java.lang.*; import java.net.*; import java.io.*; /** * First, subclass the user class and reference THIS class in the shell * THIS IS HOW ONE WOULD CREATE THEIR OWN USER OBJECT */ public class DBUser extends User { /** * Create a Legacy object here */ Legacy mylegacy; /** * In this example, the class gets its input from a socket not a * file, Therefore, this class must override the OpenStream and * CloseStream methods to start. Create the necessary objects for * the socket. */ ServerSocket serversocket; Socket activesocket; InputStreamReader inputreader; /** * Our local constructor does nothing */ public DBUser() { } /** * The post routines do nothing different from the base class * so we ll just call the base method via super. If not defined * here, the base class methods would be used anyway. Here a real * subclass might used an attached database connection, * and use these routines to build and execute insert statements. */ public boolean UserPostFileEvent(taNotifyFile event) { /**@todo: Override this tanotify.user method*/ return super.userpostfileevent( event); } public boolean UserUnknownAttribute(String elementname, String attrname, String attrvalue) { /** Here we would override this method to handle unknown attributes */ /**@todo: Override this tanotify.user method*/ return super.userunknownattribute( elementname, attrname, attrvalue); } public boolean UserAppStart(String[] parm1) { 294 TelAlert Administrator Guide - Version 5.7

/**@todo: Override this tanotify.user method*/ /** The Administrator and password strings are defined by magic here. */ /** In real code, you d need to define the logic */ mylegacy.openlegacy(administratorref, passwordref); return super.userappstart( parm1); } public void UserExit() { /**@todo: Override this tanotify.user method*/ mylegacy.closelegacy(); super.userexit(); } public boolean UserPostNotificationEvent( tanotifynotification event) { /**@todo: Override this tanotify.user method*/ /** Here one should serialize the object into a collection of strings and place them into a vector (data) */ Vector data = /* Get strings out of event */ return mylegacy.postevent( Notification, data) } public boolean UserPostHeartBeatEvent(taNotifyHeartBeat event) { /**@todo: Override this tanotify.user method*/ /** Here one should serialize the object into a collection of strings and place them into a vector (data) */ Vector data = /* Get strings out of event */ return mylegacy.postevent( HeartBeatEvent, data) } public boolean UserPostError(Exception ex) { /**@todo: Override this tanotify.user method*/ return super.userposterror( ex); } public boolean UserAppStop() { /**@todo: Override this tanotify.user method*/ return super.userappstop(); } public boolean UserTick() { /**@todo: Override this tanotify.user method*/ return super.usertick(); } /** * OVERRIDE : OpenStream * This new method gets input from a socket, not a file. */ public Reader OpenStream(String[] parm1) { /** * Get the port number for the server socket we re listening on */ String listenportstring = parm1[0]; Integer ivalue = new Integer(listenPortString); int portnum = ivalue.intvalue(); try { /** * Set up the socket and get Reader and Writer interfaces from it * once it s active. */ serversocket = new ServerSocket(portNum); activesocket = serversocket.accept();inputreader = new InputStreamReader(activeSocket.getInputStream()); PrintWriter outputwriter = new PrintWriter(activeSocket.getOutputStream()); outputwriter.println("xml Parser ready"); return inputreader; } catch (IOException ioex) { Chapter 17: Security Features 295

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(); } } } 296 TelAlert Administrator Guide - Version 5.7