Documents
Resources
Learning Center
Upload
Plans & pricing Sign in
Sign Out

KnowledgeSync v7.8

VIEWS: 17 PAGES: 543

									KnowledgeSync
     v7.8
 Reference Guide
                                  Tablle of Contents
                                  Tab e of Contents
Table of Contents ................................................................................... ii
Installation & Configuration .................................................................. 1
  Welcome to KnowledgeSync! .................................................................................. 1
  Download KnowledgeSync ...................................................................................... 1
  Installation Requirements ....................................................................................... 2
  Upgrading Your Version of KnowledgeSync .............................................................. 3
  Migrating to SQL Server.......................................................................................... 4
    If You Are Migrating a New Installation ................................................................ 4
    If You Are Migrating an Existing Installation ......................................................... 4
    Do NOT Delete the Access Databases .................................................................. 5
    Schedule Your SQL Database Backup ................................................................... 5
  Reset SQL Server Database Location ....................................................................... 5
  Download KnowledgeSync “EventPaks” ................................................................... 6
  Choose the KnowledgeSync Server .......................................................................... 6
  Configure KnowledgeSync User Account .................................................................. 7
    User Account Specifications ................................................................................. 7
  KnowledgeSync & Regional Settings ........................................................................ 8
  Install KnowledgeSync ............................................................................................ 8
    KnowledgeSync Components to Install ................................................................. 8
       Where You Can Install KnowledgeSync............................................................. 9
    KnowledgeSync Client Install ............................................................................. 10
  Install KnowledgeSync EventPak(s) ....................................................................... 11
  Configure KnowledgeSync Service ......................................................................... 11
  KnowledgeSync Licensing ..................................................................................... 12
  KnowledgeSync Initial Set-Up ............................................................................... 12
    A Note About KnowledgeSync Servers................................................................ 13
    Step #1: Connect KnowledgeSync to a Database............................................... 13
       Add / Verify Application ODBC Source ............................................................ 13
       Logging Into KnowledgeSync ......................................................................... 14
       Log Into KnowledgeSync ............................................................................... 14
           If You Need to Add an Application ........................................................................ 15
           Connecting KnowledgeSync to Your Application ..................................................... 16
           If the Application Branch Already Exists ................................................................ 17
           Connecting KnowledgeSync to The “Sample” Application ........................................ 18
       Test Your Connection .................................................................................... 18
     Step #2: Set Up E-Mail “Sending” Account ........................................................ 19
       E-Mail “Sending” Account Notes ..................................................................... 20
           Sending Mail Outside of Your Domain ................................................................... 21
           Sending Mail in a Hosted Environment .................................................................. 21
           Authentication .................................................................................................... 21
        Running Exchange Without SMTP .................................................................. 22

                                        KnowledgeSync User’s Guide                                                       ii
       Configuring KnowledgeSync Stand-Alone E-Mail .............................................. 23
       Configuring Multiple E-Mail Accounts .............................................................. 24
    Step #3: Test the E-Mail “Sending” Account ...................................................... 24
    Step #4: Define Yourself as a “Subscriber”........................................................ 24
  Configuration Complete: Status Check .................................................................. 26
  Before You Begin Designing Events ....................................................................... 26
  Implementation: How to Proceed ......................................................................... 27
  Tutorials .............................................................................................................. 27
  For More Help . . . ................................................................................................ 27
Product Tutorial ................................................................................... 29
  Product Tutorial ................................................................................................... 29
  Before You Begin ................................................................................................. 29
  The Event Manager: Overview .............................................................................. 29
  If the “Sample Application” Does Not Exist............................................................. 31
  Create a “Record-Level” Event .............................................................................. 31
     Specify the Query’s Tables ................................................................................ 32
     Link the Tables ................................................................................................. 33
     Select the Query’s Columns (Fields) ................................................................... 34
     Select the Query’s Sorting Order ........................................................................ 35
     Specify the Filter............................................................................................... 36
     Skip the Sub-Filter Tab...................................................................................... 37
     Preview the Results of the Query ....................................................................... 37
     Add the Event .................................................................................................. 38
     Link the Query to the Event............................................................................... 39
     Specify the E-Mail Alert Message Text ................................................................ 40
     Event “Response Actions” ................................................................................. 42
     Specify the Event’s Subscribers.......................................................................... 42
     Specify the Event’s Schedule ............................................................................. 43
     Save & Close the Event ..................................................................................... 44
  Create an “Aggregate” Event ................................................................................ 44
     Create the Aggregate Query .............................................................................. 45
     Specify the Query’s Tables ................................................................................ 45
     Link the Query’s Tables ..................................................................................... 45
     Select the Query’s Columns (Fields) ................................................................... 45
     Sorting Order ................................................................................................... 46
     Specify the Filter............................................................................................... 46
     Specify the Sub-Filter ........................................................................................ 47
     Preview the Results of the Query ....................................................................... 48
     Save & Close the Query .................................................................................... 48
     Add the Event .................................................................................................. 48
     Select the Event’s Query ................................................................................... 48
     Specify the E-Mail Message Text ........................................................................ 49
     Specify the Event’s Subscribers.......................................................................... 50
     Specify the Event’s Schedule ............................................................................. 50
     Save & Close the Event ..................................................................................... 51
  Verify KnowledgeSync Server Status ..................................................................... 51
  Submit Your Two Events ...................................................................................... 51
                                        KnowledgeSync User’s Guide                                                   iii
  Track Events in the KnowledgeSync Monitor .......................................................... 51
  A “Getting Started” Hint........................................................................................ 52
  You’re On Your Way! ............................................................................................ 52
Administration...................................................................................... 54
  KnowledgeSync Administration ............................................................................. 54
  The Administrator: Logging In .............................................................................. 54
    Calling the KnowledgeSync Administrator ........................................................... 55
    How to Navigate ............................................................................................... 55
  Activity Folder ...................................................................................................... 56
    Server Status ................................................................................................... 56
       KnowledgeSync Server Descriptions ............................................................... 57
       KnowledgeSync Server Notes......................................................................... 57
       Enabling / Disabling a Server ......................................................................... 58
       Starting / Stopping Servers ............................................................................ 58
       KnowledgeSync Server Login Information ....................................................... 58
    Current User Logins .......................................................................................... 59
  Corrective Actions ................................................................................................ 60
    Application Event Errors .................................................................................... 61
    Message Delivery Errors .................................................................................... 61
    Report Generation Errors .................................................................................. 61
    Response Action Errors ..................................................................................... 62
    Taking a Corrective Action................................................................................. 62
  Hardware Set-Up ................................................................................................. 63
    Configuring KnowledgeSync for Faxing............................................................... 63
    Configuring KnowledgeSync for Paging .............................................................. 64
  Software Set-Up................................................................................................... 65
    E-Mail “Sending” Account .................................................................................. 66
       E-Mail Set-Up: Integration With GroupWise ................................................... 68
       E-Mail Set-Up: Microsoft Exchange Notes ...................................................... 68
       Email Authentication ..................................................................................... 69
       E-Mail Set-Up: Configuring Exchange Under SMTP ......................................... 70
       E-Mail Set-Up: Configuring Exchange Natively ............................................... 70
       E-Mail Set-Up: Lotus Notes Mail .................................................................... 71
       Test Your E-Mail Account (Outside of KnowledgeSync) .................................... 72
       Test Your E-Mail Account (Within KnowledgeSync).......................................... 72
       Using Dial-Up Networking to Send E-Mail ....................................................... 73
       Using Multiple E-Mail “Sending” Accounts ....................................................... 73
    Fax “Sending” Accounts .................................................................................... 74
       Using Multiple Fax “Sending” Accounts ........................................................... 75
    Fax Cover Pages ............................................................................................... 75
    Holiday Schedule .............................................................................................. 76
       Defining Your Holidays .................................................................................. 76
    Paging Services ................................................................................................ 76
    Webcast (Dashboard Alert) Locations................................................................. 78
    User Access: Logins ......................................................................................... 78
       The “General” Tab ........................................................................................ 78
       The “User Access” Tab .................................................................................. 79
  Database Tools .................................................................................................... 80
                                     KnowledgeSync User’s Guide                                                     iv
    Remove Completed Items ................................................................................. 80
      Automating the Removal of Completed Items ................................................. 82
    Remove Pending Items ..................................................................................... 82
    Compact Database............................................................................................ 83
  Backing Up the KnowledgeSync Database .............................................................. 84
    What KnowledgeSync Files Are Backed Up? ........................................................ 85
  Moving KnowledgeSync to a New Server ............................................................... 85
  Enabling KnowledgeSync Diagnostics .................................................................... 86
  Unable to Start Server (Error 1053) ....................................................................... 87
  ACTVMSG_ERR_NOT_FOUND (Error 8139) ............................................................ 88
  ACTVMSG_ERR_FAILURE (Error 8002) .................................................................. 88
Query Designing ................................................................................... 89
  Query Designing .................................................................................................. 89
  Queries, VB Scripts, & SQL Triggers ...................................................................... 90
  Designing a Query To Be Used in Many Events ...................................................... 90
  Query Designing: Preparation .............................................................................. 91
    Identifying Needed Database Fields ................................................................... 91
    Record-Level Query Designing: Preparation ....................................................... 92
       Step #1: Identify Overall Purpose ................................................................. 92
       Step #2: Consider Alert Message Content ..................................................... 92
       Step #3: Identify Alert Message Data Fields .................................................. 92
       Step #4: Identify Needed Database Tables ................................................... 93
       Step #5: Identify the Condition .................................................................... 93
       Step #6: Identify Who’s to be Notified .......................................................... 93
       Step #7: Identify Related Reports ................................................................. 94
       Step #8: Identify Triggered Workflow / Updates ............................................ 94
    Aggregate Query Designing: Preparation........................................................... 95
       Step #1: Identify Overall Purpose ................................................................. 95
       Step #2: Consider Alert Message Content ..................................................... 95
       Step #3: Identify Alert Message Data Fields .................................................. 95
       Step #4: Identify Aggregate Field & Function ................................................ 96
       Step #5: Identify Aggregate Grouping Field................................................... 96
       Step #6: Identify Needed Database Tables ................................................... 96
       Step #7: Identify the Record-Level Condition ................................................ 96
       Step #8: Identify the Aggregate Condition .................................................... 97
       Step #9: Identify Who’s to be Notified .......................................................... 97
       Step #10: Identify Related Reports ............................................................... 97
       Step #11: Identify Triggered Workflow / Updates .......................................... 98
  Query Design Worksheets ..................................................................................... 98
  Stop! Have You Read the Installation Chapter? ................................................... 101
  Add/Edit a Query ............................................................................................... 101
    Record-Level Queries ...................................................................................... 101
    Query Description ........................................................................................... 102
    Query Tables .................................................................................................. 102
       Note: Choosing the Same Table Multiple Times ........................................... 103
    Query Links .................................................................................................... 104
       Note: Overriding the Default Linking Syntax ................................................ 106
                                      KnowledgeSync User’s Guide                                                 v
  Modifying Your Links ................................................................................... 106
  Multi-Field Links .......................................................................................... 106
Query Columns ............................................................................................... 107
  If No Query Columns Are Displayed ............................................................. 108
  How to Select Query Columns ...................................................................... 108
      Selecting “All” Query Columns.............................................................................109
   The Column “Type” Field ............................................................................. 109
   The “Customized Name” Field ...................................................................... 109
   The “Unique” Field ...................................................................................... 110
      How KnowledgeSync Tracks a “Triggered” Record ................................................111
      Creating a Multi-Field Unique Value .....................................................................112
   Resizing the Display Grid ............................................................................. 113
   Calculated Fields ......................................................................................... 113
      How Do You Create a Calculated Field? ...............................................................114
      Using Advanced Calculations (Functions) .............................................................115
      Calculated Field Notes ........................................................................................117
      Date-Related Functions ......................................................................................117
   Field Editing Notes ...................................................................................... 118
      Concatenation ...................................................................................................118
      Concatenation (Order Line Item Unique)..............................................................119
      Trimming “Padded Spaces” from a Field’s Value ...................................................119
      Retrieving ‘x’ Characters of a Field’s Value ...........................................................120
      Converting a Field Type (Date, Numeric, Character) .............................................120
      Retrieving the “Top x” Number of Records ...........................................................120
      Creating a Column that is a Label + Field Value....................................................121
      Creating a Column that Contains a Date Substitution Value ...................................121
      Retrieving Just the Month or Day from a Date Field ..............................................122
      Creating a Column that Contains a Hard-Coded Value ...........................................122
      Creating a Column Containing File Specifications ..................................................122
      Using “if – then – else” Logic ..............................................................................123
  Removing Columns from a Query ................................................................. 123
  Return Distinct Rows of Data Only ............................................................... 124
  Sub-Queries (Embedded Selects) ................................................................. 124
Query Sorting Order ....................................................................................... 125
  The Effect of Sorting on “Record Breaks”...................................................... 126
Query Filters .................................................................................................. 127
  Query Filter Operators ................................................................................. 127
  Query Filter “Compare Values” ..................................................................... 128
  Query Filter “Parameters” ............................................................................ 128
  The Seven Filter Components ...................................................................... 129
  Compare Values .......................................................................................... 130
      Comparing a Column Against a Constant Value ....................................................131
      Comparing a Column Against Another Database Field ...........................................132
      Comparing a Column Against a Date or Numeric Range ........................................133
      Comparing a Column Against a Date Substitution Variable.....................................135
      Retrieving “New” Records Since the Last Time the Event Ran ................................136
      Pervasive & Providex SQL Date Formatting ..........................................................136
      Creating a Parameter-Driven Filter ......................................................................136
   Checking a Column Against a “Changed” Value ............................................. 138
      Selecting a “Changed” Field ................................................................................140
      Specifying a “Changed To” Value ........................................................................141
      Storing & Reporting On “Changed” Values ...........................................................142
   Operator Notes ........................................................................................... 142
                            KnowledgeSync User’s Guide                                                     vi
         Operator:     “One Of” ...........................................................................................142
         Operator:     “Between” .........................................................................................143
         Operator:     “Starting With” ..................................................................................143
         Operator:     “Like” ...............................................................................................144
         Operator:     “Null”................................................................................................144
     Using Calculated Fields in Filters .................................................................. 144
     And/Or Logic .............................................................................................. 146
     Using SQL-Related Functions ....................................................................... 148
  Query Sub-Filters ............................................................................................ 148
  Query SQL ..................................................................................................... 148
     Using a Stored Procedure in a Query ............................................................ 150
  Query Preview ................................................................................................ 150
Saving a Query .................................................................................................. 152
Copying a Query ................................................................................................ 152
Deleting a Query ................................................................................................ 152
Scrolling Through Your List of Queries ................................................................. 152
Aggregate Queries ............................................................................................. 153
  The Results of an Aggregate Query ................................................................. 153
  Aggregate Query Configuration ....................................................................... 154
  Creating & Naming a New Aggregate Query ..................................................... 154
     Note: Aggregate Query Naming Conventions ............................................... 155
  Aggregate Query Tables.................................................................................. 155
  Links (for Aggregate Queries) .......................................................................... 156
  Aggregate Functions ....................................................................................... 156
     Aggregate Function: “Summarize”................................................................ 156
     Aggregate Function: “Average” .................................................................... 157
     Aggregate Function: “Count” ....................................................................... 158
     Aggregate Function: “Maximum” & Minimum ................................................ 159
  Aggregate Grouping........................................................................................ 160
  Aggregate Query Columns............................................................................... 160
     A Query With Multiple Aggregate Columns.................................................... 160
     Column Selection: “Summarize” & “Average” ................................................ 161
     Column Selection: “Count”........................................................................... 161
     Column Selection: “Minimum” & “Maximum”................................................. 161
     Additional Column Selections ....................................................................... 162
     The “Unique” Field ...................................................................................... 162
     Aggregates and Calculated Fields ................................................................. 162
  Query Sorting Order (for Aggregate Queries) ................................................... 163
  Query Filter Overview (for Aggregate Queries) ................................................. 163
     Query Filters (for Aggregate Queries) ........................................................... 164
  Query Sub-Filters ............................................................................................ 164
  Query SQL (for Aggregate Queries) ................................................................. 165
  Query Preview (for Aggregate Queries) ............................................................ 165
Multi-Query Events ............................................................................................. 166
  Multi-Query Events that Are Not Linked............................................................ 167
  Linking Queries from the Same Application....................................................... 167
     How Do You Link Queries from the Same Application? .................................. 168
     How To Design Linked Queries .................................................................... 168
         Design The Initial Query.....................................................................................168

                                     KnowledgeSync User’s Guide                                                        vii
           Design The “Link To” Query................................................................................169
           Query Linking Notes...........................................................................................170
     Data Manipulation Between Linked Queries ...................................................... 171
     Linking Queries from Different Applications ...................................................... 172
        How Do You Link Queries from Different Applications? .................................. 172
           Design The Initial Query.....................................................................................173
           Design The “Link To” Query................................................................................173
  Database Triggers .............................................................................................. 174
Subscriber Maintenance ..................................................................... 175
  Event Subscribers .............................................................................................. 175
  Who Can Be a Subscriber? .................................................................................. 175
    Using KnowledgeSync for Target Marketing ...................................................... 175
    Designating a Computer as a Subscriber .......................................................... 176
  How Are Subscribers Categorized? ...................................................................... 176
  Subscriber Alert Methods & Addresses ................................................................. 177
    A Note About Webcasting (Dashboard Alerts) ................................................... 177
  Subscriber Entry Methods: Overview ................................................................... 178
    Manual Entry .................................................................................................. 178
    Importing Subscribers ..................................................................................... 178
    Linking to a Subscriber Database ..................................................................... 178
  Subscriber Definition: Preparation ...................................................................... 179
    Step #1: Identify Means of Entry.................................................................... 179
    Step #2: Manual Entry ................................................................................... 179
    Step #3: Imported / Linked Entry ................................................................... 180
  Subscriber Entry Worksheets .............................................................................. 180
  Subscriber Maintenance ...................................................................................... 183
    Subscriber Group Maintenance ........................................................................ 183
       Adding a Subscriber Group .......................................................................... 184
       Changing a Group’s Name ........................................................................... 184
       Deleting a Subscriber Group ........................................................................ 184
  Subscriber Maintenance ...................................................................................... 184
    Manually Entering Subscribers ......................................................................... 185
       Adding a Subscriber .................................................................................... 185
           About the “User Lookup Key” Field ......................................................................186
           Using a “Group” Lookup Key ...............................................................................187
           “Copy” Method Notes .........................................................................................187
           “Paging” Method Notes ......................................................................................188
           “Webcasting” Method Notes ...............................................................................189
           About the “Subscriptions” Tab ............................................................................189
           Creating a “Template” Subscriber Record .............................................................189
       Copying Subscribers .................................................................................... 190
       Deleting Subscribers ................................................................................... 190
       Scrolling Quickly Through Your List of Subscribers ........................................ 190
     Importing / Linking Subscribers ....................................................................... 190
       Step 1: Create the Import / Link Query ....................................................... 191
       Step 2: Create the Import / Link Group ....................................................... 191
       Step 3: Activate the Import Link Function .................................................... 191
       Step 4: Choose the Import / Link Query ...................................................... 192

                                       KnowledgeSync User’s Guide                                                  viii
      Step 5: Map the Subscriber Fields ............................................................... 193
      Step 6: Save Your Link ............................................................................... 193
      Choose to “Link” or “Import” ....................................................................... 194
      Removing a Subscriber Link ......................................................................... 195
      Editing Imported / Linked Subscribers .......................................................... 195
  Creating “Intelligent” Subscriber Groups .............................................................. 195
Event Designing ................................................................................. 196
  Event Designing ................................................................................................. 196
  What Triggers an Event? .................................................................................... 196
  What Happens When an Event is Triggered?........................................................ 196
  The Components of an Event .............................................................................. 197
    An Event’s Query(ies) ..................................................................................... 198
    An Event’s Message Content............................................................................ 198
    An Event’s Actions .......................................................................................... 198
    An Event’s Subscribers .................................................................................... 199
    An Event’s Schedule........................................................................................ 199
  Webcasting (Dashboard Alerts) ........................................................................... 200
  “Checked” Vs. “Triggered” .................................................................................. 200
    Monitoring the Status of Events ....................................................................... 200
  An Event Without a Query .................................................................................. 200
  Before You Begin ............................................................................................... 201
  Event Designing: Preparation ............................................................................. 201
       Step #1: Identify Event Purpose ................................................................. 202
       Step #2: Identify Related Query(ies) .......................................................... 202
       Step #3: Identify Trigger Frequency ........................................................... 202
       Step #4: Identify Event Message Content ................................................... 202
       Step #5: Identify Alert Action(s) ................................................................. 203
       Step #6: Identify Subscribers ..................................................................... 203
       Step #7: Identify the Schedule ................................................................... 203
  Event Design Worksheets ................................................................................... 203
  Accessing the Event Designer ............................................................................. 210
  Viewing/Editing an Event .................................................................................... 210
  Creating a New Event ......................................................................................... 211
  Event Description, Priority, & Repeat Status ......................................................... 211
       Repeat Notification for Triggered Items ........................................................ 212
           Enabling an Event to “Not Repeat” a Triggered Record .........................................213
           Clearing a Record’s Trigger .................................................................................213
           Using “Repeat” in a Field-Level Change Event ......................................................213
       Keep Only Last Checked Record in Monitor ................................................... 213
     Event Queries ................................................................................................. 214
       Selecting Multiple Queries ........................................................................... 215
           Selecting Queries from Other Applications............................................................216
        Using a VB Script Instead of a Query ........................................................... 216
        Using SQL Triggers Instead of a Query ......................................................... 217
        Event Trigger Parameters ............................................................................ 217
           Parameter Answer .............................................................................................218
           Using Date Substitution Variables ........................................................................218
                                       KnowledgeSync User’s Guide                                                   ix
  Removing a Query from an Event ................................................................ 219
The Reports Tab ............................................................................................. 219
  Sending an HTML Report as E-Mail Text ....................................................... 220
  Enabling the Report Server .......................................................................... 221
The Files Tab ................................................................................................. 221
  File “Alternative Text” Options ..................................................................... 222
The Copy (FTP) Tab........................................................................................ 223
  Enabling the Copy Server ............................................................................ 224
  Monitoring the Status of Copied Files ........................................................... 225
      Transferring Files to an AS/400 Environment........................................................225
Trigger Frequency .......................................................................................... 225
Event Message Formatting .............................................................................. 227
E-Mail Tab ...................................................................................................... 227
   Enabling the E-Mail Server ........................................................................... 228
   E-Mail Account to Send From ....................................................................... 229
   E-Mail Reply (& From) Address .................................................................... 229
   E-Mail Subject Text ..................................................................................... 230
   E-Mail Message Text ................................................................................... 231
      E-Mail Message Text: How to Edit .......................................................................231
   Field Formatting Options ............................................................................. 232
      Displaying Data in a Table with Rows & Columns..................................................232
      Shortening the Display Length of a Field ..............................................................233
      Making Fields Line Up ........................................................................................233
      Numeric Formatting Options ...............................................................................233
      Formatting Currency ..........................................................................................234
      Formatting Numbers ..........................................................................................234
      Skipping Fields With Null Values ..........................................................................235
   Text Formatting Notes & Hints ..................................................................... 236
   Embedding URL Links in Message Text ......................................................... 237
   Sample Alert Messages ................................................................................ 237
      Event: Customers; More than 2 Late Shipments Last Quarter ...............................238
      Event: Customers; Shipment Confirmations for Today..........................................238
      Event: Customers; Frequent Buyer Incentives .....................................................238
      Creating a Message With Both HTML & Non-HTML Text ........................................238
   Inserting HTML Output from a Report .......................................................... 239
   Controlling Trigger Frequency (“Repeat”) ..................................................... 239
      Repeating Text in an Event’s Message .................................................................240
      Trigger Once for All Matching Records .................................................................241
      Trigger Once Per Group: Options .......................................................................242
      Trigger Once Per Alert Recipient .........................................................................242
      Example: Trigger Once Per Recipient ..................................................................243
      Trigger Once Per Alert Recipient & Secondary Break Field .....................................244
      Example: Trigger Once Per Recipient & Break Field .............................................245
      Trigger Once Per Break Field ..............................................................................245
      Example: Trigger Once Per Break Field ...............................................................246
      “Begin Repeat” Notes .........................................................................................246
  E-Mail Message Handling Options................................................................. 246
  What Needs to Happen to Send E-Mail Alerts ................................................ 248
  Monitoring the Status of E-Mail Alerts........................................................... 248
Fax Tab ......................................................................................................... 249
  Enabling the Fax Server .............................................................................. 250
  Fax Cover Page, Subject, & Message Text .................................................... 250
                                  KnowledgeSync User’s Guide                                                    x
  Configuring Fax Text to Use E-Mail Content .................................................. 250
  Fax Message Handling Options .................................................................... 251
  What Needs to Happen to Send Fax Alerts ................................................... 252
  Monitoring the Status of Fax Alerts .............................................................. 253
  Using an External Faxing Application ............................................................ 253
Page Tab ....................................................................................................... 253
  Using Email to Send Pager Text Messages .................................................... 254
  Enabling the Page Server ............................................................................ 255
  Pager Message Text .................................................................................... 255
  Pager Message Handling Options ................................................................. 255
  What Needs to Happen to Send Pager Alerts ................................................ 256
  Monitoring the Status of Pager Alerts ........................................................... 256
Webcast (Dashboard Alerts) Tab ..................................................................... 257
  Sample Webcast Output .............................................................................. 258
  Enabling the Webcast Server ....................................................................... 258
  Webcast Subject & Message Text, & Options ................................................ 259
  Monitoring the Status of Webcast Alerts ....................................................... 259
Action Tab ..................................................................................................... 259
  Actions & the “Repeat” Function .................................................................. 260
  Enabling the Action Server........................................................................... 260
  The Six Types of “Actions”........................................................................... 260
      The Order of Action Execution ............................................................................261
   Monitoring the Status of “Actions” ................................................................ 261
   Referencing an Event’s Files Within “Actions”................................................ 261
   Create a File Containing Event Data ............................................................. 262
      File Creation Notes ............................................................................................263
   Execute a SQL Statement??? ....................................................................... 264
      SQL “Where” Clause ..........................................................................................265
      Specifying Your SQL ODBC Connection ................................................................265
      Entering Your SQL Syntax ..................................................................................266
      Delaying SQL Execution Until Reports Are Complete .............................................267
      Executing SQL and “Begin Repeat” ......................................................................267
   Submit a Stored Procedure .......................................................................... 268
   Run a Program ........................................................................................... 268
      Selecting a Program to Run ................................................................................269
      Allow Multiple Tasks...........................................................................................269
      Command Line Parameters .................................................................................269
      Delaying Program Execution Until Reports Are Complete .......................................269
      Program Execution Notes ...................................................................................270
      Program Execution and “Begin Repeat” ...............................................................270
   Run a Basic Script ....................................................................................... 271
      VB Script Notes .................................................................................................272
      Scripts and “Begin Repeat” .................................................................................272
   Run the SalesLogix or GoldMine API Wizard.................................................. 272
   The Wizards and “Begin Repeat”.................................................................. 273
   Sample Use of the Wizards .......................................................................... 273
      Triggering External Updates ...............................................................................274
      Identifying the Records to Update .......................................................................274
      Specifying the API Login Information...................................................................274
      Accessing the GoldMine API Wizard .....................................................................275
      Accessing the SalesLogix API Wizard ...................................................................275
      Choose “Add History” or “Schedule Activity” .........................................................276
                                  KnowledgeSync User’s Guide                                                      xi
            Specify Application Login Information ..................................................................277
            Identify the Contact You Wish to Update .............................................................277
            Updating from Non GoldMine or SalesLogix Apps ..................................................278
            Identify History/Activity Data Field Values ............................................................278
            GoldMine & SalesLogix “Types” and “Codes” ........................................................279
            SalesLogix Wizard Notes.....................................................................................279
            GoldMine Wizard Notes ......................................................................................280
            Delaying Wizard Execution Until Reports Are Complete .........................................280
     Subscribers Tab .............................................................................................. 280
       Monitoring the Status of Alert Messages ....................................................... 281
       Standard Subscribers .................................................................................. 282
            Adding a Standard Subscriber .............................................................................282
            Choosing a Subscriber’s Delivery Methods ............................................................283
            Removing an Event’s Subscribers ........................................................................284
        Advanced Subscribers & Message “Breaking” ................................................ 284
            Delivering to Subscribers Using a “Database Lookup Value” ...................................285
            Delivering to Subscribers Using an Address in the Triggered Event .........................286
            Delivering to Multiple Addresses from the Triggered Event ....................................286
     Schedule Tab ................................................................................................. 287
       Monitoring the Status of Scheduled Events ................................................... 288
       Choosing a Schedule ................................................................................... 288
       Creating/Editing a New Schedule ................................................................. 288
            Configuring a Schedule’s “Allowed Range” ...........................................................290
        Schedule Holiday Handling .......................................................................... 290
        Event Dependencies .................................................................................... 290
            How to Configure a Dependent Event ..................................................................291
            Removing an Event’s Dependencies ....................................................................292
            How to Configure a Job Stream??? ......................................................................292
            Job Streams and KnowledgeSync Processing ........................................................292
            Job Stream Example ..........................................................................................293
            Event Schedules in Job Streams ..........................................................................295
            Viewing the Components of a Job Stream ............................................................296
            Creating a New Job Stream ................................................................................296
            Editing an Existing Job Stream ............................................................................297
            Job Stream Name, Description, & Schedule ..........................................................297
            Adding Events to a Job Stream ...........................................................................297
            Re-Ordering Events in a Job Stream ....................................................................297
            Removing Events from a Job Stream ...................................................................298
            Deleting a Job Stream ........................................................................................298
            Running a Job Stream Right Now ........................................................................298
     The “Tracking” Tab ......................................................................................... 299
       Clearing Triggered Records.......................................................................... 300
  If Your Event Isn’t Triggering . . ......................................................................... 300
  If Your Event Is Triggering Over and Over . . . ..................................................... 301
  Schedule an Event to Run “Right Now” ................................................................ 301
  Test an Event .................................................................................................... 302
Visual Basic Scripting ......................................................................... 303
  Visual Basic Scripting .......................................................................................... 303
  Requirements .................................................................................................... 303
  VB Scripting Support .......................................................................................... 303
  “Front-End” Versus “Back-End” Scripts ................................................................ 304
                                        KnowledgeSync User’s Guide                                                  xii
    Sample Back-End Scripting Scenarios ............................................................... 304
    Sample Front-End Scripting Scenarios .............................................................. 305
  Sample VB Scripts .............................................................................................. 305
  Back-End Scripting Set-Up .................................................................................. 305
    Prepare Queries.............................................................................................. 306
    Create the Back-End Script .............................................................................. 306
       Adding a New Back-End Script ..................................................................... 307
    Editing a Script ............................................................................................... 307
       Script Part II: Retrieve General Event Data .................................................. 310
       Script Part III: Retrieve Alert Message Text ................................................. 311
       Script Part IV: Retrieve Query SQL Syntax ................................................... 312
       Script Part V: Retrieve Event Data Fields ..................................................... 313
       Script Part VI: Run Subsequent Events ........................................................ 314
       Script Part VII: Specify Return Status Codes ................................................ 315
       Script Part VIII: Enter Your Script Syntax .................................................... 316
    Link The Script to an Event ............................................................................. 317
  Front-End Scripting Set-Up ................................................................................. 318
    Identify the Script’s “Application” ..................................................................... 318
    Step #2: Design the Front-End Script ............................................................. 319
       Script Part I: General Info .......................................................................... 320
       Script Part II: Use the Script to Trigger an Event ......................................... 321
       Script Part III: Specify Return Status Codes................................................. 322
       Script Part IV: Enter Your Script Syntax ....................................................... 323
    Sample Front-End Script ................................................................................. 323
       Example: Check for Low Disk Space ............................................................ 324
       Example: Check for Low Disk Space (con’t) ................................................. 325
    Link the Script to an Event .............................................................................. 326
Navigator Module ............................................................................... 327
  The KnowledgeSync Navigator ............................................................................ 327
  Accessing the Navigator ..................................................................................... 327
  Scheduled Events ............................................................................................... 328
    Adding a New Schedule .................................................................................. 329
    Edit a Scheduled Event ................................................................................... 329
    Schedule An Event to Run Now ....................................................................... 329
    Test An Event ................................................................................................. 330
  In Progress Events ............................................................................................. 330
  Event Exceptions ................................................................................................ 332
    Correcting Event Exceptions ............................................................................ 333
  Add/View/Edit Events in the Navigator ................................................................ 334
  How Event Details are Displayed ......................................................................... 335
  Adding New Records (Queries, Events, Report Definitions, Scheduled Reports, &
  Basic Scripts) ..................................................................................................... 336
  Viewing & Modifying Events ................................................................................ 336
    Editing an Application’s “Connection” ............................................................... 336
    Enabling / Disabling an Event .......................................................................... 337
    Changing an Event’s Schedule ......................................................................... 338
    General Processing Parameters........................................................................ 339
                                       KnowledgeSync User’s Guide                                                xiii
    Adding/Changing/Removing Event Queries....................................................... 341
      Adding a Query to an Event ......................................................................... 341
      Changing a Query’s Trigger Parameter Values .............................................. 341
      Removing a Query from an Event ................................................................ 343
      Changing a Query’s Configuration ................................................................ 344
    Adding/Changing/Removing Event Reports ...................................................... 345
      Adding a Report to an Event ........................................................................ 345
      Changing a Report’s Parameter Values ......................................................... 346
      Changing a Report’s Output Format ............................................................. 348
      Viewing/Editing the Report’s Definition ......................................................... 349
      Removing a Report from an Event ............................................................... 351
    Adding/Changing/Removing Event Files ........................................................... 351
      Adding a File to an Event............................................................................. 351
      Changing or Removing Event Files ............................................................... 351
    Adding or Changing the Event Email Alert Message .......................................... 353
      Adding Email Alert Text to an Event ............................................................. 353
      Viewing/Editing an Event’s Email Alert Message ............................................ 353
    Adding or Changing the Event Fax Alert Message ............................................. 355
      Adding Fax Alert Text to an Event ................................................................ 355
      Viewing/Editing the Event’s Fax Alert Message .............................................. 356
    Adding or Changing the Event Pager Message .................................................. 357
      Adding Pager Alert Text to an Event............................................................. 358
      Viewing/Editing the Event’s Pager Alert Message .......................................... 358
    Adding or Changing the Event Webcast Message .............................................. 359
      Adding Webcast Alert Text to an Event ........................................................ 360
      Viewing/Editing the Event’s Webcast Alert Message ...................................... 360
    Add/Change/Remove Event Actions (Workflow) ................................................ 361
      Adding Actions (Workflow) to an Event ........................................................ 362
      View/Edit/Remove the Event’s Actions (Workflow) ........................................ 363
      Viewing/Editing the Script Definition ............................................................ 364
    Add/Change/Remove Event Subscribers ........................................................... 366
      Adding Subscribers to an Event ................................................................... 366
      Changing/Removing a Subscriber for an Event.............................................. 367
      Viewing/Editing a Subscriber’s Profile ........................................................... 368
  Subscriber Maintenance ...................................................................................... 370
    Subscriber Group Maintenance ........................................................................ 371
    Subscriber Linking .......................................................................................... 371
Event Monitor ..................................................................................... 372
  Event Monitor .................................................................................................... 372
  KnowledgeSync Event “WatchDog” ..................................................................... 372
  Logging In to the Event Monitor .......................................................................... 373
    Monitor Display Sorting Order.......................................................................... 374
    Resizing the Display Grid ................................................................................. 374
  Activity Folder .................................................................................................... 374
    Server Status ................................................................................................. 374
       KnowledgeSync Server Descriptions ............................................................. 375
       KnowledgeSync Server Notes....................................................................... 375
    Current User Logins ........................................................................................ 376
  Scheduler Folder ................................................................................................ 377
                                     KnowledgeSync User’s Guide                                                    xiv
  Application Events Folder .................................................................................... 378
     How to Handle Event Errors ............................................................................ 379
     Keeping Last Checked Record .......................................................................... 379
     Triggered Records .......................................................................................... 380
     Application Event Data .................................................................................... 380
        Displaying Full Message Text ....................................................................... 381
        Deliverables Button ..................................................................................... 382
        Triggered Items Button ............................................................................... 383
  Report Distribution Folder ................................................................................... 384
  E-Mail Delivery Folder ......................................................................................... 385
     How to Handle E-Mail Delivery Errors ............................................................... 386
  Fax Delivery Folder ............................................................................................ 386
     How to Handle Fax Delivery Errors................................................................... 387
  File Delivery Folder............................................................................................. 388
     How to Handle File Delivery Errors ................................................................... 389
  Pager Delivery Folder ......................................................................................... 389
     How to Handle Pager Delivery Errors ............................................................... 390
  Webcast (Dashboard Alerts) Delivery Folder ........................................................ 391
     How to Handle Webcast Delivery Errors ........................................................... 392
  Report Generation Folder.................................................................................... 392
     How to Handle Report Generation Errors.......................................................... 393
  Actions Taken Folder .......................................................................................... 394
     How to Handle Action Errors ........................................................................... 394
  E-Mail Response Folder ...................................................................................... 395
E-Mail Response System .................................................................... 397
  E-Mail Response System ..................................................................................... 397
  Migrating ERS to SQL Server ............................................................................... 397
  Storing ERS Data in SQL Server .......................................................................... 398
  Web Form Support ............................................................................................. 398
  Supported E-Mail Systems .................................................................................. 398
  How It Works .................................................................................................... 398
  What This Chapter Covers .................................................................................. 399
  ERS Configuration .............................................................................................. 399
    Add ODBC Source for ERS Database ................................................................ 399
    Identify Email Accounts to Monitor .................................................................. 400
       E-Mail Account Properties ............................................................................ 401
       E-Mail Response System Options ................................................................. 402
           ERS & Attached Files..........................................................................................404
        E-Mail Message Text Parsing Options ........................................................... 405
           Modifying the ERS Table ....................................................................................406
           ERS Pre-Defined “Loadable” Database Fields ........................................................406
           How To Specify ERS Parsing ...............................................................................409
      E-Mail Message Posting Options ................................................................... 410
    Specify ODBC Source for ERS Application ......................................................... 410
  ERS Queries & Events......................................................................................... 411
    ERS Query Tables ........................................................................................... 411
                                       KnowledgeSync User’s Guide                                                  xv
    ERS Query Columns ........................................................................................ 411
    ERS Query Filters............................................................................................ 414
  ERS Query Sub-Filters ........................................................................................ 414
  ERS Events ........................................................................................................ 415
    ERS Event Alerts & Actions .............................................................................. 417
    Using E-Mail for “Info or Report Requests” ....................................................... 417
    ERS Subscribers ............................................................................................. 418
    Event Schedule............................................................................................... 418
  ERS in the KnowledgeSync Monitor ..................................................................... 418
Triggered Reports, Documents & Forms ............................................ 420
  Triggered Reports, Documents, & Forms ............................................................. 420
  Reports Vs Forms & Documents .......................................................................... 421
  Define Reports in KnowledgeSync ....................................................................... 421
    New Report Definition ..................................................................................... 421
       The Report ODBC Source ............................................................................ 423
  3 Types of Event-Triggered Reports .................................................................... 423
    The Event -> Report Correlation ...................................................................... 424
    Reports With No Dynamic Selection Criteria ..................................................... 424
    Reports With Event-Independent Selection Criteria ........................................... 426
    Reports With Event-Dependent Selection Criteria .............................................. 428
       Preparing for an Event-Dependent Report .................................................... 429
            Query Design for Event-Dependent Reports .........................................................429
            Query Design Notes ...........................................................................................431
            Report Design for Event-Dependent Reports ........................................................431
       Configure the Event-Dependent Report ........................................................ 432
  Report Delivery Methods .................................................................................... 434
    Delivering a File Via Copy/FTP ......................................................................... 434
    E-Mail Delivery Options ................................................................................... 434
       Sending an HTML Report as E-Mail Text ....................................................... 435
       Attaching Reports to an E-Mail Message ....................................................... 436
    Fax Delivery Options ....................................................................................... 436
       Attaching Reports to a Fax Message ............................................................. 436
    Pager Delivery Options .................................................................................... 437
    Webcast Delivery Options................................................................................ 437
       Posting Reports to a Webcast Message ........................................................ 438
  How Reports Appear in the Monitor ..................................................................... 438
  Report Error 541: Error in File ............................................................................. 439
  “Not Enough Memory” Error ............................................................................... 439
Scheduled Crystal Reports ................................................................. 441
  Scheduled Reports ............................................................................................. 441
  Define Reports Within KnowledgeSync ................................................................ 441
    Add a New Report Definition ........................................................................... 442
  Scheduled Report Examples ................................................................................ 443
  Definition: Scheduled Report “Event” ................................................................. 443
  Create a Scheduled Report Event ........................................................................ 444
    Link the Report(s) to the Event........................................................................ 444
                                        KnowledgeSync User’s Guide                                                  xvi
        Specifying Report Parameter Values ............................................................. 446
     Link File(s) to the Event .................................................................................. 447
     Choose Report Delivery Methods ..................................................................... 447
        Delivering a File Via Copy/FTP ..................................................................... 447
        E-Mail Delivery Options ............................................................................... 447
        Sending an HTML Report as E-Mail Text ....................................................... 448
           Attaching Reports to an E-Mail Message ..............................................................448
        Fax Delivery Options ................................................................................... 449
           Attaching Reports to a Fax Message ....................................................................449
        Pager Delivery Options ................................................................................ 450
        Webcast Delivery Options ............................................................................ 450
           Posting Reports to a Webcast Message ................................................................451
     Report Subscribers ......................................................................................... 451
       Adding a Report Subscriber ......................................................................... 452
       Choosing a Subscriber’s Delivery Methods .................................................... 453
           Removing a Report Event’s Subscribers ...............................................................453
     Report Schedule ............................................................................................. 453
       Creating/Editing a New Schedule ................................................................. 454
           Configuring a Schedule’s “Allowed Range” ...........................................................456
      Schedule Holiday Handling .......................................................................... 456
  How Reports Appear in the Monitor ..................................................................... 457
Dashboard Alerts ................................................................................ 458
  What is a “Dashboard Alert”? .............................................................................. 458
  How Are “Dashboard Alerts” Used? ..................................................................... 459
  What Does a “Dashboard” Consist Of? ................................................................. 459
  How Do “Dashboard Alerts” Work? ...................................................................... 459
  Dashboard Alert Set-Up ...................................................................................... 460
    Enable Dashboard Creation ............................................................................. 460
    Create Dashboard Template ............................................................................ 460
      Storing the Dashboard Template .................................................................. 461
      Creating Multiple Templates ........................................................................ 462
    Create Publishing Location .............................................................................. 462
      Add Publishing Location Folder(s) ................................................................ 462
    Define Default Template & Publishing Location ................................................. 463
    Dashboard Subscribers ................................................................................... 465
    Dashboard Query Design ................................................................................ 465
      One Query – One Dashboard ....................................................................... 465
      One Query – Multiple Dashboards (“Dynamic Dashboards”) ........................... 466
      Dynamically Naming the Dashboard Output File ............................................ 468
      Choosing the Webcast Template & Publishing Location ................................. 469
      Other Query Design Considerations .............................................................. 469
    Configure Dashboard Event ............................................................................. 471
      Create Dashboard Header Information ......................................................... 472
      Create Dashboard Details Section ................................................................ 474
      {BEGIN*REPEAT} / {END*REPEAT} Note ..................................................... 475
      Dashboard “Expiration Days” ....................................................................... 475
      Linking a Report to a Dashboard .................................................................. 475
      “Repeat-Enable” the Dashboard Event.......................................................... 477
    Dashboard Subscribers ................................................................................... 477
                                      KnowledgeSync User’s Guide                                            xvii
    Schedule the Dashboard Event ........................................................................ 478
    Run the Dashboard Event ............................................................................... 478
  Creating User Alert Listings ................................................................................. 478
  Specify Subscribers’ Addresses ............................................................................ 480
  When an Event is Triggered ................................................................................ 481
  Webcasting for Report Distribution ...................................................................... 481
EventPaks ........................................................................................... 482
  EventPaks .......................................................................................................... 482
  The Contents of an EventPak .............................................................................. 482
  The Purpose of an EventPak ............................................................................... 483
  Access the EventPak Functions ........................................................................... 483
  EventPak Vendor Identification ........................................................................... 484
  Building an EventPak .......................................................................................... 485
    Select Applications .......................................................................................... 485
    Specify EventPak Name, Version & Date .......................................................... 486
    EventPak Encryption Password ........................................................................ 486
    Brand the EventPak ........................................................................................ 487
    EventPak Installation Notes ............................................................................. 487
    EventPak Licensing ......................................................................................... 487
    Creating the EventPak File .............................................................................. 488
  Installing an EventPak ........................................................................................ 488
    Installation Note ............................................................................................. 489
  EventPak License Generator................................................................................ 489
KnowledgeSync Utilities ..................................................................... 491
  Utilities .............................................................................................................. 491
  KnowledgeSync Linking Function (KLF) ................................................................ 491
  Real-Time Data Access ....................................................................................... 492
  How the Linking Utility Works ............................................................................. 492
  Licensing & the Linking Utility ............................................................................. 492
  Linking Utility Requirements................................................................................ 492
  Running KLF ...................................................................................................... 493
  Create ODBC Source for the Linked DB................................................................ 493
  Create Linked Application Branch ........................................................................ 494
     Create Queries & Events ................................................................................. 494
  Data Extractor ................................................................................................... 495
  How the Data Extractor Works ............................................................................ 495
  Licensing & the Data Extractor ............................................................................ 495
  The 3 Ways to Run the Extractor ........................................................................ 496
  Data Extractor Requirements .............................................................................. 497
  The Extract Definition File ................................................................................... 497
     Creating the Extract Definition File ................................................................... 497
     Viewing an Extract Definition File ..................................................................... 500
     Selecting an Existing Extract Definition File ...................................................... 501

                                        KnowledgeSync User’s Guide                                                 xviii
Create the Extracted Database ............................................................................ 501
Review Extracted Data ....................................................................................... 502
Create ODBC Source for the Extracted DB ........................................................... 503
Create Extract Application Branch ....................................................................... 504
   Create Queries & Events ................................................................................. 504
Running the Data Extract.................................................................................... 505
   Scheduling the Extract as a Program ................................................................ 505
   Scheduling the Extract as a VB Script ............................................................... 506
External Message Editing .................................................................................... 507
How External Message Editing Works .................................................................. 507
Step #1: Create External Message Table ............................................................. 508
Step #2: Create Field(s) for Message Formats ..................................................... 508
Step #3: Create Access for Editing the Table ....................................................... 508
What Should the Table’s Contents Look Like? ...................................................... 509
Linking an Event to Your External Message .......................................................... 510
Step #4: Link a Query to the External Table ........................................................ 510
Step #5: Edit the Event to Use External Data....................................................... 510
Submitting an Event to Run ................................................................................ 511
Calling a KnowledgeSync Event ........................................................................... 511




                                   KnowledgeSync User’s Guide                                           xix
                                                           CHAPTER 1
                         Installllatiion & Confiiguratiion
                         Insta at on & Conf gurat on


Welcome to KnowledgeSync!

   Thank you for using KnowledgeSync, the industry’s leading Business Activity
   Monitoring (BAM) technology for superior business intelligence.
   This guide is designed to help you install, initially configure, and implement
   KnowledgeSync according to the specific needs of your organization. For quick set-
   up and configuration instructions, please review the “KnowledgeSync
   Implementation Guide” and then proceed to the following chapter for a brief
   (approximately 20 minute) tutorial of the KnowledgeSync application
   For complete instructions on every KnowledgeSync function, from query and event
   designing to report distribution, e-mail response, and webcast set-up, please refer to
   the corresponding chapters in the remainder of this guide.
   We hope that you enjoy working with KnowledgeSync and encourage you to contact
   us with your feedback (contact information is at the end of this chapter). Now let’s
   get started with KnowledgeSync!


Download KnowledgeSync

   The first step in installing and configuring KnowledgeSync is to download
   KnowledgeSync from the Vineyardsoft FTP site. To do so, go to:

           http://www.vineyardsoft.com/html/download.html

   Fill out the download form and you will be shown information on where and how to
   download the appropriate files.
   Note that there is a single “KnowledgeSync Setup” file (KS_Setup.exe) to download
   regardless of the operating system of the machine on which you plan on installing
   KnowledgeSync (Windows 2000 or 2003, Windows NT, Windows XP, or Vista).




                            Installation & Configuration                                    1
Installation Requirements

   If you plan on configuring KnowledgeSync to integrate with your Microsoft Outlook
   (Exchange) based email system, you will need to have either Microsoft Outlook or
   Microsoft Office Pro (which includes Microsoft Outlook) installed on the
   KnowledgeSync server. Note that the Microsoft Outlook installation must include the
   installation of a Microsoft component called “CDO” (collaboration data objects).
   KnowledgeSync does not need to be installed on the same server as your database(s).
   As long as KnowledgeSync can access your application’s data via ODBC, it can be
   installed anywhere on your network (local network is preferred).
   KnowledgeSync runs on both 32bit and 64bit machines; if installing on a 64bit
   machine, KnowledgeSync must use the 32bit ODBC Device Manager (this program
   is automatically part of the 64bit Windows operating systems).
   KnowledgeSync may be configured to use either a Microsoft Access or a Microsoft
   SQL Server database. If you plan on using an Access database, you do not need to
   have Microsoft Access installed on the KnowledgeSync server. If you plan on using a
   SQL Server database, you do need to have MS SQL Server 2000 (Enterprise or
   Standard) with Service Pack 4 or above, SQL Server 2005 (Longhorn) with no
   service packs required, or SQL Server Express 2005 (formerly known as MSDE).
   (Note that the MS Access database files store “pointer” information under a SQL
   installation, so please do not delete the Access database files. No application data is
   actually stored in Access under SQL Server.)
   If you plan on using SQL Server Express, you will need to download and install the
   (free) SQL Server Express database from the Microsoft Windows website.
   (Note also that each of KnowledgeSync's servers (e.g., the application event server,
   the email server, the fax server, etc.) will use its own SQL Server login, so the SQL
   Server version is best utilized by those organizations that license SQL Server per
   "server" and not per "user".)
   As far as hardware requirements are concerned, here are some general requirements:
   I. Minimum System Requirements (One-Connection License):
   Platform: MS Windows NT, 2000, 2003, XP, and Vista
   Memory: 128MB
   Processor: Pentium 290 (or greater)
   Disk Space: (For installation) 80 MB
   Disk Space: (For the application) 32 MB
   Disk Space: (Per event) 5kb maximum (this includes event, query, subscribers, and
   all message texts)




                            Installation & Configuration                                     2
   Minimum & Suggested System Requirements (Two & Unlimited Connections)
           Minimum           Recommended          Minimum         Recommended
           2 connection       2 Connection         Unlimited        Unlimited
   CPU      1.0ghz/1            1.2ghz/1            1.2ghz/1          1.8ghz/2
   RAM       256mb                512mb              512mb            1gb
   HD        20GB                30GB                30GB              50GB
   OS       ------------------------- NT/XP/2000/2003/Vista ----------------------------


Upgrading Your Version of KnowledgeSync

   If you already have a copy of KnowledgeSync installed but wish to upgrade it to the
   most current version, you should download the “KS_Setup.exe” file from the
   Vineyardsoft FTP site.
   To upgrade KnowledgeSync, follow these steps:

           Back-up your KnowledgeSync data files

           Un-install KnowledgeSync (this will leave your data files intact)

           Re-install the new version of KnowledgeSync in the same location as the
           previous version.

           (If you are currently running a KnowledgeSync version prior to V6.x and you
            will be upgrading to version V6.x or higher, you must (after installing the
            new version) next select the option called “Upgrade Earlier Version
            Database to V6”. This option is located in the KnowledgeSync Programs
            Group.)

           Once these steps are complete, you should decide whether you wish to host
           the KnowledgeSync database under Microsoft Access or under Microsoft
           SQL Server. If you opt for MS Access, your upgrade is complete. If you opt
           for MS SQL Server, please follow the steps detailed the section titled
           “Migrating to SQL Server”.
   Note that when you uninstall and reinstall KnowledgeSync, the username and
   password that the KnowledgeSync service use to log in is removed.

   After the upgrade is complete, you should go into the KnowledgeSync Administrator
   module on the KnowledgeSync server and set the server log on information to the
   appropriate password. You can do this by selecting the toolbar button called “Server
   Login Information”.
   To check to see what version of KnowledgeSync you currently have installed, log
   into any KnowledgeSync module, click on the “Help” menu and then on the “About”
   option. On the top right-hand section of the window that appears you will be shown
   the version of KnowledgeSync that you are currently running. If you are not sure if

                            Installation & Configuration                                   3
    this is the current version, please contact Vineyardsoft’s Customer Support
    Department.


Migrating to SQL Server

    As of Version 6.0 of KnowledgeSync, you have the option to host the
    KnowledgeSync database under either MS Access (the default) or MS SQL Server.
    Note that KnowledgeSync supports SQL Server Express (formerly known as MSDE).
    If you plan on using SQL Server Express, you will need to download and install the
    (free) SQL Server Express database from the Microsoft Windows website.
    If you wish to host the KnowledgeSync database under SQL Server, follow these
    steps:

            Install the KnowledgeSync application on your server

            Open the KnowledgeSync Programs group and select the option to “Migrate
            Database to SQL Server”.
    Note: The option to migrate the KnowledgeSync database must be taken from the
    KnowledgeSync server; it cannot be run from a remote KnowledgeSync client.
    Before migrating your database to SQL Server, make sure that you have the
    following two pieces of information:
    1) Which SQL Server name (instance) you wish to migrate to.
    2) A SQL Server username and password that has the privileges to create and to
       alter a database
    Note that the migration program, once successfully executed, will not be able to be
    run again on the same KnowledgeSync database.

If You Are Migrating a New Installation
    If you are migrating a new installation of KnowledgeSync and are using an
    evaluation license code, you may take the “Migrate” option and your evaluation
    license code will continue to work in the SQL Server version.

If You Are Migrating an Existing Installation
    If you are migrating an existing installation of KnowledgeSync, the migration
    program will check to see if you have a valid Version 6.0 KnowledgeSync license
    code. If a V6 license code is not located, the migration program will abort with a
    message instructing you to contact your Business Partner (or Vineyardsoft) to acquire
    a valid KnowledgeSync license code.




                            Installation & Configuration                                  4
Do NOT Delete the Access Databases
    If you are running KnowledgeSync under SQL Server, please do not delete any of
    the Microsoft Access databases that KnowledgeSync installs by default. Although
    KnowledgeSync will not use those databases to store any application data, their
    presence is required as part of the audit trail used by the KnowledgeSync application.

Schedule Your SQL Database Backup
    If you are running KnowledgeSync under SQL Server, it is essential that you make
    sure that this database is being backed-up as part of your nightly (or periodic) backup
    of your other SQL Server application databases.
    Note that unlike the MS Access version of KnowledgeSync, the MS SQL Server
    version of KnowledgeSync does not automatically create backups of its own
    database; this must be configured and scheduled through the standard Microsoft SQL
    Server Backup Utility.


Reset SQL Server Database Location

    [Applicable only if you are hosting the KnowledgeSync database in MS SQL Server.]
    In some cases, you may encounter the need to “reset” the information about where
    the KnowledgeSync database is located. The reasons for needing to do this are:
     If your KnowledgeSync server has gone down and you wish to re-install the
      KnowledgeSync application on another server
     If you rename your KnowledgeSync server
     If you change the username or password of the SQL Server account that
      KnowledgeSync uses to log into SQL Server
    Prior to running the “Reset SQL Server Database Location” option, you must have
    your Database Administrator restore the two KnowledgeSync internal databases to
    the Target Server that you are resetting the database location to. (If you do not take
    this step, the Reset Database Location option will fail with the message “Failed to
    connect to database.”)
    The two KnowledgeSync databases that your DBA must restore to the target server
    before this option is selected are:

            KS_Object

            KS_Inbox
    If (for any reason) your DBA is unable to restore these databases to your Target
    Server, you may also use the option to “copy” the KnowledgeSync internal databases
    and log files to the Target Server. To do so, you will need to “detach” these two
    databases from SQL Server (on your Source Server) copy both the “.mdf” and “.ldf”
    files to your Target Server, and then re-attach those two databases to SQL Server.

                             Installation & Configuration                                    5
   The two KnowledgeSync databases that must be detached and re-attached are:

           KS_Object

           KS_Inbox
   The four SQL files that must be copied from the Source Server to the Target Server
   are:

           KS_Object.mdf

           KS_Object.ldf

           KS_Inbox.mdf

           KS_Inbox.ldf



   Once you restore (or copy) these four files, you are ready to take the “Reset Database
   Location” option from the KnowledgeSync Programs group. When you take this
   option, you will be prompted to confirm the new SQL Server instance name that
   KnowledgeSync will be connecting to, along with the username and password of the
   account that KnowledgeSync will use for accessing its database.


Download KnowledgeSync “EventPaks”

   EventPaks are collections of pre-configured alerts for specific applications that you
   are interested in. Vineyardsoft offers EventPaks for such applications as GoldMine,
   SalesLogix, Great Plains, Macola, and many other applications. Download as many
   of these EventPaks as you are interested in.
   Please note that since some applications are available for use under multiple database
   systems (e.g., Pervasive SQL, Oracle, and Microsoft SQLServer), you may have
   multiple EventPaks to choose from. The EventPaks are named according to the
   application and database that they work with. Place your cursor over the EventPak
   you are interested in to view the full name of the EventPak and thus the particular
   database that the EventPak is designed to be used with.
   Note that it is suggested that you download the version 7 EventPaks from the
   Vineyardsoft site for demonstration purposes. These EventPaks have a limited set of
   events that are configured for ideal presentation purposes. You may then also
   download the complete collection of events for a given application by downloading
   the generic (non v7-specific) EventPaks.


Choose the KnowledgeSync Server

   KnowledgeSync is designed to be installed on a single machine – a server from
   which KnowledgeSync can access the database(s) of the application(s) you wish it to
   monitor.

                            Installation & Configuration                                   6
    Please note that all set-up and maintenance of KnowledgeSync is to be done from
    this server.


Configure KnowledgeSync User Account

    If you will be installing KnowledgeSync to run under Microsoft Windows NT, 2000,
    or XP, you will need to configure the account that the KnowledgeSync service will
    run under.
         Create (or determine) the username under which the KnowledgeSync service
          will run. This must be a domain user account and this account must be a
          member of the “Power Users” group. (You may wish to create a new user
          called something like “Ksync”.)
         Note that if you plan on using KnowledgeSync to send or receive e-mail via
          a Microsoft Exchange-based e-mail system, you must be sure that the user
          account you have selected is a domain controller authenticated user.
         Log into the user account you have created (or selected) and install
          KnowledgeSync.
    Note: The account that you log into when you install KnowledgeSync is also the
    account that you must log into for all subsequent set-up and maintenance of the
    KnowledgeSync application.

User Account Specifications
    As stated, the KnowledgeSync Service should be configured to run out of a specific
    user account. If you are using Microsoft Exchange, this account must be defined as a
    Domain User account.
    This user account should have local admin rights only on the computer on which the
    KnowledgeSync service is running. If local admin rights are not possible, you should
    give the user account the following minimum rights:
    Act as part of the operating system
    Create a token object
    Create global objects
    Create permanent shared objects
    Lock pages in memory
    Log on as a service
    Log on locally
    It is also suggested that you check the dcom security program as the settings in this
    option can cause the KnowledgeSync servers to sit in a perpetual state of “startup”

    If the KnowledgeSync service is idle, but one or more of the KnowledgeSync servers
    do not get past the “startup” mode, do the following:

    1) Stop the KnowledgeSync service
    2) Run “dcomcnfg.exe”

                             Installation & Configuration                                   7
    3) Click on the "Default Security" tab
    4) Check the “Default Launch” button as well as the other two buttons on this tab.
    5) You will (in most cases) see at least one user for each category. If one
       user is listed, then all other users are denied access unless they are also
       entered in the corresponding category. If no users are listed, then all users have
       access.
    6) Add the username that you are running the KnowledgeSync service from if
       other users are listed. Note that you may need to run the KnowledgeSync service
       from a domain user account with local machine admin rights.


KnowledgeSync & Regional Settings

    Because many KnowledgeSync events are triggered by date and/or time fields in
    your application databases, you should make sure that the KnowledgeSync service is
    running from a user account that has the correct regional settings.
    Because regional settings are personal for each logon username, you should check to
    make sure that the regional settings for the KnowledgeSync service user account are
    set in an appropriate fashion.
    Note that the “Local System account” uses the default regional settings for the
    KnowledgeSync server when the operating system was originally installed on that
    server.


Install KnowledgeSync

    After you download the “KS_Setup.exe” file, you may run this file to begin the
    installation of KnowledgeSync. Note that you will be prompted to specify the
    installation password, which will have been provided to you at the time you
    downloaded the KnowledgeSync setup file.
    You will receive a number of prompts that you need to reply to (such as the
    acceptance of license agreement, and installation location), and then you will be
    prompted to specify the KnowledgeSync components that you wish to install.

KnowledgeSync Components to Install
    There are three options regarding what KnowledgeSync components you wish to
    install. These are:
         Core Components: These components are always installed.
         Server Components: These components are installed on the server on which
          the KnowledgeSync database will reside.
         Client Components: These components are installed both on the server on
          which the KnowledgeSync database is installed and for any remote clients

                             Installation & Configuration                                   8
            from which you wish to access the KnowledgeSync database. (See following
            section on Client Installation.)
         Email Components: These are components that correspond to an embedded
          SMTP engine that ships with KnowledgeSync.

            If you are installing KnowledgeSync for the first time, you can check this
            option if you wish to use the embedded SMTP email engine that comes with
            KnowledgeSync for the sending out of email alerts. If you wish to use your
            organization’s own email system (whether Exchange, Internet/SMTP, or
            Lotus Notes), do not select this option.

            If you are upgrading from a previous version of KnowledgeSync and were
            NOT using the embedded KnowledgeSync SMTP engine to send out email
            alerts, it is suggested that you NOT install this component.

            If you are upgrading from a previous version of KnowledgeSync and WERE
            using the embedded KnowledgeSync SMTP engine to send out email alerts,
            you MUST install this component in order to continue using this email
            engine.

            (Note that remote KnowledgeSync clients must be individually licensed in
            order to run the KnowledgeSync application.)
    By default, KnowledgeSync is configured to install all three components. The only
    instance in which you should modify this setting is if you wish to install the
    KnowledgeSync client components on a remote client.
    Note the following:
         To opt that the server components not be installed, click on the down-arrow
          to the left of the “Server Components” option and select “Entire feature will
          be unavailable”.
         Do not select “Feature will be installed when required” for any of the
          components.
         If you wish to install a specific component set, make sure that the option
          “Will be installed on local hard drive” is selected.
         Vineyardsoft requires that the machine on which the KnowledgeSync server
          components are installed also have the KnowledgeSync client components
          installed on it.
    Finally, note that if you install one or more remote KnowledgeSync clients, you will
    not need to specify the location of the KnowledgeSync database during the
    installation process. The first time that a remote client is executed, the user will
    receive a browse button that allows them to locate the KnowledgeSync database they
    wish to connect to.

Where You Can Install KnowledgeSync

    When you purchase KnowledgeSync, you are provided with a license code that
    enables you to install and run KnowledgeSync on a single named server.

                            Installation & Configuration                                  9
    (This license code will have been generated only after you have indicated which
    server KnowledgeSync will be installed on.)
    As a result, you may not install KnowledgeSync on any machine other than the one
    you have a license for. (The server-specific license code that you were issued will not
    work on any other machine.)
    Since KnowledgeSync is installed on a server, however, you may wish to install a
    “client version” of KnowledgeSync on one or more local PCs so that you can
    perform KnowledgeSync system maintenance and KnowledgeSync event monitoring
    without having to log on to the KnowledgeSync server.
    Before you install the KnowledgeSync client module on a PC, however, you must
    purchase one “KnowledgeSync Client License” for each PC that you wish to run the
    KnowledgeSync client on.
    Please contact your KnowledgeSync Business Partner (or Vineyardsoft) for details on
    purchasing KnowledgeSync client licenses.

KnowledgeSync Client Install
    In order to successfully configure a KnowledgeSync client, you must follow these
    steps (regardless of the version of KnowledgeSync you are using):
    1) On the KnowledgeSync server, create a network share to the KnowledgeSync
       folder of where you installed KnowledgeSync. You must grant read and write
       privileges to the domain/user who will be accessing it (otherwise the remote user
       will not be able to log in.) Note that most default network shares are created with
       “read” access only.
    2) On the client computer, run the normal KnowledgeSync install, but uncheck the
       “Server” components when you get to the features section. This will install only
       the “core” and “client” components on the client computer.
    3) Run the Event Manager module on the client computer. You will be prompted to
       specify the location of the “KS_Object.mdb” database. Choose the network share
       location, look in the KnowledgeSync “Data” folder, and then select the
       “KS_Object.mdb” file.
    If you have done the above steps and are unable to log in on the client, open the
    registry using REGEDIT (on the client) and go to the following location:
    HKEY_LOCAL_MACHINE\SOFTWARE\Vineyardsoft
    Corporation\KnowledgeSync2000\General
    Review the settings for the following three items:
    Database
    EPAKTemplate
    Triggered
    Make sure that each of these items has its respective location set like this:
    \\yourservername\yoursharename\Data\KS_Object.mdb
    \\yourservername\yoursharename\Data\KS_EPAK.mdb
    \\yourservername\yoursharename\Data\KS_Triggered.mdb
                           Installation & Configuration                                 10
Install KnowledgeSync EventPak(s)

   After installing KnowledgeSync, you may choose to install one or more of the
   EventPaks that you also downloaded. Simply double-click on the EventPak file and
   reply to the installation prompts. Once this part of the installation is complete, you
   will be prompted to log into the KnowledgeSync EventPak installation module.
   By default, the user name “Admin” (no password) will allow you install an EventPak.
   Once you log into this module, click on the “Install” button at the bottom of the
   EventPak Installation window.




                             EVENTPAK INSTALLATION WINDOW

   The EventPak will now be loaded into the KnowledgeSync application and you will
   receive a “Finished!” message at the bottom of your window when this process is
   complete.


Configure KnowledgeSync Service

   If you will be running KnowledgeSync under Microsoft Windows NT, 2000, or XP,
   your next step is the configuration of the KnowledgeSync service.
        Go into the Control Panel in the system on which KnowledgeSync was
         installed.
        Go to “Admin Tools” and then to “Services”.
        Find the KnowledgeSync service, go to “Properties”, and click on the
         “Logon” tab.
        Select the “This Account” option.



                            Installation & Configuration                                11
        Type in the username (and password) of the account you previously created
         (or selected for use by KnowledgeSync).
        Press “OK”.
        You may start the KnowledgeSync service when ready.
   The installation of KnowledgeSync is now complete. Your next step is the initial
   configuration of the application.
   Note: Under all operating systems (Windows NT, 2000, 2003, and XP), you will see
   a KnowledgeSync Program Group icon called “Desktop Service.”
   This option may be used to run a local (or “desktop”) service for KnowledgeSync,
   which is used for debugging purposes only. You should follow the normal “service
   configuration” instructions for configuring KnowledgeSync for most efficient
   operation.


KnowledgeSync Licensing

   KnowledgeSync is licensed for use on a specific server and for use with a specific
   number of applications. It is suggested that you verify that you have the correct
   license code installed on your system.
   To view your license code information, follow these steps:
        Log into any KnowledgeSync module, click on the “Help” menu and then on
         the “About” option.
        Click on the “License” button.
        Verify the license owner, expiration date, server name, and number of
         database connections (‘0’ or blank connections indicates that you have an
         Unlimited Connection license.)
   If any of the information on this window is not correct, please contact the
   organization from whom you purchased KnowledgeSync, or you may contact
   Vineyardsoft’s Customer Support Department.


KnowledgeSync Initial Set-Up
   There are four steps in the initial set-up of KnowledgeSync:
       1. Connecting KnowledgeSync to an underlying application database and
          verifying that this connection is valid.
       2. Specifying the e-mail account that KnowledgeSync will use for the sending
          of e-mail alert messages.
       3. Testing the operation of the e-mail account defined in step #2.
       4. Creating a “subscriber” record for yourself to use during initial event testing.



                            Installation & Configuration                                12
A Note About KnowledgeSync Servers
    As a “lights-out” application, KnowledgeSync uses multiple “server processes” in its
    daily processing. These servers do everything from scheduling events for submission
    and checking for triggered events, to sending out alerts via e-mail, fax, pager, et
    cetera.
    For a list of all the individual server processes that KnowledgeSync uses, you can log
    into the Administrator module (default user name “Admin”, no password), and under
    the “Activity” folder you can click on the branch for “Server Status.” The window on
    the right will list all of KnowledgeSync’s servers and their current status (e.g.,
    whether they are running or not).
    Under Microsoft Windows NT, XP, 2000, and 2003, all of these servers run under an
    overall KnowledgeSync service, which you can check from your service manager.
    It is important to note that each individual KnowledgeSync server process may be
    “enabled” or “disabled” for running from the KnowledgeSync Administrator module.
    (You simply double-click on a specific server process name and then place a
    checkmark in the field called “Allow Server to Process.”)
    By default, some of KnowledgeSync’s “delivery” servers (such as the fax, page, and
    webcast servers) are pre-configured to not start when the KnowledgeSync service (or
    server manager) is begun. (The KnowledgeSync, scheduler, application event, and e-
    mail servers are enabled by default.)
    You may wish to review the status of the various KnowledgeSync servers to see
    which servers are (and are not) configured to run. Please note that if you will be using
    KnowledgeSync to perform a function related to one of the servers on this list (e.g.,
    send alerts via fax), you must be sure that the fax server is enabled to run.

Step #1: Connect KnowledgeSync to a Database
    Since KnowledgeSync uses Microsoft ODBC to integrate with an underlying
    database, the first step is to check for (or create) one ODBC source that
    KnowledgeSync will use for integrating with each of the desired underlying
    application databases that you wish it to monitor.

Add / Verify Application ODBC Source

    You must have an ODBC source for each application database you wish
    KnowledgeSync to monitor. Note that KnowledgeSync must use the 32bit ODBC
    Manager regardless of whether you are running KnowledgeSync on a 32bit or 64bit
    machine.
    Go into ODBC and either add or verify the existence of a “System DSN” source for
    the applications you are integrating KnowledgeSync with. Your source will look
    similar (but not identical) to the following, depending on the application and on the
    type of database you are working with:




                             Installation & Configuration                                13
                                 ODBC SOURCE DEFINITION
                               (OUTSIDE OF KNOWLEDGESYNC)

    Please note that if you are working with a Microsoft SQLServer database, the options
    to “Use ansi quoted identifiers” and to “Use ansi paddings and nulls” must be
    checked on.

Logging Into KnowledgeSync

    There are two ways that you can log into the KnowledgeSync application; one is
    designed for initial access and system set-up, and the other is designed for use after
    you have initially configured the system and are going back into the application to
    view, add to, or change your event configurations.
    For initial system set-up and access, you should log into the “Event Manager”
    module (as shown in the following section). Once you have completed initial
    configuration, you should log into the “Event Manager – Navigator” module as that
    provides quicker and easier access to the KnowledgeSync system.

Log Into KnowledgeSync

    Log into the KnowledgeSync Event Manager (default user name is “Admin” and
    there is no password); you will see a column titled “Event Management Folders” with
    a branch beneath it titled “Application Events.”
    Note that if you are running KnowledgeSync from a remote client, you will receive a
    browse button that allows you to locate the KnowledgeSync database that you wish
    to connect to.




                             Installation & Configuration                                    14
                               KNOWLEDGESYNC EVENT MANAGER

     The branches that follow are a listing of all of the applications that KnowledgeSync
     is currently configured to integrate with. Among the branches that you will see are a
     branch called “E-Mail Response System” and “Sample Application.”
     (The E-Mail Response System is a module that enables KnowledgeSync to monitor,
     process, and respond to incoming e-mail messages, and the Sample Application is a
     small “contacts and orders” database that is provided for your KnowledgeSync
     evaluation, learning, and testing purposes.)
     If you have downloaded and installed an EventPak (such as the SalesLogix
     EventPak), you will see a branch for that application (e.g., “SalesLogix Alerts”). If
     you wish to integrate KnowledgeSync with an application that did not have a pre-
     defined EventPak, you will need to add that application as a branch beneath the
     branch titled “Application Events.”

If You Need to Add an Application

     If you wish to integrate KnowledgeSync with an application for which there was not
     a pre-defined EventPak, follow these steps:


          Single click on the “Application Events” branch.
          Click on the “New Application” button at the top-left of the Event Manager
           window.




                              Installation & Configuration                                   15
                                   ADD NEW APPLICATION
         Key in the application’s name and click on the “New Connection” button.

Connecting KnowledgeSync to Your Application

     Once you have added your new application to the list within KnowledgeSync, you
     are now ready to integrate the two using an ODBC source you created previously.




                           APPLICATION “CONNECTION” WINDOW
         Key in a description of the ODBC source that you will be using to connect
          KnowledgeSync to the underlying database.
         Choose (from the drop-down list) the ODBC source that will allow
          KnowledgeSync to connect to the underlying database.
         (If needed) Specify the username and password that will allow
          KnowledgeSync access to this database.
         The “Use Coordinated Universal Time” checkbox allows you to specify
          whether the dates and times stored in this application database are stored
          according to the regional settings of the database server, or are stored in UTC
          (also referred to as “GMT”) format. If stored in GMT format, place a
          checkmark in this field.
         Leave the date separation, long tablename, link/join prefix and suffix, and
          column alias fields with their default values.
                            Installation & Configuration                                16
           The three “Script API” fields can be used to contain login information for
            VB scripts that are used to write information back into this application’s
            database. Typically, the “Script Name” field contains the name of the server
            on which the application’s database resides, and the “Script Username” and
            “Script Password” fields contain the user ID and password that
            KnowledgeSync will use when executing the script to gain access to the
            database that KnowledgeSync will be writing data into.
           Click on “Save and Close” at the top-left of your window and then click on
            “OK” from the previous window.
      Please note that if you go into the ODBC Administration program (outside of
      KnowledgeSync) and add or change the definition of an ODBC source, you will
      have to exit from the Event Manager and re-enter it in order for KnowledgeSync to
      recognize the new or modified ODBC source.

If the Application Branch Already Exists

      If there is already a branch for the application which you wish to integrate
      KnowledgeSync with, single click on the branch that contains the application’s name.
      Then, go up to the top of the Event Manager window and click on the “Properties”
      button and click on the “Edit Connection” button.




                             APPLICATION “CONNECTION” WINDOW

      Follow these steps:
           Key in a description of the ODBC source that you will be using to connect
            KnowledgeSync to the underlying database.
           Choose (from the drop-down list) the ODBC source that will allow
            KnowledgeSync to connect to the underlying database.
           (If needed) Specify the username and password that will allow
            KnowledgeSync access to this database.
           Leave the remainder of the fields with their default values.
                            Installation & Configuration                                  17
          Click on “Save and Close” at the top-left of your window and then click on
           “OK” from the previous window.
     Please note that if you go into the ODBC Administration program (outside of
     KnowledgeSync) and add or change the definition of an ODBC source, you will
     have to exit from the Event Manager and re-enter it in order for KnowledgeSync to
     recognize the new or modified ODBC source.

Connecting KnowledgeSync to The “Sample” Application

     KnowledgeSync ships with a small “contacts and orders” database that you can use
     when building sample KnowledgeSync events. This database is a Microsoft Access
     database and requires you to configure a corresponding ODBC source.
     The ODBC source that you define for this database should point to a file called
     “KS_Sample.mdb” and this file is located in the KnowledgeSync data directory.


Test Your Connection

     To test your ODBC connection to make sure that it is valid within KnowledgeSync,
     take these steps:
          From the main Event Manager window, double-click on the name of the
           application you just specified the ODBC source for. This will expand this
           branch to display five sub-branches, the first of which is called “Query
           Definitions.”
          Single-click on the “Query Definitions” branch.
          Go up to the top-left of your window and click on the “New Query
           Definition” button. (If you get an error message, the ODBC source is
           incorrectly defined.)
          Go to the “Tables” tab and from the left-hand column, choose (double-click
           on) a database table that you know has some records within it. (If no table
           names appear on the left, the ODBC source is incorrectly defined.)
          Go to the “Columns” tab and make sure that the table’s columns appear in
           the list titled “Available Columns to Query.” Click on the button called “Add
           All Columns to Query.”

             (If no column names appear in the list, the ODBC source is incorrectly
             defined.)
          Click on the “Preview” tab – and you should see a list of records from this
           table.

             (If you receive an error message, the ODBC source may be incorrectly
             defined.)
     If you are able to take all of these steps successfully, your integration test is complete
     and you may now proceed with specifying the e-mail account that KnowledgeSync
     will use for the sending of e-mail alert messages.



                               Installation & Configuration                                 18
Step #2: Set Up E-Mail “Sending” Account
    If this is a new installation of KnowledgeSync and you are using the embedded
    SMTP email engine that ships with KnowledgeSync, you should skip over this
    step and go immediately to Step #3.
    Since KnowledgeSync can send out alert messages via e-mail (among other
    methods), one of the most important configuration steps is to define the e-mail
    account that KnowledgeSync will use for the sending of e-mail alert messages.
         Log into the KnowledgeSync Administrator (default user name is “Admin”
          and there is no password).




                              KNOWLEDGESYNC ADMINISTRATOR
         In the center column you will see a top-branch titled “Administration
          Folders.” Expand the “Software Setup” folder and single click on the branch
          called “Email Accounts.”
         Click on the “New Email Account” button at the top-left of the window. You
          are going to set up the e-mail account that KnowledgeSync will use when
          sending e-mail alerts.
         Fill in all of the fields (as detailed in the following sections), make sure the
          “Active” box is checked, and click on the “Save and Close” button.




                             Installation & Configuration                                    19
                          E-MAIL “SENDING” ACCOUNT DEFINITION



E-Mail “Sending” Account Notes
    The ability to send HTML-formatted e-mail alert messages is supported only with e-
    mail type Internet.

    E-mail type “Mapi” should be used only on stand-alone PCs (or notebooks) where
    KnowledgeSync is running. (See “Configuring KnowledgeSync Stand-Alone E-
    Mail.”)
    Important: Do not use type Mapi or type Exchange if you have applied any of the
    MS Office or MS Outlook “send mail” patches. These patches forbid 3rd party
    software applications (such as KnowledgeSync) from using Mapi or Exchange
    without prompting for a user's approval each time a mail message is to be sent.
    If you intend on using a Microsoft Exchange mail account for the KnowledgeSync
    account from which e-mail alerts will be sent, you need to be aware of the following
    configuration issues pertaining to whether you are running Exchange under SMTP, or
    are running Exchange in its own native environment.
    If you are running Exchange under SMTP:
         Stop the KnowledgeSync servers (service).
         In the set-up of the KnowledgeSync e-mail sending account, change the e-
          mail type field to INTERNET.
         Be sure that the postoffice field is blank.
         Adjust the default server names(s) to your site (such as
          server.[your_company].com.
         Adjust the SMTP From Name to be a valid e-mail account.

                            Installation & Configuration                              20
          Restart the KnowledgeSync service.
     Please note that if you have set up SMTP access to your Exchange server using SSL
     (secure socket layer) only, this will not work with KnowledgeSync and you must
     follow the steps below.

Sending Mail Outside of Your Domain

     If you are using mail type “Internet”, you may encounter a situation where you can
     send email within your domain, but are not able to send mail outside of your domain.
     This is due to your SMTP Server not having "Relay' turned on.
     In order to send SMTP-based email outside of an organization’s domain,
     KnowledgeSync requires that your SMTP server have “Relay” enabled. Once you set
     the server to allow “Relay”, you should also verify that no servers other than the
     servers within your domain can use that SMTP server for relay purposes.

Sending Mail in a Hosted Environment

     KnowledgeSync supports sending email alerts from a hosted environment. The only
     issue that you need to be aware of when setting up KnowledgeSync email alerts in an
     environment where the email is hosted buy an outside provider is that the outside
     provider often requires email authentication; see the following section to configuring
     authenticated email.

Authentication

     If you wish, you can configure the system to use authenticated email for the sending
     of email alert messages. Note that KnowledgeSync does not as yet support
     authentication for the processing of monitoring incoming email, but this will be
     added in a future release.
     Note that email authentication is enabled for Internet-based email systems only
     (Email Type must be set to "Internet").
     To configure a Google email account that uses authentication and secure sockets
     (SSL), set the Email Account Description to whatever you like (e.g., "Company
     Alerts") followed by "/AUTH/LOGIN/SSL" as in:
     Company Alerts/AUTH/LOGIN/SSL
     Set the Login Name to your gmail email address. Set your outgoing SMTP server
     name accordingly (e.g., smtp.gmail.com), and choose Port 465, which is the normal
     SMTP SSL port.
     Option two is to configure an IIS email account that uses authentication and SSL.
     Note that this approach uses the "NTLM" flag to connect to an MS Virtual SMTP
     server. (NTLM is used throughout MS systems as an integrated, single sign-on
     mechanism.)
     To configure an IIS email account that uses authentication and secure sockets (SSL),
     set the Email Account Description to whatever you like (e.g., "Company Alerts")
     followed by "/AUTH/NTLM/SSL" as in:

                              Installation & Configuration                               21
   Company Alerts/AUTH/NTLM/SSL
   Set the Login Name to your domain username. Set your outgoing SMTP server name
   accordingly (you can use the IP address), and choose Port 25, which is the normal
   SSL port.
   Option three is to configure an IIS email account that uses authentication but does not
   use SSL. Note that this approach also uses the "NTLM" flag to connect to an MS
   Virtual SMTP server as detailed above.
   To configure an IIS email account that uses authentication but not secure sockets
   (SSL), set the Email Account Description to whatever you like (e.g., "Company
   Alerts") followed by "/AUTH/NTLM" as in:
   Company Alerts/AUTH/NTLM
   Set the Login Name to your domain username. Set your outgoing SMTP server name
   accordingly (you can use the IP address), and choose Port 25, which is the normal
   SSL port.
   Option four is if you're not using any of the preceding email methods (not Google,
   not IIS). This method also provides authentication, but does not use SSL
   To configure such an email account that uses authentication but not secure sockets
   (SSL), set the Email Account Description to whatever you like (e.g., "Company
   Alerts") followed by "/AUTH/LOGIN" as in:
   Company Alerts/AUTH/LOGIN
   Set the Login Name and password as needed. Set your outgoing SMTP server name
   accordingly, and choose Port 25, which is the normal SSL port.

Running Exchange Without SMTP

   If you wish to connect KnowledgeSync to MS Exchange directly, (without using
   SMTP), you must make sure that CDO (“Collaborative Data Objects” – a component
   from Microsoft) is installed.

   Note that if you are running MS Windows 2000, CDO is not installed by default,
   even if you have already installed MS Outlook. Regardless of Operating System, you
   should first check to see if CDO is installed. To do so, follow these steps:
       1. Run the server’s “Add/Remove Programs” option and select either MS
          Office or MS Outlook and click on the “Change” button.
       2. Expand the “Office” or “Outlook” tree branch and see if CDO has a red ‘x’
          through it. If it does, you need to install it. If it doesn't have a red ‘x’ through
          it, you should be all set, although you may still choose to re-install (or repair)
          it as this will not harm your system.
   Once you have verified the installation of CDO, follow these steps:

       1. Decide which Windows domain account you will run the KnowledgeSync
          service from. It must be run from a real user account -- not the system
          account.


                             Installation & Configuration                                  22
        2. MS Exchange authenticates access to mailboxes by using your login name.
           (Use of the local system account to read or write Exchange mailboxes is not
           allowed.) If you have a user account set up already, log into that account.
           Otherwise, create a new account.
        3. Test this account by sending two e-mail messages; one to yourself and one to
           another person within your organization.
        4. Make sure that the Post Office field in the email account setup in
           KnowledgeSync has your Exchange server name in it.
        3. Make sure that the Login name is set to the mailbox alias or directory name.
           (Sometimes the mailbox might be 'Bob Jones' but the real name is ‘bjones’.)
           You must specify the real name that is being used. (The real name will never
           have spaces in it.)
        4. Specify the password for this login name.
        5. In your “Services” control panel, adjust the “Log On As” information for the
           KnowledgeSync service to run from the user account you have selected.
        6. Start the service.
    One final note: Make sure on the server that KnowledgeSync is running that MS
    Outlook is not also running at the same time. CDO allows only one user to access the
    mailbox at a time from one machine. Thus, KnowledgeSync will not be allowed to
    access the mailbox if Outlook is open on the same machine.

Configuring KnowledgeSync Stand-Alone E-Mail

    For those individuals who wish to run KnowledgeSync stand-alone on a notebook or
    other such system, there are some special steps that you can follow to configure
    KnowledgeSync to send e-mail messages. Please note that these steps require that
    you be running MS Outlook on your local system.

         Determine your MS Outlook “Profile Name”. To do so, right-click on your
          Outlook icon (on your desktop), click on the “Properties” button, and then
          click on the “Show Profiles” button. This will show your Outlook Profile
          name.
         Go into the KnowledgeSync “Email Accounts” set-up option.
         Choose an e-mail type of “MAPI”.
         Key in an account description.
         Specify your profile name in the “Profile Name” field.
           Leave the other fields blank and click on the “Active” checkbox.
    Disable the KnowledgeSync service (if running under NT/XT/2000/2003), and select
    the option to run KnowledgeSync as a “Desktop Service” .
    When KnowledgeSync goes to send an e-mail message, the message will appear in
    your Outlook “Outbox”.



                                Installation & Configuration                           23
Configuring Multiple E-Mail Accounts

    KnowledgeSync gives you the ability to configure multiple e-mail sending accounts.
    The most common reason why an organization might wish to do this is so that you
    can have different “send from” names appear on the e-mail messages that
    KnowledgeSync sends out.
    For example, if KnowledgeSync is sending e-mail alert messages to internal
    employees, you might want the sending account to read “KnowledgeSync Alerts”,
    but if KnowledgeSync is sending e-mail messages to your clients and prospects, you
    might want the sending account to appear as your company’s name.



Step #3: Test the E-Mail “Sending” Account
    Since the configuration of the KnowledgeSync e-mail sending account is key to the
    application’s ability to send e-mail alerts, it’s wise to test this configuration before
    proceeding.
    Once you have saved and closed the e-mail account(s) you set up, follow these steps
    to test it:
        1. Start the KnowledgeSync service (or servers).
        2. Back on the main KnowledgeSync Administrator window, single click on the
           “Email Accounts” branch so that the account that you just set up is displayed
           in the right-hand column of this window.
        3. (In the right-hand column) Single-click (highlight) the account you just set
           up.
        4. Go up to the top of the Administrator window and click on the “Perform
           Email Test” button. Key in your own mail address as the recipient of this test
           message. (It is suggested that you also run a second test, in which you send a
           message to someone other than yourself.)
        5. Log into the KnowledgeSync Monitor (user name “Admin” and no
           password) and watch the branch called “Email Delivery.” You should see
           your test e-mail go from a “Pending” state to a “Sent Today” state. If the e-
           mail appears in the “Errors Today” branch (or never leaves the “Pending”
           branch), there is an error in the configuration of the e-mail sending account.
        6. If the e-mail fails to be sent successfully, stop the KnowledgeSync service
           and review the e-mail sending account set-up. (Contact Vineyardsoft
           Customer Support if needed.) Once you have re-configured the e-mail
           sending account, you do not need to re-submit the e-mail test as the previous
           test is still “pending.” Simply re-start the service and see if the pending
           message gets sent.

Step #4: Define Yourself as a “Subscriber”
    The final step in the initial configuration of KnowledgeSync is to define yourself as
    an event subscriber – a person who will receive an alert message. To do so, go back
    into the KnowledgeSync Event Manager.
                               Installation & Configuration                              24
 Expand the folder called “Subscribers.”, double-click on the folder called
  “Users”, and single click on the “Sales Team” group.




                KNOWLEDGESYNC “SUBSCRIBERS” BRANCHES
 Click on the “New User” button at the top-left of the Event Manager
  window.




                          SUBSCRIBER DESCRIPTION

    For initial configuration purposes, we shall set up your record with an e-mail
    address only. (You can come back later and specify fax, page, copy, and
    webcast addresses.)
 Fill in the first six fields in the “Description” tab, and make sure the “Active”
  box is checked. Click on the “Email” tab, enter your e-mail address in the

                     Installation & Configuration                               25
           “Email Address 1” field and press tab to copy that address into the “Email
           Address 2” field. Click on the “Save and Close” button.




                         SUBSCRIBER E-MAIL ADDRESS DEFINITION


Configuration Complete: Status Check

   You have successfully completed the initial configuration of KnowledgeSync. You
   are almost ready to begin setting up events and running the KnowledgeSync
   application.


Before You Begin Designing Events

   As Business Activity Monitoring application, one of KnowledgeSync’s core
   capabilities is the ability to identify and respond to important business information.
   Based upon the steps that you have taken thus far, the only “response” that
   KnowledgeSync is configured perform is to send out e-mail alerts.
   KnowledgeSync can not only send alerts via many other methods (fax, pager,
   webcast, etc.), it can also trigger the generation and distribution of Forms and
   Reports, and it can trigger the execution of Workflow to update your business
   applications with the information you require. These added areas of functionality
   have not yet been configured.
   And, although KnowledgeSync can send out alerts, forms, and documents to a wide
   variety of people (employees, clients, business partners, etc.), we have configured
   only a single subscriber within KnowledgeSync at this point – yourself.
   You can add many more subscribers to KnowledgeSync (as well as import or use
   subscribers from other applications), but this is not yet configured either.


                            Installation & Configuration                                    26
    Vineyardsoft suggests that your initial implementation and use of KnowledgeSync
    not go beyond what has been configured thus far. Once you are able to create queries
    and events that send alerts – via e-mail – and to yourself – you should consider
    expanding your use of the application not only in the area of alerting, but also in such
    areas as:
         Triggering Application Workflow and Integration
         Monitoring & Processing Incoming E-Mail Messages
         Triggering (and/or Scheduling) Crystal Reports
         Monitoring Data Across Multiple Applications
         Monitoring Conditions in the Operating System


Implementation: How to Proceed

    There are many components of the KnowledgeSync application, and the best way to
    implement KnowledgeSync is to approach it by “module.”
    The most basic components to KnowledgeSync are queries and events; their primary
    use is to identify critical, time-sensitive conditions of data within (or between)
    business applications and to execute automated responses which include the sending
    out of alert messages. In this regard, the best way to begin implementing
    KnowledgeSync is to create a few queries and events that will trigger alert messages.


Tutorials

    In the following chapter you may follow a tutorial that is designed for use with the
    “sample” application that is shipped with the KnowledgeSync application.
    There are two additional Training Courses that are designed for use with
    KnowledgeSync. These courses are available from the following locations:
    Query Design: http://www.vineyardsoft.com/lit/ks_course1.zip
    Event Design: http://www.vineyardsoft.com/lit/ks_course2.zip


For More Help . . .

    Contact Vineyardsoft Corporation.
    The best way to contact Vineyardsoft’s Technical Support Team is via the web, at
    http://www.vineyardsoft.com/html/email_support.html.
    If you’d prefer to use phone or e-mail, you can call us at 800-850-8055 (within the
    US), or at 508-696-6495. You can also e-mail us at support@vineyardsoft.com.
    Please note that in most cases, callers into our Support department will be asked to

                             Installation & Configuration                                  27
leave a detailed voicemail of your question as this enables our support reps to
respond to the highest priority calls first.
Thank you for your interest in KnowledgeSync and we look forward to helping you
with a smooth and successful implementation of the KnowledgeSync Business
Activity Monitoring solution.




                         Installation & Configuration                             28
                                                             CHAPTER 2
                                                       Product Tutoriiall
                                                       Product Tutor a


Product Tutorial

     KnowledgeSync is a Business Activity Monitoring (BAM) application that enables
     organizations to monitor one or more application databases (and incoming e-mail
     messages) for critical, time-sensitive conditions of data.
     When these conditions occur, KnowledgeSync can send out alert messages (via e-
     mail, fax, pager, PDA, cell phone, and the web), it can generate Forms, Documents,
     and Crystal Reports, and it take can appropriate “response actions” such as updating
     one or more underlying applications with pertinent details, such as the details of what
     happened and what has to happen to address the situation.
     This tutorial is meant to provide you with a brief tour of the KnowledgeSync
     application; those options and functions that are not discussed in this chapter will be
     completely detailed in the chapters that follow.
     For the purpose of this tutorial, you will be using a sample sales application database
     that was created in Microsoft Access and is shipped as part of the KnowledgeSync
     solution.
     This tutorial will guide you through the creation of two alert events:
            An event that notifies you if there are any orders that have been shipped later
             than their “required by” date
            An event that notifies you about a specific product that has sold less than ‘x’
             dollars last week


Before You Begin

     Before you can proceed with this tutorial, you must have successfully completed all
     of the installation and configuration steps outlined in chapter one.


The Event Manager: Overview

     Log into the KnowledgeSync Event Manager Navigator module (default user name is
     “Admin” and there is no password); you will see the following window:

29                                 Product Tutorial
                   KNOWLEDGESYNC EVENT MANAGER NAVIGATOR

The Navigator module presents you with following options:
     Scheduled: View events that are currently scheduled to be submitted to run
     In Progress: View events that are currently in the process of being executed
     Exceptions: View & correct any errors that have occurred in the execution
      of KnowledgeSync events
     All Events: Add, view, & modify events (or event components). Note that
      you can right-click on the “All Events” branch to choose whether to show all
      events for a given application or only “active” events for that application.
     Job Streams: Add, view, and modify Event Job Streams. (Job Streams are
      linked events that run in a sequential manner.
     Subscribers: Add, view, and modify subscriber (alert recipient) records.
Within the “All Events” branch, there are sub-branches that list the applications
whose data KnowledgeSync is eligible to monitor and respond to. Within each of
these sub-branches is a list of the events that KnowledgeSync is configured to run.


     Expand the “All Events” branch and then the “Sample Application” sub-
      branch. (If the “Sample Application” does not exist in your version of the
      software, please skip to the following sections for details on adding the
      “Sample Application” to your KnowledgeSync database.).

        You will see a window such as the following:




                             Product Tutorial                                         30
                             THE SAMPLE APPLICATION’S EVENTS

   Each event consists of multiple components; the first of which is the “triggering
   condition” that the event is based on. In KnowledgeSync, a triggering condition is
   known as a “query” and an event can have one or more queries associated with it.
   An event not only specifies what query it will use, it also specifies such items as
   whom you wish to notify if the event is triggered, what message you wish to send to
   the event’s “subscribers”, how often you wish to check for the event’s conditions,
   and what kind of workflow response (if any) the event should execute.


If the “Sample Application” Does Not Exist

   This tutorial uses a small Microsoft Access application called “Sample Application”.
   Depending on your KnowledgeSync installation, this application may or may not be
   pre-loaded into your Event Manager.
   If it is not pre-loaded in your Event Manager, follow “Step 1” in the preceding
   chapter to create an ODBC Data Source for this application and to add that
   application to the Event Manager module.
   Note that the “Sample Application” uses a Microsoft Access database called
   “KS_Sample.mdb” and this data file is located in the KnowledgeSync Data folder.
   Note also that the “KS_Sample.mdb” database does not allocate a KnowledgeSync
   database connection license.


Create a “Record-Level” Event

   The first event that you are going to create is referred to as a “record-level” event
   because it is triggered by the existence of individual data records that meet certain
   conditions.
   In this exercise, we will create an event that is triggered if there are orders that were
   shipped later than their “required” date.
                                  Product Tutorial                                          31
    Since the first component of an event is its query, follow these steps to create this
    new query:
         Beneath the “All Events” branch, right-click on the “Sample Application”
          branch and choose New Query.
         Key in a query description of:

            “Orders; Shipped Later Than Required Date”

         Press your Tab key so that the query description will be copied into the
          display description field
         Click the “Active” checkbox.




                                      QUERY DESCRIPTION

Specify the Query’s Tables
         Click on the “Tables” tab
    All of the tables (and views) in the associated application’s database are displayed for
    you under “Available Tables”. You select which tables contain the data that this
    particular query needs to access. For this event, you will choose the tables that
    contain the data you might wish to include in an outgoing alert message.
         Double-click (select) the “Customers”, “Orders”, and “Salesreps” tables.
    For this query, you are choosing the “customers” table (because you might wish to
    include the client’s name in your alert message), the “orders” table (because this table
    contains order details such as the required date and ship date), and the “salesreps”
    table (because you might wish to include the name of the salesrep associated with
    each order).
    If you wish to include application data in an alert message, you must select the
    table(s) in which that data resides.

                                  Product Tutorial                                          32
                                       QUERY TABLES


Link the Tables
    Since we have selected more than one database table, we must tell KnowledgeSync
    how the tables are linked (or joined) together. If you do not know how tables are
    linked in a specific database, you’ll need to get a copy of the “database schema” of
    the application you’re working with.

         Click on the “Links” tab
         Click on “Add Table Link” button.




                               THE “ADD TABLE LINK” WIZARD
         Under “Table Name”, select “Orders.”
         For the “Linked to Table Name”, select “Salesreps.”
         In the “Column Name” field, select “Orders.EmployeeID.” The “Linked To
          Column Name” will automatically retrieve “Salesreps.EmployeeID” and the
          link type may be left as “left outer join”. (“Left Outer Join” is the standard
          method for linking the vast majority of database tables.)
         Click on “OK”.



                                 Product Tutorial                                          33
    You have successfully linked the “Orders” and “Salesreps” tables. Next, you need to
    bring in the “Customers” table, so you’ll create a link between the “Orders” and
    “Customers” tables.
         Click on “Add Table Link” again.
         Under “Table Name”, select “Orders.”
         For the “Linked to Table Name”, select “Customers.”
         In the “Column Name” field, select “Orders.CustomerID.” The “Linked To
          Column Name” will automatically retrieve “Customers.CustomerID” and the
          link type may be left as “left outer join”.
         Click on “OK”.
    Note that when you link tables together, the first table you select must be the query’s
    primary table, (i.e., the table whose records the query reads first).




                                THE RESULTING LINKED TABLES




Select the Query’s Columns (Fields)
    Part of designing a query is to select those fields of data that you might wish to
    include in your alert messages.
    Select (double-click on) the following fields from the window titled
    “Available Columns to Query:”
    [From the “customers” table]
           Company Name
    [From the “orders” table]
                                  Product Tutorial                                       34
           Order Date
           Order ID
           Required Date
           Shipped Date
           Total
    [From the “salesreps” table]
           First Name
           Last Name
    Note the “Unique” column. If you do not identify a unique column, a single record
    will trigger (i.e., send an alert) repeatedly each time the record meets the query’s
    criteria. If you do identify a unique column, you will have the choice as to whether
    you would like the same record to trigger alerts over and over, or whether you would
    like the record to trigger an alert only the first time the record meets the query’s
    criteria.
         Place a checkmark in the “Unique” column of the Order ID field.




                             COLUMNS SELECTED FOR THE QUERY

Select the Query’s Sorting Order
    When KnowledgeSync checks for this query’s conditions (orders shipped late),
    KnowledgeSync may find just a single matching order, or it may find two, five, ten,
    or more orders. If multiple matching records (i.e., orders) are found, KnowledgeSync
    will use the “Sorting” tab to determine the order in which retrieved records will be
    organized.
         From the list of “Available Columns for Sorting”, double-click on the
          “Required Date” field.

                                 Product Tutorial                                     35
         Choose a sorting order of “ascending” so that the orders will be listed in
          chronological sequence, starting from the orders that have the earliest
          required dates.




                                 THE QUERY’S SORTING ORDER

Specify the Filter
    The “Filters” tab lets you specify the condition(s) that records must meet in order for
    them to be retrieved by the query. KnowledgeSync filters can test for such conditions
    as:
           Sale amount greater than ‘x’
           Customers in industry ‘y’
           Opportunities forecast to close today, tomorrow, next week, or next month
           Sale amount, multiplied by its probability, greater than ‘z’
           Date “shipped” is later than the “required” date
    For this query, you’ll be using the last of these examples as your filter. Follow these
    steps:
         In the “Available Columns to Filter” list, select (double-click on) the
          “Orders.ShippedDate” field.
         Leave the value of “is or is not” as “is”.
         Click in the “Operator” field, click on the drop-down arrow that appears, and
          change “equal to” to “greater than.”

         Click in the “Compare Value” field, remove the ‘?’ and type in
          “Orders.RequiredDate” (without the quotation marks).


                                  Product Tutorial                                        36
         Since you are comparing one field against another, you need to tell
          KnowledgeSync that the value in the “compare field” is to be translated into
          its actual (or “literal”) value. Click in the “Type” field, click on the drop-
          down arrow that appears, and change “Date” to “Literal.”
         Leave the rest of the columns with their default values.
    Your resulting filter window should look like the following:




                                      THE QUERY’S FILTER

Skip the Sub-Filter Tab
    The “Sub Filters” tab is not used in the design of record-level queries; it is used only
    with an aggregate query which we will design a little later.
         Leave the “Sub Filters” tab blank.

Preview the Results of the Query
    The “Preview” tab lets you review the results of your query. When you click on this
    tab, you should see a single record such as in the following illustration:




                                  Product Tutorial                                        37
                            PREVIEW THE RESULTS OF YOUR QUERY
         Click on “Save and Close” at the top left of your window to save your query.
    If you need to go back and make changes to any of the query design information,
    simply click on the appropriate tab.

Add the Event
    Now that you have created a query, the next step is to configure the event that uses
    this query.
    KnowledgeSync separates queries and events so that a single query can be used in
    multiple events. For example, a single query that identifies “sales of greater than ‘x’
    dollars” could be used in the following three events:
           Sales of Greater than $10,000
           Sales of Greater than $25,000
           Sales of Greater than $50,000


    Follow these steps to continue with the creation of your event:

         Beneath the “All Events” branch, right-click on the “Sample Application”
          branch and choose New Event.
         Key in a description of “Orders; Shipped Late.”
         Leave the “Lookup Key” field blank
         The “Priority” field is used only if you have multiple events that are due to
          be executed at the same time; higher priority events are executed first. Select
          a priority of “5”

                                  Product Tutorial                                         38
         Check the “Active” box.
         Do not check the “Repeat” box. (You want to be notified only once for each
          order that was shipped late.)
         Check the “Keep only last checked record in Monitor” box. (This keeps the
          amount of history that KnowledgeSync retains to a minimum.)




                                   THE EVENT’S DESCRIPTION

Link the Query to the Event
    The next step is to link the query that you just designed to this event.
         Click on the “Queries” tab
         Click on the “Add Query” button.
         Select the query you were just working with.
    The grid at the bottom of this window will remain empty since the query included
    only a single filter and its “compare values” were identified on the query level. (You
    can design queries whose filter values can be identified on the event level as well.)




                                  Product Tutorial                                      39
                                     THE EVENT’S QUERY

Specify the E-Mail Alert Message Text
    One of the ways that KnowledgeSync can respond to a “triggered” event is to send
    out alert messages. (Other responses include generating Forms, Documents, and
    Crystal Reports, and updating one or more applications based on the triggered event.)
    KnowledgeSync can send out alert messages to any number of people (employees,
    clients, prospects, and business partners) via the following methods:
           E-Mail
           Fax
           Pager / PDA / Cellular Phone
           Screen Pop
           Copy / FTP
           Webcast
    For the purpose of this event, you will be skipping over the “Reports”, “Files”, and
    “Copy” tabs, and will be configuring the event to send out e-mail alerts only.
         Click on the “E-mail” tab.
         Enter (or verify) the value in the “E-mail Account to Send From” field.
          (KnowledgeSync’s e-mail sending account was defined in chapter one.)
         Leave the Email Reply Address field blank.
         Key in a message subject of:

            Order Shipped Later Than Required Date

         In the top line of the e-mail “Message Text,” key in:


                                 Product Tutorial                                          40
        The following order was shipped later than the
        customer's required date:

     Press your Enter key to leave a blank line in the message text.
       In lines three through seven of the message text, type in:

        Order ID:
        Company:
        Required Date:
        Shipped Date:
        Salesperson:

     Position the cursor to the right of the words “Order ID:” in your message
      text. Use your spacebar to leave some room after “ID:”
     Go up to the list of “Available values for use in message content” and select
      (double-click on) the field called “{OrderID}”. Notice how this field now
      appears next to “Order ID:” in your alert message.
        Position the cursor to the right of the words “Company:” in your message
        text. Use your spacebar to leave some room after this label.
     Go up to the list of “Available values for use in message content” and select
      (double-click on) the field called “{CompanyName}”. Notice how this field
      now appears next to “Company:” in your alert message.
     Repeat these steps for the remaining three fields in your alert message. When
      you get to the “Salesperson” field, put in the “{FirstName}” field, enter a
      space or two, and then put in the “{LastName}” field. You might also want
      to use your spacebar to make all the fields line up.
When finished, your E-Mail tab should look like the following window:




                         THE EVENT’S E-MAIL ALERT MESSAGE

For this event, you can skip the process of specifying the alert message text for the
other notification methods (fax, page, and webcast).
                               Product Tutorial                                       41
Event “Response Actions”
    As mentioned previously, KnowledgeSync can do much more than just send out alert
    messages when an event is triggered. KnowledgeSync can:
           Generate one or more Forms, Documents, or Crystal Reports and send those
            items along with the outgoing alert message
           Send product brochures, Order Confirmations, invoices, or other documents
            to specific recipients
           FTP specific files to pre-determined locations
           Write “triggered event data” to a file and deliver that file to a specific
            computer or recipient
           Create records in any front-office or back office application (such as creating
            a support ticket in an underlying help desk application)
           Update records in any front-office or back-office application (such as
            updating a contact’s record, or scheduling an activity for a salesrep)
           Pass triggered event data to external technologies, such as a digital display
            board, or to a synthesized voice response unit.
    For the purpose of this event, you will not be configuring any automated response
    actions, and so may move on to identifying the event’s “subscribers.”

Specify the Event’s Subscribers
    The people who receive KnowledgeSync alerts are referred to as “subscribers.” For
    any single event, KnowledgeSync can send alerts to an unlimited number of
    subscribers. These subscribers may be configured within the KnowledgeSync
    database (as you set yourself up as a subscriber in chapter one), and subscribers may
    be retrieved from any number of external application databases.
    For the current event, you will configure it to send alerts to yourself.
         Click on the “Subscribers” tab.
         Click on the “Add Subscriber” button.
         Click on the plus sign next to the “Sales Team” group.
         Click on (place a checkmark within) the box that appears to the left of your
          name.
         Click on the “Add Subscriber” button again.
    Choose (or verify) “Email” as the method by which you wish to receive notifications
    about this event (when it is triggered). The completed subscribers window will thus
    look like the following:




                                   Product Tutorial                                         42
                                  THE EVENT’S SUBSCRIBERS


Specify the Event’s Schedule
    The final step in the configuration of a KnowledgeSync event is to specify how often
    you wish KnowledgeSync to check to see if that event has been “triggered.” For this
    event, you will set KnowledgeSync to check for it everyday at 9:00 in the morning.
    Follow these steps:
         Click on the “Schedule” tab.
         Click in the “Choose a schedule to use” field and select the schedule called
          “Daily at 9:00 AM.” (KnowledgeSync is pre-configured with approximately
          a dozen schedules, and you can create additional schedules of your own.)
         Leave the rest of the fields on this tab with their default values.




                                  Product Tutorial                                    43
                                    THE EVENT’S ScHEDULE


Save & Close the Event
    Note that you do not need to access the “Triggered” tab; this tab will show you the
    details of when this event was last run and whether any records were triggered. This
    option also lets you “un-trigger” (or clear) records that had previously been triggered.
    Since your event has not run yet, this tab will appear empty.
    Click on the “Save and Close” button at the top-left of your window to save the event
    you have just created.


Create an “Aggregate” Event

    The first event you created used a query with a single filter (condition) whose
    “compare value” was specified on the query level.
    The next event will use a query with three conditions and will allow the answers to
    two of these conditions to be specified on the event level.
    In addition, this query will use a KnowledgeSync “aggregate” function. Aggregate
    functions allow KnowledgeSync to trigger an event based on the condition of a
    “group” of records. The following are all examples of aggregate events:
           More than 10 orders in the “evaluation” stage of the sales pipeline
           Fewer than 12 activities scheduled for any sales rep this week
           Support reps whose average call length last week is greater than 30 minutes
           More than $25,000 dollars lost to a specific competitor this month


                                  Product Tutorial                                        44
Create the Aggregate Query
         Beneath the “All Events” branch in the Navigator, right-click on the “Sample
          Application” branch and choose New Query.
         Key in a query description of:

            Orders; More Than 'x' Dollars from Any Region

         Press “Tab” to copy the query description to the Display Description and
          then click on the “Active” checkbox.

Specify the Query’s Tables
         Click on the “Tables” tab.
         Select (double-click on) the “Customers” and “Orders” tables.

Link the Query’s Tables
    Since this query uses two tables, you need to link them together.
         Click on the “Add Table Link” button.
         In the “Table Name” field, select “Orders.”
         In the “Linked to Table Name” field select “Customers.”
         In the “Column Name” field, select “Orders.CustomerID.”
          (“Customers.CustomerID” will automatically appear in the “Linked to
          Column Name” field.)
         Leave the “Link Type” as Left Outer Join”.
         Click on “OK” to save your link.

Select the Query’s Columns (Fields)
    Aggregate queries are different from record-level queries in that aggregate queries
    perform one of five arithmetic functions (summarize, count, average, minimum, or
    maximum) on a specific database field.
    As a result, aggregate queries do not require access to many of the detail fields that
    are commonly found in a record-level query. Since this query will be summarizing
    (totaling) the sales for specific regions over a specific time range, the first column
    you need to select is the one you want KnowledgeSync to perform the aggregate
    function on.
    In this query, this field will be the one that contains the sales total for each order.
         Select Orders.Total as the first column in your query.
    Since this query needs to total the sales for each region, we need to tell
    KnowledgeSync that it has to total (or “summarize”) the values in each matching
    order’s “total” field.
                                   Product Tutorial                                           45
         Click in the “Column Type” field for the “Orders.Total” field.

         Click on the drop-down list and select Summarize.
    And since the goal of this query is to total the orders per region, you need to tell
    KnowledgeSync that it will “group” (or total) the accumulated order totals by region.

         Select Customers.Region as the second column in your query. The “Column
          Type” for this field remains as “Normal”.

    Note that when designing aggregate queries, the first column selected in a query
    should be the field that you are performing the aggregate on, and the second (and all
    ensuing) columns represent how that total is to be grouped.

Sorting Order
    You may either leave this tab blank, or (if you wish for the query to list matching
    regions in alphabetic order of region name), you may select the “Region” field and
    choose a sorting order of “ascending.”

Specify the Filter
    Similar to the first query, this query will use filters to restrict which records are
    eligible to be retrieved. The first filter you will configure will exclude any orders that
    are not associated with a specific region.
    Follow these steps:
         Select Customers.Region from the list of “Available Columns to Filter.”
         Change the value of “is or is not” to “is not”.
         Choose an operator of “null”. (This will exclude any orders for customers
          that have a blank value in their “region” field.)
         Remove the “?” from the Compare Value field. Since this filter is checking
          for a “null” value, there is no other compare value.
         Leave the rest of the fields with their default values.
    The next two filters will enable this query to retrieve order records that fall within a
    specific date range. However, these filters will be configured so that their compare
    values will be filled in on the event level (as opposed to on the query level).
    This will enable this one query to be used in many different events, each event
    having its own unique date range that it is selecting records for. Follow these steps
    for the second filter:
         Select Orders.OrderDate from the list of “Available Columns to Filter.”
         Leave the value of “is or is not” as “is”.
         Choose an operator of “greater than or equal to”.
         Leave the Compare Value as a “?”. The question mark is what will allow the
          value of this filter to be specified on the event level.


                                   Product Tutorial                                         46
         Use your “Tab” key to move beyond the “Type” and “And/Or” fields. You
          may leave them with their default values.
         In the “Optional Prompt” field (you may need to scroll the Filter window to
          the right), key in the words “Order Date Range Begins:”.

    And then follow these steps for the third filter:

         Select Orders.OrderDate a second time from the list of “Available
          Columns to Filter.”
         Leave the value of “is or is not” as “is”.
         Choose an operator of “less than or equal to”.
         Leave the Compare Value as a “?”. The question mark is what will allow the
          value of this filter to be specified on the event level.
         Leave the “Type” and “And/Or” fields with their default values.
         Scroll the Filter listing window to the right, and in the Optional Prompt field,
          key in the words “Order Date Range Ends:”.
    Notice how the “order date” field was chosen twice (as two filters) so that an event
    can retrieve only those orders that fall within a certain date range.
    Note also that this query uses two filters on the “order date” field as opposed to using
    one filter and the “between” operator. This is because in most cases, the use of two
    filters has been proven to be more efficient (require less system resources) than a
    single filter using the “between” operator.

Specify the Sub-Filter
    Only aggregate events use sub-filters. A sub-filter is what allows you to perform a
    test against the aggregate value. Using the current query as an example, a sub-filter is
    what allows you to retrieve only those regions whose total sales are greater than ‘x’
    dollars.
    To configure the aggregate sub-filter for this query, follow these steps:
         Select SUM(Orders.Total) from the list of “Available Columns to Filter.”
         Leave the value of “is or is not” as “is”.
         Choose an operator of “greater than”.
         Leave the Compare Value as a “?”. The question mark is what will allow the
          value of this filter to be specified on the event level.
         Leave the “Type” and “And/Or” fields with their default values.
         Scroll the Filter listing window to the right, and in the Optional Prompt field,
          key in the words “Regional Total is Greater Than:”.




                                   Product Tutorial                                        47
Preview the Results of the Query
    Click on the “Preview” tab to review the results of your query. Since this query
    includes filters whose “compare value” are not defined within the query, you will be
    prompted to specify the corresponding values.
    For the date range prompts, specify a beginning date of “01/01/1990” (do not include
    the quotation marks), and an ending date of the current date (you can also use the
    date substitution variable “%Current Date%” from the list shown).
    For the regional total threshold, specify “1000” (without the quotations). Your results
    should yield approximately 16 records.

Save & Close the Query
    Click on the “Save and Close” button at the top-left of your window to save the query
    you have just created.


Add the Event
    Back on the main Navigator window, go to the “All Events” branch, right-click on
    the “Sample Application” branch and choose New Event.
         Key in a description of:

            Orders; More Than $100,000 Closed Per Region Last Month

         Leave the “Lookup Key” field blank.
         Select a priority of “5”.
         Place a checkmark in the “Active” box.
         Since you want to be notified only once when this event is triggered, do not
          place a check in the “Repeat” box.
         Do place a checkmark in the “Keep only last checked record in Monitor”
          option.

Select the Event’s Query
         Click on the “Queries” tab.
         Click on the “Add Query” button.
         Select the query you were just working with.
         The grid at the bottom of this window will prompt you to specify a value for
          the query’s filters that have a ‘?’ in their compare values. Fill in the answers
          to these questions as follows:
               Order Date Range Begins: Click in the “Answer” field, and from the
                list of “Available Substitution Variables” select
                {%Last Month Start Date%}.

                                  Product Tutorial                                      48
               Order Date Range Ends: Click in the “Answer” field, and from the list
                of “Available Substitution Variables” select
                {%Last Month End Date%}
               Regional Total is Greater Than: Click in the “Answer” field and type in
                100000.

    Note that an event must have valid values specified for any event trigger parameters.
    Since KnowledgeSync is not an interactive application (it runs as a service), it will
    not prompt a user to specify an event’s parameters when the event is run. Any event
    with blank trigger parameters will fail to run successfully.

Specify the E-Mail Message Text
         Click on the “E-mail” tab.
         Enter (or verify) the value in the “E-mail Account to Send From” field.
         Leave the E-Mail Reply Address field blank.
         Key in a message subject of:

            Orders; More Than $100,000 Closed Per Region Last Month

         For the first line of your e-mail message text, type in the following:

            The following regions yielded more than $100,000 in sales last
            month:

         Press your Enter key to insert a blank line of text.
         In line three of your alert message, type in “Region:”
         In line four of your alert message, type in “Sales Total:”
         Position the cursor to the right of the word “Region:” in your message text.
          Press your spacebar twice to leave some room after it.
         Go up to the list of “Available values for use in message content” and select
          (double-click on) the field called “{Region}”.
         Position the cursor to the right of the words “Sales Total:” in your message
          text. Press your spacebar twice to leave some room after it.
         Go up to the list of “Available values for use in message content” and select
          (double-click on) the field called “{Total}”.
         Position your cursor after the word “{Total}” and press your Enter key to
          insert a final blank line at the end of your message.
    When a KnowledgeSync event is triggered by multiple matching records (e.g., more
    than one region with closed sales over $100,000), you have a choice as to how many
    alert messages KnowledgeSync will send:
    Option #1: It will send one alert message for each matching record
    Option #2: It will send one alert message for ALL matching records (i.e., the
    message will “repeat” the details of each matching record)

                                 Product Tutorial                                        49
    Option #3: It will send one alert message per “group” of matching records (e.g., if
    different regions are owned by different managers, you could have KnowledgeSync
    send one message per manager – each message containing the regions owned by that
    manager).
    You will configure this event to send a single e-mail message that contains the details
    of all of the regions that exceeded $100,000 in sales. (You do not want to receive one
    e-mail message for each region that exceeded $100,000 in sales.)
    This is referred to as “repeat-enabling” an event.
    To repeat enable this event, you need to tell KnowledgeSync which part of the alert
    message should be “repeated” for each matching record. For this particular event,
    you wish to “repeat” the last two lines of your alert message (the lines that contain
    the region name and sales total) for each region that meets the event’s criteria.
         Click in the second line of your alert message text (the blank line).
         Go up to the list of “Available values for use in message content,” scroll to
          the very end of the list, and select (double-click on) the field called
          “{BEGIN*REPEAT}”.
         Click in the last line of your message text (the blank line after the “Sales
          Total” line).
         Go up to the list of “Available values for use in message content,” scroll to
          the very end of the list, and select (double-click on) the field called
          “{END*REPEAT}”.
    You have thus told KnowledgeSync what part of the message to repeat, and so are
    finished designing the outgoing alert message.



Specify the Event’s Subscribers
         Click on the “Subscribers” tab.
         Click on the “Add Subscriber” button.
         Click on the plus sign next to “Sales Team”.
         Click on the box that appears to the left of your name.
         Click on “Add Subscriber.”
         Click on the “Email” box to the right of your name to place a checkmark in
          it.

Specify the Event’s Schedule
         Click on the “Schedule” tab.
         Choose the schedule called “The 1st of the Month; 9:00 AM.”




                                  Product Tutorial                                        50
Save & Close the Event
    Click on the “Save and Close” button at the top-left of your window to save the event
    you have just created.


Verify KnowledgeSync Server Status

    Now that you’ve got two fully configured KnowledgeSync events, you’re ready to
    check those two events and see if they get triggered.
    In order for KnowledgeSync to check events, the KnowledgeSync service (or
    Desktop Service) must be running.
    If you’re running KnowledgeSync under Windows NT, XP, 2000, 2003, or Vista, the
    application’s servers will run as a service; if this service is not currently, running, go
    to your system’s “Services” option and start it.
    You can check to make sure that the KnowledgeSync servers are running by logging
    into the KnowledgeSync Monitor (default user “Admin”, no password), clicking on
    the “Activity” folder, and then on the “Server Status” folder.
    (At minimum, the first four servers should be running.)


Submit Your Two Events

    Since your two events are scheduled to run at different times (one at 9:00 AM daily,
    and one at 9:00 AM on the first day of a month), you might wish to submit these two
    events to run “right now” so that you can track their progress.
    To submit your two events to run “right now”, follow these steps:
         Beneath the “All Events” branch, expand the “Sample Application” branch
          so that you can view the events within it. Locate the first event you created.
         Right-click on this event and choose “Schedule This Event Now”.
         You will be asked to confirm the submission of your selected event. Click on
          “Yes.”
         The event will be scheduled for immediate execution, and may be tracked in
          the KnowledgeSync Monitor.
         Repeat these steps for your second event.


Track Events in the KnowledgeSync Monitor

    The KnowledgeSync Monitor is an excellent place from which to track the status of
    your events.
    Follow these steps to track the progress of your events:

                                   Product Tutorial                                        51
        Double-click on the “Scheduler” folder and then single-click on the “Next
         Run Date/Times” branch. You will see the events that are due to be
         submitted.
        Once an event’s submission time arrives, proceed to the “Application
         Events” folder.
        An event will go from a “pending” state to a “checked” state, and then (if the
         event’s conditions are met), to a “triggered” state. If there is an error in an
         event’s configuration, the event will appear in the “Errors Today” branch,
         and will also remain in the “Pending” branch.
        Depending on the number of records that trigger an event, you will see one or
         more “triggered event” records. To view the text of alert messages associated
         with the event, point your cursor at the columns that contain the e-mail, fax,
         pager, or webcast text.

           KnowledgeSync will automatically expand the contents of these fields to
           display the full contents of the outgoing alert message.
        To see details about the delivery of alert messages for an event, highlight
         (click on) a specific triggered record and click on the “Deliverables” button.
        Note that the “Deliverables” button will show you whom was notified about
         the event, how they were notified, and when.
        When you are satisfied that your events have executed successfully, you may
         shutdown the KnowledgeSync service.


A “Getting Started” Hint

   After you have triggered some events, you might wish to “clear” the KnowledgeSync
   monitor of its history and “start again.” To do so, follow these steps:
        Shut down the KnowledgeSync service.
        Go to the KnowledgeSync Administrator.
        Go to the “File” menu and select “Database Tools” and then “Remove
         Completed Items”.
        Specify that you wish to remove all items dated before a certain date. If you
         wish to remove all history, key in any date in the future.


You’re On Your Way!

   Congratulations on completing the KnowledgeSync tutorial. There are lots of other
   functions that you can try in KnowledgeSync, including alternate alert methods
   (page, fax, file copy, and webcasting), triggering application updates and/or
   workflow, report distribution (via Crystal Reports), processing incoming e-mail
   messages, and cross-application alerts (events that are based on conditions that exist
   in multiple business applications).


                                 Product Tutorial                                       52
If you have any questions while using KnowledgeSync, contact our technical support
department via the web (http://www.vineyardsoft.com/html/email_support.html), via
e-mail at support@vineyardsoft.com, or via phone at 800-850-8055 (within the US)
508-696-6495 (outside the US).
And thank you for using KnowledgeSync!




                            Product Tutorial                                    53
                                                         CHAPTER 3
                                                      Admiiniistratiion
                                                      Adm n strat on

KnowledgeSync Administration
   The KnowledgeSync Administration Module lets you perform seven functions:
          View the status of application servers
          View the names of all users logged onto KnowledgeSync modules
          View (and take corrective actions for) any errors that were encountered when
           the application attempted to either execute an event, or send notifications
           about an event
          Configure hardware settings for faxing, paging, and printing
          Configure software settings for e-mail, faxing, paging, and holiday
           definitions
          Specify user authorizations for access to different KnowledgeSync modules
          Maintain and optimize the KnowledgeSync database


The Administrator: Logging In
   Log into the KnowledgeSync Administrator (default user name is “Admin” and no
   password); you will see “Administration Folders” with a branch titled “Activity.”




                            KNOWLEDGESYNC ADMINISTRATOR
                                   Administration                                      54
Calling the KnowledgeSync Administrator
    If you wish to “call” the KnowledgeSync Administration module from another
    application and/or program and do not wish to be presented with the Administrator
    logon window, you may create a shortcut to the Administrator that eliminates this
    step.
    Use the following Administrator command string:
    "C:\Program Files\Vineyardsoft\KnowledgeSync 2000\Bin\KS_Admin.exe"
    And at the end of the preceding command, add a single blank space followed by the
    “@” sign and then the username, semicolon, and password of the KnowledgeSync
    account that you wish to login under.
    For example, if you wished to create a command that enables a user to log into the
    Administration module under the username “Hallman” and password “fox”, your
    command string would look like the following:
    "C:\Program Files\Vineyardsoft\KnowledgeSync 2000\Bin\KS_Admin.exe"
    @Hallman;fox
    Note that this syntax works for any of the KnowledgeSync modules.

How to Navigate
    To select a folder, do either of the following:
         In the middle column, double-click on the folder you wish to work in.
         In the left-most column, single-click on the button (e.g., "Software Setup")
          whose folder you wish to work in.
    To select a specific option, select a folder first, and then single-click on the item you
    wish to select. (E.g., select the "Hardware Setup" folder, and then the "Fax Serial
    Ports" option.)
    Note that once you select a specific option, the right-most window changes to display
    the records associated with that option.
    To add a new record under a specific option (e.g., to add a new fax communications
    port), click on the "New" button that appears under the KnowledgeSync
    Administrator menu bar.
    (The "New" button will read "New [xxx]" where "xxx" refers to the type of record
    you are adding.)
    As a shortcut, you may also select "New" under the KnowledgeSync Administrator
    File menu and select the object you wish to add.
    To view or update an existing record under a specific option (e.g., to review the set-
    up of an existing fax communications port), double-click on the record in the right-
    most window.
    To delete a record, single-click on the record in the right-most window and click on
    the "Delete" button that appears under the KnowledgeSync Administrator menu bar.
    (You may also delete a record after having selected it for viewing or updating.)
                                   Administration                                          55
Activity Folder

    The KnowledgeSync Activity folder tells you about the current processing and user
    activity occurring within the application.

Server Status
    This will display the current status of all the servers used by the KnowledgeSync
    application. The possible status states are as follows:
           Shutdown: The server is not running at this time. Among the possible
            reasons for this are:
               The KnowledgeSync service could be shutdown. (On NT/2000/XP/2003,
                this is done via the control panel by selecting “Services”, clicking on the
                “KnowledgeSync” service and clicking on “Stop”.)
               The server is flagged not to run. This is done by double-clicking on the
                specific server and un-checking the checkbox that enables the specific
                server to run.

                You can control which servers will be allowed to run. If you know that
                your site will not be performing certain types of notifications (e.g.,
                faxing), you can disable the corresponding server to conserve system
                resources.

                By default, KnowledgeSync is shipped with all servers enabled except
                for the Paging, Faxing, Reporting, Copying, Webcasting & Action
                servers.
           Idle: The server is running and in memory but is not processing any data.
            The server is in this state if there is no data to process.
           Processing: The server has been woken up and is processing.
           Linking: (For the application event server only) If KnowledgeSync is
            retrieving alert recipient (aka “subscriber”) data from an external database,
            the “linking” status will appear when KnowledgeSync needs to retrieve this
            data.
           Startup: The server is in initialization and startup mode.




                                  Administration                                           56
                        KNOWLEDGESYNC SERVER STATUS WINDOW

KnowledgeSync Server Descriptions

    KnowledgeSync uses the following server manager and servers:
          KnowledgeSync Server Manager: This server initiates all of the other
           servers. Note that this is a service.
          Scheduler: This server keeps track of when events are scheduled to be
           executed. When an event is due for execution, this server sends the
           corresponding task to the appropriate event server (e.g., the application event
           server).
          Application Event: This server executes application events.
          Report: This server generates Crystal reports.
          E-Mail: This server delivers e-mail messages.
          Fax: This server delivers fax messages.
          Page: This server delivers pager messages.
          Webcast: This server delivers webcast (dashboard alert) messages.
          Copy: This server copies and ftp’s files and reports.
          Action: This server executes event “response actions.”

KnowledgeSync Server Notes

    Please note the following about the KnowledgeSync servers:



                                 Administration                                         57
            If any of the first three servers are shutdown or paused, KnowledgeSync will
             not be able to check for events and/or send notifications or execute other
             automated actions in response to triggered events.
            If any of the notification servers (i.e., e-mail, fax, pager, copy, or webcast)
             are shutdown or paused, KnowledgeSync will not be able to send
             notifications via that particular delivery means.
            When data is being processed by a server, the server will show a status of
             "processing." When there is no data to be processed, the server will show a
             status of "idle."
            For each server, you are shown its status, the error message (if any) that
             prevents the server from running, the name of the computer and user account
             from which the server is running, the server computer’s operating system and
             version, and the date and time the server was last started.
            Under the “Unlimited Connection” license only, the Application Event server
             is multi-threaded.

Enabling / Disabling a Server

     You may either enable a server to run, or disable a server from running.
     To enable a server, select (double-click on) the server record from the Server Status
     window and place a check in the field titled "Allow Server to Process."
     To disable a server, select (double-click on) the server record from the Server Status
     window and make sure that there is no checkmark in the field titled "Allow Server to
     Process."

Starting / Stopping Servers

     To start a server that is shutdown, the first thing that you need to do is to put a
     checkmark in the corresponding server’s "Allow Server to Process" field.
     If the Service is running, you may pause (or stop) the Service and subsequently
     restart the Service. This will start the server that was previously shutdown.
     If the Service is not running, you simply have to start the Service.
     To stop a server that is currently running, simply remove the checkmark in the
     corresponding server’s "Allow Server to Process" field. (The server will show a
     status of "paused")
     To start a server that is paused, simply place a checkmark in the corresponding
     server’s "Allow Server to Process" field.
     To stop all KnowledgeSync servers, stop the KnowledgeSync Service.

KnowledgeSync Server Login Information

     By default, all KnowledgeSync servers log into the KnowledgeSync database using
     user “Admin” with a blank password. However, if you want to use Microsoft Access
     security to secure the database from un-authorized access, then you must tell the

                                     Administration                                            58
    KnowledgeSync servers what username and password to use when accessing the
    KnowledgeSync database.
    To access the username and password for the KnowledgeSync service, follow these
    steps:
         Highlight (single-click on) the “Server Status” branch.
         Click on the “Server Login Information” button at the top of the
          Administration window.
         Fill in the username and password for the KnowledgeSync servers.
         Click on OK.
    It is suggested that you change this setting only if you are using Microsoft Access
    security or want the servers to use a username other than “Admin.”
    Please not that the server will not start up properly if you are using Microsoft Access
    security and you leave these fields blank.
    Also note that you must perform the KnowledgeSync server login username
    administration on the computer where the KnowledgeSync application have been
    installed. When saved, this information is written to the local system’s registry.

Current User Logins
    The Current User Logins option tells you who is currently logged into the
    KnowledgeSync application. By selecting an individual user, you can display the
    following information:
           The KnowledgeSync module the user is logged into. This will display either
            the “Administrator”, “Event Monitor”, or “Event Manager.”
           The user’s computer and user names
           The user’s operating system and platform
           The date and time that the user last logged into the application
           The date and time of the user’s last activity




                                   Administration                                         59
Corrective Actions

   When KnowledgeSync executes a specific function (whether checking for an event,
   sending an alert message, executing a response action, et cetera), it is possible that an
   error in configuration or a system-related error may prevent the KnowledgeSync
   function from executing successfully.
   If such an error in execution does occur, KnowledgeSync will not only track what the
   error was that occurred, KnowledgeSync will also allow you to take a “corrective
   action” to address the error. (The type of corrective action that you can take will vary,
   based upon the type of error that occurred.)
   Note also that “pending” tasks (such as pending events, pending emails, pending
   reports, etc.) will also appear within these options and you may use the “corrective
   actions” options to remove or “complete” those tasks that are simply in a “pending”
   state.
   KnowledgeSync lets you take corrective actions in response to the following error
   conditions:
          Application event errors (Errors when checking for triggered events)
          E-Mail delivery errors
          Fax delivery errors
          File copy (ftp) delivery errors
          Pager delivery errors
          Webcast delivery errors
          Report generation errors
          Action errors
   When an error occurs, KnowledgeSync will automatically place the erroring record
   in an “error” state as well as in a “pending” state (both of which you can see in the
   KnowledgeSync Monitor). The error will also be listed in the KnowledgeSync
   Administration module, within the corresponding “Errors” sub-branch under the
   “Corrective Actions” branch.
   For every error record that appears in a corrective action branch, you will be shown:
          Error: The internal application database error number
          Error Message: The error message text
          Application: The name of the application to which the erroring record
           belongs
          Description: The description of the record that errored
   (You will also see additional error data that is specific to the record that errored, such
   as an erroring mail message’s recipient’s address, subject and message text.)
   KnowledgeSync will attempt to re-submit any erroring record every minute until the
   record is: 1) successfully processed, 2) manually deleted, or, 3) marked as
   “complete” by an authorized KnowledgeSync administrator.

                                   Administration                                          60
Application Event Errors
    Application event errors are the most common type of error that occurs; these are
    usually caused by an application event that has a configuration error, such as an
    invalid query, but can also be caused by system problems, such as KnowledgeSync’s
    inability to access a database on a server that is currently down.
    Application event errors that are due to a configuration error within KnowledgeSync
    may be addressed simply by correcting the associated error (such as re-configuring
    the related query). Once this condition has been addressed, the erroring event will
    execute successfully the next time KnowledgeSync attempts to re-submit the erroring
    record.

Message Delivery Errors
    “Delivery” errors (such as e-mail, fax, pager, copy, and webcast errors), often result
    from one of three causes:
           KnowledgeSync is not configured properly to send out the corresponding
            alert (e.g., the e-mail “sending” account is incorrectly configured)
           There is a system problem (such as your e-mail server being down) that
            prevents KnowledgeSync from sending a message
           The recipient’s address contains invalid information (such as an invalid pager
            PIN number)
    Like application event errors, KnowledgeSync will attempt to re-send the erroring
    delivery record every minute until the record is successfully delivered, manually
    deleted, or marked as complete by an authorized KnowledgeSync administrator.
    Unlike application event errors, however, the “Corrective Actions” option also allows
    you to update (correct) delivery address information for a delivery error that
    occurred. For example, if a pager alert has an invalid PIN, or if an e-mail address has
    an invalid character within it, KnowledgeSync will allow you to use the
    corresponding corrective actions option to modify the recipient’s delivery address,
    thus enabling KnowledgeSync to successfully re-deliver the message.

Report Generation Errors
    Report generation errors are similar to application event errors in that they are most
    often caused by an invalid report design, or by a system problem (such as a database
    server being unavailable).
    If you correct the problem that is causing the report generation error (such as
    correcting the report design), KnowledgeSync will be able to successfully execute the
    report the next time KnowledgeSync submits it.
    Note that if you have an event that generates a report, it is possible to have many
    notifications (e.g., e-mail messages, faxes, etc.) that are dependent on the successful
    generation of that report. If the report generation is unsuccessful, the resulting
    notification records will not appear in either a "pending" or "error" state since the
    report itself was never completed.

                                   Administration                                         61
Response Action Errors
    Action errors are due to problems that KnowledgeSync encountered when trying to
    submit a response action such as executing a workflow or integration process via a
    Visual Basic script, SQL statement, stored procedure, an executable program, or
    other type of API. (One example of such an error would be an incorrect program file
    name or directory name referenced in an API process.)
    Like all other types of errors, action errors will be re-submitted every minute until
    they are successfully completed, manually deleted, or marked as complete by an
    authorized KnowledgeSync administrator. Please note that like application events,
    you can correct the associated error (such as modifying the related VB script) and
    once this condition has been addressed, the erroring action will execute successfully
    the next time KnowledgeSync attempts to re-submit the erroring record..

Taking a Corrective Action
    The first step to taking a corrective action is to click on the corresponding corrective
    action option (such as E-Mail Delivery Errors” and reviewing the window on the
    right side of the Administrator module to see if there are any current error records.
    If an error record does exist, select (double-click on) the record. You will see a
    window like the following:




                       KNOWLEDGESYNC CORRECTIVE ACTION WINDOW

    You have three options from a corrective actions window:
        1. Complete the record manually. Although the record did error, you can flag
           the record as “complete” and it will be retained in KnowledgeSync’s history
           as successfully completed.
        2. Delete the record. Click on the “Delete” button. This will remove the record
           from the KnowledgeSync database.

                                   Administration                                         62
        3. Correct the record. Not all records may be corrected; this depends on the
           type of error that occurred. Invalid pager PIN numbers are an example of
           errors that can be corrected from this option.
    Please note that e-mail messages that are sent to “undeliverable” addresses are not
    recorded within KnowledgeSync as errors. (You may wish to use KnowledgeSync’s
    E-Mail Response System to monitor for undeliverable messages.)


Hardware Set-Up

    There are two components to configuring your hardware for use with
    KnowledgeSync:
           Defining Fax Ports
           Defining Pager Ports
    If you will be using KnowledgeSync for sending out messages via modem-driven fax
    or pager, you must take these options; if you will not be sending modem-driven
    messages via either of these two methods, you may skip this option.
    Note that many faxing and paging utilities allow messages to be sent to a fax number
    of pager number through an e-mail interface (i.e., you can send a message to a pager
    by sending an e-mail message to the pager’s phone number.) If you will be using this
    method to send fax or pager messages, you do not need to configure modem ports for
    either of these methods.

Configuring KnowledgeSync for Faxing
    KnowledgeSync supports any class 1 or class 2 modems installed on (or
    reachable from) the KnowledgeSync server.
    KnowledgeSync offers two faxing interfaces; an embedded faxing technology
    that supports only plain-text (ascii) formatted documents, and Microsoft Fax,
    which supports the faxing of documents in any format.
    For details on the Microsoft Fax interface, please contact Vineyardsoft’s
    Technical Support department or visit Vineyardsoft’s on-line knowledgebase
    (located in the Support page of www.vineyardsoft.com) and download details on
    Microsoft Fax.
    To send out messages via a modem-driven fax, KnowledgeSync requires the use of a
    modem that is reachable from the server on which KnowledgeSync is installed. This
    modem may be shared by other applications and devices.
    To configure KnowledgeSync for faxing, follow these steps:
         Click on the “Fax Serial Ports” branch within the “Hardware Setup” branch.
         Up at the top-left of the Administrator window, click on the button called
          “New Fax Communication Port.” The following window will appear:




                                   Administration                                      63
                            FAX PORT CONFIGURATION WINDOW

         COM Port Number: Select the port to use for sending faxes.
         COM Port Description. Key in a description of this port.
         Use Port for Faxing. Specify whether this port is currently available for
          faxing. (You can configure a COM port for availability without enabling it
          for immediate use.)
         Pulse Dialing. Whether you use pulse dialing (check this box if you do).
         Dial Out Prefix. The prefix (if any) that you use to reach an outside line
          (e.g., "9")
         Modem Initialization String. The command that you use to initialize this
          modem (e.g., "at").
         Modem Dial String. The command that you use to precede your dial-out
          number (e.g., "atdt").
    Note that if you configure multiple fax communications ports, KnowledgeSync will
    automatically scan the list of ports for the first available modem when a fax message
    needs to be sent.

Configuring KnowledgeSync for Paging
    KnowledgeSync supports any class 1 or class 2 modems installed on (or
    reachable from) the KnowledgeSync server. KnowledgeSync also supports SMS
    (short message syntax) paging.
    To send out messages via modem-driven pager, KnowledgeSync requires the use of a
    modem that is reachable from the server on which KnowledgeSync is installed. This
    modem may be shared by other applications and devices.
    To configure KnowledgeSync for paging, follow these steps:
         Click on the “Pager Serial Ports” branch within the “Hardware Setup”
          branch.

                                  Administration                                       64
        Up at the top-left of the Administrator window, click on the button called
         “New Page Communication Port.” The following window will appear:




                          PAGER PORT CONFIGURATION WINDOW

        COM Port Number: Select the port to use for sending pages.
        COM Port Description. Key in a description of this port.
        Use Port for Paging. Specify whether this port is currently available for
         paging. (You can configure a COM port for availability without enabling it
         for immediate use.)
        Pulse Dialing. Whether you use pulse dialing (check this box if you do).
        Dial Out Prefix. The prefix (if any) that you use to reach an outside line
         (e.g., "9")
        Modem Initialization String. The command that you use to initialize this
         modem (e.g., "at").
        Modem Dial String. The command that you use to precede your dial-out
         number (e.g., "atdt").
        Paging Diagnostic File. This file is used to store diagnostic data from pages
         that are sent and can be used to help track down the problems of any pages
         that are unsuccessfully executed. Leave this field blank unless otherwise
         instructed by Vineyardsoft
   Note that if you configure multiple pager communications ports, KnowledgeSync
   will automatically scan the list of ports for the first available modem when a pager
   message needs to be sent.


Software Set-Up

   There are seven components to the configuration of KnowledgeSync before you can
   begin defining events:

                                 Administration                                           65
           E-Mail Sending Account Definition
           E-Mail Response System Configuration*
           Fax Sending Account Definition
           Fax Cover Page Design
           Holiday Calendar Definition
           Paging Services Definition
           Webcast Location Definition**
    * The configuration of the E-Mail Response System (ERS) is located within the
    option for “E-Mail Account” set-up. As the E-Mail Response System is a separate
    KnowledgeSync module, its configuration and use are detailed in the chapter titled
    “E-Mail Response System.”
    ** Please note that the configuration of the KnowledgeSync Webcasting module is
    detailed in the chapter on the set-up and use of the webcast module and thus is not
    covered in this chapter.

E-Mail “Sending” Account
    If you are running version 7.4 or greater of KnowledgeSync and you are using
    the embedded SMTP email engine that ships with KnowledgeSync, you can skip
    over the entire Email Configuration process because your email sending account
    is pre-configured upon installation.
    Since KnowledgeSync sends out alert messages via e-mail (among other methods),
    one of the most important configuration steps is to define the e-mail account that will
    be used for the sending of e-mail alert messages.
    Expand the “Software Setup” folder and single click on the branch called “Email
    Accounts.”
    Click on the “New Email Account” button at the top-left of the window. This is
    where you set up the e-mail account (or accounts) that KnowledgeSync will use when
    sending e-mail alerts.
    (If you wish to modify the details of an existing e-mail account, simply double-click
    on the account on the right side of your window.)
    Fill in the fields as follows:
         E-Mail Type: Select from “Exchange”, “Mapi”, “Vim”, “Internet”, or
          “Unknown”. Please note that the ability to send HTML-formatted e-mail
          alert messages is supported only with e-mail type Internet.

            Also note that type “Mapi” should be used only on stand-alone PCs (or
            notebooks) where KnowledgeSync is running.
            Important: Do not use type Mapi or type Exchange if you have applied any
            of the MS Office or MS Outlook “sendmail” patches. These patches forbid
            3rd party software applications (such as KnowledgeSync) from using Mapi
            or Exchange without prompting for a user's approval each time a mail
            message is to be sent.
                                     Administration                                       66
 E-Mail Account Description: Key in a description of the account that will
  be used for sending e-mail notifications.
 Login Name: Identify the login user name for this account. Use the profile
  name for Mapi, and use the mailbox alias name for Exchange.
 Password: Key in the password of this user.
 Postoffice: This field is for use with only Exchange, Lotus Notes e-mail and
  Vim-compliant e-mail systems.

   For Notes and Vim, you need to fill this in only if the postoffice you will be
   using is different from the default postoffice you defined when you set up the
   Notes or Vim client. For Exchange, this value is the exchange server name.
 Active: Whether this account is currently available for sending e-mail (check
  this field if this account is “active”).
 Outgoing mail SMTP Server Name: This field is for use with Internet-
  compliant e-mail systems (such as SMTP). Key in the name of the server that
  will be used when sending e-mail notifications.
 SMTP From Name: This field is for use with Internet-compliant e-mail
  systems. Key in the name that will appear as the "sender" of the e-mail
  message from KnowledgeSync. This value is required when using type
  INTERNET and it must be a valid e-mail address with a valid domain name.
  For example, a valid from name will look like the following:
   Technical Support Department <support@mydomain.com>
 SMTP Port: (For special cases only) The port that will be used to
  accommodate specific firewall security software. Leave this field blank
  unless otherwise instructed by Vineyardsoft.
 Incoming mail POP Server Name: This field is for use with Internet-
  compliant e-mail systems. Key in the name of the server that will be used
  when sending e-mail messages.
 POP Port: (For special cases only) The port that will be used to
  accommodate specific firewall security software. Leave this field blank
  unless otherwise instructed by Vineyardsoft.




                         Administration                                        67
                          E-MAIL “SENDING” ACCOUNT DEFINITION

E-Mail Set-Up: Integration With GroupWise

    KnowledgeSync supports connectivity with GroupWise via SMTP. When
    configuring the "Email Account" record, please be sure to specify the email type of
    "INTERNET". Also, you must have both SMTP and POP3 enabled in the
    GroupWise email system.

E-Mail Set-Up: Microsoft Exchange Notes

    You will gain ease-of-use and functionality if your Exchange server is configured for
    SMTP.
    Note that KnowledgeSync does support authenticated email; see following section
    for details.
    Step #1: Install Microsoft CDO (Collaboration Data Objects) if it’s not already
    installed. To check to see if CDO is installed, follow these steps:
         Go to your Control Panel
         Select “Add/Remove Programs”
         Look for (single click on) Microsoft Office or Microsoft Outlook
         Click on “Add or Remove Features”
         Expand the branch for Microsoft Outlook
         Look for a branch called “Collaboration Data Objects”. If a red ‘x’ appears
          next to it, CDO is not installed.

                                  Administration                                        68
    Please note that on Windows 2000, even if Microsoft Outlook is already installed,
    CDO by default is not installed. You can obtain CDO from the Microsoft Office
    Professional CD-1.
    Step #2: Verify that the KnowledgeSync Service is running under an account
    username that has authenticated access to an Exchange mailbox (i.e., the user account
    must be a domain controller authenticated user).
    By default, the KnowledgeSync service is installed to run under the user called Local
    System account. This is not a valid local account username and will not work with
    Exchange. Go into your Services control panel and ensure that a valid authenticated
    username and password have been selected.
    Step #3: Make sure that neither you nor anybody else is in Microsoft Outlook
    (connected to Exchange) on the same computer that KnowledgeSync is installed on.
    There is a limit of one (1) connection to exchange from an individual computer.
    KnowledgeSync will receive a “login failure” message if you are connected via
    Outlook to the Exchange server while KnowledgeSync is attempting to send/receive
    e-mail.

Email Authentication

    If you wish, you can configure the system to use authenticated email for the sending
    of email alert messages. Note that KnowledgeSync does not as yet support
    authentication for the processing of monitoring incoming email, but this will be
    added in a future release.
    Note that email authentication is enabled for Internet-based email systems only
    (Email Type must be set to "Internet").
    To configure a Google email account that uses authentication and secure sockets
    (SSL), set the Email Account Description to whatever you like (e.g., "Company
    Alerts") followed by "/AUTH/LOGIN/SSL" as in:
    Company Alerts/AUTH/LOGIN/SSL
    Set the Login Name to your gmail email address. Set your outgoing SMTP server
    name accordingly (e.g., smtp.gmail.com), and choose Port 465, which is the normal
    SMTP SSL port.
    Option two is to configure an IIS email account that uses authentication and SSL.
    Note that this approach uses the "NTLM" flag to connect to an MS Virtual SMTP
    server. (NTLM is used throughout MS systems as an integrated, single sign-on
    mechanism.)
    To configure an IIS email account that uses authentication and secure sockets (SSL),
    set the Email Account Description to whatever you like (e.g., "Company Alerts")
    followed by "/AUTH/NTLM/SSL" as in:
    Company Alerts/AUTH/NTLM/SSL
    Set the Login Name to your domain username. Set your outgoing SMTP server name
    accordingly (you can use the IP address), and choose Port 25, which is the normal
    SSL port.

                                  Administration                                        69
    Option three is to configure an IIS email account that uses authentication but does not
    use SSL. Note that this approach also uses the "NTLM" flag to connect to an MS
    Virtual SMTP server as detailed above.
    To configure an IIS email account that uses authentication but not secure sockets
    (SSL), set the Email Account Description to whatever you like (e.g., "Company
    Alerts") followed by "/AUTH/NTLM" as in:
    Company Alerts/AUTH/NTLM
    Set the Login Name to your domain username. Set your outgoing SMTP server name
    accordingly (you can use the IP address), and choose Port 25, which is the normal
    SSL port.
    Option four is if you're not using any of the preceding email methods (not Google,
    not IIS). This method also provides authentication, but does not use SSL
    To configure such an email account that uses authentication but not secure sockets
    (SSL), set the Email Account Description to whatever you like (e.g., "Company
    Alerts") followed by "/AUTH/LOGIN" as in:
    Company Alerts/AUTH/LOGIN
    Set the Login Name and password as needed. Set your outgoing SMTP server name
    accordingly, and choose Port 25, which is the normal SSL port.

E-Mail Set-Up: Configuring Exchange Under SMTP

    If you are running Exchange under e-mail type Internet, follow these steps:
        1. Stop the KnowledgeSync service.
        2. Select e-mail type “Internet”.
        3. Key in the e-mail account name/description.
        4. Specify the login name and password.
        5. Leave the postoffice field blank.
        6. Adjust the default server names(s) to your site (such as
           server.[your_company].com.
        7. Adjust the SMTP From Name to be a valid e-mail account.
        8. Restart the KnowledgeSync service.

E-Mail Set-Up: Configuring Exchange Natively

    Note: The following steps assume that you are logged in under the user account that
    the KnowledgeSync service will run under.
    If you are running Exchange under e-mail type Exchange, follow these steps:
        1. Stop the KnowledgeSync service.
        2. Be sure CDO is installed.
        3. Configure the KnowledgeSync service to run under an account username that
           has authenticated access to an Exchange mailbox.
                                 Administration                                   70
       4. Select e-mail type “Exchange”.
       5. Key in the e-mail account name/description.
       6. Create (or determine) the Exchange account that KnowledgeSync will use for
          the sending of e-mail alerts.
       7. Go into the Exchange Administration module and (using the “Primary
          Account” option), make sure that the primary account for this mailbox is
          configured to use the same user account that the KnowledgeSync Service
          runs from.
       8. Make sure that the Mailbox login name is set to the mailbox alias or
          directory name. (Sometimes the mailbox might be 'Bob Jones' but the real
          name is ‘bjones’.) You must specify the real name that is being used. (The
          real name will never have spaces in it.)
       9. Specify the password (which is usually the logon user password) to access
          the mailbox.
       10. In the Post Office field, place your Exchange server name.



E-Mail Set-Up: Lotus Notes Mail

    Note that KnowledgeSync supports Lotus Notes Mail only if POP is not enabled.
    Here are the steps to configure KnowledgeSync to send (& optionally receive) email
    via Lotus Notes Mail:

           Make sure the Lotus Notes Client components are installed on the
           KnowledgeSync server and are accessible by the KnowledgeSync service.
           You should decide which user account will be used by KnowledgeSync for
           sending email and you should install the Lotus Notes client components for
           that user.

           Log on to Lotus Notes for the user specified in the preceding step and send a
           test email. To ensure that this account has the ability to send email messages
           via Lotus Notes Mail.

           Open the KnowledgeSync Service “Log On” tab and specify that the user
           identified in the previous two steps will be the one KnowledgeSync uses to
           send and receive email messages.

           In the KnowledgeSync Administration “Email Accounts” option, set the
           email type to “VIM”.

           Leave the postoffice field blank. This field is used only if you want to
           connect to a postoffice other than the default one. (Most sites leave this field
           blank.)

           Specify the Username / mailbox that KnowledgeSync will use. Do not use
           the “short name” for this user/mailbox;, use the full specification. A typical
           Lotus Notes username looks like this:

           Robert Williams/Faculty/Atlanta
                                  Administration                                         71
            Or like this:

            Robert Williams/Faculty

            Typically, using just a name value (such as “Robert Williams”) will not work
            properly and will fail to login to the Lotus Notes mail system.

            Make sure that the installed Lotus Notes folder is included in the “PATH”
            variable (usually C:\Lotus or c:\Notes)


    If the logon to the Lotus Notes mail system fails with a bad username or bad
    password, Lotus Notes will typically pop up an error message and prompt for the
    correct username and password.
    This can be a problem, since KnowledgeSync runs as a service and thus there is
    nobody to respond to this error and prompt. It is suggested, therefore, that you
    initially run the KnowledgeSync “Desktop Service” to confirm whether your Lotus
    Notes mail settings are correct.
    With the Desktop Service, any error messages and/or prompts will appear on the
    desktop of the user who started the service.
    If you are unsure of the username of the Lotus Notes user mailbox to use, you should
    scan your system for the file called “Lotus.ini” (or any similarly named file) and
    review the contents of the file. You should see information within it naming the
    Lotus Notes user account.


Test Your E-Mail Account (Outside of KnowledgeSync)

    Particularly when working with Exchange, it is helpful to test the configuration of
    your e-mail sending account by first attempting to send an e-mail message from
    outside of the KnowledgeSync application.
    Be sure that you are logged on to the account which KnowledgeSync will use to send
    e-mail alert messages and then try to send a message to someone other than yourself.
    Once you have successfully completed this test, you should proceed with running a
    KnowledgeSync test message to ensure that your configuration is running smoothly.


Test Your E-Mail Account (Within KnowledgeSync)

    Once you have tested your e-mail sending account from outside of KnowledgeSync,
    follow these steps to test it from within KnowledgeSync:
         Start the KnowledgeSync service.
         Back on the main KnowledgeSync Administrator window, single click on the
          “Email Accounts” branch so that the account that you just set up is displayed
          in the right-hand column of this window.


                                  Administration                                          72
         (In the right-hand column) Single-click (highlight) the e-mail account you
          just set up.
         Go up to the top of the Administrator window and click on the “Perform
          Email Test” button. Key in your own mail address as the recipient of this test
          message. (It is suggested that you also test sending a mail message to a
          recipient other than yourself.)
         Log into the KnowledgeSync Monitor (user name “Admin” and no
          password) and watch the branch called “Email Delivery.” You should see
          your test e-mail go from a “Pending” state to a “Sent Today” state. If the e-
          mail appears in the “Errors Today” branch (or never leaves the “Pending”
          branch), there is an error in the configuration of the e-mail sending account.
         If the e-mail fails to be sent successfully, stop the KnowledgeSync service
          and review the e-mail sending account set-up. (Contact Vineyardsoft support
          if needed.) Once you have re-configured the e-mail sending account, you do
          not need to re-submit the e-mail test as the previous test is still “pending.”
          Simply re-start the service and see if the pending message gets sent.


Using Dial-Up Networking to Send E-Mail

    If your organization does not maintain a permanent connection to the Internet, you
    may use KnowledgeSync’s “Dial-Up Networking” option to automatically dial a
    modem and connect to the Internet when event e-mail needs to be sent.
    To enable this function, click on the “Dial-Up Networking” tab, select the field titled
    “Use Dial-Up Networking for Email,” and fill out the following three fields:
         Dial-Up Networking Profile Name to Use: The name of the Dial-Up
          Networking connection profile that you wish KnowledgeSync to use when
          connecting to the Internet.
         User Name: The login user name for this account
         Password: The password of this user.
    Note that KnowledgeSync will use dial-up networking only if it detects that an
    Internet connection is not currently present.



Using Multiple E-Mail “Sending” Accounts

    You may wish to configure multiple e-mail sending accounts. The primary reasons
    for this are:
           To distribute the workload of sending many e-mail messages. Instead of
            sending all e-mail messages out via a single account, you can distribute this
            workload via configuring different events to use different e-mail sending
            accounts.
           To have different “sending” address names associated with different
            outgoing messages. Depending on the type of event that is triggering an
            event and the type of alert recipient, you may want some e-mail messages to


                                   Administration                                        73
            come from an account called “Employee Alerts,” and other messages to
            come from an account called “Customer Alerts.”
           To have different “reply to” addresses associated with an e-mail message
            (e.g., some events should be replied to at alerts@yourcompany.com, whereas
            other events should be replied to at offers@yourcompany.com.

Fax “Sending” Accounts
    In addition to e-mail, paging, and webcasting, KnowledgeSync can send out
    messages via facsimile (fax). This function requires no additional hardware or
    software, other than a modem that is reachable from the server on which
    KnowledgeSync is installed.
    Note: KnowledgeSync may be configured to send faxes using an external faxing
    application, such as WinFax or Microsoft Fax. For details on integrating
    KnowledgeSync with external faxing applications, please contact Vineyardsoft’s
    Customer Support Department or search our on-line knowledgebase for “Microsoft
    Fax”.
    To configure KnowledgeSync to send faxes, you need to set up one or more faxing
    accounts.
    Expand the “Software Setup” folder and single click on the branch called “Fax
    Accounts.”
    Click on the “New Fax Account” button at the top-left of the window. This is where
    you set up the fax account (or accounts) that KnowledgeSync will use when sending
    fax alerts.
    (If you wish to modify the details of an existing fax account, simply double-click on
    the account on the right side of your window.)
    Fill in the fields as follows:
         Fax Account Name: A description of the account that will be used for
          sending fax notifications.
         Coverpage Filename: The name of the cover page to be used with this fax.
          (Fax cover pages are defined separately within the “Fax Cover Pages”
          option.)
         Maximum Retry Attempts: This is the number of retries attempted for a
          single fax when a "No Answer" or "Busy" signal is returned to
          KnowledgeSync. Once the "Maximum # of Retries" is reached the Fax Send
          will error for that particular fax.
         Active: Whether this account is currently available for sending faxes.
         Fax Machine Identification: The name of the fax machine from which the
          notifications are sent
         Banner: The heading that appears (typically with the date and time) on all
          sent fax pages
         Sending Company Name
         Sending Department/User

                                     Administration                                     74
         Sending Fax Number: The number from which the fax is sent.
         Voice Number: The voice telephone number associated with the fax.
         Notes about this account
    Your completed fax account window will look similar to the following:




                            FAX “SENDING” ACCOUNT DEFINITION

Using Multiple Fax “Sending” Accounts

    You may wish to configure multiple fax sending accounts. The primary reasons for
    this are:
           To have different fax machine identification names associated with different
            outgoing messages. Depending on the type of event that is triggering an
            event and the type of alert recipient, you may want some fax messages to
            come from an account called “Sales Fax,” and other messages to come from
            an account called “Support Fax.”
           To have different company, department, or voice numbers associated with a
            fax message.

Fax Cover Pages
    Although KnowledgeSync has an option to create and design fax cover pages, this
    option is currently hard-coded with two types of cover page designs; one that uses a
    small font on the cover page, and one that uses a large font on the cover page.
    In the current version of KnowledgeSync, you cannot edit these cover pages nor
    create additional cover pages of your own. The current extent of this option is your
    ability to “activate” or “deactivate” either of the two pre-configured cover pages for
    use with specific fax accounts.


                                   Administration                                        75
    (Use the “Active” checkbox to activate or de-activate a fax cover page design.)

Holiday Schedule
    When KnowledgeSync events are configured, you have the option to specify whether
    or not the event will be submitted if it’s scheduled execution date falls on a holiday.
    The definition of these holidays is done within this option.

Defining Your Holidays

    To define a new holiday, click on the “Holiday Schedule” branch and then click on
    the “New Holiday” button at the top-left of the Administrator window.
    To edit the configuration of an existing holiday, simply double-click on the holiday
    in the window on the right.
    For each holiday that you define, you have access to the following four fields of
    information:
           The holiday name (e.g., “Christmas Day”)
           The holiday date (entered in the format “XX/XX/YYYY”)
           Whether the holiday falls on the same numeric date every year (e.g.,
            Christmas always falls on December 25th)
           Whether the holiday is currently active, thus enabling an event to be
            configured to observe that holiday and not be submitted.
    Note that each event may be configured to either run or not run on a holiday.




                                     HOLIDAY DEFINITION

Paging Services
    Note: KnowledgeSync supports SMS paging.
    If you will be using KnowledgeSync to send alerts via pager, you need to identify the
    paging services that you will need KnowledgeSync to communicate with and (if
                                   Administration                                          76
needed) the site-specific connection data that each service requires.
KnowledgeSync’s paging function requires no additional hardware or software, other
than a modem that is reachable from the server on which KnowledgeSync is
installed.
Note: KnowledgeSync may be configured to send pager messages using an external
paging application, or via an e-mail interface. For details on configuring
KnowledgeSync for either of these methods, please contact Vineyardsoft’s Customer
Support Department.
Expand the “Software Setup” folder and single click on the branch called “Paging
Services.”
Click on the “New Paging Service” button at the top-left of the window. This is
where you set up the services that KnowledgeSync will use when sending pager
alerts.
(If you wish to modify the details of an existing pager service, simply double-click on
the account on the right side of your window.)
Fill in the fields as follows:
     Paging Vendor: E.g., "Skytel"
     Service Description: E.g., "Skytel Pager Service"
     Paging Station TAP Phone Number: The access number for this paging
      service
     Password: The password (if any) required to access this paging service
     Baud Rate: (Contact your paging service.)
     Parity: (Contact your paging service.)
     Data Bits: (Contact your paging service.)
     Stop Bit: (Contact your paging service.)
     Characters Per Block: (Contact your paging service.)
     Customer Support Number: The support number of your paging service
      vendor. This number is for informational use only.
     Active: Whether this paging service is currently available for use in pager
      notifications
     Notes about this paging service




                                 Administration                                     77
                                 PAGING SERVICE DEFINITION

Webcast (Dashboard Alert) Locations
    Please refer to the manual titled “Dashboard Alerts” for complete details on the
    configuration and use of the webcasting module.

User Access: Logins
    The last branch in the list of Administrative functions is titled “User Access” and if
    expanded will show a sub-branch called “Logins.” This is where you control the user
    access privileges of the people who have access to the KnowledgeSync application.
    Expand the “User Access” folder and single click on the branch called “Logins.”
    Click on the “New KnowledgeSync Username” button at the top-left of the window.
    You will be taken into the option where you can define this user’s access settings.
    (If you wish to modify the details of an existing user authorization record, simply
    double-click on the corresponding record on the right side of your window.)

The “General” Tab

    The “General” tab is where you can define the username and password that a user
    will use to log into the KnowledgeSync application. Specify the following:
         Login Name: The name the user will log into KnowledgeSync with.
         Description: The user’s full name.
         Active: Whether this user is granted immediate access to the selected
          modules.


                                  Administration                                          78
         Set/Change Password...: Click this button to password protect this
          username. Passwords may be 1-14 characters in length and are case sensitive.




                        USER LOGIN AUTHORIZATION: GENERAL INFO

    If you ever accidentally change user authorizations so that no one can access
    KnowledgeSync, contact Vineyardsoft’s Technical Support department for a
    KnowledgeSync utility that will reset all user passwords to blank.

The “User Access” Tab

    The “User Access” tab controls what KnowledgeSync modules and (within each
    module) what application functions a specific user has access to.
    The options are divided by application module (the KnowledgeSync Administrator,
    Event Manager, and Monitor). Note the following:
           If you give a user access to the “User Access” option within the
            Administrator, that user can modify the authorization settings for
            himself/herself and for any other users.
           It is strongly suggested that you limit the number of users who have access
            to the Event Manager, as this is where events are configured.
           Exercise extreme caution in allowing access to the “Submit SQL” and “Run
            Program” options as these functions allow KnowledgeSync to add, update, or
            delete data from other software applications and databases.




                                  Administration                                      79
                        USER LOGIN AUTHORIZATION: ACCESS INFO


Database Tools

   The final administrative functions in KnowledgeSync are located under the “File”
   menu. The options are:
          Remove Completed Items
          Remove Pending Items
          Compact Database

Remove Completed Items
   Depending on how many events you have configured KnowledgeSync to check, how
   often you are checking them, and how many alerts you are sending out, the amount of
   history that KnowledgeSync retains can grow to a large degree.
   The option to “Remove Completed Items” allows you to remove (delete) the history
   of completed items (events that have been checked, alerts that have been sent, reports
   that have been generated, et cetera) from the KnowledgeSync database.
   Note that this option will also compact the KnowledgeSync database after the
   corresponding records have been removed.
   (This option must be enabled if you are running the MS Access version of
   KnowledgeSync; it is optional (and not required) if you are running the MS SQL
   Server version of KnowledgeSync.)
   This removal process may be done on either an ad-hoc manual basis, or you may
   schedule it to occur automatically within the KnowledgeSync database.
   To manually remove completed items from the database, follow these steps:
                                 Administration                                       80
 Shut down all KnowledgeSync servers (and service).
 Make sure that no other users are logged onto the application.
 Click on the Administrator “File” menu.
 Select “Database Tools”.
 Select “Remove Completed Items” and the following window will appear:




                    REMOVE COMPLETED ITEMS WINDOW
 At the bottom of this window, type in the date prior to which you wish to
  remove all KnowledgeSync history of completed items. (This information
  will be removed from the database and cannot be restored.)
 Click on the “Remove” button.
Note that you should always select the option to “Compact Database” after you
have removed completed items.
Note also that if the KnowledgeSync servers are not all shut down you will
receive the error message, "3356 You attempted to open a database that is
already open..."




                         Administration                                         81
Automating the Removal of Completed Items

    Important: By default, the KnowledgeSync function to automatically remove
    completed items is turned on, with KnowledgeSync configured to run this process
    every night at 1:03 AM and to remove all completed items that are more than 90 days
    old. You may wish to disable this function if you are running KnowledgeSync under
    a SQL Server environment and wish to retain more history on-line.
    To automate the removal of completed items, follow these steps:
         Click on the Administrator “File” menu.
         Select “Database Tools”.
         Select “Remove Completed Items”.
         Click on the “Automate This Task” button and the following window will
          appear:




                     AUTOMATIC REMOVAL OF COMPLETED ITEMS SET-UP
         Specify the time of day that this procedure should run. (KnowledgeSync will
          run this process daily.)
         Indicate how many days worth of history KnowledgeSync should retain in its
          database. (The default is to retain 30 days worth of history.)
         Click on “OK”.

    Note: If you are running KnowledgeSync under an extremely heavy load (e.g., 50 or
    more events running every few minutes, sending alerts to 100+ subscribers and
    executing very sophisticated scripts, you may wish to decrease the number of days of
    retained history to seven to fourteen days. This will help to optimize system
    performance.
    Likewise, if you are not running KnowledgeSync under a very heavy load but wish to
    retain a few months worth of history on-line, you may wish to increase the number of
    days of retained history to sixty or ninety days.

Remove Pending Items
    The option to “Remove Pending Items” is one of the most useful in the application,
    as it allows you to remove (delete) selected items (such as pending e-mail messages,
    faxes, pages, reports, actions, et cetera) from the KnowledgeSync database.


                                  Administration                                       82
   This option is particularly useful if you have a large number of pending items that are
   pending because of an error state, and you simply wish to delete the erroring records.
   However, this option must be used carefully, as once you remove a pending item, it
   will not be executed by KnowledgeSync and there is no “undo” function for this
   option.
   To remove pending items from the database, follow these steps:
        Shut down all KnowledgeSync servers (and service).
        Make sure that no other users are logged onto the application.
        Click on the Administrator “File” menu.
        Select “Database Tools”.
        Select “Remove Pending Items” and the following window will appear:




                             REMOVE PENDING ITEMS WINDOW
        Select the types of items you wish to remove. Choose from:
              Actions
              Application events
              E-Mail, fax, pager, and webcast messages
              Report generation requests
              File delivery requests
        Click on the “Remove” button.
        Click on “Yes” to confirm the removal.
        Note that you should always select the option to “Compact Database” after
         you have removed completed items.

Compact Database
   (Note that this option is not needed if running KnowledgeSync under SQL Server; it
   should be taken if running KnowledgeSync under MS Access.)
   Compacting the KnowledgeSync database is always advised after you delete records
   from the database as the compact function will remove any unnecessary space from


                                 Administration                                        83
   the KnowledgeSync database. Note that you'll need 3 times the size of the database in
   free disk space to compact the database.
   To compact your database, follow these steps:
        Click on the Administrator “File” menu.
        Select “Database Tools”.
        Select “Compact Database”.
        Click on the “Compact” button.
   Note that you can delete the KS_*_[previous_year].mdb databases from your system


Backing Up the KnowledgeSync Database

   Notes:
   1) By default, the KnowledgeSync backup function is turned on.
   2) Regardless of which type of database (MS Access or MS SQL Server) you are
      using with KnowledgeSync, you must always back up the MS Access database
      files, as these files are used in both versions of KnowledgeSync.

       Note: In the SQL Server version of KnowledgeSync, the MS Access files
       do not contain any KnowledgeSync data; they are used only to facilitate the
       processing of KnowledgeSync data.
   3) If you are using the MS SQLServer version of KnowledgeSync, you need to
      configure the standard SQL Server backup function to backup the
      KnowledgeSync SQL Server database files.
   KnowledgeSync is designed to automatically back up its data files and to compress
   its database for optimal system performance on a daily basis. It is important that at
   this time nobody should be running the following KnowledgeSync modules:
        Event Manager
        Event Monitor
        Administrator
   (The KnowledgeSync service may be kept running at this time.)
   If any one of these 3 modules is in use when KnowledgeSync tries to back up its
   files, the back-up will be aborted.
   To review (and optionally, modify) when KnowledgeSync is configured to perform
   its daily system backup, follow these steps:
        Click on the Administrator “File” menu.
        Select “Database Tools”.
        Select “Remove Completed Items”.



                                  Administration                                           84
         Click on the “Automate This Task” button. (KnowledgeSync’s “Backup”
          function is designed to run at the same time as the KnowledgeSync function
          to remove completed item history from its files.)
         The following window will appear:




                        COMPLETED ITEM REMOVAL / BACKUP SET-UP
         Specify the time of day that this procedure should run. (KnowledgeSync will
          run this process daily.)
         Indicate how many days worth of completed event history KnowledgeSync
          should retain in its database.
         Click on “OK”.

What KnowledgeSync Files Are Backed Up?
    KnowledgeSync’s back-up procedure makes copies of the following database files:
         “KS_Inbox” (a “KS_Inbox_Backup” is created)
         “KS_Triggered” (a “KS_Triggered_Backup” is created)
         “KS_Object” (a “KS_Object_Backup” is created)
         “KS_Changed” (a “KS_Changed_Backup” is created)
    Vineyardsoft suggests that you create a nightly job (such as a batch job) that picks up
    these four files and either makes copies of them, writes them out to a tape back-up, or
    otherwise safeguards them for later use, if necessary.


Moving KnowledgeSync to a New Server

    Note: Moving KnowledgeSync from one server to another server is referred to as
    “Re-Licensing”. There is a $500 fee for each time you wish to re-license
    KnowledgeSync.
    Vineyardsoft requires an e-mail confirmation from your organization confirming that
    KnowledgeSync has been removed (un-installed) from the original server.
    To move KnowledgeSync from one server to another, follow these steps:
         Install KS_Setup.exe on the new server. If possible, please choose the
          same disk and directory for the installation on the new server as you had

                                  Administration                                        85
            chosen on the old server because all of KnowledgeSync’s VB script and
            Crystal report definitions each reference a specific disk and location.

            (If KnowledgeSync is installed on the old server is on drive C: and you then
            install KnowledgeSync on the new server on drive D:, all of your Crystal
            reports within KnowledgeSync on the new server will fail with the error
            message “Unable to locate C:yourreportfile.rpt”.
         If you cannot install KnowledgeSync in the same disk and directory on the
          new server as you had specified on your old server, You will have to change
          all of your VB script and Crystal report definitions manually.

            You can do this by going into the KnowledgeSync Event Manager, opening
            each report and script definition, browsing to the new location of the file, and
            re-saving the record.
         Copy all the folders from old server to the new one. Make sure to get all of
          the files from the following folders located within your “KnowledgeSync”
          folder:

            \Attachments
            \Data
            \Reports
            \Scripts
   If you have any questions as you go through this process, please contact
   Vineyardsoft’s Customer Support department.


Enabling KnowledgeSync Diagnostics

   KnowledgeSync has the ability to record the steps that it takes when running events
   in a diagnostic file so that you can track down the cause of any errors or problems
   you may be encountering. Furthermore, you have the ability to turn “on” of “off”
   different aspects of diagnostic tracking.
   To enable KnowledgeSync’s diagnostic tracking function, stop the KnowledgeSync
   service. Next, edit the registry on the KnowledgeSync server by running the
   following program (use the “run” option from the “Start” menu):
   REGEDIT
   This will display the registry on the KnowledgeSync server. Navigate to the
   following branch in the registry:
   My Computer\HKEY_Local_Machine\Software\Vineyardsoft
   Corporation\KnowledgeSync 2000\General\Diagnostics
   You may set the diagnostic value to the following possible settings:
   0        No diagnostics
   -1       All Servers in Diagnostics
   1        Main Server in Diagnostic Mode
   2        Schedule Server in Diagnostic Mode

                                  Administration                                         86
   3       Application Server in Diagnostic Mode
   4       Email Server in Diagnostic Mode
   5       Page Server in Diagnostic Mode
   6       Fax Server in Diagnostic Mode
   7       Copy Server in Diagnostic Mode
   8       Report Server in Diagnostic Mode
   9       Webcast Server in Diagnostic Mode
   10      Action Server in Diagnostic Mode
   When you are done setting the diagnostic value, you may exit from the registry and
   then restart the KnowledgeSync service.
    The KnowledgeSync Diagnostics Log file will be written to:
   C:\Program Files\Vineyardsoft\KnowledgeSync 2000\Data\KS_Diagnostics.txt.
   If you require assistance in reviewing the contents of the log, please send it to our
   Support department at support@vineyardsoft.com.


Unable to Start Server (Error 1053)

   One of the most common server-related error messages in KnowledgeSync is error
   number 1053 – “The service did not respond to the start or control request in a timely
   fashion”.
   The first thing that you should do if you receive this error is to check the Event
   Viewer Application: specifically, the Application Log. This should show you the full
   details of what occurred with the KnowledgeSync Service (called “KS_SERV.exe”).
   One of the typical causes of this error is if someone changes the “Admin” password
   to log into KnowledgeSync. If this has been done, make sure that you also change the
   logon information for the KnowledgeSync server.
   To do so, follow these steps:

           Log into the “Administrator” module

            Click on the “Server LogOn Information” button in the toolbar.

           Confirm (or modify) the Admin username and password. (Or else you will
           lock the KnowledgeSync service out of its own system.)
   To Change the Password for the “Admin” user:

           Log into the KnowledgeSync Administrator Module

           Select the option for User Access

           Select “Logins”

           Double Click on Admin

           Choose the “General” tab

           Choose "Set /Change Password"
                                   Administration                                          87
   You should also verify that the "Admin" user has the appropriate access options
  checked under the "User Access" tab.


ACTVMSG_ERR_NOT_FOUND (Error 8139)

  This KnowledgeSync error typically is due to one of five things:

          You are using “mapped drives” in the specifying the location of a file.

          You are specifying an attachment file that KnowledgeSync cannot locate.

          KnowledgeSync cannot find your Exchange server.

          KnowledgeSync cannot find the Exchange mailbox you have specified.

          KnowledgeSync cannot find the Outlook profile you have specified.


ACTVMSG_ERR_FAILURE (Error 8002)

  This KnowledgeSync error typically is due to one of the following:

          CDO (Collaboration Data Objects) is not installed. CDO is part of Office or
          Outlook and you can use “Add/Remove Programs” to verify its installation
          status.

          The KnowledgeSync service is not running from a valid domain/username

          The KnowledgeSync service user has insufficient privileges to access
          incoming & outgoing email

          You have an open MS Outlook session on the KnowledgeSync server while
          trying to receive incoming email. (You must close this session while testing
          incoming email.)

          the Microsoft Outlook security patch is installed (it requires you to press OK
          every time a 3rd party application such as KnowledgeSync tries to send
          email on your behalf).
  If you are not able to figure out the cause of this error, it is suggested that you stop
  the KnowledgeSync service and (instead) run the KnowledgeSync Desktop Service
  as it will re-direct all error messages to your desktop.




                                  Administration                                             88
                                                              CHAPTER 4
                                                     Query Desiigniing
                                                     Query Des gn ng


Query Designing

   A KnowledgeSync query is an object that retrieves specific information from an
   application’s database. In KnowledgeSync, an event uses one or more queries to
   identify a condition that should trigger alerts, reports, and/or database updates. If the
   conditions of a query (or queries) that an event uses are met, the event is “triggered”
   and the resulting alerts, reports, and actions are executed.
   (Note that KnowledgeSync can also use SQL “triggers” to detect and respond to data
   conditions; please refer to the KnowledgeSync knowledgebase for details on using
   database triggers.)
   The majority of events require only a single query, but some events require multiple
   queries; specifically, those events whose triggering is based on a combination of
   conditions that exist across multiple application databases. (Each query is associated
   with a single database.)
   There are three types of queries. The first type is a record level query, and it checks
   for one or more records that meet certain conditions. Examples of this type of query
   are:
          Open service calls with a priority of “critical”
          Activities that are overdue for completion
          Opportunities for more than $25,000 due to close within the next 30 days

   The second type of query is an aggregate query, and it checks to see if a group of
   records collectively meet a certain condition. Examples of this type of query are:

          More than 10 open service calls with a priority of “critical”
          Fewer than 5 scheduled activities per salesrep next week
          Salesreps with more than $500,000 in their pipeline

   The third type of query is a field-level change query, and it checks to see if one or
   more fields within a record have had their value changed. Examples of this type of
   query are:

          Customers whose credit status has changed
          A support call whose priority has changed to “Urgent”
          Opportunities whose amount, forecast probability, or forecast close date has
           changed
                                    Query Designing                                        89
Queries, VB Scripts, & SQL Triggers

   KnowledgeSync has three ways to identify that a condition exists that should trigger
   the execution of an event’s response actions.
   The first of these is through a query. A query extracts data from any ODBC-
   compliant database, checks to see if the data meets certain criteria, and (if the criteria
   are met), the query triggers the corresponding response actions.
   KnowledgeSync includes a wizard-driven Query Designer that makes it very easy for
   you to create queries. You do not need to be a programmer; you do not even have to
   know how SQL (“structured query language”).
   However, there may be some instances where a KnowledgeSync query is not able to
   identify the conditions you are interested in. The primary reason for this would be in
   cases where the data you wish to interrogate is not stored in an ODBC-compliant
   database. For example, a KnowledgeSync query cannot identify when a certain file is
   present (or is missing) on your system.
   To interrogate conditions of data that are not accessible through a KnowledgeSync
   query, KnowledgeSync provides you with a Visual Basic (VB) Scripting module.
   Using this module, you can write your own “interrogation scripts” that monitor
   conditions outside of an ODBC-compliant database.
   Vineyardsoft provides examples of this function within its sample collection of
   Operating System events. These events (which monitor your operating system) all
   use KnowledgeSync VB Scripts instead of KnowledgeSync queries.
   And lastly, some organizations have a need to “trigger” a KnowledgeSync event as
   soon as specific conditions exist. This real-time triggering can be accomplished in
   KnowledgeSync through the use of SQL Triggers. For details and examples on using
   SQL Triggers in KnowledgeSync, please contact Vineyardsoft’s Technical Support
   department at support@vineyardsoft.com or search our knowledgebase for “database
   triggers”.
   The remainder of this chapter will focus on the design and use of KnowledgeSync
   queries to identify conditions of data within ODBC-compliant databases. For details
   on how to use KnowledgeSync’s VB Scripting module to identify conditions of data
   outside of ODBC-compliant databases, please refer to the chapter of this guide titled
   “Visual Basic Scripting.”


Designing a Query To Be Used in Many Events

   Consider an organization that wishes to receive the following alerts:
          Clients who have pending sales of more than $25,000
          Clients who have pending sales of more than $50,000
          Clients who have pending sales of more than $100,000
   These three events could each be designed to use their own query, with each query
   checking for the corresponding dollar threshold. Or, these three events could all use
                                    Query Designing                                         90
    the same query; one in which the dollar threshold is designed as a parameter which
    is specified on the event level. The use of “query parameters” is very important, as it
    allows a single query to be re-used in multiple events.
    (Note that even though a query may require a parameter, the parameter value is
    required at the time an event is created. As a server-based application,
    KnowledgeSync does not prompt for the parameter value at the time the event is
    executed.)


Query Designing: Preparation

    Although KnowledgeSync requires you to define queries before you design events,
    you’ll find the query design process easier if you begin by identifying the event
    conditions that you wish to monitor.
    Unless you know the event conditions that you wish to monitor, it can be somewhat
    challenging to define the queries that need to be designed in support of those events.
    For each condition (or scenario) that you wish KnowledgeSync to check for, you
    should take the following steps in preparation to creating the corresponding queries.
    Please note that these steps are slightly different for record-level queries, aggregate
    queries, and field-level change queries.

Identifying Needed Database Fields
    A query serves two primary purposes; it identifies what conditions have to be met in
    order for an event to be triggered, and it identifies which database fields are eligible
    to be used within an event.
    It is the second of these that requires some extra consideration. Since an event can
    perform a wide range of responses to a triggered event, you need to consider what
    database fields are going to be required for each of those responses. For example:

           If an event will be sending alert messages, the corresponding query needs to
            include all the database fields that you might wish to include in the outgoing
            messages.
           If an event will be sending alert messages to one or more recipients whose
            address is located in a database field (such as an event that sends an alert to
            the support rep assigned to a specific call), the query needs to include the
            field(s) that contains the related notification address(es).
           If an event will be triggering one or more Crystal Reports, the corresponding
            query needs to include any database fields that will be used as selection
            criteria (also called “report parameters”) for the given report(s).
           If an event will be executing workflow or other automated response actions
            that update one or more application databases, the corresponding query needs
            to include any database fields whose values will be used in the workflow or
            update procedures.



                                    Query Designing                                            91
Record-Level Query Designing: Preparation
    The following steps should be followed in preparation for creating a record-level
    query or a field-level change query.

Step #1: Identify Overall Purpose
    The first step is to identify the overall purpose of an event. For example:
        “When a ‘critical’ service call is logged into our help desk application for one of
        our customers, send an e-mail alert to the customer’s account manager, attach a
        Crystal “Call Details” report to the message, and update the client’s history in
        our CRM database.”
    Whenever you identify an event, you should be sure to include not only the condition
    that you wish KnowledgeSync to check for (the receipt of a critical service call) but
    also all of the corresponding “response actions”, including the sending of notification
    messages, the generation of any Crystal reports, and the execution of specific
    workflow or database update actions.

Step #2: Consider Alert Message Content

    If the event will be triggering the sending of one or more alert messages, the first
    thing is to consider what you’d like the alert messages about this event to look like.
    The best thing to do in this instance is to sketch out what you’d like the actual alert
    message to say.
    In the case of the preceding event, you might wish the corresponding alert message to
    look like the following:


        Hello, Don Farber:

        The following critical support call was just logged for Acme Incorporated:

        Contact: Tom Jones
        Call Received: 09/14/2001 1:35 PM
        Type of Problem: Fatal error message
        Status: Open
        Assigned to: Lisa MacKinnon
        Description: Whenever the client tries to log into the application, they get
        a fatal error message that says that an error has been encountered in
        module msimm.

Step #3: Identify Alert Message Data Fields

    If you look at the preceding alert message, you immediately notice that some of the
    fields in the message will need to be filled in from one or more fields from the
    underlying database. As such, the third preparatory step is to identify all of the data
    fields that you wish to put into the message text:



                                    Query Designing                                           92
         Hello, [salesrep_name]:

         The following critical support call was just logged for
         [customer_company]:

         Contact: [customer_name]
         Call Received: [ticket_log_date] [ticket_log_time]
         Type of Problem: [ticket_type]
         Status: [ticket_status]
         Assigned to: [ticket_rep_name]
         Description: [ticket_description]


     Note that in the alert message of a field-level change query, KnowledgeSync will
     provide you with access to both the “old” value of the field(s) that were changed, as
     well as these fields’ current values.

Step #4: Identify Needed Database Tables

     By virtue of looking at the data fields in the previous message, you will have a very
     good idea of the database tables that the query will need to retrieve information from.
     In this example, this query will have to retrieve information from three database
     tables: the “ticket” table (to retrieve call details), the “customer” table (to retrieve the
     customer and contact name), and the “salesrep” table (to retrieve the name of the
     account manager).

Step #5: Identify the Condition

     The next step in preparation to creating a query for this event is to identify the
     condition of the records (in this case, the “call tickets”) in order for them to cause the
     sending of alert messages.
     If we look back upon the description of the event (“Send an alert to an account
     manager when a ‘critical’ service call is logged for one of their customers”) we can
     easily identify two key conditions:
            The call must have a priority of ‘critical’
            The call must have been received today

Step #6: Identify Who’s to be Notified

     Another step in preparing the design of a query for an event is to identify who will be
     notified about the event. In some cases, an event’s alert recipients (called
     “subscribers” in KnowledgeSync) will be hard-coded; for example, you might always
     want to send an alert to the CEO, CFO, or sales or support manager.
     In other cases, however, you might want KnowledgeSync to send an alert to a person
     who is associated with a record that is causing an event to trigger. Consider the
     example we are currently working with:
                                    Query Designing                                    93
    “Send an alert to an account manager when a ‘critical’ service call is logged for one
    of their customers.”
    In this scenario, the recipient of the alert (the account manager) will depend on the
    client for whom the critical call was logged. It is a critical function of
    KnowledgeSync that it has the ability to send an alert to a person associated
    with a triggered record.
    If we look back on the alert message (the version where we have identified the data
    fields), we can see that the person who should actually receive the alert message is
    “[salesrep_name]”. However, “[salesrep_name]” is not an e-mail address; it is simply
    someone’s name. If we look further into the salesrep table, we can find a field called
    something like “[salesrep_mail_address]” – this is the field that contains the address
    that we wish to send the alert to.
    If you are designing a query for an event that will send an alert to an address
    that is derived from a triggered record, it is essential that the query include the
    field that contains the recipient’s delivery address (whether it is a mail address,
    pager number, et cetera).

Step #7: Identify Related Reports

    If the event we are working with is to trigger the generation of one or more Crystal
    Reports, we need to review the reports to see if they require input in the form of
    report parameters (selection criteria). If they do, we would need to ensure that the
    fields containing the section criteria were included in the query.
    For example, since this event is to generate a “Call Detail Report”, it’s likely that this
    report would have a parameter that prompts for the “call number” to be reported on.
    Since the call number is stored in a field called “[ticket_number]”, we would need to
    be sure to include that field in our query.

Step #8: Identify Triggered Workflow / Updates

    Since KnowledgeSync is often used to trigger application workflow (often to add or
    update records within a database), the last preparatory step in designing a query is to
    identify what fields of data will be required in order for the workflow/updates to
    successfully add or modify a record within a database.
    In the example of the “critical support ticket” event used previously, we have
    indicated that we wish to use KnowledgeSync to update a client’s history with the
    details of this new support ticket. In such a scenario, you’d need to include in the
    query all of the fields that are required in order to correctly identify which client
    record needs updating, You’d also need to include those fields whose values you
    wished to add to the new history record.
    The good news is that even if you initially design a query without all of the required
    fields, you can always go back into the query (multiple times, if necessary!) to add
    the individual fields you need, whether for your alert message, related reports, or
    workflow actions.
    Note that in the workflow / update processes that are executed in response to a field-
    level change query, KnowledgeSync will provide you with access to both the “old”
    value of the field(s) that were changed, as well as these fields’ current values.
                                     Query Designing                                       94
Aggregate Query Designing: Preparation
    Aggregate events are ones that are triggered by a group of records meeting certain
    conditions. KnowledgeSync supports five aggregate functions (the first three of
    which are most frequently used):
           Count (as in “more than ‘x’ activities” or “fewer than ‘y’ leads)
           Summarize (as in “more than ‘x’ dollars” or “less than ‘y’ minutes”)
           Average (as in “an average sale amount that drops below ‘x’”)
           Minimum (as in the “minimum days to delivery”)
           Maximum (as in the “maximum freight charge this week”)
    The following steps should be followed in preparation for creating an aggregate
    query.

Step #1: Identify Overall Purpose

    Like a record-level query, the first step in working with an aggregate event is to
    identify the overall purpose of the event. Aggregate events can generate Crystal
    reports and execute workflow and database update actions just like record-level
    events. For example:
        “If a client has more than 3 overdue invoices in our Financial application, send
        an e-mail alert to the client’s account manager, attach a Crystal “Open
        Receivables” report to the message, update the client’s history in our CRM
        application, and schedule a phone call (also in the CRM application) for the
        account manager to contact the client.”

Step #2: Consider Alert Message Content

    The next step to consider is what you’d like an alert message about this event to look
    like.
    In the case of this aggregate event, you might wish the corresponding alert message
    to look like the following:
        The following client has more than 3 overdue invoices:
        Client: Jim Ramey
        Number of Overdue Invoices: 5
        Total Value of Overdue Invoices: $27,960.28

Step #3: Identify Alert Message Data Fields

    With this message, you can now identify the three data fields that you wish to put
    into the message text:




                                    Query Designing                                        95
        The following client has more than 3 overdue invoices:
        Client: [client_name]
        Number of Overdue Invoices: [invoice_ID_count]
        Total Value of Overdue Invoices: $[invoice_value]

Step #4: Identify Aggregate Field & Function

    Looking at your aggregate event’s alert message, it is easy to tell what aggregate
    functions you are performing: you are counting the number of invoices and you are
    totaling (or “summing”) the value of those invoices. Whenever you have
    KnowledgeSync “count” the number of records in a table, you always use the table’s
    unique key as the field that counts the number of records (because this field is never
    blank).
    In this example, KnowledgeSync would count records using the “invoice ID” field.
    The aggregate function that we would select for this field would be “count.”
    Similarly, KnowledgeSync would “sum” the totals in the “invoice value” field.

Step #5: Identify Aggregate Grouping Field

    If you look at your aggregate event’s alert message again, it is apparent that you are
    not just counting (and totaling) the number of invoices, but are counting and totaling
    the number of invoices per client.
    Whenever you are creating an aggregate event (and query), you have the option to
    group the aggregate function by one or more fields. (You could, for instance, count
    the number of invoices per client and (within each client) per product line.)
    In this particular query, our aggregate grouping field would be “[client_name].”

Step #6: Identify Needed Database Tables

    Aggregate events (by their nature) trigger alert messages that contain fewer “detail”
    fields of information than a record-level query.
    For the alert message of this example, the query will have to retrieve information
    from two database tables: the “invoice” table (to count the number of overdue
    invoices per client) and the “client” table (to retrieve the name of each client with
    more than 3 overdue invoices).

Step #7: Identify the Record-Level Condition

    This is a key point where record-level queries and aggregates differ. In a record-level
    query, you need to include selection criteria that will enable KnowledgeSync to
    determine whether or not a record will trigger the event.
    In an aggregate query, you need to include selection criteria that will enable
    KnowledgeSync to determine whether or not an underlying record will be eligible to

                                    Query Designing                                          96
     be included in the aggregate. For example, in order for an invoice to be counted as
     one that is overdue, an invoice must meet the following criteria:
            It must be unpaid (or not completely paid)
            It must be past its payment date
     In an aggregate query, these conditions are referred to as the “record-level”
     conditions that must be met in order for those records to be included in the aggregate
     function. (The aggregate function in this example is the “counting” of eligible
     invoices per client.)

Step #8: Identify the Aggregate Condition

     In the previous step we identified the conditions that would determine whether a
     record was eligible to be included in the aggregate function. Having done that, we
     next need to identify the condition that the aggregate itself must be tested against.
     If we consider the results of this aggregate query after step #7, we have a query that
     shows us how many invoices are overdue for payment by each client. The aggregate
     condition is where we can instruct KnowledgeSync to identify only those clients with
     more than 3 overdue invoices.
     Thus the aggregate condition for this query is:
            More than 3 overdue invoices

Step #9: Identify Who’s to be Notified

     As with record-level queries, the next step in preparing for the design of a query for
     an event is to identify who will be notified about the event. Just like a record-level
     query, an aggregate query can notify a specific individual, or an individual associated
     with a triggered record.
     In the case of the current aggregate event, you would choose to notify each account
     manager who has clients with more than 3 overdue invoices. This would require you
     to include the rep’s e-mail address as one of the fields in the underlying aggregate
     query.

Step #10: Identify Related Reports

     If the event we are working with is to trigger the generation of one or more Crystal
     Reports, we need to review the reports to see if they require input in the form of
     report parameters (selection criteria). If they do, we would need to ensure that the
     fields containing the section criteria were included in the query.
     For example, since this event is to generate an “Open Receivables Report”, it’s likely
     that this report would have a parameter that prompts for the “account number” of the
     client to be reported on. Since the account number might be stored in a field called
     “[account_number]”, we would need to be sure to include that field in our query.




                                     Query Designing                                         97
Step #11: Identify Triggered Workflow / Updates

    The last preparatory step in designing an aggregate query is to identify what fields of
    data will be required in order for the workflow/updates to successfully add or modify
    a record within a database.
    In the example of the preceding event, we have indicated that we wish to use
    KnowledgeSync to update a client’s history with the details of the overdue invoices,
    and we also wish to schedule a phone call for the client’s account manager. In both
    cases, you’d need to include in the query all of the fields that are required to correctly
    identify which client record needs updating, You’d also need to include those fields
    whose values you wished to add into both the history record and to the scheduled
    activity record.



Query Design Worksheets

    As illustrated in the preceding steps, the best way to approach designing queries is to
    identify the query elements you require before you log into the KnowledgeSync
    application. In that regard, you may wish to use the following worksheets to help you
    identify the necessary elements and thus streamline the creation of queries within the
    KnowledgeSync application.
    Note that the following two pages contain Query Design Worksheets; the first
    worksheet is designed for use with record-level or field-level change queries, and the
    second worksheet is designed to assist in the definition of aggregate queries.
    Feel free to make copies of the following two worksheets.




                                     Query Designing                                         98
                Record-Level Query Design Worksheet:

Purpose of Query: __________________________________________________________


Alert Message Text to Send When Query Condition Occurs:




Data Fields Required for Message, Report Parameters, or Workflow/Update Actions:




Database Tables Needed:


Query Conditions:




Alert Recipients:




                                  Query Designing                                  99
                    Aggregate Query Design Worksheet:

Purpose of Query: __________________________________________________________


Alert Message Text to Send When Query Condition Occurs:




Data Fields Required for Message, Report Parameters, or Workflow/Update Actions:




Aggregate Field: ____________________________________________________________
Aggregate Function: ________________________________________________________
Aggregate Grouping Field(s): _________________________________________________

Database Tables Needed:


Record-Level Conditions:




Aggregate Condition:


Alert Recipients:




                                  Query Designing                                  100
Stop! Have You Read the Installation Chapter?
     Before you can continue and begin designing queries within KnowledgeSync, you
     must have successfully completed the KnowledgeSync Installation and Configuration
     chapter of this guide.
     This chapter walks you through the process of downloading, installing, and initially
     configuring KnowledgeSync to work with your specific application(s) (such as
     GoldMine, SalesLogix, Great Plains, Macola, etc.), as well as the process of setting
     up other critical KnowledgeSync components.
     The remainder of this guide assumes that you have successfully integrated
     KnowledgeSync with your applications of choice and have verified this connectivity.
     If you have not taken these steps, please refer to the KnowledgeSync Installation and
     Configuration chapter of this guide for assistance, and/or contact the Vineyardsoft
     Customer Support Department for assistance.


Add/Edit a Query
     Once you have completed one or more worksheets for the design of queries, you are
     ready to go into KnowledgeSync and work with queries in the application. First,
     decide whether you are adding a new query to the system, or wish to view or modify
     an existing query.
     If you wish to add a new query to KnowledgeSync, open the Navigator module,
     expand the All Events branch and click on the Application you wish to add the query
     to. Then, right-click on the Application name and choose “New Query”.
     If you wish to view or edit an existing query, you must start by choosing an event
     that the query is associated with. To do this, follow these steps:
          Open the Navigator module, expand the All Events branch and expand the
           Application that contains the query you wish to work with,
          Locate an event that uses this query and expand the event’s components.
          Right-click on the Query component and select “Edit”.

 Record-Level Queries
     The following sections will guide you through the components of record-level
     queries as well as field-level change queries. Following these instructions will be a
     separate section on the creation of aggregate queries. Please note that the “Aggregate
     Queries” section goes over only the differences between designing record-level and
     aggregate queries, so it is necessary to review the record-level query section to
     become familiar with the basics of query designing.
     In the “Query Description” field, key in a description of the query you are adding and
     press your tab key. Your description will be copied into the “Display Description”
     field.
          Click the “Active” checkbox to enable this query to be used in an event.

                                    Query Designing                                         101
                                  QUERY “DESCRIPTION” TAB


Query Description
    It is important to name your queries logically so that they can be easily located later
    on. At the same time it’s good to keep your query names short so they’re easy to read
    in the Navigator module. For example, consider the following query descriptions:
           Activities; Overdue
           Activities; Too Few Per Rep
           Activities; Due in 3 Days
    As one possible naming convention, Vineyardsoft suggests listing a query’s “primary
    data object” as the first word in a query’s description (e.g., “Activities;”). You can
    then follow that with the appropriate condition being applied to that object.

Query Tables
    The Tables tab is where you can choose what database tables this query will retrieve
    information from. There are three items you need to consider when identifying a
    query’s tables:
        1. What data might you wish to put into an alert message that results from
           this query’s condition being met?

            As we have discussed (in the preparation steps), a query that retrieves
            something as straightforward as “overdue activities” usually needs to retrieve
            data from more than just the “activity” table. If information about the account
            for whom the activity was created is desired, the “account” table is also
            needed. And if information about the salesrep to whom the activity is
            assigned is desired, the “salesrep” table would also be needed.

                                    Query Designing                                       102
        2. Do you need to include the table that contains the e-mail/fax/pager
           address of the person you wish to alert?

            In many alert scenarios, you might wish to send an alert to a person who is
            “associated” with the record causing the event to trigger. (E.g., you might
            wish to send an alert to the salesrep to whom an overdue activity is assigned.)
            In this instance, you need to be sure to include the table that contains the e-
            mail/fax/pager addresses of the desired alert recipients.
        3. Will an event that uses this query be executing a workflow “response
           action” to update one or more database records via such API methods as
           running a VB script, a SQL statement, stored procedure, or executable
           program?

            Since an event can execute workflow “response actions” to perform such
            functions as adding or updating a database record, you need to consider what
            data you might wish to make available when executing that workflow (or
            adding/updating a record). For example, if an “Overdue Activities” query
            will trigger an update to a “contact” record, your update procedure will
            probably require the “contact ID” field and thus requires you to include the
            contact table as one of the tables for this query.
    To select that some (or all) fields from a table be made available to a query, go to the
    list of Available Tables and double-click (select) the desired tables. A selected table
    will appear at the lower part of the Tables tab.




                                     QUERY “TABLES” TAB

Note: Choosing the Same Table Multiple Times

    Consider the following alert scenario:
    You want to send an alert about activities that are overdue for completion. Each
    activity record contains the ID of the salesrep who is assigned to the activity (a field
    called “activity.assignee_id”), as well as the ID of the account manager who is

                                    Query Designing                                            103
    responsible for the client for whom the activity was scheduled (a field called
    “activity.acctmgr_id”),.
    Typically, the “ID” field is a numeric field, and the “name” associated with that field
    is stored in an additional table – such as the “employee” table. In the preceding
    example, you might wish to include the name of the salesrep – as well as the name of
    the account manager – in the corresponding alert message. The names of these
    individuals reside in the “employee” table, in a field called “employee.name”.
    To design this query so that it can retrieve the salesrep’s name, you would join the
    activity table “activity.assignee_id” field to the employee table “employee.id” field.
    (More on joining tables in the following section.) However, to retrieve the account
    manager’s name, you would also need to join the activity table
    “activity.acctmgr_id”field to the employee table “employee.id” field.
    KnowledgeSync does not permit you to join one table to the same column in another
    table multiple times.
    Instead, you must choose the target (or “join to”) table multiple times in the Tables
    tab. (E.g., you would choose the “employee” table twice in the Tables tab.)
    When you select the same table two (or more) times in the Tables tab, you will be
    presented with a pop-up window that informs you that you have already chosen this
    table and that you must specify an alias name in order for the table to be selected
    again.
    Once you key in an alias name (and press return), you will see the table’s alias name,
    followed by an exclamation mark and then the table’s original name, appear in the
    list of selected tables. You may then accomplish the requirement of linking to the
    same table multiple times through the use of this alias table name.

Query Links
    You must be familiar with an application database’s schema in order to link
    tables together in KnowledgeSync.
    If you have chosen more than one table for a query, you must tell KnowledgeSync
    how those tables are linked (or “joined”) together.
    It is very important that you identify a query’s primary database table before
    starting the linking process in KnowledgeSync.
    KnowledgeSync will run a query using the order in which the tables are listed in the
    “Links” tab. As a result, you should be careful to make sure that you select your
    tables in an order that will result in the most efficient processing by KnowledgeSync.
    This requires that the primary table used by a query be chosen first in your list of
    links.
    In the example of an “Overdue Activities” query that uses the “activity”, “account”,
    and “salesrep” tables, this query’s primary database table is the “activity” table.
    Having identified a query’s primary database table, you may proceed with the linking
    process:
         Click on the “Links” tab. You will see the following:


                                    Query Designing                                         104
                             QUERY “LINKS” TAB
 Click on the “Add Table Link” button. The following window will appear:




                       THE “ADD TABLE LINK” WIZARD
 In the field called “Table Name,” select the query’s primary database table
  (only if this is the first link; if not, choose any table).
 In the field called “Linked to Table Name,” select any of the query’s other
  tables.
 In the field called “Column Name,” select the field that allows the tables to
  be linked together.
 If KnowledgeSync is able to find a column in the “Link to Table” with the
  same name as the selected column in the “Link from Table,” that field name
  will automatically be loaded in the “Linked to Column Name” field.
 If KnowledgeSync is not able to find a column in the “Link to Table” with
  the same name as the selected column in the “Link from Table,” the “Linked
  to Column Name” field will be left blank and you may select the appropriate
  column from the drop-down list.
 The link type will default to “left outer join” and may be left as is unless your
  database schema specifically requires a different type of join.

                           Query Designing                                        105
          Click on OK.
          If you have more than two tables that require linking, click on the “Add
           Table Link” button again and repeat this process until all tables are linked.

Note: Overriding the Default Linking Syntax

     Depending on the applications, databases, and ODBC drivers you are using with
     KnowledgeSync, you may come across an instance where KnowledgeSync’s default
     linking syntax is not sufficient for the type of “join” you wish to create.
     For example, some applications require you to join two tables together by taking the
     first (or “left”) ‘x’ characters of a field in one table, and linking them to the first ‘x’
     characters of another field in the second table. KnowledgeSync’s default linking
     syntax does not allow you to link using only ‘x’ characters of a specific field. To
     create a link such as this, you need to override KnowledgeSync’s default linking
     syntax.
     To do so, follow these steps:
          Join the two tables together using the KnowledgeSync table linking wizard.
          Click on the SQL tab.
          Copy the “join” syntax (everything that follows the word “from”). Do not
           include the word “from” in your copy and do not include the parentheses that
           begin and end the join syntax.
          Click back on the Links tab and click on the checkbox titled “I would like to
           manually input the table linking.” A blank line will appear beneath this
           checkbox.
          Paste the “join” syntax that you copied from the SQL tab into this line.
          Edit this syntax to perform the join exactly as you require.

Modifying Your Links

     Once you have chosen your links, you have the ability to modify or edit them as
     needed. To modify an existing link, follow these steps:
          Do not select “I would like to manually input the table linking”.
          Go to the link line you wish to modify.
          Click your cursor in any of the 5 fields you wish to modify.
          Edit the value of the field you clicked in. If you clicked in the “Link Type”
           field, a drop-down list will be available from which you can select any of the
           valid link types.

Multi-Field Links

     In some cases you will come across the need to link one table to another using more
     than one field. For example, to link an “order comments” table to an “order line”
     table, you might have to link on both the order number and on the line number.

                                      Query Designing                                              106
   To create a multi-field link, follow these steps:
        Create a link (via the “Add Table Link” button) using the first of the two
         fields you need to link with.
        Click in the "Linked to Column Name" field so that your cursor is flashing at
         the end of the column name in this field.
        Add a blank space after the column name.
        Type in "and table1.2nd_link_field = table2.2nd_link_field"
   In place of "table1.2nd_link_field", key in the secondary linking field in the first
   table, and in place of "table2.2nd_link_field", key in the secondary linking field in
   the second table. Do not include the quotation marks in your syntax.

Query Columns
   The next step in designing a record-level (or field-level change) query is the
   identification of the fields of data (columns) that this query should have access to.
   Remember: just as you did when you selected a query’s tables, there are three
   questions that you need to answer when choosing a query’s columns:
       1. What data might you wish to put into an alert message that results from this
          query’s condition being met?
       2. Do you need to include the field that contains the e-mail/fax/pager
          address(es) of the person you wish to alert?
       3. Will an event that uses this query need to execute some sort of “response
          action” such as executing application workflow or adding or updating
          database records? If so, what fields of data might that response action
          require?
   The first question is the easiest to answer. For example, if you are designing a query
   that will identify activities that are overdue for completion, you might wish to include
   such fields as the activity description, the due date and time, the account name, and
   the name of the person to whom the activity is assigned.
   The answer to the second question might result in your including the database fields
   that contain the e-mail address, pager number, and/or fax number of the person(s) to
   whom an activity is assigned.
   And if this query is to be used in a response action that automatically updates the
   contact record of the client for whom the activity is overdue, you might also wish to
   include the contact’s name and/or ID as query columns.
   There is one other factor you need to consider:
       4. If the results of this query are presented in a list, what order might you
          want these records listed in?
   Since KnowledgeSync gives you the option to create a single alert message that
   contains the details of multiple records, you need to identify what order you would
   want those records listed in.


                                   Query Designing                                         107
    In the case of a list of “overdue activities,” you might want these activities listed first
    in order of activity priority, and then (within each priority) listed in chronological
    order of the activity’s due date. In this case, we’d want to be sure to include the
    activity priority field and the activity due date as two of the columns for this query.

If No Query Columns Are Displayed

    If KnowledgeSync does not display the columns for your selected table(s), it may be
    because your tables have embedded blanks within the table names. If this is the case,
    follow these steps:
                  Back on the main Navigator window, go to the branch that contains
                   the of the application you are working in.
                  Right-click on the application branch and then choose “Properties”.
                  Click on the “Edit connection” button.
                  Change the value for the “Long Tablename Left” and “Long
                   Tablename Right” characters to the double quote (“) symbol.
                  Save and Close your work.
                  Go back into the “Columns” tab for your query and check to see if
                   the column names appear.
    If the column names still do not appear, please contact Vineyardsoft’s Technical
    Support department for further assistance.


How to Select Query Columns

    Follow these steps:
         Click on the “Columns” tab. You will see the following:




                                     QUERY “COLUMNS” TAB

                                     Query Designing                                          108
          Go to the list titled “Available Columns to Query”
          Double-click on the field you wish to include, OR, single-click on the field
           you wish to include and click on the “Add Column to Query” button.
          Repeat this process for each column you wish to select. When done, your
           window will look like the following:




                         “COLUMNS” TAB – WITH COLUMNS SELECTED

Selecting “All” Query Columns

     If you wish to include all of the “Available Columns to Query” within a query, you
     can click on the button called “Add All Columns to Query.”
     Although this is an excellent technique for ensuring that you can retrieve data from
     all columns (as well as for verifying the data within each of these columns), this
     option is not suggested for normal query building as it makes it difficult for the
     person(s) designing alert messages to quickly and easily locate the specific fields
     whose values they wish to include in an outgoing alert message.

The Column “Type” Field

     When designing a record-level or field-level change query, the “Column Type” field
     should always be set to “Normal” for every column selected within a query.

The “Customized Name” Field

     Note: Do not change the default Customized Name of a query’s “unique” column if
     the query is going to track changes made to one or more database fields.
     When a query is used within an event, the event designer has the opportunity to use
     the query’s columns in a number of ways, including in the design of alert message
     text, and in the design of event response actions. Whenever the event designer needs
     to reference a query’s column, the event designer always does so by referring to the
     column’s “Customized Name.”
                                    Query Designing                                         109
    This is very important, as some databases have rather cryptic names for their
    columns. For example, a sales application may have an “activity” table with a column
    that stores the activity’s due date. This column might be called “ddate.”
    Now although you might know that a column called “ddate” actually stores the
    activity’s due date, the person designing an event’s alert message might not.
    Therefore, you can modify a column’s “Customized Name” so that when a person is
    designing an alert message for this query, they see a field called “Due_Date” rather
    than “ddate”.
    By default, when you select a column for a query, KnowledgeSync will automatically
    take the column’s name and place it in the “Customized Name” field. You can then
    modify that field’s customized name.
    Here are some notes about a field’s customized name:
           Do not include blank spaces in a column’s customized name. Some databases
            and/or ODBC drivers accept blank spaces, others do not. Instead of using
            blank spaces (as in “Due Date”), use underscores (as in “Due_Date”).
           Try to keep your customized names under 20 – 25 characters. Again, some
            databases and/or ODBC drivers accept customized names of only up to ‘x’
            characters. If you stay below 20 – 25 characters, you’ll be OK.
           Do not begin a customized name with SQL reserved words, such as “sum”,
            “sub”, “add”, “avg”, “min”, “max”, “total”, “trim”, “format”, and so on.
           Make sure than you don’t have multiple fields with the same customized
            names; you won’t be able to tell them apart! (E.g., a contact name column
            and a salesrep name column may both show up with a customized value of
            “name” – so change the first value to “contact_name” and the second value
            to “rep_name”.)
           Use only letters and numbers in a customized name; do not use symbols.

The “Unique” Field

    In KnowledgeSync, you have two choices as to how many times an event will be
    triggered by a single database record (such as an overdue activity). You can
    configure the event to:

        1. Trigger once for an individual record that meets a query’s criteria. For
           example, you are checking for overdue activities every hour. At 9 AM,
           activity #123 is overdue and triggers the event. At 10 AM the activity is still
           overdue, but since the event has already been triggered by activity #123, that
           activity does not cause the event to trigger again. (The event could, however,
           be triggered by other, new overdue activities.)
        2. Be notified over and over about a record until it no longer meets the query’s
           criteria. Using the preceding “Overdue Activities” event, activity #123 would
           trigger again at 10 AM – and every hour thereafter – until activity #123 was
           no longer overdue (i.e., it’s been completed).
    The option whether to “repeat” triggering for an individual record is specified on the
    event level.


                                   Query Designing                                           110
     However, in order to use this functionality (“repeat” versus “no repeat”) you must
     first tell KnowledgeSync how it can uniquely remember each record that has been
     triggered. This is done on the query level.
     If you do not tell KnowledgeSync how to uniquely remember each record that has
     been triggered, KnowledgeSync will (automatically) use option #2 and continue to
     trigger an event for the same record until that record no longer meets the query’s
     criteria.
     If you do tell KnowledgeSync how to uniquely remember each record that has been
     triggered, you will have the option (on the event level) to specify whether you want
     the event to trigger just once per record, or to trigger repeatedly.
     To tell KnowledgeSync how it can uniquely remember a record that has been
     triggered, you need to identify the column within a query that uniquely identifies
     each record. In the example of a query that is sending alerts about overdue activities,
     this would be a column such as the “activity ID”.
     If this column has not already been selected as one of this query’s columns, select it
     now. Once the column has been selected, place a checkmark in the “Unique” field for
     that column.
     Note #1: It never hurts to specify a unique field since you always have the option to
     turn the “repeat” function “on” or “off” within an event.
     Note #2: Every record-level event should have a unique column identified;
     aggregate events typically have no “unique” column.
     Note #3: Only a single column may be checked as a query’s unique column. If a
     query’s unique value is based on the combined values of two or more fields (such as
     an “order number” and “line number”), you can create a concatenated field that
     combines the values of these two columns and then identify that column as “unique.”
     (See following section)
     Note #4: Note: Do not change the default Customized Name of a query’s “unique”
     column if the query is going to track changes made to one or more database fields.

How KnowledgeSync Tracks a “Triggered” Record

     KnowledgeSync automatically updates itself when a “triggered” record no longer
     meets an event’s criteria. Consider the following example:
     You have an event that runs daily and is triggered to send a single (non-repeat) alert
     about customers who have been placed on credit hold.
     On Monday, Acme Corp is placed on credit hold. The KnowledgeSync event runs
     and triggers an alert about Acme Corp.
     On Tuesday, Acme Corp is still on credit hold. The KnowledgeSync event (which is
     set to “not repeat”) runs and does not trigger another alert about Acme Corp.
     On Wednesday, Acme Corp is taken off of credit hold. The KnowledgeSync event
     runs, sees that Acme Corp not longer meets this event’s criteria, and “clears” (or “un-
     triggers”) the Acme record within the KnowledgeSync database.


                                     Query Designing                                           111
     On Thursday, Acme Corp is once again placed on credit hold. The event runs, is
     triggered again, and another alert is sent out about Acme Corp.

Creating a Multi-Field Unique Value

     Only a single KnowledgeSync column can be identified as a “unique” column. (If
     you place a unique checkmark next to multiple columns, only the last checked
     column will be used as the query’s “unique”.)
     However, in some cases you might need to use more than one column to identify a
     query’s unique value. For example:
          You might need to combine an invoice number and a line number to arrive at
           a unique value for a query.
     To do this, you’ll need to create a column that concatenates (combines) the values
     from the two (or more) fields that should make up the query’s unique value.
     Depending on the database and ODBC driver you are using, you can combine the
     values from multiple fields. Before you do so, however, note the following:
          The “type” of fields you are concatenating should always be “character” or
           “string” type fields. If you need to concatenate fields whose type is not
           character (e.g., is a number or a date), you must use the convert function to
           make either (or both) field types into character values. (See “Field Editing
           Notes” for details.)
          The maximum length of a unique column for a query is 64 characters
     To concatenate fields for a SQLServer database, follow these steps:
          Choose the first column that you wish to comprise your concatenated unique
           so that the column appears in the grid at the bottom of the Columns tab (e.g.,
           “order.number”).
          Take your cursor and in the row of the grid where “order.number” shows up,
           position your cursor at the end of the word “number”.
          Click your left mouse button. (The cursor will now be flashing in the space
           right after the “r” of “number”.) Note that you can also click on the Edit
           Button in this field to access a large-screen editing window for this field.
          Type in an plus sign (+). This is the concatenation symbol.
          Type in the name of the second field that you wish to concatenate to the first
           (e.g., “order.lineno”).
          The column name now reads:
           order.number+order.lineno
     To concatenate multiple fields for an Oracle database, follow these steps:
          Choose the first column that you wish to comprise your concatenated unique
           so that the column appears in the grid at the bottom of the Columns tab (e.g.,
           “order.number”).
          Take your cursor and in the row of the grid where “order.number” shows up,
           position your cursor at the end of the word “number”.

                                    Query Designing                                         112
          Click your left mouse button. (The cursor will now be flashing in the space
           right after the “r” of “number”.)
          Type in two vertical bars (||). This is the concatenation symbol for Oracle.
          Type in the name of the second field that you wish to concatenate to the first
           (e.g., “order.lineno”).
          The column name now reads:
           order.number||order.lineno
     Please note that you cannot use a concatenated unique if your query is checking for a
     “change” to the value of one or more fields in a database.

Resizing the Display Grid

     The grid that is displayed in the Columns tab is a standard KnowledgeSync
     component that is used in many places within the KnowledgeSync application. In
     some cases, you will find the need to expand or contract the width of specific
     columns within the grid. To do so, follow these steps:
          In the heading line of the grid (the line with the “Column Name Selected”
           and “Column Type” titles in it), position the cursor at the vertical dividing
           line between the columns whose width you wish to adjust.
          The cursor will change into a two-headed arrow.
          Click your left mouse button and hold.
          Drag your mouse to the right or to the left to enlarge or decrease the width of
           the corresponding columns. Release your mouse button when the size is to
           your liking.
     Note that the re-sized grids will be in effect as long as you are working with a
     specific query in the Query Designer. Once you exit from this query, the grids will
     return to their default width.

Calculated Fields

     One of the most important aspects of query designing is that you can create
     calculated fields. For example:
            A field that calculates the number of days that an activity is overdue for
             completion
            A field that calculates the “weighted value” of an opportunity by multiplying
             the opportunity amount times the forecast probability of it closing
            A field that calculates the percentage of stock on-hand that is in excess of its
             desired maximum level.
     Calculated fields may be placed in alert messages, they may be used as selection
     criteria to determine whether a record should be triggered, and they may be used in
     an event’s response actions.




                                     Query Designing                                            113
How Do You Create a Calculated Field?

     Creating a calculated field is easy; all you need to do is click on the “Add Calculated
     Column to Query” button. (If you want to add a calculation to an existing column for
     a query, just click in that selected column and then click on the Edit button that
     appears there.)
     Let’s say that you wanted to create a field that stores an opportunity’s weighted
     value. You would take these steps:
          Click on the “Add Calculated Column to Query button. You are taken into
           the Calculated Column Wizard window.
          If the calculation you wish to perform is a date calculation or other advanced
           SQL function, you can review the list of such functions at the top of this
           window. If the calculation you wish to perform is a simple arithmetic
           calculation, you can simply begin choosing and entering your calculation
           syntax.
          In the window titled “Database Columns to use in Calculation”, select the
           field that contains the opportunity’s forecast amount. This field then appears
           in the Calculated Column Workbox.
          In the Calculated Column Workbox, type in the multiplication symbol (the
           asterisk) after the forecast amount field in the workbox.
          Go back to the window titled “Database Columns to use in Calculation” and
           double-click on the field that contains the opportunity’s probability of
           closing.
          The workbox area now reads similar to this:

             opportunity.amount*opportunity.probability

          Click on OK to return to the main Columns tab.
          Modify the column’s default customized name to be something like
           “weighted_amt”.
          You’re done! The following is an example of a calculated column. (In this
           example an opportunity’s probability of closing (a whole number) is
           multiplied times the opportunity amount which is then multiplied by “.01” to
           get the actual weighted value.)




                                     Query Designing                                        114
                                    A “CALCULATED” COLUMN

Using Advanced Calculations (Functions)

     Calculated fields may include any arithmetic functions as well as any “functions” that
     are valid according to the type of database being monitored.
     To create a calculated field that uses a database “function”, click on the “Add
     Calculated Column to Query” button and you will be taken to a window called
     “Calculated Column Editor” as shown below:




                                  CALCULATED COLUMN EDITOR



     The top window in this editor will present a list of valid “functions” that you can use
     in your calculation. Note that these functions are specific to the kind of database that
     your query is connecting to.

                                     Query Designing                                            115
The middle two boxes in the editor will show you both a list of database fields that
you can include in your calculation, as well as a list of date substitution variables
which you can use in your editor. The bottom window in the editor is where you can
enter the syntax of your calculated column. You can double-click on any of the
elements in the top and middle boxes in this window to add them to your calculation.
When finished formatting your calculation, click on “OK” to return to the main
“Columns” window for your query.
Example #1: A Calculated Field that computes the gross margin of an item.
The gross profit percentage of an item is calculated by determining the difference
between an item’s price and cost, multiplying that total by one hundred, and then
dividing that total by the item’s cost. Thus you would do the following in the
Calculated Column editor:
     Click on the “Add Calculated Column to Query” button to access the
      “Calculated Column Editor”.
     From the list of “Database Columns”, double-click on the column that
      contains an item’s price so that it appears in the workbox area of this
      window.
     In the workbox editor, add a minus sign after that field
     Double-click on the item’s “cost” field from the list of columns
     Add “*100” to your calculation
     Add the division symbol “/” to your calculation
     Double-click on the item’s “price” field
     Insert parentheses into the calculation in order to ensure that the order of
      execution is correct.
Your end result would look like the following:
((INVENTORY.ITEMPRICE-INVENTORY.ITEMCOST)*100)/INVENTORY.ITEMCOST

Example #2: A Calculated Field that determines the number of days until an invoice
is due for payment.
In a Microsoft SQL Server environment, this kind of calculation would make use of a
function called “DATEDIFF” – which calculates the number of days between two
date values. Thus you would do the following in the Calculated Column editor:
     Click on the “Add Calculated Column to Query” button to access the
      “Calculated Column Editor”.
     From the list of “Calculations to Perform”, choose the function called
      “DATEDIFF – Difference in Days between two dates”. The following will
      appear in the workbox area:

        DATEDIFF(DAY,$Column$,$Column$)



                               Query Designing                                       116
          Since you want to calculate the number of days between “today” and an
           invoice’s due date, double-click on the “%Current Date%” variable.
          Double-click on the column that contains an invoice’s due date.
          Your end result will look like the following:
             DATEDIFF(DAY,'{%Current Date%}',dbo.tarInvoice.DueDate)



Calculated Field Notes

     There’s no limit to the types of calculations that you can include in a column; you
     can include any accepted arithmetic functions, you can include parentheses to control
     the order of arithmetic operations, and you can include database (and driver) specific
     “functions” for even more advanced calculations.
     Here are a few guidelines about creating and using calculated fields:
         1. Use a query’s “Preview” mode to ensure that your calculation syntax is
            acceptable to the database, the ODBC driver, and to KnowledgeSync.
         2. Be sure to modify the “Customized Name” of a calculated field.
         3. A single query can have multiple calculated fields within it.
         4. You can copy and paste the content of a calculated field by using CTRL/C to
            copy the contents and CTRL/V to paste them.
         5. Be certain that you know the format in which your application stores its
            “date” or “date/time” values. Even thought the values might (for example) be
            displayed as mm/dd/yyyy, your application might store those values in a
            different format.

Date-Related Functions

     Most databases (and drivers) support functions that allow you to calculate the
     difference between two dates. The syntax of these functions is very much dependent
     on the database (and driver) you are working with. Please see your database
     administrator (and/or SQL documentation) for details on how to use these functions.
     Here are a couple of examples:
         1. Invoices Due Within ‘x’ Days (MS SQLServer)

             datediff(Day,'{%Current Date%}’,ARinvoice.DueDate)

         2. Client Whose Last Order Was More Than ‘x’ Days Ago (MS Access)

             datediff('d',"Invoice"."TimeCreated",'{%Current Date%}’)

         3. Quotes Due to Expire Within ‘x’ Days (Pervasive SQL)

             datediff(Day,oehdr.CancelDate,’{%Current Date%}’)

         4. The number of hours between a date/time in a database and the current
            date/time
                                      Query Designing                                      117
             datediff(hour,table.column,'{%Current Date%}’

         5. Add 3 hours to the current date/time

             dateadd(hour,3,'{%Current Date%}’)

         6. Add 3 hours to the value in a database field:

             dateadd(hour,3,table.column)
     Please be sure to check with your database administrator to ensure that you are using
     the correct date syntax.
     Note also that when you use any date calculation function in a filter, you must be sure
     to change the data “Type” field to “Number”.

Field Editing Notes

     In addition to creating calculated fields, there is a wide variety of field editing and/or
     formatting commands that you can use to further modify the data that a query
     retrieves. Please note that the following functions can be used in the query Columns
     tab, the Filters tab, and the Sub-Filters tab.

Concatenation

     Concatenating fields means to take the values from two (or more) character-type
     fields and combine them so that their values reside in a single field. There are a few
     reasons why you might wish to do this. First (as discussed previously), you might
     wish to create a query’s “unique” value that is a combination of multiple field values.
     A second common reason why you might wish to use concatenation has to do with
     sending alerts to one or more addresses that reside in database fields. (For example, if
     you wish to send a message to the support rep assigned to an open call and to that
     rep’s manager.) Although KnowledgeSync lets you send an alert to addresses that
     reside in database fields, KnowledgeSync lets you specify only a single database field
     that contains these addresses.
     Thus if you wished to have KnowledgeSync send an e-mail to both the rep assigned
     to a call and to that rep’s manager, you would be looking at two fields that contain
     the e-mail addresses that you wish to send alerts to. Since KnowledgeSync supports
     only a single field for this function, you’d need to use the “concatenate” function to
     load both e-mail addresses into a single database field.
     (Note that if you do load multiple e-mail addresses into a single field, you must
     separate each address from the next with a comma.)
     Depending on the database and ODBC driver you are using, you would use the
     appropriate concatenation command to combine the values from these multiple fields.
     Although most databases have their own symbol to indicate the concatenation
     function (SQLServer uses the “+” sign and Oracle uses the “||” sign), the basic steps
     are as follows:

                                      Query Designing                                         118
          Choose your first database column (e.g., “order.number”)
          Add the concatenation symbol at the end of that column
           (e.g., “order.number+”)
          Add the second database field (e.g., “order.number+order.lineno”)
     Please note that only character-type fields can be concatenated; if you wish to
     concatenate date or numeric fields, you will need to convert them into a character
     format. (More on the “convert” function later on.) For example, if both
     “order.number” and “order.lineno” are numeric fields, your concatenation syntax
     (under SQLServer) would appear as follows:
          convert(char(10),order.number)+convert(char(10),order.lineno)
     Note also that if you wish to concatenate multiple e-mail addresses into a single field,
     you will need to separate each e-mail value from the next with a comma as in the
     following example:
          account.repmail+’,’+account.mgrmail (SQLServer)
          account.repmail||’,’||account.mgrmail (Oracle)

Concatenation (Order Line Item Unique)

     In most accounting/financial applications, an order’s details are composed of the
     order “header” and then order “detail lines”. Because of this, every order detail line
     for a given order has the same order number associated with it.
     Thus – if you specify that the order number is the “unique” column for a query, an
     alert message that uses such a query will show only the FIRST detail line for an order
     – as all other detail lines for that order have the same order number.
     In such cases, you should be careful to make sure that the query’s unique is
     comprised of a combination (i.e., concatenation) of both the order number AND the
     line number. That way, each detail line has its own unique value and KnowledgeSync
     will therefore include each detail line in a corresponding alert message.

Trimming “Padded Spaces” from a Field’s Value

     Sometimes database fields are stored with what is referred to as “leading” or
     “following” spaces. In some cases, you may not want KnowledgeSync to include
     these spaces when it retrieves the value from the corresponding database fields.
     Depending on the database and ODBC driver you are using, you can use the
     following functions. (Note that the following are for SQLServer databases; see your
     database manual for corresponding functions in other databases.)
          rtrim: Remove all following spaces from the right side of the field value
          ltrim: Remove all leading spaces from the left side of the field value
          trim: Remove all surrounding spaces from both sides of the field value
     The format for using these functions is:

                                     Query Designing                                          119
           trim(table.column) (SQLServer)

Retrieving ‘x’ Characters of a Field’s Value

      Sometimes you might not want to retrieve the entire contents of a database field; you
      may want (for example) to retrieve only the day of a person’s birthday (as opposed to
      the day, month, and year), or you might want to retrieve only the first ‘x’ characters
      of data from a notes field.
      To do this, you would use the following functions. (Note that the following is for
      SQLServer databases; see your database manual for corresponding functions in other
      databases.)
           Substring(table.column,starting position,length)
      For example:
           Substring(account.name,1,20)
      This would retrieve the first 20 characters of an account’s name.

Converting a Field Type (Date, Numeric, Character)

      Occasionally you may find the need to convert a field from one type (such as date)
      into another type (such as character) or vice versa.
      Depending on the database and ODBC driver you are using, you can use the
      “convert” (or comparable) command to change a character field into a date format, or
      vice versa. The syntax for doing so is as follows:
           Convert(char(20),account.createdate,0) (SQLServer Syntax)
      (This example converts a date field into a string field.)
      For an Oracle database, the conversion commands appear as follows:
             TO_CHAR(table.date, 'YYYY/MM/DD')
              (This turns a date field into a string)
           TO_DATE(table.datetime,'MM/DD/YYYY HHMISS:PM')
            (This turns a datetime column into a string)
           TO_CHAR(TABLE.NUMBER,'9999999')
            (This turns a number into a string)
      For a Pervasive SQL database, the conversion command appears as follows:
           convert(ARTRAN.OrderNumber,sql_char)
            (This turns a numeric field into a string)

Retrieving the “Top x” Number of Records

      Another useful function that you can build into your queries is the ability to retrieve
      only the top ‘x’ number of records that meet your criteria. (For example, the top five
      sales this week, or the top 10 customers with the most support calls last month.)

                                      Query Designing                                           120
     Depending on the database and ODBC driver you are using, you can use the “top” (or
     comparable) command to change a character field into a date format, or vice versa.
     The syntax for doing so (under SQLServer) is as follows:
          Top x table.column
     As in:
          Top 10 sales.amount (SQLServer Syntax)

Creating a Column that is a Label + Field Value

     In some cases, you may wish to create a column that contains both a field “label” as
     well as the field’s value. This is particularly useful if you have a field whose label
     you do not wish to appear in an alert message if the value of the field itself is blank
     (null).
     For example, let’s say that you have an Order Entry application in which you can
     have four different types of line items: inventory items, non-inventory items,
     miscellaneous charges, and comment lines. Only the lines for inventory items contain
     a warehouse code, and for those lines you wish to include a section in your alert
     message that says
     WHSE: Boston
     (assuming that “Boston” is the name of the warehouse for an inventory item)
     But since the three other line types have a warehouse value is blank (null), you do not
     want the label “WHSE:” to appear in the alert message for those line types.
     The answer is to combine the label (‘WHSE:’) with the value from the warehouse
     field. Thus your query column would look like the following:
     'WHSE:'+' '+InvDetail.Whse
     Note how this column is adding the field label to the field value, and is also adding
     two blank spaces to fall between the label and field value.
     And – as you’ll learn in the “Event Designing” chapter (specifically the sections on
     formatting the content of your alert messages), you have the ability to tell
     KnowledgeSync not to print (or allocate space to) any field whose value is null.
     (And when you add any value to a null field – as in the previous “warehouse”
     example, the resulting value is still null.)
     Please note that you can add a label to only character-based fields; if you wish to add
     a label to a numeric or date based field, you will need to first convert those fields to a
     character (or “string”) format.

Creating a Column that Contains a Date Substitution Value

     KnowledgeSync includes many date substitution values, such as “current date”, “last
     Monday date”, “next Friday date”, and so on. If you wish to use one of these fields as
     a column within a query, you need to reference the appropriate date variable name
     and then enclose that name within single quotes, as in:

                                      Query Designing                                          121
     '{%Last Friday Date%}'

Retrieving Just the Month or Day from a Date Field

     In order to retrieve just the month or day from a date field (to check for a person’s
     birthday, anniversary, etc.), you would use the following syntax:
     month(hrpersnl.p_birth)
     day(hrpersnl.p_birth)

Creating a Column that Contains a Hard-Coded Value

     When designing queries, you may wish to create a query column that simply contains
     a hard-coded value, such as a column that contains a standard email address, such as
     smith@vineyardsoft.com.
     To do so, follow these steps:

             Add a column to a query

             Click your mouse in the “Column Name” field of the column you just added
             and delete the existing column name

             Type in a single quote (‘) followed by the default value followed by another
             single quote (as in ‘smith@vineyardsoft.com’)

             Go to the “Customized Name” field and enter an appropriate customized
             name for this field
     Note that you’ll need to create this field in every query in which you need it –
     KnowledgeSync does not currently support the definition of “global” values that can
     be set up once and used in all queries.

Creating a Column Containing File Specifications

     One of the special functions that you can utilize when choosing columns is to create a
     column that stores the name and location of one or more files that you wish
     KnowledgeSync to deliver to one or more recipients. Multiple files must be separated
     from each other with commas.
     Please note that the file specifications that are stored in this column must either use
     the actual server, disk, and directory specification for each file, or they must use the
     UNC path name that points to the location of these files. The specifications must not
     refer to mapped drives, or else KnowledgeSync will be unable to locate the files.
     When you add a column (containing one or more file specifications) to a query, the
     Customized Name of that column must be “attachment_files” (and it is case
     sensitive). The actual column name may be anything.
     When (later on) you use a query including such a column within an event, you will
     have the option to instruct KnowledgeSync to deliver the corresponding files to one
     or more recipients via e-mail, web browser, or FTP. The files may also be referenced
     within any of the “actions” that an event executes.


                                     Query Designing                                            122
Using “if – then – else” Logic

      Another handy function that you might wish to use within your query columns is
      “if – then – else” logic. For example:
      “if the contact’s email address is blank, use the default account email address”
      “if the contact’s email address is blank, use the salesrep’s email address”
      “if the value of the field is “H”, I want the alert message to read “Hold”
      Being able – in a query – to check the value of a field and then MODIFY that value
      (or use a different value) is very useful. In a SQL database environment, the syntax
      for doing so is as follows:
      CASE table.column when 'value' then table.column+'value' else table.column END
      For example, let’s say you have a column in a table that has values of I, C, or D and
      you want to display them as IN, CM, and DM in your alert message. How would you
      do this?
      The answer would be to create three columns in the query as follows:
      CASE table.column when 'I' then table.column+'N' else table.column END
      CASE table.column when 'C' then table.column+'M' else table.column END
      CASE table.column when 'D' then table.column+'M' else table.column END
      Note that the preceding syntax is for SQL Server databases; the format for using this
      same logic in a Microsoft Access database would be:
      switch(AR_Customer.State='WI',AR_Customer.State+'S',true,AR_Customer.State)
      The above example will look for any customer record where the state equals “WI”
      and it will append an ‘S’ to it so that the state shows up as “WIS”.

Removing Columns from a Query

      To remove a column from a query, follow these steps:
           In the KnowledgeSync grid, go to the left-most column of the row that
            contains the field you wish to remove.
           The cursor will change into a right-pointing arrow.
           Click your left mouse button.
           Click on the “Remove Column from Query” button.
      You may use the Shift/Click function (hold down your shift key and click your left
      mouse button) to select multiple columns, and you may use CTRL/Click to select
      “blocks” of records.
      Note also that you may also click on the button called “Remove All Columns from
      Query” to delete all of the columns that have been selected for this query.




                                      Query Designing                                         123
Return Distinct Rows of Data Only

    By design, record-level queries return a list of all records that meet a query’s criteria.
    For example, a query that scans orders placed last month will generate a list of all of
    those orders.
    But what if instead of a list of all orders that were placed last month, you only wished
    to receive a list of all customers who placed those orders? If your query is retrieving
    data from the “orders” table, you will see one record for every order in that table,
    including multiple orders for the same customer.
    However, based upon the columns that you select for a query, you can instruct
    KnowledgeSync to retrieve only unique (or “distinct”) records.
    Thus if you designed your query to contain only the name of a customer who
    purchased last month – and you selected the “Return Distinct” option –
    KnowledgeSync would provide you with a list that shows a customer’s name
    only once, regardless of how many matching orders there were.
    Be careful when using the “Return Distinct” option as the definition of what is (and
    what is not) “distinct” is controlled strictly by what columns you have chosen for
    your query (i.e., a record will be retrieved only if all the columns you have selected in
    your query contain unique values).
    For example, if the preceding query has just the “customer name” column, it will
    return one record per customer. But if the preceding query has “customer name” and
    “order number” as columns, it will return one record per order per customer.

Sub-Queries (Embedded Selects)

    One of the more advanced query design functions that you can use in
    KnowledgeSync is the ability to create a column whose value is the result of another
    query. This is referred to as using “sub-queries” or “embedded selects” (because
    instead of specifying a column name, you’re going to specify another SQL “select”
    statement.
    Consider the following scenarios:
    1) Project Tracking. You need to total a "minutes" value from three different tables
    per user. You then need to take that total and perform some arithmetic calculations on
    it.
    2) Customers Who Have Recorded No Activity. You need to total the number of
    activities per customer and identify only those customers with '0' activities.
    3) Aggregate "Either/Or" with different timeframes. You want to know about any
    client who has contacted your Support department either more than 6 times over the
    past month, or more than 12 times over the past three months.
    To handle scenarios such as these, you can design a query in which you embed one or
    more other queries. KnowledgeSync refers to this as using "embedded selects".
    Used in the "Columns" and "Filters" tab of a query, an embedded select takes the
    place of a selected column. For example, when you edit a column, you can edit it to

                                     Query Designing                                         124
    include a "select statement", and a select statement is essentially an additional query.
    And so, for the previous 3 scenarios, you could address them in the following ways:
        1. Have a single query that uses three embedded select statements on the
           "Columns" tab, each of which totals a specific "minutes" value. This query
           could also contain a column that totals the three "selected" values and
           performs the final calculation on that value.
        2. Have a single query (on the account table) which includes an embedded
           select on the "Columns" tab to count the number of activities per customer.
           The embedded select has a filter on it to retrieve only those customers whose
           count is equal to zero.
        3. Have a single query which includes two embedded selects on the "Filters"
           tab; one of the embedded selects counts support calls over a one-month span,
           and the other counts the calls over a three-month span. The "Compare Value"
           for the first filter is '6' (calls) and the Compare Value for the second filter is
           '12' calls. Most importantly, the filters are linked together via an 'OR'
           condition.
    Please note that embedded queries must use the same ODBC connection as the query
    in which they are embedded.
    The easiest way to create, view, or modify embedded select statements is to use the
    Calculated Column Editor, which gives you a full-screen editor in which to create
    your embedded select statement.
    Vineyardsoft has an EventPak that includes these three sample events, illustrating the
    use of embedded selects. If you would like to receive this EventPak, please contact
    Vineyardsoft’s Customer Support department at support@vineyardsoft.com.

Query Sorting Order
    When a record-level query is executed, it will retrieve matching data records. These
    records can be placed into an alert message, they can be exported into a file, they can
    be used in application workflow and updates, and they can be used in a variety of
    other response actions.
    Regardless of how you will have KnowledgeSync act on these matching records, you
    have the option to specify the order in which these records will be listed and acted
    upon. This is referred to as the query’s “sorting order.”
    Any fields that were selected on the query’s “Columns” tab are available for use in its
    sorting order. To select your sorting order, follow these steps:
         Click on the “Sorting” tab. The following window will appear:




                                    Query Designing                                         125
                                     QUERY “SORTING” TAB
          Go to the list titled “Available Columns for Sorting”
          Double-click on the field you wish to sort on.
          The “Sort Direction” field will default to sorting records in an “ascending”
           order), but if you wish to change the order to descending, click on this field
           and choose the word “descending” from the drop-down list.
     Note that you can specify multiple levels of sorting (also called “nested sorting”).
     Once you have chosen your first sorting field you can simply repeat the preceding
     three steps to create an additional level of sorting.
     (For example, to sort overdue activities first by priority and then by activity due date,
     you would select the activity priority column as your first sort field and then select
     the activity due date column as your second sorting field.)

The Effect of Sorting on “Record Breaks”

     When you configure a KnowledgeSync event to send alerts about a specific
     condition, you have 3 choices as to how many messages will be sent. You can:
         1. Send one alert message per triggered record. (E.g., send one message per
            overdue activity to each salesrep who has overdue activities. Thus if a rep
            has 5 overdue activities, they will receive 5 alert messages.)
         2. Send one alert message for all triggered records. (E.g., send one message
            which contains the details of all overdue activities.)
         3. Send one alert message per user-defined group of triggered records. (E.g.,
            send one message for each rep who has overdue activities; each message
            containing the details of all of that rep’s overdue activities.)


                                     Query Designing                                         126
     It is the third of these choices that we need to take into consideration when designing
     a query. Here are some examples:
                  Send one message (listing all of a rep’s overdue activities) to each
                   salesrep.
                  Send one message (listing all of an invoice’s line items) to each
                   customer.
                  Send one message (listing all the calls) for each priority of all open
                   support calls.
     In each of these examples you would need to tell KnowledgeSync how to group (or
     sort) the matching records. The first example would sort by rep ID, name, e-mail
     address (or other rep-unique field), the second example would sort by invoice number
     (and probably line number, so the lines appear in the correct order), and the third
     example would sort by call priority.
     Please note that there is additional set-up (on the event level) that needs to be done in
     order to enable the grouping and breaking of alert messages.

Query Filters
     The most important part of designing a query is the identification of the “conditions”
     that will cause the query to trigger an event. These conditions are referred to as a
     query’s “filters.”
     There are three general concepts of query filter design that you should review before
     starting to create filters. These concepts are:
            What operators you can use in a query filter?
            What kinds of comparisons can a filter execute?
            Will any of your filters use parameters?
     The following sections address each of these concepts.

Query Filter Operators

     A filter can use all of the standard operators that you are familiar with, such as:
            Equal to (priority is equal to “high”)
            Not equal to (priority is not equal to blank)
            Greater than (amount is greater than 100)
            Less than (amount is less than 100)
            Greater than or equal to
            Less than or equal to
            Between (amount is between 100 and 200)
            Starting with (part number starts with “Epak”)
            One of (priority is one of “Critical”, “High”, or “Medium”)

                                     Query Designing                                         127
    A filter can also use one other operator:
           Value has changed since the last time KnowledgeSync checked it
    Please note that the ability to create a filter that checks for a “changed” value is
    discussed separately from the other standard filter operators. Please see the section
    titled “Checking a Column for a Changed Value” for more details.

Query Filter “Compare Values”

    A filter can do much more than simply compare the value in one field against a pre-
    determined value. Here is a list of the types of tests that can be executed by a query
    filter:
           Test a field against a constant value
            (Priority equals “High”)
           Test a field against another field
            (sale price is less than the cost of goods sold)
           Test a calculated field against a constant value
            (Sales amount times sales probability is greater than 10,000)
           Test a calculated field against another calculated field
            (percentage of damaged items > percentage of undamaged items)
           Test a date or numeric field against a date or numeric range
            (due date is between this Monday and this Friday)
            (probability is between 60% and 90%)
           Test a date field against a date variable
            (forecast close date is less than “today”)

Query Filter “Parameters”
    Consider this scenario:
    Your organization wishes to receive alerts about pending sales opportunities. Your
    sales manager wishes to be alerted about any pending sales that are greater than
    $25,000. Your CFO wishes to be alerted about any pending sales that are greater
    than $50,000. And your CEO wishes to be alerted about any pending sales that are
    greater than $100,000.
    Do you design three different queries, each with a filter that checks for a different
    sales threshold?
    The answer is: you could, but you don’t need to.
    At the start of this guide we discussed how a single query can be used in multiple
    events. Thus although you could design three queries as follows:
           Pending Sales > $25,000
           Pending Sales > $50,000
           Pending Sales > $100,000
    You could also design a single query called “Pending Sales > ‘x’ Dollars.


                                    Query Designing                                          128
    This is where a filter’s ability to accept a parameter is invaluable. You can create a
    filter that tests to see if a sales amount is greater than ‘x’ and ‘x’ can have a different
    value in three different events, each event using the same query.
    Note: The value of any parameter-driven filter is specified on the event level,
    at the time the event is configured. KnowledgeSync does not prompt for the value of
    this parameter when the event is run. If an event using a query with a parameter-
    driven filter does not have a corresponding value for the parameter-driven filter, the
    event will fail to execute successfully.
    Let’s first go through each of the seven components of a filter, and then we’ll look at
    the process of creating a few different types of query filters.

The Seven Filter Components

    An individual filter can consist of up to seven components; although not all filters
    utilize all seven components, it is important to understand how they all function.
    When you click on the “Filters” tab you will see the following window:




                                      QUERY “FILTERS” TAB
           Column Name. The first part of a filter is the selection of the column whose
            value you wish to test. To select a column for filtering, you simply go to the
            list of “Available Columns to Filter” and double-click on the column whose
            value you wish to test. The column will be added as a filter to the grid in the
            middle of the “Filters” tab.

            Note that the Column Name field can also contain a formula or calculation;
            see “Using Calculated Fields in Filters” for more details.)

           “Is” or “Is Not”. By default, KnowledgeSync checks a column to see if it
            meets a certain condition; by choosing the “is not” function, you can instruct
            KnowledgeSync to check a column to see if it does not meet a certain
                                     Query Designing                                              129
            condition. To change the “is” function to “is not”, simply click next to the
            word “is” and choose “is not” from the drop-down list.
           Operator. KnowledgeSync provides 10 operators that you can choose from
            when testing a field for a certain value. By default, the operator “equal to” is
            selected for you, but you can choose a different operator by clicking in this
            field and displaying the drop-down list. (See the section titled “Operator
            Notes” for more details on individual operators.)
           Compare Value. The “Compare Value” field is where you place the value
            against which KnowledgeSync will compare the selected column’s value.
            The compare value field may contain a constant value, it may contain the
            value from another database field, it may contain a date substitution value, or
            it may contain the question mark. (See following sections for details.)

            Note that the Compare Value field can also contain a formula or calculation;
            see “Using Calculated Fields in Filters” for more details.)
           Type. The “type” field identifies the type of data that this filter is
            processing; this can include “character” based data (i.e., alphanumeric data),
            numeric data, or date-formatted data. KnowledgeSync automatically fills in
            the value of this field for you.

            The “Literal” data type is used only if you are comparing one column against
            the value in another column, or against an SQL function. (See “Comparing a
            Column Against Another Database Field” for details.)
           “And / Or”. Since a single query can include multiple filters,
            KnowledgeSync gives you the ability to specify “and/or” logic in the
            sequence of those filters, as in “look for condition ‘a’ or condition ‘b’”).

            Please note that this default “and/or” logic is sequential and the “and” or “or”
            that you select applies to the current filter in relation to the next filter.

            For example, if filter #1 has an “or” in it, you are creating a query that will
            retrieve records if filter #1 or filter #2 prove true. If filter #1 has an “and” in
            it and filter #2 has an “or” in it, you are creating a query that will retrieve
            records if filters #1 and #2 both prove true, or if filter #3 proves true.

            Although this option does not allow for “grouped” or parenthetical
            expressions, this is also supported in KnowledgeSync. For more details on
            this, see the section titled “And/Or Logic”.

           Optional Prompt. (Scroll your window to the right to see this field) The
            optional prompt field is used only with query filters that are parameter driven
            (have a ‘?’ in the Compare Value field). See the section titled “Creating a
            Parameter-Driven Filter” for details.)

Compare Values

    You can compare the value of a column against a constant value, against the value
    from another database field, against a calculated value, against a date or numeric
    range, against a date substitution value, or against the parameter indicator (the
    question mark).

                                     Query Designing                                              130
Comparing a Column Against a Constant Value

     Example: “activity priority is equal to ‘high’”




                         COMPARING A COLUMN TO A CONSTANT VALUE

     You have two ways to choose a constant as the compare value for a column; you can
     manually type in the value, or you can choose that value from a database list.
     To manually type in a value, simply go to the “Compare Value” field, delete the
     default question mark that appears there, and type in the value you wish to compare
     the column to. Note that the comparison that KnowledgeSync performs is case-
     sensitive, so a compare value of “high” will not retrieve those records that have a
     value of “High”.
     KnowledgeSync also allows you to directly query the database to retrieve potential
     values for a field. To do this, follow these steps:
          Click in the “Compare Value” field and click on the list button that appears
           there.
          Click on the down-arrow list button that appears under the heading “Type in
           a Value or Choose from dropdown List”. This will display a list of possible
           entries for this field.
          Choose the value that you wish to compare the column to and click on “OK”.
     Note: The dropdown list that appears lists all of the values that have appeared in this
     field in the underlying database. This list does not display every possible value that
     could appear in this field.




                                     Query Designing                                       131
Comparing a Column Against Another Database Field

     Example: “cost of goods sold is greater than the sale price”




                              COMPARING ONE FIELD VALUE TO
                                  ANOTHER FIELD VALUE

     In this example, the “Compare Value” will contain the name of another database
     field. To do this, follow these steps:
         In the “Compare Value” field, delete the ‘?’ that appears there.
         Type in the full name (“table.column”) of the field you wish to compare the
          selected column to (e.g., “opportunity.costofgoods”).
         Go to the “Type” field and select “Literal”.




                                   Query Designing                                      132
Comparing a Column Against a Date or Numeric Range

     Example: “due date is between 10/15/2004 and 10/31/2004”
     Example: “probability is between 60 and 90 percent”




                          COMPARING A FIELD AGAINST A DATE RANGE
                                  OR A NUMERIC RANGE

     One of the most common KnowledgeSync query scenarios is to test to see if records
     fall within a date or numeric range. This is most typically used for identifying records
     whose dates fall within a certain range, or to identify records whose numeric values
     fall within a certain range.
     KnowledgeSync has two ways of creating filters that let you identify records whose
     values fall within a range. The first is with the use of the “between” operator, as in:

             Due date is between ‘x’ and ‘y’

             Or;

             Probability is between ‘a’ and ‘b’

     The second (and recommended) way that KnowledgeSync lets you identify records
     whose values fall within a range is with the combined use of the “greater than or
     equal to” and “less than or equal to” operators, as in:




                                     Query Designing                                           133
        Due date is greater than or equal to ‘x’ and

        Due date is less than or equal to ‘y’

        Or;

        Probability is greater than or equal to ‘a’ and

        Probability is less than or equal to ‘b’

Vineyardsoft suggests the second approach (the use of “greater than or equal to” and
“less than or equal to”) for three reasons:
    1. Not all databases and /or ODBC drivers support the “between” operator.
       “Greater than or equal to” and “less than or equal to” are universally
       supported.
    2. The “between” operator cannot be used with parameters, whereas “greater
       than or equal to” and “less than or equal to” can. (This allows you to create
       one query that can be used in multiple events with differing date or numeric
       ranges.)
    3. In most cases, the use of the “greater than or equal to” and “less than or equal
       to” perform faster (more efficiently) than the “between” operator.
To create a date or numeric range filter, you have to use two filters – a “beginning”
range filter and an “ending” range filter. Follow these steps to create the “beginning”
range filter:
     Choose the date or numeric field that you wish to create a “range” filter for
      (e.g., “opportunity.probability”).
     Choose the operator “greater than or equal to”
     In the “Compare Value” field, key in a specific “beginning” date, or use a
      date substitution variable (see following section), or key in a ‘?’ to indicate
      that this filter will be parameter-driven (see section titled “Comparing a
      Column Against a Parameter Value”)
     Make sure the “And/Or” option reads “And”.
And follow these steps to create the “ending” range filter:
     Choose the same field again as a filter (e.g., “opportunity.probability”).
     Choose the operator “less than or equal to”
     In the “Compare Value” field, key in a specific “ending” date, or use a date
      substitution variable, or key in a ‘?’ to indicate that this filter will be
      parameter-driven.




                                Query Designing                                         134
Comparing a Column Against a Date Substitution Variable

     Example: “due date is less than today”




                                COMPARING A FIELD AGAINST A
                                DATE SUBSTITUTION VARIABLE

     In many KnowledgeSync queries you will want to test the value of a date field
     against a value such as “today”, “tomorrow”, “last week”, or “next month”. To
     facilitate this, KnowledgeSync provides a wide variety of “date substitution
     variables” that can be used in the “Compare Value” field of a filter.
     To use a date substitution variable as a compare value, follow these steps:
          Click in the “Compare Value” field and click on the list button that appears
           there.
          Review the list of “Available Substitution Variables.” You’ll notice that there
           is a wide variety of variables to choose from. For many variables (such as
           “%Current Date%”) you will see multiple formats for the same value. The
           format without any suffix (as in “%Current Date%”) will use your system’s
           date format. The other formats will each contain a suffix (such as
           “YYYY-MM-DD”) that indicates the format in which the corresponding date
           will be returned.
          Choose the value that you wish to compare the column to, click on the
           “Select this Item to Compare” button, and then click on “OK”.
     Note: Be careful when using the “current date” substitution variable, particularly if
     you are comparing a field that contains both the date and time to the “current date”
     variable.
     For example: you create a filter that retrieves any activities whose “creation
     datetime” field is equal to the “current date”. You won’t get any records because a
                                    Query Designing                                          135
     field that contains today’s date plus a time will automatically be greater than a field
     that contains just today’s date.
     You can address this issue in two different ways:
          Make your filter check to see if the “creation datetime” is
           greater than or equal to today’s date.
          Make your filter check to see if the “creation datetime” is
           greater than “{%Current Date%} 00:01” and
           less than “{%Current Date%} 23:59”

Retrieving “New” Records Since the Last Time the Event Ran

     Example: “leads added since the last time the event ran”
     KnowledgeSync has a special date substitution variable called
     “Last Date/Time Event Checked”. This variable allows you to configure a query to
     retrieve only those records that have been added to your database subsequent to the
     last time KnowledgeSync checked for those conditions. For example:
     You have a large database of contacts. You want to notify your sales manager
     whenever a new contact is added. Typically, you would create a query that looks at
     contacts created today, and the corresponding event would send alerts about only the
     newly-created contacts.
     However: If your database is quite large and you are running an event like this one
     on a frequent basis (e.g., every 30 or 60 minutes), it would be more efficient to have
     KnowledgeSync retrieve only those records that were added since the last time
     KnowledgeSync checked this event. (As opposed to having KnowledgeSync retrieve
     all the records created “today” and then search through those to see which ones it had
     already sent alerts about.)

Pervasive & Providex SQL Date Formatting

     Pervasive SQL and Providex databases typically store their dates in "YYYY-MM-
     DD" format. This if you wish to compare a date value from one of these databases to
     a KnowledgeSync date substitution variable, you would typically use a variable such
     as:
     {%Current Date YYYY-MM-DD%}

Creating a Parameter-Driven Filter

     Example: “priority is equal to ?”




                                     Query Designing                                           136
                       MAKING A FILTER “PARAMETER-DRIVEN”

As was discussed in an earlier section (“Query Filter Parameters”), you can design a
query so that its filters allow the query to be used in multiple events, as in a query
that can be used in one event that checks for sales greater than $25,000, and in a
second event that checks for sales greater than $50,000, and in a third event that
checks for sales greater than $100,000.
The way to accomplish this is through the use of filter “parameters.”
A filter parameter – represented by the ‘?’ symbol – indicates that the compare value
of a particular query filter will be specified on the event level. This is what enables a
single query to be used in multiple events, each with a different filter parameter
value.
It is important to note that any filter that is parameter-driven will require that a
compare value be specified at the time that the event is configured. (KnowledgeSync
will not prompt for this value at the time the event is run.)
Once the event is fully configured and activated, the parameter value will have a
specific value which will be used each and every time that the event is executed.
Note: The following operators may not be used with parameters:
       One of
       Between
       Null
To set up a filter to be parameter-driven, follow these steps:
     Make sure that a ‘?’ appears in the “Compare Value” field.
     Move to the last column in the filter grid, titled “Optional Prompt.”
      The optional prompt is the text that will appear (on the event level) when this
      query is selected for use with an event. When a query that has one or more
                              Query Designing                                       137
            parameter-driven filters is selected for an event, the person configuring the
            event will receive a prompt informing them that they need to supply a
            compare value for this filter. The text of this prompt is defined here.
           Delete the default optional prompt text and key in your own text. Typical
            optional prompts include:
               “Select a Priority:”
               “Status is:”
               “Forecast Date Range Begins:”
               “Sales of Greater than How Much?”

Checking a Column Against a “Changed” Value

    Please Note: The ability to identify when a field’s value has changed does not
    include the ability to detect when a new record is added to a database.
    To identify when a new record is added, you should use either use a query that
    monitors a “create date” field (if the record has one), or you should use
    KnowledgeSync’s ability to “remember” what records have been processed and
    which records (i.e., new ones) have not been processed.
    Example: “credit status has changed”
    The manner in which KnowledgeSync knows whether a database field has “changed”
    is as follows:

         When the event is first run, KnowledgeSync stores the current value of one
          or more pre-determined fields which you wish to monitor for a change.

         The next time KnowledgeSync checks the value of these fields, it compares
          the “new current value” of these fields to the “old values” that are stored
          from the previous check. If the two values are different, KnowledgeSync
          considers the value as changed.

         If the values are different, KnowledgeSync replaces the “old value” that it
          has been storing with the “new current value”. And so the cycle begins again.

    Please read the following important notes about using “Change-Based” queries in
    KnowledgeSync:

        1. A query may check for changes made to any fields within the primary
           database table for that query. The primary database table is the first table
           listed in the “Links” tab.

        2. To enable a query to use change-based logic, the query must conform to the
           following rules:

                a. It must have a unique column.
                b. The unique column cannot be a calculated or otherwise edited field
                   (it must just contain the “table.column” name).


                                    Query Designing                                         138
        c. The unique column’s default “Customized Name” (which is equal to
           the column’s name) must not be changed from the default value.

3. The application/database that you are monitoring via KnowledgeSync may
   already support an “auditing” function that allows it to record database
   changes.

    If so, it is suggested that you build KnowledgeSync queries to monitor that
    database’s audit table records rather than using KnowledgeSync changed-
    based queries. This will be a much more efficient way to trigger change-
    based alerts, and it will eliminate audit data redundancy.

4. The database that you are monitoring via KnowledgeSync may contain the
   ability to execute stored procedures when a database field is changed. If so, it
   is suggested that you use this database function to populate an audit table of
   field-based changes within that database.

    As in item #3, you would then build KnowledgeSync queries to monitor that
    database’s audit table records rather than using KnowledgeSync changed-
    based queries. This will be a more efficient way to trigger change-based
    alerts, as it will enable KnowledgeSync to avoid scanning through every
    record in a database table for potential changes.

5. If you do create change-based queries in KnowledgeSync, be aware that
   KnowledgeSync will store the value of a database field according to the last
   time that it was checked (for a change) by any query. Thus it is very
   important that if you have multiple events that are checking for a change in
   the same database field, these events must be scheduled to run at the exact
   same time (e.g., every day at 9:00 AM).

6. KnowledgeSync can check to see if a field value has changed, or if a field
   value has changed to a specific value. And if a field can contain only a set
   number of valid values, KnowledgeSync can also check to see if a field value
   has changed from one or more a specific values.

7. A single query can check to see if the value in a single field has changed, or
   if the value in multiple fields have changed. Note, however, that if you select
   multiple “change” fields for a single query, KnowledgeSync assumes an
   “OR” relationship between them.

    (This means that a single query that checks for changes in a client’s credit
    status, ship via, or payment terms would trigger an alert if ANY of those
    three values changed. If you wish to notify different people (or take different
    actions) based upon different fields changing, you should create one query
    for each field whose value you wish to monitor for a change.)

8. If a query includes one (or more) “change-based” filters and one (or more)
   standard filters, KnowledgeSync assumes an “AND” relationship between
   them.

    (For example, if a query is checking to see if a “credit status” field has

                            Query Designing                                       139
             changed and the query is also checking to see if the “customer type” is equal
             to “distributor”, the query will retrieve only those records whose credit status
             has changed and whose customer type is equal to distributor.)

         9. Any event(s) that use a change-based query should be certain to have the
            “repeat” function (“Repeat Notification for Triggered Items”) turned on. If
            turned off, the event will trigger only the first time a field is changed; if
            turned on, the event will trigger each time the corresponding field is changed.

         10. A query whose “unique ID” is a concatenated or calculated field cannot use
             the “if column values have changed” functionality.

         11. When you Preview a query, KnowledgeSync ignores the “change” filter
             parameters.

         12. If a query is using the “If Column Value Has Changed” functionality, the
             corresponding button at the bottom of the Filters tab will appear underlined.

Selecting a “Changed” Field

     To create a filter that checks to see if the value of a database field has changed since
     the last time KnowledgeSync checked it, you must go to the bottom of the Filters tab
     and click on the button called “If Column Values Have Changed . . . ”.

     You’ll see a window such as the following:




                                 CHECKING A FIELD TO SEE IF ITS
                                       VALUE HAS CHANGED

     Note that only the columns that you have selected from the query’s primary database
     table are available to be selected from this list (i.e., the columns for the first table
     selected in your list of linked tables).
     To select the field(s) whose value you wish to check for a change, simply highlight
     (single-click on) the field from the column on the left and then click on the right-
     arrow button to move that field to the column on the right.



                                     Query Designing                                         140
     To remove a field which you have selected (and appears in the right-hand column),
     simply highlight the field from the column on the right and then click on the left-
     arrow button to move that field back to the column on the left.
     Once you are done selecting “change” fields, click on the OK button to return to the
     query Filters tab.
     You do not have to specify any additional filters for this query if the only thing you
     wish to check for is a “change” made to the selected field(s). However, you may add
     additional filters to this query, including a filter that refines your “change” selection
     to check for only those records whose content has changed to a specific value.

Specifying a “Changed To” Value

     By combining KnowledgeSync’s ability to check to see if a field’s value has changed
     along with KnowledgeSync’s ability to check to see if a field has a current value of
     ‘x’, you can create a query filter that checks to see if a field has changed to a specific
     value. To do so, follow these steps:
          Create your “change” filter (e.g., “if a client’s credit status changes”)
          Create a standard filter that checks to see if the field’s value is equal to ‘x’
           (e.g., “if a client’s credit status equals ‘hold’”)
          When KnowledgeSync runs this query, it will first check to see if a client’s
           credit status has changed, and then it will also check to see if the current
           value of the client’s credit status is equal to “hold”. (In other words,
           KnowledgeSync will check to see if the client’s credit status has changed to
           “Hold”.)
     Note that you can combine any kind of “standard” filters with change-based filters.
     (E.g., you could check to see if a client’s credit limit has changed and the limit is
     greater than $100,000.)
     Using the previous illustration as the first-part of a “changed to” filter, the following
     illustration shows how a standard filter would complete this scenario:




                                      Query Designing                                            141
                                 CHECKING A FIELD TO SEE IF ITS
                            VALUE HAS CHANGED TO A SPECIFIC VALUE


Storing & Reporting On “Changed” Values

     If you wish to be able to store the history of when a “changed value” event has been
     triggered, it is suggested that you use the “Create File” action to create such a history
     audit trail.
     By using the “Create File” action, you can tell KnowledgeSync to store the details of
     what records were changed, when they were changed, and what the old and new
     values for the change are. Later on, when you wish to report on the history of
     changes for a specific event, it’s simply a matter of reviewing the contents of this file.

Operator Notes

     Of KnowledgeSync’s 10 operators, five require a few additional notes.

Operator: “One Of”

     The “one of” operator allows a person to test a column for any one of multiple
     values.
     “One of” tends to be most useful in “and/or” situations such as the following:
             Send an alert for any calls that are open
             and have a priority of ‘A’ or ‘B, or ‘C’.
     This is a perfect requirement for the use of “one of”. The corresponding event would
     have one filter that checks to see if a call is “open” and a second filter (using the “one
     of” operator) that checks for any one of the three different priority codes.

                                      Query Designing                                         142
     To use the “one of” operator, follow these steps:
          Select “one of” from the operator list.
          Click in the “Compare Value” field and click on the list button that appears
           there.
          The first thing you need to do is to remove the ‘?’ as a compare value. In the
           box titled “One of the Following Values”, click on the ‘?’ and then click on
           the “Remove Compare” button.
          You are now ready to begin entering your selected compare values. You may
           either type in the individual compare values (pressing ‘Enter’ after each
           entry), or you may choose the compare values from the drop-down list.
          Click on “OK” when complete
     Note that the “one of” operator may not be parameter-driven; you must specify the
     compare values for a filter using this operator on the query level.

Operator: “Between”

     Note: Not all databases and/or ODBC drivers support the “between” operator.
     Vineyardsoft suggests that you use the combination of the “greater than or equal to”
     and “less than or equal to” operators in place of the “between” operator wherever
     possible.
     If you do use the “between” operator, follow these steps:
          Select “between” from the operator list.
          Click in the “Compare Value” field and click on the list button that appears
           there.
          Enter your two selected compare values. You may either type in the
           individual compare values (pressing ‘Enter’ after each entry), or you may
           choose the compare values from the drop-down list.
          Click on “OK” when complete
     Note: The “between” operator may not be parameter-driven; you must specify the
     compare values for a filter using this operator on the query level. Vineyardsoft
     suggests using two filters on the same field (one with “greater than or equal to” and
     the other with “less than or equal to”) in place of the “between” operator.

Operator: “Starting With”

     The “starting with” operator enables you to locate any database records that have a
     field whose value starts with a certain string of letters, numbers, and/or symbols.
     For example, you could create a query to retrieve any clients whose mailing address
     postal code begins with “070”. Or, you could create a query to retrieve any clients
     who purchased any products beginning with the characters “Epak”.
     To use the “starting with” operator, follow these steps:
          Select “starting with” from the operator list.


                                     Query Designing                                         143
          Click in the “Compare Value” field and type in the first few characters of the
           string that you wish to use for matching purposes.
     Note that the “starting with” operator may be parameter-driven simply by leaving the
     ‘?’ in the compare value field. If you do make this filter parameter-driven, be sure to
     specify a helpful optional prompt, such as “Part Numbers Starting With:”.

Operator: “Like”

     The “like” operator is similar to the “starting with” operator except that it enables
     you to locate any database records that have a field whose value contains a certain
     string of letters, numbers, and/or symbols.
     Please note the difference between “starting with” and “like”:
     “Starting with ‘brit’” will retrieve “Britain” and “Britannia” but not “New Britain”.
     “Like ‘brit’” will retrieve all three values.
     To use the “like” operator, follow these steps:
          Select “like” from the operator list.
          Unlike the “starting with” operator, when you use the “like” operator you
           need to enclose the string of text that you are searching for within percent
           signs, as in “%brit%”. Enter your compare value using this format.
     Note that the “like” operator may also be parameter-driven simply by leaving the ‘?’
     in the compare value field. If you do make this filter parameter-driven, be sure to
     specify a helpful optional prompt, such as “Part Numbers that Contain the Letters:”.

Operator: “Null”

     When designing KnowledgeSync queries, you might find the need to check to see if a
     specific field value is blank. It’s important to remember that a blank value in a
     database field can often be interpreted in two ways: as blank, and as null.
     To test a field for a blank value, you simply leave the compare value field blank (be
     sure to remove the default question mark).
     To test a field for a null value, follow these steps:
          Select “null” from the operator list.
          Blank out any value in the compare value field.
     Note that if you are not sure how a specific application identifies an “empty” field,
     you might want to create a query with two filters – one filter that tests the field for a
     blank value, and another filter that tests the field for a value of “null”.

Using Calculated Fields in Filters

     Using a calculated field in a filter is done is the same manner as creating a calculated
     field as a query column. All you need to do is click on the button called “Add
     Calculated Column to Filter”. For example:



                                      Query Designing                                            144
Let’s say that you wanted to create a filter that tests an opportunity’s weighted value.
You would take these steps:
     Click on the “Add Calculated Column to Filter” button. This will bring you
      into the Calculated Column Editor.
     Select the column that contains the opportunity’s forecast amount. This field
      would then appear in the Editor’s “workbox”.
     In the workbox area, type in an asterisk (*) after your selected field name.
      (The asterisk is the multiplication symbol.)
     From the window listing available column names, select the field that
      contains the opportunity’s probability of closing (e.g.,
      “opportunity.probability”).
     The column name now reads:
      opportunity.amount*opportunity.probability
     You can now continue to specify the operator and compare value just like
      any other filter.
The following is an example of the Calculated Column Editor window:




                             CALCULATED COLUMN EDITOR

And the following is how a calculated field appears in the filter tab:




                                Query Designing                                        145
                            USING A CALCULATED FIELD IN A FILTER

    Note that calculated fields can be used in both the column name field and in the
    compare value field. Note also that calculated fields may be parameter-driven (i.e.,
    you can use them in conjunction with the ‘?’ in the compare value field).
    Note also that as in the “Columns” tab, you can use an “embedded select statement”
    instead of a column name. Please refer to the section on embedded selects detailed
    earlier in this chapter.
    (You can also access the Calculated Column Editor for an existing filter by simply
    clicking in the “Column Name” field and clicking on the Edit Button that appears
    there.)

And/Or Logic

    As mentioned previously, the combination of the “and/or” selection on the “Filters”
    tab, plus the use of the “one of” operator addresses a great deal of the “and/or” logic
    that you might require in your query. In some instances, however, you might need to
    specify more complex “and/or” conditions such as:
    Retrieve orders for greater than $99 with freight charges less than < $5,
    or:
    orders with freight charges less than < $5 shipping via Fedex
    This type of “and/or” logic requires the ability to “group” filters together, using
    parenthetical expressions. This function is supported within the “Filters” tab, but
    requires a few extra steps.
    Using the example shown above, here are the steps that would be required to create
    the corresponding query:
         Create the four filters that the query will need:

                                    Query Designing                                           146
        1. Orders greater than $99
        2. Freight charges less than $5

            and:

        3. Freight charges less than $5
        4. Orders shipping via Fedex
     Filter #1 should have an “and” (to link the first two conditions).
     Filter #2 should have an “or” (to separate the first two conditions from the
      last two conditions)
     Filter #3 should have an “and” (to link the last two conditions)
     Click in the “Column Name” field of filter #1 and place a left parentheses in
      front of the column name.
     Click in the “Compare Value of filter #2 and place a right parentheses after
      the compare value.
     Click in the “Column Name” field of filter #3 and place a left parentheses in
      front of the column name.
     If the compare value is a character or date value, click in the “Compare
      Value of filter #4 and place single quotation marks around the compare
      value. (If the compare value is a number, you do not need the quotation
      marks.)
     Place a right parentheses at the end of the compare value
     If the compare value is a character or date value, change the “Data Type”
      value for the fourth filter to “Literal.” (If the data type is “number” you may
      leave things as they are.)
Your filters tab will look like the following:




                                Query Designing                                       147
                               A QUERY WITH “GROUPED” FILTERS

    The most important thing to remember about “grouping” filters for “and/or” logic is
    that if the last filter in a parenthetical group is testing the value of a character or date
    field, you must be sure to enclose the compare value in single quotation marks and to
    change the data type to “Literal.”
    If the last filter in a parenthetical group is testing the value of a numeric field, (e.g., if
    in the previous example the “ship via” is identified by a numeric code instead of a
    name), your filters tab would look like the following:




                                      “GROUPED” FILTERS II

Using SQL-Related Functions

    In addition to creating calculated fields, you can also include a wide variety of SQL-
    related functions within your filters. These include (but are not limited to) such
    functions as calculating the number of days since something has happened (or until
    something is scheduled to happen), field concatenation, trimming extraneous spaces,
    and converting dates to strings and vice versa. Additional information is contained in
    the section titled “Field Editing Notes” earlier in this chapter, and you should also
    refer to your database manual for details on these and other functions.

Query Sub-Filters
    Sub-filters are not used with record-level queries; they are used only with aggregate
    queries and thus will be discussed in the section on aggregate queries.

Query SQL
    Note: Although KnowledgeSync allows you to enter (or modify) the SQL for a
    query, this is NOT the recommended manner for creating your queries, as direct SQL
                                 Query Designing                                      148
editing is not supported by Vineyardsoft’s technical support staff if a problem with
this SQL is encountered.
The “SQL” tab allows you to look “under the covers” and review the SQL syntax that
a query is executing. There is rarely (if ever) the need for you to make any changes to
a query’s SQL, and there is no requirement for you to use this tab to enter or modify
a query’s SQL. (And Vineyardsoft strongly suggests NOT manually editing the SQL
for a query, since once you do so, all subsequent changes to the query MUST be done
through the SQL tab.)
You can review a query’s SQL by clicking on the “SQL” tab; if you do wish to
manually edit the SQL syntax, you need to place a checkmark in the “I would like to
manually edit the SQL for this query” box. A query’s SQL will appear like the
following:




                                  QUERY “SQL” TAB

Once you activate the manual editing of SQL syntax, any modifications that you
make to any of the other query definitions tabs (the tables, links, columns, sorting,
filters, and subfilters tabs) will not be retained.
If you do edit a query’s SQL syntax and then remove de-activate the manual editing
of SQL syntax (i.e., remove the checkmark from the “I would like to manually edit
the SQL for this query” box), KnowledgeSync will automatically re-constitute the
SQL syntax based on the content from the other query definition tabs. (Note that you
will need to remove the checkmark, click off of the SQL tab, and then back onto the
SQL tab to see the re-constituted SQL syntax.)
If you do have a need to manually edit a query’s SQL, here are a couple of
suggestions about modifying the SQL syntax:
       Go through all the standard KnowledgeSync Query Designer tabs before you
        begin editing the SQL syntax. This way, you have a pre-built foundation of
        your SQL statement that you can edit, as opposed to building the SQL
        statement from scratch.
                               Query Designing                                     149
           You can include database (and ODBC driver) specific functions in your SQL
            syntax.
           Once you are done modifying the SQL syntax, be sure to select the
            “Preview” option to verify the successful execution of your query.
           If you are manually editing the SQL, the only query data fields that your
            event will have access to are those columns that are referenced within the
            SQL statement itself.
           Make sure that before you start editing the SQL that you have identified a
            “Unique” column for the query on the “Columns” tab.

Using a Stored Procedure in a Query

    If you wish to use a stored procedure in a KnowledgeSync query (instead of a SQL
    “select statement”), you can do so within the “SQL” tab.
    To do so, follow these steps:
         Place a checkmark in the “I would like to manually edit the SQL for this
          query” box.
         Type in the procedure name, as in “dbo.myprocedurename”
         To pass parameters into your procedure, use the following syntax:
            “dbo.myprocedurename param1,param2,param3”
            (Parameters that are string values must be enclosed by apostrophe symbols.)

Query Preview
    One of the most useful tabs in the Query Designer is “Preview” – it lets you verify
    that the query you are designing will retrieve the specific records you wish it to.
    Note: Preview mode ignores any “change-based” filters you have configured.
    Preview mode can be used as many times as you wish when building a query; once
    you have selected some tables and columns, the preview mode will be available to
    you.
    Hint: Don’t wait until you have built every aspect of a query to preview it; use the
    preview function repeatedly as you add more and more elements to a query and begin
    to refine its selection criteria.
    When you click on the “Preview” tab, KnowledgeSync will automatically return any
    records that meet your query’s filters criteria. If the preview tab is blank (containing
    no records), it means that KnowledgeSync was not able to locate any records that
    meet your query’s criteria.
    When Preview mode returns matching records, it will appear similar to the following:




                                    Query Designing                                            150
                                 QUERY “PREVIEW” TAB

(It’s always advisable to go into your underlying database and add a record (or two)
that meets a query’s criteria so that you can be sure that the query is working as
required.)
If you receive an error message when previewing a query, it means that
KnowledgeSync was not able to successfully execute your query. The most common
reasons for this are:
       The ODBC source for this application was not correctly configured
       Multiple tables for this query were not correctly linked
       Your query includes one or more calculated fields that contain invalid SQL
        syntax
       You have specified an invalid customized name for a query column
       You have specified an invalid filter (such as trying to compare the value in
        an alphanumeric field to a date)
       You have edited the underlying SQL and introduced a syntax error
       You have referenced a SQL function or formula that is not supported by the
        ODBC driver you are using
Most of the error messages that the preview mode returns will give you a clue as to
where the error exists; to help pinpoint the error you can begin to remove individual
query elements and try to preview the query after each removal. Once the error no
longer appears, you will have found the erroring component.
Note that if your query includes parameter-driven filters, you will be prompted to
enter corresponding values for those filters; as in the “Filters” tab you will be able to
manually enter a value for such a filter, you will be able to choose a value from a
drop-down list, or (if the filter requires a date value), you will be able to choose any
one of KnowledgeSync’s date substitution variables.
                                 Query Designing                                            151
Saving a Query

   To save your query, click on the “Save and Close” button at the top-left of your
   window. If you wish to save this query and begin immediately working on your next
   query, click on the “Save and New” button.


Copying a Query

   Since many queries can be similar in design, it is very important to know how to
   copy one query to another. Follow these steps:
        Open the Event Manager window (not the Navigator window), expand the
         application that contains the query you wish to copy, locate the query and
         highlight (single-click on) the one you wish to copy.
        Go to the “Edit” menu and select “Copy.”
        Go to the “Edit” menu again and select “Paste.”
        A duplicate of the query will now appear in the query list in the Event
         Manager. Go into either of the two (identical) queries and modify it as
         needed – and don’t forget to change the query’s description!
   Note that you may not only copy queries within a KnowledgeSync application, but
   you may also copy queries from one KnowledgeSync application to another.


Deleting a Query

   Before deleting a query, you should make sure that there are no events that use the
   query you are about to delete. If you delete a query that is linked to an event, the
   event will fail to execute successfully the next time it is scheduled to run.
   To delete a query:
          Open the Event Manager window (not the Navigator window), expand the
           application that contains the query you wish to delete, locate the query and
           highlight (single-click on) the one you wish to delete.
          Click on the “Delete” button at the top of your window.
          (You may also delete a query by going into the query you wish to delete and
           clicking on the “Delete” button at the top of your window.)
   Note that there is no “Undo” option once you have deleted a query.


Scrolling Through Your List of Queries

   In some instances, you might need to scroll sequentially through a list of queries
   (e.g., if you wanted to activate or de-activate a series of queries). Although you could

                                   Query Designing                                        152
    select each query individually, edit it, save it, and then select the next query, there is
    a faster way to do this.
    Once you have selected and edited your first query, click on the “Previous” or “Next”
    buttons instead of on the “Save and Close” button.
    If you have made changes to the current query, you will be prompted to save (or
    abandon) your changes before proceeding. Once you have answered this prompt, you
    will be taken into the previous (or next) sequential query and will be allowed to
    continue editing in this manner.


Aggregate Queries

    As discussed at the start of this guide, aggregate queries are queries that are triggered
    by a group of records that collectively meet a certain condition. For example:
           More than 10 open service calls with a priority of “critical”
           Fewer than 5 scheduled activities per salesrep next week
           Salesreps with more than $500,000 in their pipeline
    Unlike record-level queries, aggregate queries do not retrieve “details” about
    individual records that are triggered; instead, aggregate queries are triggered by the
    aggregate condition being met. For example:
           An aggregate query designed to be triggered only if there are more than 10
            open service calls with a critical priority would (as it results) retrieve the
            number “12” (if there were 12 critical, open support calls.)
           An aggregate query designed to be triggered only if there are any salesreps
            with fewer than five scheduled activities next week would retrieve “Smith
            4”, “Jones 1”, and “Davidson 3” (if Smith had 4 scheduled activities, Jones
            had 1, and Davidson had 3).
    Please note that aggregate queries can not use the “change-based” filtering options
    available in record-level queries.

The Results of an Aggregate Query
    The results of an aggregate query look quite different from the results of a record-
    level query for the simple reason that an aggregate query does not display record-
    level details.
    Here are some samples of output that you might see from an aggregate query.
           Query: “More Than 5 Orders Today Over $10,000”
            Result: “17” (the number of orders today over $10,000)

           Query: “More Than 5 Orders Per Region Today Over $10,000”
            Result:           “6      Northwest”
                              “7      Southeast”

                                     Query Designing                                             153
                             “26     Southwest”

           Query: “More Than 5 Orders Per Region & Rep Today Over $10,000”
            Result:          “7      Southwest”       Karen Chavez”
                             “11     Southwest”       Mark Davidson”
                             “8      Southwest”       John Langley”

Aggregate Query Configuration
    Note: Please read through the process of record-level query designing before
    proceeding with the following sections. The instructions on aggregate query
    configuration assume that you are familiar with record-level query design.
    The following sections will address the set-up of an aggregate query. In those areas
    where the set-up of an aggregate query is identical to that of a record-level query, the
    documentation will refer the reader to the corresponding section for full details.


Creating & Naming a New Aggregate Query
         Single-click on the “Query Definitions” branch.
         Click on the “New Query Definition” button at the top-left of your window.
            In the “Query Description” field, key in a description of the query you are
            adding and press your tab key. The description that you entered will be
            copied into the “Display Description” field.
         Click on the “Active” checkbox to indicate that this query can be used in an
          event.
    The following illustration shows the Description tab of an aggregate query.




                                    Query Designing                                        154
                           AGGREGATE QUERY “DESCRIPTION” TAB

Note: Aggregate Query Naming Conventions

    Just as with record-level queries, it is important to choose logical, easy-to-locate
    names for your aggregate queries. One standard approach that is commonly used with
    KnowledgeSync aggregate queries is to follow the format:
           Data Object; Description
        As in:
           Opptys; Too Many Overdue
           Opptys; Low Avg Price
           Opptys; High Forecast

Aggregate Query Tables
    Unlike a record-level query, an aggregate query requires fewer tables of information
    since the results of an aggregate query do not include record-level details. There are,
    however, a few items you need to consider when identifying the tables for an
    aggregate query:
           What data will be evaluated by the aggregate function?

            If you’re going to “count” support calls, you’ll need the “call” table. If you’re
            going to “summarize” (or accumulate) sales figures, you’ll need the
            “opportunity” table. Identify the value that the aggregate will be performed
            on, and be sure to select the table that contains that value.
           Will the aggregate value be “grouped” by another field?

            In many aggregate queries, the aggregate value is “grouped” by another field,
                                    Query Designing                                           155
            such as “sales per region” or “calls per product.” If this type of “grouping” is
            to occur, be sure to identify the grouping field and to include its table in the
            query.
           Do you need to include the table(s) that contain the address(es) (such as
            e-mail address(es)) of the person(s) you wish to alert?

            Just like a record-level query, an aggregate query can also be designed to
            send an alert to persons who are associated with the triggered record. (For
            example, you might wish to have an aggregate query that totals sales per
            region send an alert to the regional sales manager.)

            If this is the case, be sure to include the table that contains the delivery
            address(es) of the person(s) who are to be notified when this query is
            triggered.
    To select a table for a query, go to the list of Available Tables and double-click
    (select) the desired tables. A selected table will appear on the right side of the Tables
    tab.

Links (for Aggregate Queries)
    Linking (or “joining”) tables together for an aggregate query is done in the same
    manner as for a record-level query. Please refer to the earlier section titled “Query
    Links” for details.

Aggregate Functions
    KnowledgeSync supports five aggregate functions:
           Summarize
           Average
           Count
           Maximum
           Minimum
    With the exception of the “count” function, all of these aggregate functions
    must be applied to numeric fields only.
    The following sections will detail each of these functions.

Aggregate Function: “Summarize”

    The “summarize” function lets you accumulate (or total) the record amounts for a
    numeric field. This function would be used for such queries as:
           Salesreps with less than $50,000 in their pipeline
           More than 1,000 minutes of support calls this week
           Less than 500 widgets sold last month



                                    Query Designing                                         156
                            AGGREGATE “SUMMARIZE” FUNCTION:
                              TOTAL SALES PER SALESPERSON


Aggregate Function: “Average”

    The “average” function lets you derive the numeric average for a numeric field from
    multiple records. This function would be used for such queries as:
           Salesreps whose average sale price is less than $5,000
           Clients whose average support call is over 30 minutes long
           Suppliers who average more than 5% damaged goods




                                   Query Designing                                        157
                              AGGREGATE “AVERAGE” FUNCTION:
                               AVERAGE SUPPORT CALL LENGTH

Aggregate Function: “Count”

    The “count” function lets you count the number of records that meet certain
    conditions. This function would be used for such queries as:
           Salesreps with fewer than 10 scheduled activities this week
           Clients with more than 3 late payments this year
           More than 5 sales opportunities that are overdue for closing
    The count function is handled a little differently from the other aggregate functions as
    you should always apply the count function to the field that uniquely identifies the
    records to be counted. Using the preceding three examples, this means that:
           For activities, you’d apply the count function to the “activity ID” field
           For payments, you’d apply the count function to the “payment no” field
           For sales, you’d apply the count function to the “sale ID” field




                                    Query Designing                                       158
                             AGGREGATE “COUNT” FUNCTION:
                            NUMBER OF ACTIVITIES PER SALESREP

Aggregate Function: “Maximum” & Minimum

    The “maximum” and “minimum” functions let you identify the maximum or
    minimum record values for a numeric field. This function is for such queries as:
           The maximum sale closed last week
           The minimum order quantity this week




                       AGGREGATE “MAXIMUM/MINIMUM” FUNCTION:
                           MAXIMUM SALE PRICE PER SALESREP
                                   Query Designing                                     159
Aggregate Grouping
    Consider this scenario:
    You want to trigger an event if next week’s forecast sales is greater than $100,000.
    Solution: Create an aggregate that summarizes all sales due to close next week.
    But now consider this:
    You want to trigger an event if any salesreps have forecast sales of greater than
    $100,000.
    Solution: Create an aggregate that summarizes sales and groups them by salesrep.
    The ability to create aggregates that group (or “sort”) resulting records by one or
    more specific fields is one of the most powerful aspects of aggregate queries.
    Consider how you can take an ordinary aggregate query such as “total sales for next
    week” and create the following just by adding one or more “group by” fields:
           Total sales by salesrep
           Total sales by region
           Total sales by product line
           Total sales by region and (within region) by product line
           Total sales by regional sales manager
    All of KnowledgeSync’s aggregate functions support grouping, but grouping is most
    commonly used in “summarize”, “average”, and “count” aggregates.

Aggregate Query Columns
    Unlike a record-level query where you choose columns based primarily on the fields
    of data that you wish to put in an outgoing alert message, an aggregate query’s
    columns are selected based on the following three criteria:
           The field that the aggregate function will be performed on
           The “group by” field(s)
           Other fields to appear in the alert message, fields that contain an alert
            recipient’s address, or fields that will be used in workflow / database update
            response actions.

A Query With Multiple Aggregate Columns

    Note that an aggregate query may include more than one aggregate column. For
    example, an aggregate query may both count the number of open opportunities
    greater than $25,000 and may total the value of these opportunities.
    If a query will be using multiple aggregates, the aggregates must be listed first (in the
    “Columns” tab) and the “group by” fields must be listed after the aggregates.



                                      Query Designing                                        160
Column Selection: “Summarize” & “Average”

    To select columns for an aggregate “summarize” or “average” query, follow these
    steps:
         Go to the list titled “Available Columns to Query”
         Select the numeric field whose value you wish to total or whose average you
          wish to derive the average of (e.g., “sales amount”). Note that the aggregate
          column should always be the first column selected.
         Click next to the word “Normal” in the Column Type field. Display the drop-
          down list and select either “Summarize” or “Average.”
         Move to the “Customized Name” field. By default, this field will contain the
          name of the selected column (e.g., “amount”). Change the name to reflect
          that this field contains an aggregate total (e.g., “amount_total” or
          “amount_avg”).

            (Note: Do not put the name of the aggregate function at the start of a
            customized name – e.g., “total_amount” or “avg_amount” – as many ODBC
            drivers identify aggregate functions as reserved words and do not permit
            them to appear at the start of a customized name.)
         Go back to the list titled “Available Columns to Query” and select your first
          “group by” field (e.g., “salesrep”). This query will now total (or derive the
          average for) the amount in your first column (sales amount) and group it by
          the value in your second column (salesrep).
         If needed, add more “group by” columns to this query.

Column Selection: “Count”

    To select columns for an aggregate “count” query, follow these steps:
         Go to the list titled “Available Columns to Query”
         Select the unique or record-identifying column for the table whose records
          you wish to count. Note that the aggregate column should always be the first
          column selected.
         Click next to the word “Normal” in the Column Type field. Display the drop-
          down list and select “Count.”
         Change the “Customized Name” field as needed (see previous section).
         Select your “group by” fields.

Column Selection: “Minimum” & “Maximum”

    The aggregate functions “minimum” and “maximum” are configured in the same
    manner as both “summarize” and “average”. Please refer to the instructions for those
    aggregates for details.




                                   Query Designing                                        161
Additional Column Selections

    Here are a few hints for choosing additional columns in your aggregate query:
           Try to make your “group by” field as informative as possible. For example,
            in a scenario where you wish to display total sales per salesrep, you should
            not make your “group by” field the salesrep’s ID (which is probably some
            cryptic code), but rather the salesrep’s full name.

            This might require you to add another table to this query (such as the
            “salesperson” table), but it is well worth it as it will make the query’s output
            much more usable.
           You may wish to be able to send the results of this query to the individuals
            that are identified within the query (i.e., if the query identifies “Paul” as a
            salesrep with a lower-than-expected pipeline, you want to send an alert to
            Paul). To do so, you need to include the columns that contain the delivery
            address(es) that the alert will be sent to. (The fields than contain Paul’s e-
            mail address, fax number, et cetera.)
           You can create a query with multiple aggregate fields. For example, if you
            wanted to create a query that counted the number of orders last month and
            showed the total of all those orders and showed the average order price, you
            could create a single query that uses the “count” and “summarize” and
            “average” functions.

            (Another such example would be to create a query that counted the number
            of regions whose total forecast sales for next month is below quota.)

            Make sure that you list your aggregates before you select any “group by”
            fields.

The “Unique” Field

    The “Unique” field does not apply to aggregate queries; you may skip specifying a
    unique column for an aggregate query.

Aggregates and Calculated Fields

    Calculated fields may be used with aggregate queries in the same manner that they
    are used with record-level queries. For example:
           You could create a query that uses a calculated field to identify any activities
            that are overdue by more than seven days, and then use the “count” function
            to identify how many activities are overdue by that many days.
           You could create a query that uses a calculated field to identify the “weighted
            value” of an opportunity and then use the “summarize” function to identify
            the total “weighted” forecast for a salesrep.
    For details on creating a calculated field, please refer to the previous sections on
    Calculated Fields. Once you have created such a field, you may then apply the
    appropriate aggregate function to it.

                                    Query Designing                                            162
Query Sorting Order (for Aggregate Queries)
    Sorting the order of an aggregate query’s matching records is done in the same
    manner as for a record-level query. Please refer to the earlier section titled “Query
    Sorting Order” for details.

Query Filter Overview (for Aggregate Queries)
    Consider the following condition:
        Send an alert if there are more than six open, high priority support calls.
    There are two levels of testing (or “filtering”) that need to occur in the underlying
    query. First, you need to make sure that only “open” and “high priority” calls are
    eligible to be considered by the query.
    This is referred to as testing the record-level conditions and would be done by
    defining the query’s filters as shown in the following illustration:




                                  AGGREGATE QUERY FILTERS

    But secondly, you need to check to see if there are “more than six” open, high
    priority support calls.
    This is referred to as testing the aggregate condition, and this is done by defining the
    query’s “sub-filter.”




                                    Query Designing                                            163
Query Filters (for Aggregate Queries)

     Creating record-level filters for an aggregate query is done in the same manner as for
     a record-level query. Please refer to the earlier section titled “Query Filters” for
     details.
     Note: You cannot use the “If Column Values Have Changed” filter function in
     aggregate queries.

Query Sub-Filters
     Sub-filters are used only with aggregate queries; they allow you to test the value of
     the aggregate condition. For example, by using a sub-filter on an aggregate query,
     you can transform the following informational queries:
            Total forecast sales per salesrep next month
            Average sale price for widgets
            The number of open support calls per call agent
     Into the following queries that pinpoint critical conditions:
            Total forecast sales of less than $10,000 per salesrep next month
            Average sale price of more than $25 for widgets
            More than 10 open support calls per call agent
     To create a sub-filter for an aggregate query, follow these steps:
          Click on the “Sub-Filters” tab.
          Column Name. Go to the list of “Available Columns to Filter” and double-
           click on the aggregate column you created earlier.
          “Is” or “Is Not”. By default, KnowledgeSync checks the column to see if it
           meets a certain condition. To change the “is” function to “is not”, simply
           click next to the word “is” and choose “is not” from the drop-down list.
          Operator. KnowledgeSync provides 10 operators that you can choose from.
           (See the section titled “Operator Notes” under record-level query designing
           for more details on individual operators.)
          Compare Value. The “Compare Value” field is where you place the value
           against which KnowledgeSync will compare the selected column’s value.
           The compare value field may contain a constant value, it may contain the
           value from another database field, it may contain a date substitution value, or
           it may contain the question mark. (See the section titled “Compare Values”
           under record-level query designing for details.)
          Type. The “type” field identifies the type of data that this filter is
           processing; this can include “character” based data (i.e., alphanumeric data),
           numeric data, or date-formatted data. KnowledgeSync automatically fills in
           the value of this field for you.

             The “Literal” data type is used only if you are comparing one column against
             the value in another column, or against an SQL function. (See the section

                                     Query Designing                                         164
            titled “Comparing a Column Against Another Database Field” under record-
            level query designing for details.)
         “And / Or”. Since a single query can include multiple filters,
          KnowledgeSync gives you the ability to specify “and/or” logic in the
          sequence of your sub-filters.
         Optional Prompt. The optional prompt field is used only with a query sub-
          filter that is parameter driven (has a ‘?’ in the Compare Value field). See the
          section titled “Creating a Parameter-Driven Filter” under record-level query
          designing for details.)




                               AGGREGATE QUERY SUB-FILTERS

Query SQL (for Aggregate Queries)
    Reviewing and/or modifying an aggregate query’s SQL syntax is done in the same
    manner as for a record-level query. Please refer to the earlier section titled “Query
    SQL” for details.

Query Preview (for Aggregate Queries)
    Previewing an aggregate query is done in the same manner as for a record-level
    query. Please refer to the earlier section titled “Query Preview” for details.
    The following is the sample Preview results from a query that counts the number of
    open support calls:




                                    Query Designing                                         165
                              AGGREGATE QUERY PREVIEW MODE


Multi-Query Events

   As discussed previously, a single query can be used in multiple events; use of filter
   parameters allows a single query to be used with various parameter thresholds in
   different events.
   It is also possible, however, for a single event to use multiple queries. Consider the
   following three examples:
          An event that is triggered if the total forecast sales for next quarter is more
           than $300,000 and if the count of pending sales of at least $20,000 is more
           than 10.
          An event that is triggered if a client has purchased less than $5,000 worth of
           products over the last six months, and if that same client has also called into
           support more than 25 times.
          An event that is triggered if a client has open sales opportunities in a CRM
           application, and if that same client is also on credit hold in a financial
           application.
   Each of these events requires two queries each.
   The first event requires an initial query that totals the forecast sales for next quarter
   (to see if they are greater than $300,000), and a subsequent query that counts the
   number of sales over $20,000 (to see if there are more than 10).
   The second event requires an initial query to total a clients pending sales (and see if
   they are less than $5,000), and a subsequent query to see if any of those customers
   also have recorded more than 25 support calls.

                                    Query Designing                                            166
    And the third event requires an initial query to identify which clients have pending
    sales opportunities, and a subsequent query to see if any of those clients are also on
    credit hold.
    The first example (an event that is triggered if the total forecast sales for next quarter
    is more than $300,000 and if the count of pending sales of at least $20,000 is more
    than 10) requires no linking between the queries; both queries merely need to prove
    true in order for the event to trigger.
    (KnowledgeSync automatically assumes an “and” correlation between multiple
    queries in a single event; KnowledgeSync does not currently support an “or”
    correlation between multiple queries.)
    In the second and third examples, however, the queries must be linked to each other;
    that is, data from the first query must be passed into the second query in order to
    identify whether there are any records that meet the conditions of both queries.
    Note: Field-level change queries cannot be linked to any other queries.

Multi-Query Events that Are Not Linked
    If you need to design more than one query that will be used in a single event, the first
    thing you need to identify is whether the queries will need to “pass” data between
    them. Consider the example given earlier:
           An event that is triggered if the total forecast sales for next quarter is more
            than $300,000 and if the count of pending sales of at least $20,000 is more
            than 10.
    This event requires two queries, but the queries do not need to be linked to each other
    in any manner. Both queries simply have to prove true (be “triggered”) in order for
    the event as a whole to be triggered.
    An event of this nature would require you to create two aggregate queries. Once the
    queries are created, you could then create the corresponding event and choose to
    associate both queries with that event.
    Note: When multiple queries are associated with an event, both queries must prove
    true (i.e., be triggered) in order for the event as a whole to be triggered. You cannot
    specify “and/or” logic between multiple queries chosen for an event.

Linking Queries from the Same Application
    When designing queries that identify more complex conditions of data, you will
    occasionally notice that you cannot configure a single query to handle every
    condition that you need it to check for.
    Sometimes this can be a result of needing to check for a combination of multiple
    aggregate conditions, such as:
           An event that is triggered if a client has purchased less than $5,000 worth of
            products over the last six months, and if that same client has also called into
            support more than 25 times.


                                     Query Designing                                          167
     In this scenario, you would require one query that performs a “summarize” aggregate
     on a client’s sales, and you would also require a second query that performs a
     “count” aggregate on the client’s number of support calls.
     What differentiates this example from the example in the preceding section is that
     you need to take the records that result from the first query (“clients who have
     purchased less than $5,000 worth of products”) and ‘feed’ those records into the
     second query to see if any of those clients have also called into support more than 25
     times.
     This is what is meant by “linking” queries together; it is the process of ensuring that
     the records that are retrieved by query #1 are fed into query #2. Without this link,
     your first query would retrieve one set of matching clients, and your second query
     would retrieve a second set of matching clients, and you wouldn’t be able to see
     which clients met both conditions.

How Do You Link Queries from the Same Application?

     The first step that is required in linking queries from the same application is to
     identify the field of data that “links” records from both queries. Consider the
     following example again:
            An event that is triggered if a client has purchased less than $5,000 worth of
             products over the last six months, if that same client has also called into
             support more than 25 times.
     Clearly, the field that will link both queries together is the “client” field.
     What KnowledgeSync will do is this:
            Retrieve any clients who have purchased less than $5,000 worth of products
             over the past six months
            Take each of those clients and see if any of them have also called into
             support more than 25 times
            Generate a result set of any clients who meet both conditions

How To Design Linked Queries

     Designing linked queries requires a couple of extra steps when creating both the
     initial query (also sometimes called the “Link from” query), and the secondary query
     (sometimes called the “Link to” query).
     We will use the scenario detailed in the preceding section as our example in
     designing a linked query.

Design The Initial Query

     The first step in designing linked queries is to design the first query in a linked set.
     The first query (such as “Clients Who Have Purchased Less Than $5,000 Over the
     Past Six Months”) is designed just like any normal, aggregate query. There is just one
     extra step you need to take:
          Go to the “Columns” tab of the query you are designing.
                                 Query Designing                                                168
          Make sure that you have included the “linking field” as one of the columns
           for this query. (Using the preceding example, we would need to include the
           “client ID” column in this query.)
          Make a mental note of (or write down!) the Customized Name of the linking
           field (e.g., “CLIENTID”).
          That is all we need to do on the first query.

Design The “Link To” Query

     The second step in designing linked queries is to design the query that will receive
     information from the first query.
     Note: Although the first (or “Link from”) query can be used both as a stand-alone
     query and as the first query in a set of two (or more) queries, the second (or “Link
     to”) query cannot be used as a stand-alone query, and can only be used after an
     appropriate “Link from” query.
     The second query (such as “Clients Who Have Called Into Support More Than 25
     Times”) is also designed just like any normal, aggregate query. This query, however,
     requires one additional filter – and this is a filter that will restrict it to only those
     records that have been retrieved by the initial (Link from) query. Follow these steps:
          Go to the “Filters” tab of the “Link to” query you are designing.
          Add a filter for the linking field (e.g., for the “Client ID” field).
          Select an operator of “is equal to”.
          In the Compare Value field, key in (enclosed in curly braces)
           the customized name of the linking field from the initial query
           (e.g., “{CLIENTID}”.)
          That’s all there is to it.
     By designing your “link to” query in this manner, it will automatically use the results
     of query #1 as part of its selection criteria.
     The following is an example of the Filters tab on a “link to” query:




                                        Query Designing                                      169
                              “LINK TO” QUERY FILTER SYNTAX

Query Linking Notes

     Please make note of the following:
           If you design your “link to” query in this manner, it will execute successfully
            only if it follows a preceding query containing the appropriate customized
            name. Do not use this query stand-alone in an event; it will not execute
            successfully.
           Make a point to give your “link to” queries clearly identifiable names. In the
            preceding example, you might wish to call this query
            “Link To; Closed Accts”..
           In the Compare Value field where we entered the customized name of the
            link to field, you might wish to enter a ‘?’ and make the value parameter-
            driven. This allows you to more easily test this query (by choosing a valid
            client ID), and you can always specify the link to field “{CLIENTID}” on
            the event level, when you are prompted to supply a value.
           You are not limited to just two levels of linking; you could, for example,
            have an event that checks for clients who have purchased less than $5,000
            worth of product, have called into support more than 25 times, and whose
            average support call length is greater than 10 minutes.

            (This would require an event using three queries; you would have to link
            query #1 to query #2, and then query #2 to query #3.)
           The second query of a linked set should not use a “group by” value. For
            example, if the second query is going to “count” the number of activities
            completed for a specific client over a specific time period, the query should

                                   Query Designing                                           170
            have only a single column (the field to be counted) and the filter will perform
            the linking function. The query should not include both a “count” column
            and a group by column.
           The second query cannot be used to retrieve “advanced” subscriber
            information. This information must be retrieved by the initial query.

Data Manipulation Between Linked Queries
    One of the special benefits of linking queries together is that it enables you to use
    data from query #1 in query #2. Consider the following example:
    You are using a CRM application and a Financial application. When a new sales
    opportunity is placed in the CRM application, you want KnowledgeSync to take the
    value of that opportunity and to add it to the client’s current balance in the Financial
    application and then see if that total is greater than the client’s credit limit.
    When you link queries together, data from the first query can be used in the second
    query in the following places:
         In the “Columns” tab. You can create calculated columns in your second
          query in which the calculation utilizes one or more fields from the first
          query.
         In the “Filters” and “Sub-Filters” tabs. You can create filters and sub-filters
          in your second query in which the filter column or the filter “compare value”
          utilize one or more fields from the first query.
    The following is an illustration of the example detailed above:




                                    Query Designing                                         171
                        DATA MANIPULATION BETWEEN LINKED QUERIES

    Note also that when an event uses multiple queries, all of the data fields (from all
    related queries) are available to be used in the event’s alert messages, as report
    selection criteria, and is available to be used in the event’s workflow / database
    update actions.

Linking Queries from Different Applications
    Linking queries from different applications is one of KnowledgeSync’s unique
    strengths, as it enables you to check for a combination of conditions across multiple
    applications that may have little (or no) integration between them.
    For example:
           An event that is triggered if a client has open sales opportunities in a CRM
            application, and if that same client is also on credit hold in a financial
            application.
    This scenario requires one query that checks for a client’s open sales, and a second
    query that checks to see if that client is on credit hold.

How Do You Link Queries from Different Applications?

    Linking queries across applications is no different from linking queries within the
    same application: you still need to identify the common field that will enable
    KnowledgeSync to take records from the first query and feed them into the second
    query.


                                    Query Designing                                         172
     Consider the example we are working with:
            An event that is triggered if a client has open sales opportunities in a CRM
             application, and if that same client is also on credit hold in a financial
             application.
     Clearly, the field that will link both queries together is the “client” field.
     The key here is that unlike two queries that are retrieving information from the same
     application, you might have to do a little research to find a field from both
     applications that contain the same value.
     Using the previous example, you would need to locate a field containing the same
     value in both applications that uniquely identifies each client. This might be:
            The client’s account number
            The client’s phone number
            The client’s name
            The client’s e-mail address
     If the applications that you wish to link queries between do not contain a common
     field of data, you should consider adding a custom field (such as an account number)
     to one or the other application.
     Note that the fields with which you are linking the queries do not have to have the
     same name; i.e., a field could be called “client ID” in one application and “account
     number” in another, but as long as they contain the same value, KnowledgeSync will
     be able to successfully link the queries.

Design The Initial Query

     The first step in designing cross-application linked queries is to design the first query
     in a linked set.
     The first query (such as “Clients; Pending Sales”) is designed just like any normal,
     record-level query. There is just one extra step you need to take:
          Go to the “Columns” tab of the query you are designing.
          Make sure that you have included the “linking field” as one of the columns
           for this query. (e.g., “Account Number”)
          Make a mental note of (or write down!) the Customized Name of the linking
           field (e.g., “ACCOUNTNO”).
          Now let’s move on to the “link to” query.

Design The “Link To” Query

     The second step in designing cross-application linked queries is to design the query
     that will receive information from the first query.
     The second query (such as “Clients; On Hold”) is also designed just like any normal,
     record-level query. This query, however, requires one additional filter that will
     restrict it to only those records that have been retrieved by the initial query. Follow
     these steps:
                                      Query Designing                                        173
        Go to the “Filters” tab of the query you are designing.
        Add a filter for the linking field (i.e., for the “Client ID” field).
        Select an operator of “is equal to”.
        In the Compare Value field, key in (enclosed in curly braces) the customized
         name of the linking field from the initial query (e.g., “{ACCOUNTNO}”.)
        That’s all there is to it.
   By designing your “link to” query in this manner, it will automatically use the results
   of query #1 as part of its selection criteria.
   Please be sure to read the notes earlier in this section titled “Query Linking Notes”
   for additional information.


Database Triggers

   Database triggers (which are embedded in external applications) are useful for
   knowing when records are added or changed, for triggering responses in extremely
   large databases, and for triggering “real-time” responses.
   Because KnowledgeSync provides a way to call the execution of its events from
   outside of the KnowledgeSync system, it does support database triggers, should an
   organization wish to use them.
   (Refer to the chapter titled “KnowledgeSync Utilities” for details on how you can call
   the execution of a KnowledgeSync event from outside of the KnowledgeSync
   application.)
   Please use the KnowledgeSync on-line knowledgebase (available from the
   Vineyardsoft website) to get examples of database triggers and their integration with
   KnowledgeSync.




                                      Query Designing                                      174
                                                            CHAPTER 5
                                   Subscriiber Maiintenance
                                   Subscr ber Ma ntenance


Event Subscribers

    A KnowledgeSync subscriber is a person who is eligible to receive information
    and/or alerts from KnowledgeSync as the result of triggered events. Another term for
    a subscriber is “alert recipient.” Subscribers may receive notifications via e-mail, fax,
    page, PDA, phone, web browser, screen pop, and FTP (copied files).
    Subscribers can be set-up (and maintained) within KnowledgeSync, they can be
    imported from external applications, or they can be linked from any external
    applications to KnowledgeSync.


Who Can Be a Subscriber?

    Although most organizations think of using KnowledgeSync to send alerts to
    members of their own organization (i.e., employees), KnowledgeSync has the ability
    to send alerts beyond the borders of a single organization, to include such people as
    business partners, vendors and/or suppliers, customers, and prospects.
    It is important as you configure KnowledgeSync subscribers that you consider the
    types of events that you will be configuring within KnowledgeSync and who the
    potential recipients of those events will include.

Using KnowledgeSync for Target Marketing
    Since KnowledgeSync has the ability to send alerts to customers and prospects just as
    it can notify an organization’s internal employees, it is important to consider the
    possibility of using KnowledgeSync as an aid in your direct marketing efforts.
    Consider the following scenarios:
           Notify a client when they are within ‘x’ dollars of a bonus program
           Notify a prospect about a limited-time offer about to expire
           Notify all clients using product ‘x’ about a new add-on module ‘y’
    These are all examples of types of events whose purpose is to keep clients and
    prospects better informed about marketing-related activities that are occurring within
    your organization.


                            Subscriber Maintenance                                       175
    As you go through the configuration of subscribers within KnowledgeSync, continue
    to think about how KnowledgeSync’s ability to intelligently (and selectively) contact
    customers and prospects alike can impact the success of your organization.

Designating a Computer as a Subscriber
    In addition to setting up people as subscribers, KnowledgeSync also allows you to
    designate that one or more computers will be the recipients of information when an
    event is triggered.
    Using KnowledgeSync’s FTP (“copy”) delivery method, you can instruct
    KnowledgeSync to move certain files and/or reports to specific disk and directory
    specifications on one or more computers when an event is triggered.


How Are Subscribers Categorized?

    When defining KnowledgeSync subscribers, you may wish to categorize the
    subscribers according to similar areas of work. This is done through the creation of
    “subscriber groups.” For example, you might wish to create the following subscriber
    groups:
           Engineering
           Customer Service
           Executives
           Sales
           Clients in the State of California
           Prospects
    There is no limit to the number of subscriber groups that can be configured within
    KnowledgeSync; so too can you create “nested” groups of subscribers as in the
    following example:
           Engineering
             Development
                     New Products
                   Maintenance
               Quality Assurance
               Documentation
    One of the benefits of subscriber groups is that instead of configuring an event to
    send an alert to 10, 20, or 100 individual users, you can configure an event to alert all
    the members of one or more groups. It’s also important to note that a single event can
    send alerts to any combination of individual subscribers and groups of subscribers.




                              Subscriber Maintenance                                     176
Subscriber Alert Methods & Addresses

    As mentioned earlier, each subscriber can be configured to receive alerts via up to
    five different methods. These are:
           E-Mail
           Fax
           Pager
           FTP (called “Copy”)
           Webcast (via web browser)
    (Note that KnowledgeSync can also send information to PDAs, cellular phones, and
    to users via a “screen pop”.)
    Additionally, each subscriber may have up to two (2) delivery addresses per delivery
    method. This means that each subscriber may have:
           Two E-Mail addresses
           Two Fax numbers
           Two Pager numbers (and PINs)
           Two FTP locations
           Two Webcast locations
    The reason for the availability of two addresses per method is to allow a subscriber to
    have different delivery addresses based on the time of day and day of the week.
    For example, an employee named John Smith of “Acme Incorporated” may wish to
    receive e-mail alerts at smith@acme.com if an alert happens between 8 AM and 5
    PM on Monday through Friday, but he may wish to receive e-mail alerts at
    jwsmith@hotmail.net if an alert happens outside of those days and hours.
    The same could be true for a person who is receiving alerts via any of the other
    methods.
    These two delivery addresses (per delivery method) are referred to within
    KnowledgeSync as the “primary” and “secondary” addresses. If a subscriber does not
    have a secondary address for a given delivery method, you may wish to use the
    primary value in both the primary and secondary fields.

A Note About Webcasting (Dashboard Alerts)
    KnowledgeSync contains an alert method called “webcasting” – this is the ability for
    KnowledgeSync to generate web (html) pages that contain alert information as
    opposed to (or in addition to) sending the messages via e-mail, fax, or pager.
    This component (also called “dashboard Alerts”) requires its own configuration and
    set-up. The following pages will not discuss webcasting, as it is detailed in a separate
    chapter.



                             Subscriber Maintenance                                       177
Subscriber Entry Methods: Overview
    There are three ways that subscribers can be configured within KnowledgeSync; an
    organization may choose to use one or any combination of these methods:
           Manual entry
           Subscriber import
           Subscriber linking
    The following sections provide an overview of these three methods.

Manual Entry
    KnowledgeSync contains a “Subscriber Maintenance” option which allows an
    authorized KnowledgeSync user to manually add, change, and delete subscriber
    profiles.
    This method will be discussed in detail in the section titled “Manually Entering
    Subscribers.”

Importing Subscribers
    If an organization already has subscriber data that resides in one or more tables
    (within one or more ODBC-compliant databases), you can choose to import that data
    into the KnowledgeSync subscriber database.
    A few important notes about importing subscriber data:
        1. Data can be imported from multiple sources. For example, you might wish to
           import data from a “users” table within a sales application, from an
           “employees” table within a financial application, and from a “suppliers” table
           within a manufacturing application.
        2. In order to import data, the table whose data you wish to import must itself
           reside within an ODBC-compliant database.
        3. You can import data as often as you wish, but the import process is done
           manually (i.e., you cannot schedule it).
        4. Imported data should include a subscriber’s name and some information
           about their “delivery addresses” (such as their e-mail address, pager number,
           et cetera).
    The process of importing subscriber data from an external database will be discussed
    in more detail in the section titled “Importing / Linking Subscribers.”

Linking to a Subscriber Database
    “Linking” to a subscriber database is very similar to importing subscriber data,
    except that instead of transferring subscriber data from an external application into
    KnowledgeSync, the “linking” function allows KnowledgeSync to directly read
    subscriber details from a table in another database.

                             Subscriber Maintenance                                     178
    Subscriber linking is very powerful as it allows an organization to avoid having to
    maintain subscriber data within KnowledgeSync; subscriber data can continue to be
    maintained in external applications (such as in sales, finance, or manufacturing
    applications), but this subscriber data will be available for use within
    KnowledgeSync.
    This function is referred to as a “dynamic link” because KnowledgeSync will retrieve
    the appropriate subscriber information (from the corresponding database(s)) at the
    precise moment when a KnowledgeSync event is triggered and an alert message
    needs to be delivered to that subscriber. This ensures that KnowledgeSync always has
    the most up-to-date subscriber data to use with triggered events.
    Linking subscriber data from an external database follows much of the same
    guidelines as importing subscriber data, and will be discussed in more detail in the
    section titled “Importing / Linking Subscribers.”


Subscriber Definition: Preparation

    The following steps should be followed in preparation for creating subscriber
    records.

Step #1: Identify Means of Entry
    The first step is to identify the means by which subscriber data will be entered into
    KnowledgeSync. As previously outlined, your choices are:
           Manual entry
           Import
           Link
    Depending on the method that you choose, you will need to follow the instructions in
    the following sections.

Step #2: Manual Entry
    If you will be entering some (or all) subscriber records via manual entry, you will
    need to gather the following information for each subscriber you wish to set up:
           Subscriber’s name, company name, and title
           Subscriber’s primary and secondary e-mail, fax, pager, and FTP addresses
           The days of the week (and hours of the day) when the subscriber will receive
            alerts via their primary method or their secondary method. (Note that a
            subscriber can have different “days” and “hours” for the primary and
            secondary addresses of each delivery method.)

            The days of the week (and hours of the day) when the subscriber is
            unavailable to receive alert messages.



                             Subscriber Maintenance                                       179
Step #3: Imported / Linked Entry
    If you will be entering some (or all) subscriber records via the Import or Link
    methods, you will need to do the following:
           Make sure that the database that includes the external subscriber data is
            defined as an “application” within the KnowledgeSync Event Manager
           Identify the fields within the external subscriber table that contain the
            subscriber’s name, company name, title, and primary and secondary e-mail,
            fax, pager, and FTP addresses
           Identify the days of the week (and hours of the day) when the subscriber will
            receive alerts via their primary method, via their secondary method, or will
            be unavailable to receive alerts.


Subscriber Entry Worksheets

    The following worksheets are designed to help you identify the necessary elements
    that are required for the creation of KnowledgeSync subscribers.
    Note that the following two pages contain two Subscriber Entry Worksheets; the first
    worksheet is designed for the manual entry of subscribers; the second is designed to
    help you identify the needed components for subscriber importing and/or linking.
    Feel free to make copies of the following two worksheets.




                             Subscriber Maintenance                                     180
                        Subscriber Data Worksheet:

Subscriber Name: ______________________________________________________________
Company Name: _______________________________________________________________
Title:   ________________________________________________________________________
Phone: ________________________________________________________________________


E-Mail Address (Primary): ______________________________________________________
Days & Hours to Use Primary: ___________________________________________________
E-Mail Address (Secondary): _____________________________________________________
Days & Hours to Use Secondary: __________________________________________________


Fax Number (Primary): _________________________________________________________
Days & Hours to Use Primary: ___________________________________________________
Fax Number (Secondary): _______________________________________________________
Days & Hours to Use Secondary: __________________________________________________

Pager Vendor (Primary): ________________________________________________________
Pager PIN (Primary): ___________________________________________________________
Days & Hours to Use Primary: ___________________________________________________
Pager Vendor (Secondary): ______________________________________________________
Pager PIN (Secondary): _________________________________________________________
Days & Hours to Use Secondary: __________________________________________________


Copy/FTP Location: (Primary): ___________________________________________________
Days & Hours to Use Primary: ____________________________________________________
Copy/FTP Location: (Secondary): _________________________________________________
Days & Hours to Use Secondary: ___________________________________________________




                               Subscriber Maintenance                               181
             Subscriber Importing / Linking Worksheet:

Application That Contains Subscriber Data: _______________________________________
Table That Contains Subscriber Data: ____________________________________________


                                  Field That Contains:

Subscriber Name: ______________________________________________________________
Company Name: _______________________________________________________________
Title: _________________________________________________________________________
Phone: ________________________________________________________________________


E-Mail Address (Primary): _______________________________________________________
E-Mail Address (Secondary): _____________________________________________________


Fax Number (Primary): _________________________________________________________
Fax Number (Secondary): _______________________________________________________


Pager Vendor (Primary): ________________________________________________________
Pager PIN (Primary): ___________________________________________________________
Pager Vendor (Secondary): ______________________________________________________
Pager PIN (Secondary): _________________________________________________________


Copy/FTP Location: (Primary): __________________________________________________
Copy/FTP Location: (Secondary): ________________________________________________




                              Subscriber Maintenance                                 182
Subscriber Maintenance

    Once you have completed one or more worksheets for the design of subscribers, you
    are ready to go into the KnowledgeSync Event Manager and configure subscriber
    data.
    Log into the Event Manager Navigator and you will be presented with the main
    Navigator window. Expand the branch called “Subscribers” to display the list of pre-
    configured subscriber groups.




                                  “SUBSCRIBERS” BRANCHES

Subscriber Group Maintenance
    As detailed earlier, you can organize your subscribers into logical groups; each group
    can contain individual subscribers, or it can contain one or more other groups.
    If you are importing and/or linking subscribers, please note that each “import” or
    “link” must be associated with a unique group.
    Although you can add subscribers to the pre-configured groups that are defined
    within KnowledgeSync, you can also create and modify additional groups of your
    own. Please note that if you plan on importing and/or linking to subscriber data, you
    should create additional subscriber groups for each link or import that you plan on
    creating.




                             Subscriber Maintenance                                      183
Adding a Subscriber Group

    To add a subscriber group, follow these steps:
         In the KnowledgeSync Navigator, right-click on the “Subscribers” branch.
         Select “New User Subscriber Group”.
         Key in a name or description of the new group you are creating and click on
          “OK”.

Changing a Group’s Name

    To change the name of a subscriber group, follow these steps:
         Display the subscriber group branch whose name you wish to change.
         Right-click on that group and select “Properties”.
         Change the group’s name and click on “OK”.

Deleting a Subscriber Group

    Caution: Before deleting a subscriber group, make sure that no events are
    configured to send alerts to anyone within that group, or to the group as a whole.
    Also be certain to check to see if the subscriber group is either linking or importing
    subscribers, and remove the import or link before deleting the subscriber group.
    To delete a subscriber group, follow these steps:
         Open the Event Manager (not Navigator) module.
         Single-click on the subscriber group branch which you wish to delete.
         At the top of the Event Manager window, click on the “Delete” button.
         Confirm that you do wish to delete the selected record.


Subscriber Maintenance

    Note: Even if you will not be manually entering subscribers into the
    KnowledgeSync database, it is recommended that you review the following sections
    as they detail all of the fields of data pertaining to KnowledgeSync subscribers.




                             Subscriber Maintenance                                     184
Manually Entering Subscribers
    The first method of adding and maintaining subscribers in the KnowledgeSync
    database is through manual entry.
    You can configure the KnowledgeSync subscriber database to include a combination
    of manually-entered subscribers, imported subscribers, and linked subscribers.

Adding a Subscriber

    To add a subscriber, follow these steps:
         In the KnowledgeSync Navigator, expand the “Subscribers” branch.
         Navigate to the group to which you wish to add the subscriber.
         Right-click on that group and select “New User”.




                                  SUBSCRIBER DESCRIPTION
         Fill in the user’s name, company, title, and related information. If you wish
          this user to be able to be selected as an alert recipient, click on the “Active”
          checkbox.

            Make sure that the “Full Name” field has a value, as this is the value
            that is used when subscribers are listed elsewhere in the application.

            (If the subscriber is a computer, fill in the computer’s name, description, and
            IP address.)

            See the following section for details on the use of the “User Lookup Key”
            field.

                             Subscriber Maintenance                                     185
          Key in the appropriate address information (e-mail, fax, pager, copy, and
           webcast) for the user (or computer) you are creating.

             Note that if you enter a primary delivery address and press your tab key, the
             primary address will automatically be copied into the secondary address
             field.




                                  SUBSCRIBER “E-MAIL” TAB
          Note the grid in each of the “address” tabs; this is where you can specify
           which address (primary, secondary, both, or none) will be used based upon
           the time of day and day of the week when an alert occurs. Notice that the grid
           scrolls down to display times after 6 AM.

             The grid is divided into 30 minute segments for each day of the week; within
             each segment you can specify whether you wish to use the primary delivery
             address (‘1’), the secondary address (‘2’), both addresses (‘*’), or neither
             address (blank out the value).

             Notice also that you have four grid manipulation buttons that you can choose
             from:
                    Use Address 1 (the primary address) for all segments
                    Use Address 2 (the secondary address) for all segments
                    Use Both Addresses for all segments
                    Restore the system default grid selections
          Click on the “Save and Close” button at the top-left of your window.

About the “User Lookup Key” Field

     Consider the following scenario:




                              Subscriber Maintenance                                   186
     You have a customer support application that tracks which calls are assigned to
     various support reps. Each support rep is identified by a unique ID as well as a non-
     unique “group” code (such as the “Frontline” group).
     The support application does not store the corresponding rep’s e-mail and other
     notification addresses anywhere in the application.
     When a support call meets a condition that warrants an alert to the corresponding
     support rep, you need the following to occur:
          KnowledgeSync looks at the triggered record and finds the corresponding
           rep’s “ID” and “group name”.
          KnowledgeSync “looks up” the matching KnowledgeSync subscriber record
           (based on the rep’s ID) and the matching subscriber’s group (based on the
           rep’s group name) in the KnowledgeSync subscriber database
          KnowledgeSync alerts the corresponding support rep and/or group
     Thus the use of the “User Lookup Key” field is to allow you to designate a unique
     value that identifies this user for the purpose of linking them to a database record.

Using a “Group” Lookup Key

     Just like the “User Lookup Key” addressed previously, KnowledgeSync can also
     look at a field within a database record and identify the value of that field as equating
     to a KnowledgeSync subscriber group.
     For example, an organization might have four support “groups” and might have an
     event that identifies any group that has more than 20 open calls. If a group is found to
     have more than 20 calls, you want KnowledgeSync to send an alert to all the
     members of the corresponding KnowledgeSync subscriber group.
     To do so, you simply have to make sure that the “group” names that exist in your
     support application are reflected (exactly) in the names of KnowledgeSync subscriber
     groups. (KnowledgeSync is case-sensitive.)
     Thus if a KnowledgeSync event detects that two out of the four support groups have
     more than 20 open calls, KnowledgeSync will take the two group names from the
     triggered event, look for matches in KnowledgeSync subscriber group names, and
     (assuming that matches are found), KnowledgeSync will send alerts to every member
     of those groups.

“Copy” Method Notes

     The “copy” (also referred to as “FTP”) method allows KnowledgeSync to move files
     and Crystal Reports (both of which may be attached to triggered events, or scheduled
     on a periodic basis) to specific locations (disks and directories).




                               Subscriber Maintenance                                     187
                                   SUBSCRIBER “COPY” TAB

     The copy location should be specified using standard UNC format
     (as in “//computername/sharename”). You may also specify an FTP address, using
     the format ftp://username:password@ftp.location.net/directory_name. Do not
     reference any mapped drives in your location specifications.

“Paging” Method Notes

     Important: Many paging vendors allow pages to be sent to their subscribers via e-
     mail as well as by the traditional method of dialing out through a modem.
     KnowledgeSync supports both methods for sending alerts via pager.
     Note: KnowledgeSync supports SMS paging.
     Before you can configure a subscriber to receive alerts via pager, you must configure
     KnowledgeSync to integrate with the various paging services that your organization
     uses.
     The configuration of these paging services consists of defining such information as
     the paging service vendor name, the access (or TAP) phone number for the paging
     service, an optional access password, and other modem configuration settings.
     All of this information is defined in the KnowledgeSync Administration module,
     under the option for “Software Setup  Paging Services.”
     Once you have defined these services, you may then go into a subscriber record and
     select a valid paging service, as well as that subscriber’s individual personal
     identification (or PIN) number as shown the following illustration.




                              Subscriber Maintenance                                   188
                                     SUBSCRIBER “PAGE” TAB

“Webcasting” Method Notes

     The configuration of the “webcasting” alert message delivery method requires a
     separate set of steps that you need to take in order to configure the webcasting
     module. Please refer to the chapter on Webcasting” for instructions.

About the “Subscriptions” Tab

     The “Subscriptions” is an informational listing of all the events that this subscriber is
     currently signed-up to receive alerts about. Please note that this list is informational;
     you cannot add or remove events to this list from here, nor can you alter the methods
     by which the subscriber is to be alerted about a given event.

Creating a “Template” Subscriber Record

     For organizations who are manually entering subscriber records, it will quickly
     become evident that there are certain fields of data that will remain the same from
     one subscriber to next – fields such as “company,” “active,” and (most importantly)
     the “grid” of which delivery address to use for different dates and times.
     Instead of editing each new record you create, you can establish (one or more)
     subscriber “templates” and then use those templates each time you add a new
     subscriber.
     To create a template, simply add a new subscriber and give it a name such as “User
     Template.” Modify the fields to reflect the common values that should be used in all
     new users, and then save that record.
     The next time you need to create a new subscriber and wish to use that template,
     simply copy that template instead of clicking on the “New User” button. (See
     “Copying Subscribers” for details.)

                               Subscriber Maintenance                                     189
Copying Subscribers

     Since many subscribers can be similar in design, it is very important to know how to
     copy one subscriber to another. Follow these steps:
          Open the Event Manager (not Navigator) module.
          Expand the group of subscribers that contains the subscriber you wish to
           copy.
          Highlight (single-click on) the subscriber you wish to copy.
          Go to the “Edit” menu and select “Copy.”
          Go to the “Edit” menu again and select “Paste.”
          A duplicate of the subscriber will now appear in the subscriber list in the
           Event Manager. Go into either of the two (identical) subscribers and modify
           it as needed – and don’t forget to change the subscriber’s name!

Deleting Subscribers

     Before deleting a subscriber, you should make sure that there are no events that send
     alerts to the subscriber you are about to delete.
     To delete a subscriber:
              Go into the subscriber you wish to delete and click on the “Delete”
               button at the top of your window.
     Note that there is no “Undo” option once you have deleted a subscriber.

Scrolling Quickly Through Your List of Subscribers

     In some instances, you might need to scroll sequentially through a list of subscriber
     (e.g., if you wanted to activate or de-activate a series of subscribers). Although you
     could select each subscriber individually, edit it, save it, and then select the next
     subscriber, there is a faster way to do this.
     Once you have selected and edited your first subscriber, click on the “Previous” or
     “Next” buttons instead of on the “Save and Close” button.
     If you have made changes to the current subscriber, you will be prompted to save (or
     abandon) your changes before proceeding. Once you have answered this prompt, you
     will be taken into the previous (or next) sequential subscriber and will be allowed to
     continue editing in this manner.

Importing / Linking Subscribers
     The second and third methods of adding and maintaining subscribers in the
     KnowledgeSync database is by importing or linking the subscribers from an external
     database to the KnowledgeSync database.
     The configuration for importing versus linking subscribers in KnowledgeSync is
     almost identical; the only difference is that the import function actually transfers the

                               Subscriber Maintenance                                     190
    data from an external application into KnowledgeSync, and the link function
    maintains a “live link” between the subscriber fields in the external application and
    the corresponding fields within KnowledgeSync.


Step 1: Create the Import / Link Query

    In order to import subscribers from (or link KnowledgeSync to) subscriber data in an
    external database, you need to first have a means of retrieving the necessary
    subscriber data from your external database. This is done via a KnowledgeSync
    query.
    You must design a KnowledgeSync query that retrieves the subscriber-related fields
    of data from your external application. The fields of data that you will need to
    retrieve (if available) include:
           Subscriber full name, last name, and first name
           Subscriber title, company name, and phone number
           Subscriber’s primary and secondary e-mail address(es), fax number(s),
            preferred copy locations, and pager service TAP number and PIN.
    The corresponding query should be designed just like any normal, record-level query;
    typically the query will include just the one table that contains subscriber data, it will
    include the fields shown in the previous list, and it may (or may not) contain filters to
    limit which subscriber records are retrieved. This query must have a “unique” column
    identified.
    (If, for example, you wish to import or link to only those users with a status of
    “active”, you could add a filter that performs this restriction.)
    It is important to preview this query to be sure that it is retrieving the precise records
    you wish, along with the specific fields of subscriber data that you require.

Step 2: Create the Import / Link Group

    For each group of subscribers that you will be importing or linking to, you should
    create a separate subscriber group. For example, if you are importing user data from
    an application called “Sales First”, you might wish to create a group called “Sales
    First Users” into which those subscribers will be placed.
     (Note that a subscriber group that does a link or import also allows you to manually
    add additional subscribers to that group. Thus you could have a “Sales First Users”
    group that imports 100 subscriber records from the Sales First application and yet
    also contains six manually-entered subscriber records.)

Step 3: Activate the Import Link Function

    Once you have created the query that will retrieve the external subscriber data as well
    as the subscriber group that will contain the individual imported or linked subscriber
    records, you are ready to begin the import or link process.



                              Subscriber Maintenance                                       191
    Follow these steps:

         Locate the group that will contain the imported / linked subscribers.
         Right-click on the group and select “Properties”.
         In the ensuing window that appears, click on the “Subscriber Linking”
          button.




                                SUBSCRIBER “LINKING” OPTION

Step 4: Choose the Import / Link Query

    The next step is the selection of the query that you designed earlier to retrieve the
    subscriber data from an external database. Follow these steps:
         Click on the “Select Query” button. You are shown a list of all the
          applications that are currently defined within the Event Manager.
         Since you can import or link to subscribers from any application that is
          defined in KnowledgeSync, you first need to choose which application your
          query is associated with. Select the appropriate application and you are
          shown a list of queries for that application.
         Select the query designed to retrieve subscriber data.
         Your next step is to “map” fields from your query to the corresponding fields
          in the KnowledgeSync subscriber database.




                              Subscriber Maintenance                                        192
                           SUBSCRIBER “LINKING” FIELD MAPPING

Step 5: Map the Subscriber Fields

    Now that you have chosen your query, all that remains is for you to tell
    KnowledgeSync which fields in your query equate to specific fields in the
    KnowledgeSync subscriber database.
    The left side of the Linking window displays a list of all of KnowledgeSync’s
    subscriber data fields. The right-hand side of this window enables you to choose
    which field will be mapped from the related query to a field within KnowledgeSync.
    To map a specific query field to a subscriber data field, simply go to the row that
    contains the KnowledgeSync subscriber data field you wish to map data into, move
    to the “Linked to Database Field” column, click in the corresponding field, and use
    the down-arrow to list the fields from the associated query. Choose the query field
    whose value you wish to map.
    Note that the same query field may be mapped to multiple fields within the
    KnowledgeSync subscriber database. For example, if your query contains only a
    single “E-Mail Address” field, you should map that field into both the
    KnowledgeSync subscriber “Email Address 1” and “Email Address 2” fields.
    Note that the “Full Name” field must have a value mapped to it, as the full name
    is used to list subscriber records when they are accessed elsewhere in
    KnowledgeSync.

Step 6: Save Your Link

    At the time you save a subscriber link, KnowledgeSync automatically executes the
    link and retrieves the corresponding subscriber records from your external database.

                             Subscriber Maintenance                                   193
    These records are then displayed on the list on the right-side of your Event Manager
    window.
    Be aware that the linking / importing process may take a few seconds to execute; you
    will see an informational message at the bottom left-hand corner of your window
    telling you that the “linking is in process”, after which the corresponding subscriber
    records will appear.

Choose to “Link” or “Import”

    Once you have finished mapping your subscriber data fields and have saved your
    work and retrieved a list of corresponding subscribers, KnowledgeSync assumes that
    these subscribers will continue to be retrieved via a dynamic link.
    This means that KnowledgeSync will maintain a “live link” between this group of
    subscribers and the external database in which they were retrieved, so that any
    changes made to those subscribers in the external database will automatically be
    reflected within KnowledgeSync.
    This also means that anytime KnowledgeSync needs to send an alert to one of these
    individuals that KnowledgeSync will perform a link to the external database to
    retrieve that person’s most up-to-date address information.
    If you do not wish KnowledgeSync to maintain such a link, but rather would prefer
    that these records be imported into the KnowledgeSync subscriber database, you
    need to take the following steps:
         Locate the subscriber group for which you wish to disable subscriber linking.
         Right-click on the group and select “Properties”.
         Click on the “Subscriber Linking” button.
         Click on the “Remove Subscriber Link” button.




                              SUBSCRIBER “LINKING” OPTIONS
         Click on the second option (“I would like to remove the subscriber link but
          leave the subscribers for this group in the KnowledgeSync database.”)
         Click on “OK”. The “live link” will now be removed, but the subscribers
          whom you imported will remain for you to send alerts to, and to maintain
          within KnowledgeSync.
                             Subscriber Maintenance                                    194
         (Please note that you must save your subscriber link data before removing
          the link. This enables KnowledgeSync to import the corresponding
          subscriber records (this is executed by the “save” function), after which you
          may go back into the subscriber linking option and remove the link.)

Removing a Subscriber Link

    When you remove a subscriber link, you have the option whether to retain the details
    of the individual subscribers (as detailed in the preceding section), or whether to
    remove both the link and the details of all corresponding subscribers.
    To remove both the link and the related subscriber data, follow these steps:
         Right-click on the subscriber group that has the associated link and select
          “Properties”.
         Click on the “Subscriber Linking” button.
         Click on the “Remove Subscriber Link” button.
         Click on the first option (“I would like to remove the subscriber link and all
          subscribers in this group from the KnowledgeSync database.”)

Editing Imported / Linked Subscribers

    If you create a group of imported subscribers (i.e., you create the link, retrieve the
    subscribers, and then remove the link but retain the subscribers), you will be able to
    edit and modify those subscriber records just like any manually-entered subscriber
    record.
    If you create a group of linked subscribers, however, only the grids of alert hours and
    days will be available for editing. All of the other fields of subscriber data will appear
    gray, indicating that their values are being retrieved from an external database and
    thus are unavailable for editing from within KnowledgeSync.


Creating “Intelligent” Subscriber Groups

    One of the important benefits of creating groups of subscribers using
    KnowledgeSync queries is that you can create “intelligent” groups of subscribers. For
    example:
           Clients in the state of California
           Prospects in the banking industry
           Suppliers who have pending backorders
    All of these “groups” utilize queries that have been designed to retrieve a specific
    sub-set of records. Just be careful on creating overly-complex subscriber groups,
    since KnowledgeSync evaluates the members of a group at the time an event is
    executed, an overly-complex subscriber query that runs through a database of
    thousands (or millions) of records could significantly slow down the execution time
    of that event.


                              Subscriber Maintenance                                      195
                                                          CHAPTER 6
                                                   Event Desiigniing
                                                   Event Des gn ng


Event Designing

   A KnowledgeSync event is an object that checks to see if certain conditions exist
   and (if the conditions prove true), the event executes one or more “response actions”,
   such as sending alert messages, generating and delivering forms, documents, and
   reports, executing application workflow and/or application updates, and executing
   other site-specific actions.


What Triggers an Event?

   A KnowledgeSync event can be triggered by:

       1. One or more records within an application database (or records between
          multiple application databases) meeting certain criteria
       2. Incoming e-mail messages meeting certain criteria
       3. Operating System data meeting certain criteria
       4. A schedule whose submission time has been met

   The first two of these items utilize a KnowledgeSync query to determine if the
   corresponding conditions have been met; item #3 utilizes a Visual Basic Script to
   determine if the corresponding conditions have been met, and item #4 utilizes a re-
   occurring schedule to determine if the event should be triggered.

   (Note that SQL Triggers can also be used to trigger an event within
   KnowledgeSync.)


What Happens When an Event is Triggered?

   When an event runs, its query may return one or more matching records. The event
   can then trigger three types of responses:
                It can send an alert
                It can generate and deliver a form, document, or report
                It can execute workflow to add or update records within one or more
                 application databases
                                Event Designing                                      196
      A very important step in event design is deciding how many times an event should
      trigger the preceding three responses. Consider, for example, an event that returns 10
      matching records.

              1. Do you want the event to trigger an alert for each record?
              2. Do you want the event to trigger the generation of one form, document,
                 or report for each record?
              3. Do you want the event to execute your workflow once for each matching
                 record?

      A KnowledgeSync event can be configured to trigger its response actions:

           Once for each matching record
           Once for a group of matching records
           Once for all matching records

      This is referred to as an event’s “trigger frequency”. An event’s “trigger frequency”
      applies to all response actions of an event; thus:

      An event configured to trigger once per matching record will trigger all of the
      response actions (generating forms, documents or reports, and/or executing
      workflow) once per matching record.

      An event configured to trigger once per group of matching records will trigger all of
      the response actions (generating forms, documents or reports, and/or executing
      workflow) once per group of matching records.

      An event configured to trigger once for all matching records will trigger all of the
      response actions (generating forms, documents or reports, and/or executing
      workflow) just once.

      If, in reviewing your needs, you identify some events that need to trigger one type of
      response ‘x’ times and a different type of response ‘y’ times (such as an event that
      should create a single alert message but should execute 10 workflow rules), you will
      need to create two versions of that event – one version that triggers once for all
      matching records, and one version that triggers once for each matching record.


The Components of an Event

      Events can generally be divided into the following five components:

          1. Query(ies): The condition(s) that must occur for the event to be triggered.
          2. Event Message Content: The information that will be delivered to one or
             more recipients if the event is triggered.
          3. Actions: The workflow and/or database update actions that will be executed
             if the event is triggered.


197                                 Event Designing
        4. Subscribers: The people who will be notified about a triggered event, and
           the method(s) by which they will be notified.
        5. Schedule: When (and how often) KnowledgeSync will check to see if the
           event’s conditions exist.
    The following sections provide an overview of each of these components.

An Event’s Query(ies)
    Although an event does not require a query, it is through the use of one or more
    queries that an event determines whether specific conditions have been met. Queries
    are used when an event’s triggering is to be based either on conditions within
    application databases, or within incoming e-mail messages.
    A single event may use a single query, or it may use multiple queries, depending on
    the complexity of the conditions that you wish the event to check for.
    Additionally, a single query may be used in one or more events (See the chapter on
    “Query Designing” for more details). Depending on how a query is designed, the
    person configuring an event may be prompted to specify certain threshold values
    (such as a date range) that the event’s triggering will be dependent upon.

An Event’s Message Content
    Each event may have its own message content. If an event’s triggering is based on
    conditions within application databases, within incoming e-mail messages, or within
    an organization’s operating system, the event’s message content may include data
    from the corresponding conditions that have caused the event to trigger.
    KnowledgeSync allows you to specify both the event message content as well as the
    method(s) by which this content will be delivered. These methods include:
           E-Mail
           Fax
           Pager
           Web Browser
           Screen Pop
           FTP
    As part of an event’s message content, KnowledgeSync lets you generate and deliver
    forms and documents (such as invoices or statements), the contents of one or more
    files (such as MS Word or MS Excel files) as well as the contents of one or more
    Crystal Reports that are related to the triggered event.

An Event’s Actions
    In addition to sending event message content, KnowledgeSync can also execute
    application workflow and site-definable processes when an event is triggered. This
    gives you the ability to:

                                 Event Designing                                     198
             Update database records when an event is triggered
             Add new database records when an event is triggered
             Move data from one application to another when an event is triggered
             Trigger application workflow procedures
      KnowledgeSync includes a wide variety of event “response action” toolsets so that
      you can customize the specific response actions to the needs of your organization.

An Event’s Subscribers
      If an event will be sending alerts or other information to one or more people, you
      need to tell KnowledgeSync who those people are, and via what method(s) they will
      be receiving their information. In KnowledgeSync, a recipient is referred to as a
      “subscriber,” and a subscriber may receive information via any one – or any
      combination – of the following methods:
             E-Mail
             Fax
             Page
             PDA / Cellular Phone
             Webcast
             Screen Pop
             Copy (FTP)
      As is detailed in the chapter titled “Subscriber Maintenance,” each event may be
      configured to send alerts to individual users, to groups of users, and to one or more
      computers.
      Additionally, events may be defined so that they notify one or more people who are
      “related” to the condition that is causing the event to trigger (e.g., notify the support
      rep to whom an overdue call is assigned).

An Event’s Schedule
      The final component of an event is its schedule; this lets you determine how often
      you wish KnowledgeSync to submit this event. Note that the “submission” of an
      event means that KnowledgeSync will check to see if the corresponding conditions
      that the event is checking for have been met. If so, the event will be considered as
      having been “triggered”.
      Each event has its own schedule; some very critical events may have a very frequent
      schedule (such as ‘every five minutes’), whereas less critical events may be checked
      on a less frequent basis (such every few hours, or once per day).
      (And events that need to be triggered in “real time” (when the condition occurs)
      should make use of database triggers. Contact Vineyardsoft Support for details and
      examples of using database triggers.)


199                                  Event Designing
Webcasting (Dashboard Alerts)

    KnowledgeSync contains an alert method called “webcasting” – this is the ability for
    KnowledgeSync to generate html pages that contain alert information.
    The webcasting component (also called “Dashboard Alerts”) requires its own
    configuration and set-up. The following pages will not discuss the configuration of
    the webcasting module, as it is detailed in a separate chapter.


“Checked” Vs. “Triggered”

    As you begin to work with events, you will come across frequent references to an
    event being “checked” and it being “triggered.” There is an important difference:
    An event that has been “checked” simply indicates that KnowledgeSync has
    successfully executed the event and has ‘checked’ to see if the corresponding
    conditions have proved true. The conditions may have proven true, or they may not.
    An event that is “triggered” is one that has been checked and whose conditions have
    proven true.

Monitoring the Status of Events
    When an event is submitted, you can use the KnowledgeSync Monitor to track the
    status of the event’s execution.
    In the Monitor, you can click on the “Application Events” branch, and within that
    you can track:
           Events that are “Pending” submission.
           Events that have been “Checked” but not triggered
           Events that have been checked and “Triggered”
           Events with “Errors” that have failed to run successfully.
    If any of your events have failed to run successfully because of an error condition,
    you may attempt to correct the event, to mark the event as “complete”, or you may
    manually delete this run of the event.
    Note that if an event errors because of an error in its configuration, you can modify
    the event and/or corresponding query(ies) and KnowledgeSync will automatically use
    the modified version the next time it attempts to re-run that event.
    (KnowledgeSync automatically attempts to re-submit an erroring event every
    minute.)


An Event Without a Query

    Consider the following scenarios:

                                  Event Designing                                       200
             Every day at 2:00 PM you want to send an e-mail reminder to your VP of
              Marketing to look at your company’s newsgroup
             Every Monday at 8:55 AM you want to send a mail message to all managers
              to attend the 9:00 AM staff meeting
             Every day at 5:00 PM you want to transfer an “orders” file to a specific
              database server
             Every Friday at 6:00 PM you want to send an alert that the system backup
              will start at 6:30 and people need to be logged off
      These scenarios all represent a special kind of event – an event without a query.
      KnowledgeSync lets you create events that perform periodic actions such as the
      sending of alert messages, the execution of workflow or updates, and the execution of
      other site-specific procedures.
      These are un-conditional events that are scheduled to run on a re-occurring basis.
      The only difference between an event such as these and a “conditional” event is that
      these events’ submission are based only on scheduled submission times and are not
      also based on business conditions.


Before You Begin

      Before you begin designing events, there are a few preparatory steps that you should
      already have taken in KnowledgeSync. These are:
             Query Design. Since most events use one or more queries to identify
              underlying database conditions, you should have created your queries prior to
              creating events.
             Subscriber Maintenance. Since an event allows you to specify whom you
              wish to send alert messages to, you should have defined one or more
              subscribers within your subscriber database.
             E-Mail Sending Account. If you plan on sending e-mail alerts from an
              event, you need to have defined (within the KnowledgeSync Administration
              module) the e-mail account that KnowledgeSync will use when sending these
              messages.
      Please be sure to have completed these steps prior to designing events.


Event Designing: Preparation

      Please be sure to have gone through the chapter on Query Designing before
      proceeding any further.
      In the Query Designing chapter, you were given a set of steps to follow in
      preparation for the creation of your queries. This included the creation of
      “worksheets” for the events that your queries would ultimately be linked to. The


201                                 Event Designing
    following sections build upon the content from the worksheets you created earlier to
    create similar worksheets for your event configuration.
    Please note that some of the steps listed in the following sections refer to information
    already identified on your query-level worksheets.

Step #1: Identify Event Purpose

    The first step is to identify the overall purpose of an event. For example:
        “Send an alert to an account manager when a ‘critical’ service call is logged for
        one of their customers.”

Step #2: Identify Related Query(ies)

    If the triggering of an event will be based on one or more data conditions, you need
    to specify the name of the query(ies) or Visual Basic script that the event will use.
    Note that an event may use one or more queries to identify underlying data
    conditions, or the event may use a SQL Trigger, or a VB script. An event may not
    use a combination of queries and a SQL Triggers/VB scripts.
    Using the preceding example of an event that “sends an alert to an account manager
    when a ‘critical’ service call is logged for one of their customers.”, you might select
    a query called something like:
        “Support Calls; Open; Priority ‘x’”

Step #3: Identify Trigger Frequency

    As mentioned earlier, an event can be triggered once for each record that meets the
    event’s criteria, once per group of records that meets the event’s criteria, or once for
    all records that meet the event’s criteria.
    It is very important that you identify which of these “trigger frequencies” will be
    used for each event. Remember – this frequency applies to all of the different
    response actions that an event can execute; thus an event that triggers just once for all
    matching records will therefore generate just a single form or report (if one is
    associated with the event), it will generate just a single alert message (per delivery
    method), and it will execute the corresponding workflow or database updates only
    once for all matching records (and not once for each matching record).

Step #4: Identify Event Message Content

    Since an event can send an alert via multiple methods – including e-mail, fax, pager,
    and webcast – you need to design separate alert messages for each method by which
    the alert will be sent.
    In general, the format of an alert message sent via e-mail, fax, and webcast tend to be
    very similar (and can even be identical); the format of an alert message sent via
    pager, however, tends to be much more brief. (In fact, the text of a pager message can
    often direct the recipient to other delivery methods – such as e-mail – to get the full
    details of the event.)
                                    Event Designing                                      202
      Additionally, an event can also send forms, documents, Crystal Reports and a wide
      variety of files (such as MS Word and MS Excel documents) to one or more
      recipients. Consider whether each event should generate and/or include this content.
      Make sure that you carefully review which alert delivery methods will be needed for
      a given event and then identify the corresponding delivery content for each of those
      methods.

Step #5: Identify Alert Action(s)

      In addition to sending alert messages, KnowledgeSync events can execute “actions”
      that include (but are not limited to) executing application workflow and adding or
      updating database records.
      Although some of these actions may require additional configuration of their own, it
      is important to identify what action(s) you wish an event to execute.

Step #6: Identify Subscribers

      If an event is to send out alert messages, you should identify what individuals (or
      groups) will be the recipients of those messages.
      There are three items to keep in mind when considering subscribers:
          1. A subscriber can be an individual or a group of individuals
          2. A subscriber can be a computer (if it is to receive a file or report)
          3. A subscriber can be a specific person (e.g., “John Smith”), or it can be a
             person related to a database record (e.g., “the rep assigned to the overdue
             call”)
      For each subscriber or group of subscribers that you identify, you need to indicate
      whether they will receive notifications via e-mail, fax, pager, web browser, or
      copy/FTP. Remember that a subscriber may be alerted via any one or any
      combination of these methods.

Step #7: Identify the Schedule

      The final step in preparing for the creation of an event is the identification of the
      frequency with which KnowledgeSync will check to see if this event’s conditions are
      met. Schedules can be as often as every minute, and as infrequently as once per year.
      Please note that an event without an associated query will be executed (and triggered)
      every time that the event is run.


Event Design Worksheets

      If you take the time to fill out the information on the following worksheet for each
      event you are creating, the event set-up process will go very quickly and smoothly.



203                                 Event Designing
Once you become familiar with the event creation process, you will probably be able
to forego the use of these worksheets and design the events directly in the
KnowledgeSync Event Manager.
Note that the worksheets have a series of questions on them where you are able to
specify whether the associated event will be configured to send out alerts (and via
which methods), whether the event message content will include any files and/or
Crystal Reports, and whether the event will execute related “response actions”.
Please take the time to design the outgoing alert messages for each event.
Feel free to make copies of the following worksheets.




                              Event Designing                                         204
                               Event Design Worksheet:

Name of Event:
________________________________________________________________



Query #1:
Query #2 (If Needed):
Query #3 (If Needed):

Alerts to be Sent Via:

E-Mail:        Yes    /   No
Fax:           Yes   /    No
Pager:         Yes   /    No
Webcast:       Yes   /    No


Alerts to Include:

Forms or Reports:      Yes / No
 If ‘Yes’, List Forms or Reports:
Attached Files         Yes / No
 If ‘Yes’, List Files:


Will Event Trigger Action:       Yes /   No
 If ‘Yes’, Describe Action:




Subscribers & Delivery Methods:

Name:                               E-Mail    Fax   Page   Webcast   Send File/Rpt




Schedule:




205                                  Event Designing
                 E-Mail Message Design Worksheet:


Name of Event:




E-Mail Alert Message Subject:




E-Mail Alert Message Text:




          Attach Related Files and/or Forms/Reports to E-Mail:   Yes /   No




                                  Event Designing                             206
                   Fax Message Design Worksheet:


Name of Event:




Fax Alert Message Coverpage Text:




Fax Alert Message Text:




          Include Related Files and/or Forms/Reports In Fax:   Yes /   No




207                               Event Designing
                  Pager Message Design Worksheet:


Name of Event:




Pager Alert Message Text:




                            Event Designing         208
              Webcast (Dashboard) Design Worksheet:


Name of Event:




Webcast Dashboard Text (usually formatted as a table):




Provide a Link from Web Page to Related Files & Forms/Reports:   Yes /   No




209                                Event Designing
Accessing the Event Designer

   Once you have the information that you need in order to begin designing events, you
   are ready to go into the KnowledgeSync Event Manager Navigator module. (Note
   that you can design events in either the Navigator module or within the Event
   Manager module.)
   Log into the Event Manager Navigator (default user name “Admin”; no password),
   and you will be presented with the main Navigator window. If you expand the branch
   titled “All Events” you will see a listing of all of the applications that
   KnowledgeSync is currently configured to integrate with.
   (You will also see branches for any application EventPaks that you downloaded from
   the Vineyardsoft website.)
   To see a listing of existing events for an application, just expand the application that
   contains the events you wish to list. You will see a window such as the following:




                             EVENT LISTING FOR AN APPLICATION




Viewing/Editing an Event

   You can display the details of an existing event (as well as modify an event) simply
   by clicking on it and expanding its components.




                                 Event Designing                                        210
Creating a New Event

      To create a new event:
           Right-click on the application for which you wish to add an event.
           Choose “New Event”.
           Go through the tabs in the Event Designer from left-to-right; when done,
            click on “Save and Close” at the top-left of your window.


Event Description, Priority, & Repeat Status

      Access via Navigator: Double-click on the event name.




                                    EVENT “DESCRIPTION” TAB

      The “Event Description” field should contain a description of the event. Use a
      standard naming convention, such as “Data Object; Condition”, as in
      “Accounts; Overdue”.
      The “Lookup Key” field is used only if an event will be “called” from within another
      application, using one of KnowledgeSync’s APIs. Leave this field blank unless you
      wish to “call” this event from another application.
      (Please refer to the “Utilities” chapter of this guide for more details on calling for the
      execution of a KnowledgeSync event from outside of the KnowledgeSync
      application.)

211                                  Event Designing
     Although every event has its own schedule, it is possible that you might have two (or
     more) events that are scheduled to be submitted at the same time of day. If so, the
     “Priority” field is used to determine the order in which events will be submitted.
     The event with the highest ranking priority (priority ‘0’ being the highest) will be
     submitted first.
     The “Active” checkbox indicates whether an event is eligible to be run by
     KnowledgeSync. Place a checkmark in this field if you wish to allow
     KnowledgeSync to submit the event; leave this field blank if you wish to configure
     this event but not allow KnowledgeSync to submit it.

Repeat Notification for Triggered Items

     KnowledgeSync identifies conditions of data that trigger the “response actions” of an
     event. These response actions may include the sending of alert messages, the
     generation of forms, documents, or Crystal Reports, and the execution of application
     workflow.
     The “conditions” that cause an event to trigger are often based on the conditions of a
     database record, such as an activity record that is overdue for completion, or an
     opportunity record that meets certain criteria.
     Since events run repeatedly on a re-occurring basis (such as every hour), it is possible
     that a record that causes an event to trigger at 9 AM might still meet that event’s
     criteria at 10 AM.
     Using this scenario as an example, the question is:
     Do you want the same record that triggered the event at 9 AM to again trigger the
     event again at 10 AM?
     The answer is most likely: “It depends on the event.”
     For some events, you might want the same record to trigger the event repeatedly
     for as long as the record meets the event’s criteria. For other events, you might want
     an individual record to trigger an event just once.
     Consider the following two examples:
            Example #1: A salesrep is notified at the end of every day about activities
             that are overdue for completion. If an overdue activity remains open for
             multiple days, you want to alert the salesrep each day.

             In this example, KnowledgeSync’s “repeat” function would be enabled.

            Example #2: Every hour, you want to check for newly-entered orders and
             send the corresponding customer an Order Confirmation. Once a customer
             has been sent a confirmation, you do not want to send them another.

             In this example, KnowledgeSync’s “repeat” function would be disabled.
     If you wish for an event to trigger only once about an database record that meets the
     event’s criteria, do not place a checkmark in the field called “Repeat notification for
     triggered items.”


                                   Event Designing                                       212
      If you wish for an event to trigger repeatedly about an individual record until that
      record no longer meets the event’s criteria, do place a checkmark in the field called
      “Repeat notification for triggered items.”

Enabling an Event to “Not Repeat” a Triggered Record

      In order for you to configure an event to not repeat the triggering of an individual
      database record, the event must use a query that has a “Unique” field identified.
      If the event’s query has no “Unique” field identified, KnowledgeSync has no way to
      “remember” what records have previously been triggered, and thus KnowledgeSync
      will continue to trigger the event for the same record until that record no longer meets
      that event’s criteria.
      (See the chapter on “Query Designing” for more details on the identification of a
      “Unique” field.)

Clearing a Record’s Trigger

      If a database record meets an event’s conditions, that record will be flagged as
      “triggered” by KnowledgeSync. If, the next time the event is run, the same record no
      longer meets that event’s criteria, KnowledgeSync will “un-trigger” (or “clear”) that
      record.
      Thus, if KnowledgeSync were to check this same record a third time and find that it
      once again meets the event’s criteria, KnowledgeSync will once again flag that
      record as “triggered”.
      Note that if the “Repeat” function is disabled, you may view and manually clear the
      triggered status from one or more of an event’s records by going into the “Tracking”
      tab of an event within the Event Designer option.

Using “Repeat” in a Field-Level Change Event

      If an event will be using a query that tests for a “change” made to one or more
      database fields, be sure to place a checkmark in the “Repeat” field.
      If you do so, the event will be triggered each time the corresponding field(s) are
      changed. If you do not place a checkmark in this field, you will be notified only the
      first time that the corresponding field(s) have their value changed.

Keep Only Last Checked Record in Monitor

      As KnowledgeSync submits an event, the KnowledgeSync Monitor keeps track of
      when the event was submitted, whether it was successfully executed, and whether the
      event was triggered.
      In many cases, an event will be checked many times before it is ever triggered. For
      example, an event that checks hourly for “any clients who have pending sales
      opportunities but are also on credit hold,” may run for many hours or even days
      before it is ever triggered.


213                                 Event Designing
    In the KnowledgeSync Monitor, you will automatically see the history of every time
    an event was triggered. Additionally, you have the ability to retain (and view) the
    history of every time an event was checked – regardless of whether the event was
    triggered or not.
    In the case of frequently-checked events (such as those that run every few minutes or
    hours), the amount of “checked” history that can pile up in the Monitor can be quite
    extensive.
    And although there is no limit to the amount of history that you can retain, the
    process of scrolling through a list of every submission of a given event can take up
    unnecessary time.
    To avoid retaining the history of every submission of an event, you can place a
    checkmark in the field called “Keep only last checked record in Monitor.”
    By checking this field, KnowledgeSync will retain the history of the last time an
    event was checked, along with a history of every time that event was triggered.
    If you do not place a checkmark in this field, KnowledgeSync will retain the history
    of every time that an event was submitted, plus the history of every time that the
    event was triggered.
    The suggested setting for this field is checked on.

Event Queries
    Access via Navigator:
             Add/Remove Query and/or Query Parameters: Expand the event’s
              components and double-click on its query. Note that if a query has
              “parameters”, those parameters and their values are indicated by a plus
              sign after the query name.
             View/Modify Query Definition: To view or modify the query’s
              configuration, right-click on the query and select “Edit Query”.
    The most important part of designing an event is the identification of the query (or
    queries) that the event will use to determine whether a specific condition has
    occurred.
    (Keep in mind that an event can also have no queries associated with it; this would
    cause an event to be triggered according to a periodic schedule alone.)
    As was detailed in the chapter on Query Designing, a single event can use one query,
    or it can use multiple queries (most commonly seen in cross-application events). Note
    that any event that uses a “change-based” query is limited to using only a single
    query.
    Depending on the “filters” that are configured within a query, you may be prompted
    to fill in some threshold values (called “event trigger parameters”) when you select a
    specific query for an event.
    To select a query for an event, follow these steps:
         Click on the “Add Query” button at the top-left of the Queries tab.

                                  Event Designing                                       214
           You will be shown a list of all the queries for the application in which you
            are currently working.

              (E.g., if you are creating events for the “SalesLogix” application, you are
              shown a list of all of the KnowledgeSync queries that are defined for that
              application.)
           Select the query you wish to use with this event. You are returned to the
            Queries tab, and your selected query now appears in the grid at the top of
            your window.




                                      EVENT “QUERIES” TAB

Selecting Multiple Queries

      Since a single event can use more than one query, you have the ability to select
      multiple queries for a given event. Multiple query events are typically required when
      you either wish to check for a sophisticated set of conditions, or you wish to check
      for conditions across multiple applications. (See the chapter on “Query Designing”
      for details.)
      It is important to note that when multiple queries are selected, KnowledgeSync
      automatically assumes an “and” condition between them; thus the conditions of all
      selected queries must be met in order for the related event to be triggered.
      Also note that if you have chosen a query that uses “change-based” filters, you
      cannot choose multiple queries.




215                                Event Designing
Selecting Queries from Other Applications

     As was detailed in the chapter on Query Designing, KnowledgeSync allows you to
     create events that check for conditions across multiple applications. For example:
         Check for any clients who have pending sales in a CRM application, and who are
         also on credit hold within a financial application.
     This kind of event requires two queries: one from the CRM application and one from
     the financial application. The order in which these queries must be selected is
     determined by the configuration of the queries themselves; one of the queries will
     have been designed as a “link from” query, and the other will have been designed as
     a “link to” query.
     (This is detailed in the chapter on “Query Designing.”)
     If you are creating an event that uses multiple queries from different applications,
     you must be sure that you select the queries in the appropriate order; the second
     query must be designed to include (filter) only those records from the first; the third
     query (if there is one) must be designed to include only those records from the
     second, and so on.
     Once you know the order in which the queries are to be selected, you may proceed
     with selecting them for the corresponding event. To select a query from an
     application other than the one you are currently working in, follow these steps:
          Click on the “Add Query” button at the top-left of the Queries tab.
          You will be shown a list of all the queries for the application in which you
           are currently working.
          Click on the button called “Select Another Application”.
          You will be shown a list of all the applications currently defined within the
           KnowledgeSync application. Select the application that contains the query
           you wish to include in this event.
          You are next shown a list of queries for the selected application. Choose the
           query you require and you will be returned to the Queries tab with the
           selected query now included in the grid at the top of this tab.

Using a VB Script Instead of a Query

     Although most users of KnowledgeSync utilize queries to identify the conditions that
     should trigger an event, there are some types of conditions that cannot be checked for
     via a KnowledgeSync query.
     As KnowledgeSync queries rely upon ODBC as their means of accessing data and
     determining whether a condition has been met, you may have sources of data outside
     of ODBC-compliant databases that you would like KnowledgeSync to monitor.
     Prime examples of conditions that cannot be checked via ODBC includes:
            Data that resides in non-ODBC-compliant databases
            Operating System data, such as processes not running or security breaches
                                   Event Designing                                        216
             Files that have been updated or are missing
      If you wish to utilize KnowledgeSync to check for such conditions as these, you will
      need to configure the corresponding events to use a Visual Basic (VB) script instead
      of a KnowledgeSync query in order to determine whether the corresponding
      condition has occurred.
      This capability, referred to as “Front-End Scripting”, requires that you create the VB
      scripts that will be used to check for the related conditions. The creation of these
      scripts is detailed in the chapter titled “Visual Basic Scripting.”
      Once you have created the corresponding script that an event will use, you need to
      take the following steps to link that script to an event:
           Place a checkmark in the field called “Use Script instead of Query”. (This
            will enable the “Select Script” button.)
           Click on the “Select Script” button and choose the script that will check for
            the condition related to this event.
      Please note that an event cannot use a combination of scripts and queries.

Using SQL Triggers Instead of a Query

      For instructions and examples of how to use SQL Triggers within a KnowledgeSync
      event, please visit the KnowledgeSync knowledgebase (at the Vineyardsoft website)
      to download sample SQL triggers.

Event Trigger Parameters

      As was detailed in the chapter on Query Designing, a query may be configured to
      have one or more filters that are “parameter-driven” – this is a filter whose ‘compare
      value’ is specified on the event level.
      For example, a query called “Forecast Sales > ‘x’ Due to Close Between ‘y’ and ‘z’”
      would have three parameter-driven filters:
             The amount of the sale (“Greater than How Much?”)
             The beginning date range (“Sales Due to Close Starting On?”)
             The ending date range (“Sales Due to Close Ending On?”)
      Whenever an event uses one or more queries that include parameter-driven filters,
      you will be prompted (in the grid in the lower half of the Queries tab) to specify the
      threshold values for those filters.
      Please Note: These parameters cannot be left blank on the event level; you must
      specify a valid response for each of these parameters at the time that the event is
      configured and/or maintained. If a parameter is left blank and the event is submitted
      by KnowledgeSync, the event will not successfully execute.
      If no “Event Trigger Parameters” appear after you have selected your queries, that
      simply indicates that your selected query(ies) do not include any parameter-driven
      filters. If the Event Trigger Parameters grid includes one or more records, each record


217                                 Event Designing
     will begin with a “Question” (or prompt) that instructs you on the type of answer that
     is required.
     You must supply an answer to each event trigger parameter using the options detailed
     in the following sections.

Parameter Answer

     Most parameters can be answered by keying in (or selecting) a specific value. For
     example:
     Question: Activity priority is:
     Answer:    High
     You have two ways to select such an answer; you can manually type in the value, or
     you can choose that value from a database list.
     To manually type in a value, simply go to the “Answer” field and type in the value
     you wish to use. Note that KnowledgeSync is case-sensitive, so a compare value of
     “high” will not retrieve those records that have a value of “High”.
     KnowledgeSync also allows you to directly query the underlying database to retrieve
     potential answers for a field. To do this, follow these steps:
          Click in the “Answer” field and click on the list button that appears there.
          Click on the down-arrow list button that appears under the heading “Type in
           a Value or Choose from dropdown List”. This will display a list of possible
           entries for this field.
          Choose the value that you wish to compare the column to and click on “OK”.
     Note: The dropdown list that appears lists all of the values that have appeared in this
     field in the underlying database. This list does not display every possible value that
     could appear in this field.

Using Date Substitution Variables

     One of the most powerful aspects of designing date-driven events is the use of date
     substitution variables. Consider the following event:
         Send an alert if there are any sales of greater than $20,000
         due to close next week.
     This event most likely has event trigger parameters such as:
     Question: Sales Due to Close Starting on?
     Question: Sales Due to Close Ending on?
     And although you could go into this event on a weekly basis and manually enter next
     week’s “starting” and “ending” dates, there is an easier way.
     Using KnowledgeSync’s “date substitution variables,” you can instruct
     KnowledgeSync to substitute in “next week’s starting date” and “next week’s ending


                                   Event Designing                                        218
      date” whenever this event is run. This eliminates the need for you to have to
      manually update the date answers on a weekly basis.
      To use a date substitution variable as an answer to a trigger parameter, follow these
      steps:
           Click in the “Answer” field and click on the list button that appears there.
           Review the list of “Available Substitution Variables.” You’ll notice that there
            is a wide variety of variables to choose from. For many variables (such as
            “%Current Date%”) you will see multiple formats for the same value. The
            format without any suffix (as in “%Current Date%”) will use your system’s
            date format. The other formats will each contain a suffix
            (such as “YYYY-MM-DD”) that indicates the format in which the
            corresponding date will be returned.
           Choose the value that you wish to use and then click on “OK”.
      Note: Once you select a date substitution variable as an answer, you can edit that
      value to append specific values to that variable. For example, to change the “current
      date” variable to include a specific time of day, you could edit that variable to be
      “{%Current Date%} 00:01” (for one minute past midnight) or
      “{%Current Date%} 23:59” (for 11:59 PM).
      Also Note: Make sure that you choose the date variables of the correct format. (E.g.,
      an application whose dates are stored in “mm-dd-yyyy” format will not recognize a
      trigger parameter date that is formatted as “mm/dd/yyyy”.)

Removing a Query from an Event

      To remove a query from an event, follow these steps:
           Use the Navigator to open the Queries tab of the event.
           Go to the left-most column of the row that contains the query you wish to
            remove.
           The cursor will change into an right-pointing arrow.
           Click your left mouse button to highlight that query.
           Click on the “Remove Query” button.
      Note that you may also click on the button called “Remove All Queries” to delete all
      of the queries that have been selected for this event.

The Reports Tab
      Access via Navigator:
               Add New Report: Double-click on the event name, click on the
                “Reports” tab, select “Add Report”.
               Remove Report, Change Output Format, or Report Parameters:
                Expand the event’s components, expand the “Deliverables” branch, and
                double-click on its report. Note that if a report has “parameters”, those


219                                 Event Designing
                parameters and their values are indicated by a plus sign after the report
                name.
             View/Modify Report Definition: To view or modify the report’s
              configuration, right-click on the report and select “Edit”.
    The “Reports” tab can be used to configure an event to trigger the generation and
    delivery of a report, form, or document. Typical uses of this option include:

            Triggering the generation and delivery of an Order Confirmation form when
            an order is placed for a customer

            Triggering the generation and delivery of a Picking List when there are items
            needing to be shipped from inventory

            Triggering the generation and delivery of a “Sales Pipeline” report for any
            salesreps who have less than $10,000 in forecast sales
    Each of these is referred to as a “triggered report” as the report, form, or document
    will be generated only if certain database conditions warrant it. (KnowledgeSync can
    also generate and deliver reports, forms, and documents on a scheduled basis; see the
    chapter on “Scheduled Reports” for details on this.)
    The process of configuring an event to trigger the generation and distribution of a
    report, form, or document requires a few steps of preparation and (in some cases)
    modifications to an event’s queries. The details on this process are explained in the
    chapter titled “Event-Triggered Reports.” Please refer to that chapter for details.


Sending an HTML Report as E-Mail Text

    If you wish for an event to trigger an e-mail alert in HTML format, you have two
    choices. First, you can manually format the email alert message in HTML format.
    Second, you may use the option to configure KnowledgeSync to generate a Crystal
    Report, create the report output in HTML format, and then paste that HTML content
    in the body of the e-mail message itself.
    Note: This function is available only if you have KnowledgeSync configured to send
    out e-mail messages via SMTP or via any other INTERNET-based mail system. This
    function will not work if you have KnowledgeSync configured to send out e-mail
    alerts via Microsoft Outlook / native Exchange.
    To configure a KnowledgeSync event so that it sends out the contents of an HTML-
    formatted Crystal Report as the body of an e-mail message, follow these steps:
         On the “Reports” tab, choose the Crystal Report whose content you wish to
          send within the body of an e-mail message. (You can specify only a single
          report.)
         Choose a report “Style” of “HTML”.
         Go to the “Email” tab and make sure that the “Message Text” field for this
          event is completely blank (empty).



                                  Event Designing                                       220
      When this event is triggered, KnowledgeSync will generate the corresponding report
      in HTML and will embed this HTML within the body of the e-mail message that is
      sent to the event’s subscribers.
      Please be aware that if the subscriber of such an event is using an e-mail system that
      does not support HTML, the Crystal report will automatically appear as an
      attachment to the received e-mail message.
      Also note that if an event is configured to deliver Crystal HTML report content
      within the body of an e-mail message, the event cannot have any other attachments
      (i.e., no other Crystal reports and no attached files).


Enabling the Report Server

      The KnowledgeSync “Report” server must be enabled to process if you plan on using
      KnowledgeSync to generate reports for triggered events. To enable the report server,
      follow these steps:
           Log into the KnowledgeSync Administrator module.
           Click on the “Activity” folder.
           Click on the “Server Status” folder.
           Double-click on the “Report Server”.
           Place a checkmark in the field called “Allow Server to Process.”
           Click on “Save and Close” at the top-left of your window.
      To disable KnowledgeSync from generating Crystal reports, remove the checkmark
      from the “Allow Server to Process” field for the report server.
      Note: If you disable the report server and trigger events that are configured to
      generate reports, KnowledgeSync will “queue up” the pending reports (which you
      can review in the KnowledgeSync Monitor). These “pending” reports may
      subsequently be deleted, or (if you enable the report server), they may be generated at
      a later time.

The Files Tab
      Access via Navigator:
               Add New File: Double-click on the event name, click on the “Files” tab,
                select “Add File”.
               Remove File, Change File Properties: Expand the event’s components,
                expand the “Deliverables” branch, and double-click on its file.
      In the same manner that KnowledgeSync allows you to associate one or more Crystal
      reports to an event, you are also allowed to associate one or more files to a triggered
      event. Files that are associated with an event will be delivered as e-mail attachments
      unless you use one of the “alternative text” options that are discussed in the following
      section.
      Files that are specified on this tab may be distributed by:
221                                 Event Designing
            E-Mail (as attached files)
            Fax (file content embedded within the fax)
            Web Browser (as a URL link)
            Copy / FTP
     Typical uses of attached files include:
            To attach a “Policies and Procedures” MS Word document to an outgoing
             message
            To attach a product brochure PDF to an e-mail going to a prospect
            To send an HTML newsletter to recipients
            To send an MS Excel spreadsheet to specific recipients
     To attach one or more files to a specific event, follow these steps:
          Click on the “Add File” button.
          Use the resulting window to locate the file you wish to add and select it.
          Key in an informational description of the file you are adding to this event.
          Click on the “Ascii Text” checkbox if the associated file is in ascii format.
           Note that only ascii formatted files may be delivered via fax.
          Repeat these steps for each file you wish to add.




                                       EVENT “FILES” TAB

File “Alternative Text” Options

     Note: This option is available only if KnowledgeSync is sending event messages via
     “Internet” mail. (See your “E-Mail Accounts” option in the KnowledgeSync
     Administrator.)

                                   Event Designing                                      222
      If the event you are working with will be sending out messages via an “Internet”
      e-mail based system (such as SMTP), you have the option to specify that the text in
      an associated file will be used as the “alternative text” for an e-mail message.
      “Alternative Text” is an option that allows you to create an event that sends an e-mail
      message that can be read by any e-mail system, regardless of whether or not they
      support HTML message text.
      When an event’s e-mail message is delivered, if the recipient’s e-mail client does not
      support HTML, KnowledgeSync will use the ascii-formatted text specified in the
      event’s “E-Mail” tab. If the recipient’s e-mail client does support HTML,
      KnowledgeSync will use the text from the HTML file specified as the event’s
      “alternative text”.
      When you use the “Alternative Text” option, you are sending both HTML formatted
      message text and plain, unformatted (non-HTML) text versions of the same message.
      In this way, the message will be readable by all recipients, regardless of whether their
      mail system supports HTML.
      This function is particularly useful if you will be using KnowledgeSync to distribute
      an HTML file (such as a newsletter). In this scenario, the “alternative text” option
      allows the HTML source file to be created outside of KnowledgeSync and simply
      “linked” to an event via the alternative text option.
      If you would like to send an HTML message as the “alternate” message text, click in
      the file “Description” field and click on the dropdown list that appears there. You
      may choose from “HTML”, “richtext”, or “enriched” as the format of the alternative
      file.
      You may specify more than one alternate message file; the recipient’s e-mail client
      will decide which one to use. Please note, however, that multiple alternate message
      files will increase the overall size of the KnowledgeSync message that is being sent.

The Copy (FTP) Tab
      Access via Navigator:
               Add, Change, or Remove Copy Settings: Double-click on the event
                name, click on the “Copy” tab.
      The “copy” tab is where you specify whether the reports and/or files that are
      associated with an event will be copied (or FTP’d) to the event’s subscribers’ desired
      locations.
      Files and reports may be distributed via four methods:
             Attached to e-mail messages
             Embedded within a fax message (as long as the file or report content is
              formatted as ascii)
             Linked to a webcast page (via a URL link)
             Copied / FTP’d to a recipient’s desired location
      Note: The “Copy” tab lets you specify whether the reports and files associated with
      an event will be eligible to be delivered to the event’s subscribers via FTP. You will
223                                 Event Designing
    still need to specify (on the “Subscribers” tab) which recipients will receive the
    related reports/files via the copy/FTP method.
    Note Also: If the event’s related query includes a column called “Attachment_Files”,
    KnowledgeSync will automatically deliver those files along with any others that were
    specified on the “Files” tab.
    To specify that the event’s reports and/or files will be eligible to be copied to a
    recipients’ desired location (as specified in the subscriber’s profile), click on either
    (or both) of the checkboxes on this tab. To allow for the files and/or reports to be
    attached to outgoing e-mails, faxes, and webcasts (but not allow them to be copied or
    FTP’d), do not place a checkmark in the corresponding box on this tab.




                                      EVENT “COPY” TAB


Enabling the Copy Server

    The KnowledgeSync “Copy” server must be enabled to process if you plan on using
    KnowledgeSync to copy or FTP files when an event is triggered. To enable the copy
    server, follow these steps:
         Log into the KnowledgeSync Administrator module.
         Click on the “Activity” folder.
         Click on the “Server Status” folder.
         Double-click on the “Copy Server”.
         Place a checkmark in the field called “Allow Server to Process.”
         Click on “Save and Close” at the top-left of your window.
    To disable any files or reports from being copied/FTP’d, remove the checkmark from
    the “Allow Server to Process” field for the copy server.

                                  Event Designing                                        224
      Note: If you disable the copy server and trigger events that are configured to copy
      reports or files, KnowledgeSync will “queue up” the pending copy requests (which
      you can review in the KnowledgeSync Monitor). These “pending” copy requests may
      subsequently be deleted, or (if you enable the copy server), they may copied to the
      appropriate locations at a later time.

Monitoring the Status of Copied Files

      When an event triggers the copying of files and/or reports, you can use the
      KnowledgeSync Monitor to track the status of the copying function.
      In the Monitor, you can click on the “File Delivery” branch, and within that you can
      track:
             Files that are “Pending” delivery via the copy method.
             Files that have been “Sent” successfully via the copy method.
             Files with “Errors” that have failed to be delivered successfully via the copy
              method.
      If any of your copied report and/or file deliveries have failed to complete successfully
      because of an error condition, you may attempt to correct the delivery, mark the
      delivery as “complete”, or you may manually delete the erroring delivery.
      (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
      branch and then click on the “File Delivery Errors” sub-branch.)
      Note that KnowledgeSync will attempt to re-deliver an erroring file delivery every
      minute.

Transferring Files to an AS/400 Environment

      To use KnowledgeSync to transfer files to an AS/400 machine, make sure that the
      following are all true:

              On the AS/400, verify that you have a USERID and a PASSWORD that is
              the same for the User account that is running the KnowledgeSync Service.

              On the AS/400, verify that the USERID has OBJAUTH to the Library or IFS
              Directory you are transferring the files to. (You can run a DSPOBJAUT for
              that Library or IFS Directory to verify.)

Trigger Frequency
      When a KnowledgeSync event is triggered, the event executes one or more “response
      actions”. These actions can include the sending of alert messages, the generation of
      reports, forms, and documents, and the execution of workflow and/or application
      updates.

      Consider the following three events:
              1. An event that triggers once for each overdue activity assigned to a
                 salesrep.

225                                 Event Designing
            This event will send one alert message for each overdue activity
            This event will generate any related Crystal Reports once for each
            overdue activity.
            This event will execute any related workflow/database updates once for
            each overdue activity.
        2. An event that triggers once for each salesrep who has overdue activities.

            This event will send one alert message per salesrep (listing all of a
            salesrep’s overdue activities).
            This event will generate any related Crystal Reports once for each
            salesrep who has overdue activities.
            This event will execute any related workflow/database updates once for
            each salesrep who has overdue activities.
        3. An event that triggers once for all overdue activities.

            This event will send one alert message listing all overdue activities.
            This event will generate any related Crystal Reports once.
            This event will execute any related workflow/database updates once.
In KnowledgeSync, you have the ability to control whether an event is triggered
once per matching record, once per matching “group” of records, or once for all
matching records.
This is controlled through the use of the “{BEGIN*REPEAT}” command in your
event. If the “{BEGIN*REPEAT}” command is not present within your event, the
event will trigger once for each matching record (scenario #1 previously).
The “{BEGIN*REPEAT}” command may appear only once within a single event,
and it may appear in any of the following tabs:
       Email
       Fax
       Page
       Webcast
       Create File (within the “Action” tab)
Regardless of where the “{BEGIN*REPEAT}” command appears, the command
applies to ALL of the response actions of the event – the alert messages, associated
reports, forms, and documents, and workflow/database update actions.
So – before you use the “{BEGIN*REPEAT}” function within a specific event (such
as within the e-mail message configuration tab), please consider the impact that this
command will have on the event’s other response actions.
If you have a condition (such as “Overdue Activities”) that requires the sending of
one alert message for each group of triggered records, but also requires the execution
of one database update for each triggered record, you will need to configure two
separate events.




                             Event Designing                                         226
Event Message Formatting
      The method by which you design event message text for alerts sent via e-mail, fax,
      pager, and webcast is identical, with only a few minor differences specific to each
      delivery method.
      Since the process of designing an event’s messages is identical for all delivery
      methods, only the “E-Mail” section will detail all the steps that are required to format
      a message. The other delivery method sections will address only the unique aspects
      of each of those other delivery methods.
      Note: If you already have an idea of what you would like you various alert messages
      to look like (using the worksheets from this and the previous chapter), you are ready
      to continue; if not, take a few minutes to use a pen and paper to write down the text
      and format of each alert message for each delivery method.

E-Mail Tab
      Access via Navigator:
               Add Email Message Text: Double-click on the event name, click on
                the “Email” tab.
               Modify Email Message Text: Expand the event’s components, expand
                the “Deliverables” branch, and double-click on the Email branch.
      The most common method by which KnowledgeSync sends event alert messages is
      via electronic mail.
      Up at the top of the “Email” tab (and at the top of all the other message delivery
      tabs), you will see a scrolling list titled “Available Values for Use in Message
      Content”. This is a list of all the fields that you selected within the event’s related
      queries. These fields contain data about each triggered record.
      Also included in this list are date substitution variables (such as “today”,
      “tomorrow”, and “yesterday”), as well as some special message formatting controls
      (located at the very end of the list).
      When you wish to configure your message to include information about the triggered
      event, you select the corresponding fields of data from this list.




227                                  Event Designing
                                     EVENT “E-MAIL” TAB

     KnowledgeSync can send e-mail alerts to virtually every type of e-mail system (such
     as those that rely on Microsoft Exchange, SMTP, and Lotus Notes), and the outgoing
     messages can contain an unlimited amount of information about the triggered event.
     Before you begin designing e-mail messages, however, you need to be sure that
     KnowledgeSync is enabled to send out alerts via electronic mail.

Enabling the E-Mail Server

     The KnowledgeSync “Email” server must be enabled to process if you plan on using
     KnowledgeSync to send out alerts via e-mail when an event is triggered. To enable
     the e-mail server, follow these steps:
          Log into the KnowledgeSync Administrator module.
          Click on the “Activity” folder.
          Click on the “Server Status” folder.
          Double-click on the “Email Server”.
          Place a checkmark in the field called “Allow Server to Process.”
          Click on “Save and Close” at the top-left of your window.
     To disable any alerts from being sent via e-mail, remove the checkmark from the
     “Allow Server to Process” field for the e-mail server.
     Note: If you disable the e-mail server and trigger events that are configured to send
     e-mail alerts, KnowledgeSync will “queue up” the pending e-mail alerts (which you
     can review in the KnowledgeSync Monitor). These “pending” alerts may
     subsequently be deleted, or (if you enable the e-mail server), they may be sent to the
     appropriate recipients at a later time.



                                   Event Designing                                      228
E-Mail Account to Send From

      Note: If this field is left blank for an event, the event will not deliver – and will
      not even queue up – email alert messages for this event.
      Before you can begin defining this text within KnowledgeSync, you need to identify
      which e-mail account KnowledgeSync will send e-mail messages from for this event.
      Although you may have just a single e-mail account configured, you may have
      multiple accounts, such as one account which is used to send messages to your
      employees, and another account which is used to send messages to your clients and
      prospects.
      (The configuration of your “E-Mail Sending Accounts” is done in the
      KnowledgeSync Administration module. Please refer to chapter three,
      “KnowledgeSync Administration”, for details on this subject.)
      KnowledgeSync will not be able to send alerts via e-mail unless you have correctly
      configured (and selected) an e-mail sending account. Click on the down-arrow next
      to the field titled “E-Mail Account to Send From” and choose an account.

E-Mail Reply (& From) Address

      This option is valid only if the e-mail sending account selected for this event is an
      Internet-based e-mail account. This option is not valid with EXCHANGE,
      MAPI, and VIM based e-mail accounts.
      If you are sending e-mail alerts via an Internet-based e-mail system, you can
      optionally specify what the Reply Email Address will be. Note that the “reply
      address” contains the same value as the “from” address, and thus if you specify this
      value you are in fact specifying the value that will appear as both the “from” and the
      “reply” addresses.
      If you leave this field blank, the address defined (in the KnowledgeSync
      Administrator) for the corresponding e-mail sending account will be used.
      You have three choices for the value of this field:
          1. Leave it blank. KnowledgeSync will use the default “from” and “reply”
             name that is configured in the setup of this e-mail account.
          2. Hard-code this value to a specific e-mail address
             (such as Technical Support Team <support@yourcompany.com>).
          3. Dynamically assign this address from a value from within your database
             (e.g., use the field that contains the e-mail address of the salesrep associated
             with an order). To do so, the value that you wish to use must be selected as
             one of the columns within the event’s query(ies).

              This address must be a valid email address. If not, the corresponding e-mail
              alert will fail to be sent.




229                                 Event Designing
E-Mail Subject Text

     Click in the “Message Subject” field. This is where you can specify the subject of an
     outgoing alert message when this event is triggered. Using an event that is triggered
     by “late orders” as an example, you might type in:
     “Order Shipped Later Than Required Date”
     But you can also include data fields in the subject of an e-mail message. For example,
     let’s say you want your subject field to read as follows:
     “Order #123 Shipped Later Than Required Date”
     To do this, you’d take the following steps:
          Type “Order # ” in the message subject field.
          Go up to the list of “Available values for use in message content” and find
           the “order ID” field.
          Select that field (e.g., double-click on it)
          Your message subject now reads:
           ”Order # {OrderID}”
          Click back in the message subject field and finish typing in the rest of the
           subject (“ Shipped Later Than Required Date”).
          That’s it!
     Now consider an event with an e-mail subject such as the following:
     “Sales for Next Month < $100,000”
     The problem with a subject like this is that after a few months go by, you might have
     a few e-mail messages which all read:
     “Sales for Next Month < $100,000”
     “Sales for Next Month < $100,000”
     “Sales for Next Month < $100,000”
     And you have to figure out exactly which “next month” each mail message is
     referring to.
     The solution? Add a KnowledgeSync date substitution variable to the subject of your
     message and make it read as follows:
     “Sales for {%Next Month%) < $100,000”
     To do so, follow the steps outlined previously, and instead of (or in addition to)
     selecting fields of data from the record that triggered an event, scroll the list of
     “Available values to use in message content” down until you see KnowledgeSync’s
     date substitution variables.
     You can use any combination of hard-coded text, field values, and date substitution
     variables in your e-mail subject.


                                   Event Designing                                        230
E-Mail Message Text

      Note #1: Email message text may be formatted either as ascii or as HTML.

      Note #2: There is a limit of 32K for the size of the email message text.
      Click in the “Message Text” field. This is where you can specify the body text of an
      outgoing e-mail message when this event is triggered. Since the content of an
      outgoing message typically contains some combination of hard-coded text and
      database field values, one approach for designing the text is to type in all of the hard-
      coded text and then go back and fill in all of the database field values.
      If you are creating an ascii-formatted message, you may begin typing directly into the
      “Message Text” field; if you prefer to configure your message in HTML, please refer
      to the section of this chapter titled “HTML Message Design”.

E-Mail Message Text: How to Edit

      For an alert message that might be sent about orders that were shipped later than their
      required date, you can begin by typing the “hard-coded” text of the message right
      into the “Message Text” field:
      The following order was shipped later than the customer's required date:
      Order ID     :
      Company      :
      Required Date:
      Shipped Date :
      Salesperson :
      You could then do the following:
           Use your mouse to position your cursor next to the “Order ID:” field
           Press your spacebar once (to leave a blank space)
           Go up to the list of “Available values for use in message content” and select
            the “{OrderID}” field. This field will now appear next to the hard-coded
            “Order ID:” text.
           Repeat this process for the remaining data field values you wish to include in
            your message.
      When you are finished, your completed message text will look like the following:
      The following order was shipped later than the customer's required date:
      Order ID      :{OrderID}
      Company       :{CompanyName}
      Required Date :{RequiredDate}
      Shipped Date :{ShippedDate}
      Salesperson   :{FirstName} {LastName}




231                                 Event Designing
Field Formatting Options

     KnowledgeSync includes a number of special field formatting functions that you can
     use when designing your alert messages. Please note that these functions are
     available for all of KnowledgeSync’s message delivery methods, including e-mail,
     fax, pager, and webcast.
     Also note that these functions may be used in the “Create File” action to enable you
     to populate a file with specifically-formatted values.

Displaying Data in a Table with Rows & Columns

     Note: HTML message design is available only if you are using an “Internet” based
     email sending account in KnowledgeSync.
     One of the easiest ways to display and read alert message data is in a table with rows
     and columns.
     You may use any HTML editor to create or customize the content of a table; if you
     do not have an HTML Editor (or are not HTML-savvy), Vineyardsoft suggests that
     you use the following free, non-technical HTML Table Design tool available on the
     Internet:
     http://www.spectrum-research.com/V2/generators/tableframe.asp
     Or, you can just cut-and-paste the following HTML syntax and fill in the “header”
     and “data field” sections accordingly:
     {BEGIN*HTML}
     <table class='mytable'>
             <thead>
                     <tr class='mytable'>
                              <th class='mytable'>Column 1 Heading</th>
                              <th class='mytable'>Column 2 Heading </th>
                              <th class='mytable'>Column 3 Heading </th>
                              <th class='mytable'>Column 4 Heading </th>
                              <th class='mytable'>Column 5 Heading </th>
                     </tr>
             </thead>
             <tbody>
                     {BEGIN*REPEAT}
                     <tr class='mytable'>
                              <td class='mytable'>{Data Field 1}</td>
                              <td class='mytable'>{Data Field 2}</td>
                              <td class='mytable'>{Data Field 3}</td>
                              <td class='mytable'>{Data Field 4}</td>
                              <td class='mytable'>{Data Field 5}</td>
                     </tr>
                     {END*REPEAT}
             </tbody>
     </table>
     {END*HTML}


                                   Event Designing                                      232
      Note how this HTML code creates a table with five headings (the lines that begin
      with “<th”). Note also that the message “repeat” function is used to automatically
      repeat the details lines (the lines that begin with “<td>”) so that multiple records can
      be grouped together in a single e-mail message.
      (More on the “repeat” function after the next section.)

Shortening the Display Length of a Field

      Since many database fields are designed to be much longer than the actual values that
      might be keyed into them, you may have the need to shorten the display length of a
      field that you wish to place in an alert message.
      To specify the maximum length for a field, you would append a colon (‘:’) followed
      by a number that represents the maximum length of the field, followed by the plus
      sign (‘+’). For example:
      {Item_Description:25+}
      This would tell KnowledgeSync to display no more than 25 characters of the item’s
      description in an alert message.

Making Fields Line Up

      One of the most common message formatting requirements in KnowledgeSync is to
      have rows of “record details” in which all of the fields within each row line up with
      the corresponding fields in the preceding and following rows.
      To do this, you need to specify that a field will always be allocated a specific number
      of spaces, regardless of the length of the value in that field.
      In KnowledgeSync, this is done by using two special field formatting functions; one
      that specifies the maximum display length of a field (as discussed in the preceding
      section), and a second function that tells KnowledgeSync to always allocate the same
      number of spaces to that field even if the data value is less than that number of
      characters.
      To specify that KnowledgeSync should always allocate the same number of
      characters of space for a field, even if the actual value of a field is less than that
      number of characters, you would add the plus sign (‘+’) after the field’s display
      length, as in the following example:
      {Item_Description:25+}
      Please note that the plus sign (‘+’) is used only with character-based fields; if you
      would like to shorten the length of a numeric field, you would use the “display
      length” syntax shown previously, but instead of using the plus sign, you would use
      one of the following numeric formatting commands.

Numeric Formatting Options

      KnowledgeSync supports special formatting functions for all numeric fields. This
      includes two formatting functions for “currency” fields, and four formatting functions
      for numeric fields.
233                                  Event Designing
Formatting Currency

     If you are including currency fields (such as “Unit Price”) in your alert messages,
     KnowledgeSync provides you with two options for formatting these fields.
     The value in the corresponding currency field will be formatted according to the
     regional currency settings for the server on which KnowledgeSync is installed.
     Note that if a currency field’s length is controlled through the use of the “display
     length” function (e.g., ‘{Unit_Price:10}’), KnowledgeSync will automatically
     allocate the indicated number of characters when this field is placed in an alert
     message.
     (This allows KnowledgeSync to automatically line this field up with other records
     even if other records have a longer or shorter value in this field).
          Currency; Right-Justified: By placing a dollar sign (‘$’) at the end of a
           field name, the regional currency symbol will automatically be placed to the
           left of the corresponding field and the value within the field will be right-
           adjusted.

             Example #1: {sales_amount$}
             Displayed Value:        $1250.00 (right-justified)

             Example #2: {sales_amount:10$}
             Displayed Value:        $1250.00 (right-justified; limited to 10 digits)


          Currency; Left-Justified: By placing the ampersand symbol (‘&’) at the
           end of a field name, the regional currency symbol will automatically be
           placed to the left of the corresponding field and the value within the field will
           be left-adjusted

             Example #1: {sales_amount&}
             Displayed Value: $1250.00 (left-justified)

             Example #2: {sales_amount:10&}
             Displayed Value: $1250.00 (left-justified; limited to 10 digits)

Formatting Numbers

     If you are including numeric, non-currency fields (such as “Units Ordered”) in your
     alert messages, KnowledgeSync provides you with four options for formatting these
     fields.
     The value in the corresponding numeric field will be formatted according to the
     settings for the server on which KnowledgeSync is installed.
     Note that if a numeric field’s length is controlled through the use of the “colon and
     length” function (e.g., ‘{Units_Ordered:10}’), KnowledgeSync will automatically
     allocate the indicated number of characters when this field is placed in an alert
     message.


                                   Event Designing                                          234
      (This allows KnowledgeSync to automatically line this field up with other records
      even if other records have a longer or shorter value in this field).
           Number; Right-Justified; 2 Places to the Right of the Decimal: By
            placing the number sign (‘#’) at the end of a field name, the value in the
            corresponding field will have two digits to the right of the decimal point and
            the value in the field will be right-adjusted.

              Example #1: {sales_units#}
              Displayed Value:          85.50 (right-justified)

              Example #2: {sales_units:10#}
              Displayed Value:          85.50 (right-justified; limited to 10 digits)

           Number; Left-Justified; 2 Places to the Right of the Decimal: By placing
            the percent sign (‘%’) at the end of a field name, the value in the
            corresponding field will have two digits to the right of the decimal point and
            the value in the field will be left-adjusted.

              Example #1: {sales_units%}
              Displayed Value: 85.50 (left-justified)

              Example #2: {sales_units:10%}
              Displayed Value: 85.50 (left-justified; limited to 10 digits)

           Number; Right-Justified; No Places to the Right of the Decimal: By
            placing the exclamation mark (‘!’) at the end of a field name, the value in the
            corresponding field will have no digits to the right of the decimal point and
            the value in the field will be right-adjusted.

              Example #1: {sales_units!}
              Displayed Value:           85 (right-justified)

              Example #2: {sales_units:10!}
              Displayed Value:          85 (right-justified; limited to 10 digits)

           Number; Left-Justified; No Places to the Right of the Decimal: By
            placing the asterisk (‘*’) at the end of a field name, the value in the
            corresponding field will have no digits to the right of the decimal point and
            will be left-adjusted.

              Example #1: {sales_units*}
              Displayed Value: 85 (left-justified)

              Example #2: {sales_units*}
              Displayed Value: 85 (left-justified; limited to 10 digits)

Skipping Fields With Null Values

      Depending on how you are formatting an alert message, you may find the need to tell
      KnowledgeSync to “skip” a field if its value is null. (Note that this function checks
      for “null” values only and not for a value of “blank”.)

235                                Event Designing
    To help understand when and why you might wish to use this function, consider an
    Order Entry application in which a single order might have the following different
    line types:
         Inventory items
         Special (non-inventory) items
         Miscellaneous charges
         Comments
    An inventory item will have an item number, warehouse code, unit price, and so on.
    A non-inventory item will not have a warehouse code. A miscellaneous item will not
    have a unit price. And a comment line will not have any of these items.
    In order to format an alert message that handles all of these different combinations,
    you need to tell KnowledgeSync to “skip” a field (and not even allocate any space for
    it within the alert message) if the field’s value is null.
    Let’s say that an individual order detail line has any one of the following (each of
    which is stored in a separate field in the database):
                    An item number
                    A non-inventory item code
                    A miscellaneous charge code
                    A comment code
    You need a way to tell KnowledgeSync to ignore (and not to allocate any space to)
    those fields that are blank. This is done by including the tilde character (‘~’) at the
    very end of the field name which you wish to check for a null value.
    Here’s an example of a section of an alert message that addresses the preceding
    scenario:
    {BEGIN*REPEAT}
    {ItemNo:15+~}{NonInvNo:15+~}{MiscChgCode:15+~}{CommentCode:15+~}
    {END*REPEAT}
    This message will show one field (whichever one is not null) and the value will be
    left-adjusted in the message text.
    Each of these fields is formatted as follows:
                 To show up to 15 characters of the field’s value (‘:15’)
                 To always allocate 15 spaces, even if the value is less than that (‘+’)
                 To skip over the field if its value is blank (‘~’)
    When used, the tilde should always be the final formatting command in a field.

Text Formatting Notes & Hints

    Here are a few suggestions regarding the formatting of your message text:


                                   Event Designing                                         236
          1. If you wish to generate message content in a columnar format, you have 3
             choices: 1) use the field formatting controls listed previously, 2) use an
             HTML formatted message, or, 3) use an associated Crystal report.
          2. If you wish your e-mail to include sub-totals, totals, line and page breaks,
             headers, footers, et cetera, design this output using a Crystal Report and
             attach the report to the event.
          3. If you wish your e-mail message to include a blank line, be sure to enter that
             line in the message text.
          4. If you are placing multiple field values next to each other (as in the previous
             example of {“FirstName}{LastName}”, you might wish to separate them
             with a single blank character.
          5. In addition to selecting field values from the list of Available values, you can
             also manually type in the field names you wish to use.
          6. You can include KnowledgeSync date substitution variables within an alert
             message. This includes the value “Last Date/Time Event Checked” variable,
             which will display the date and time of the last time that KnowledgeSync
             checked this event.
          7. Do not use the curly braces (“{}”) anywhere in your message text except
             when they are surrounding the name of a database field.

Embedding URL Links in Message Text

      In KnowledgeSync email messages, you can send an email with a URL link in it
      (such as an email to a customer when their order has shipped that includes a link to
      the shipper's website).
      To do this, you would first want to make sure that any information that is required
      within the URL link (such as the tracking number) is one of the chosen columns in
      the underlying query.
      Then, you could embed a link such as the following (a FedEx example):
      http://www.fedex.com/cgi-bin/tracking?action=track&tracknumbers={fedexnumber}
      Note that “{fedexnumber}” is the value from the underlying query.

Sample Alert Messages

      Here are a few sample alert messages that show a variety of information in e-mail
      message text:




237                                 Event Designing
Event: Customers; More than 2 Late Shipments Last Quarter

     The following customer had more than 2 shipments arrive late last quarter:
     Company:                {CompanyName}
     Number of Late Orders: {Late_Order_Count}

Event: Customers; Shipment Confirmations for Today

     Dear {ContactName}:
     This message is confirm that the following order has been shipped to you today:
     Order Number: {OrderID}
     Order Date:   {OrderDate}
     Company:      {CompanyName}
     Total Amount: {Total}
     Salesperson: {Salesrep_FirstName} {Salesrep_LastName}

Event: Customers; Frequent Buyer Incentives

     The following customer has placed more than four orders of at least $5,000 over the
     last quarter and is eligible for our frequent buyer incentive program:
     Company:                                          {CompanyName}
     Number of Matching Orders Over the Last Quarter: {Sales_Count}

Creating a Message With Both HTML & Non-HTML Text

     If you’re not sure whether your event subscribers can read HTML mail messages,
     you might wish to create a single e-mail message that contains both HTML and non-
     HTML text. Note how the following example starts off with ascii formatted text but
     then follows this text with the same content formatted in HTML:
     The following customer had more than 2 shipments arrive late last quarter:
     Company:               {CompanyName}
     Number of Late Orders:{Late_Order_Count}
     {BEGIN*HTML}
     Your HTML content would go here
     {END*HTML}
     If the alert recipient’s e-mail client does not support HTML, they will see only what
     is in the top section of this message, and the content of HTML section will appear as
     an attachment.
     Conversely, if the alert recipient’s e-mail client does support HTML, they will not
     see the content of the top section and will see only what is between the
     {BEGIN*HTML} and {END*HTML} labels.
     Note: You are limited to 30K of data in the e-mail message text.


                                  Event Designing                                      238
Inserting HTML Output from a Report

      If you wish to send an e-mail alert in HTML format, you have the option to configure
      KnowledgeSync to send an HTML-formatted Crystal Report so that the report’s
      contents appear in the body of the e-mail message itself.
      Note: This function is available only if you have KnowledgeSync configured to send
      out e-mail alert messages via SMTP or via any other INTERNET-based mail system.
      This function will not work if you have KnowledgeSync configured to send out e-
      mail alerts via Microsoft Outlook / native Exchange.
      To configure a KnowledgeSync event so that it sends out the contents of an HTML-
      formatted Crystal Report as the body of an e-mail message, follow these steps:
           On the “Reports” tab, choose the Crystal Report whose content you wish to
            send within the body of an e-mail message. (You can specify only a single
            report.)
           Choose a report “Style” of “HTML”.
           Go to the “Email” tab and make sure that the “Message Text” field for this
            event is completely blank (empty).
      When this event is triggered, KnowledgeSync will generate the corresponding report
      in HTML and will embed this HTML within the body of the e-mail message that is
      sent to the event’s subscribers.
      Please be aware that if the subscriber of such an event is using an e-mail system that
      does not support HTML, the Crystal report will automatically appear as an
      attachment to the received e-mail message.
      Also note that if an event is configured to deliver Crystal HTML report content
      within the body of an e-mail message, the event cannot have any other attachments
      (i.e., no other Crystal reports and no attached files).

Controlling Trigger Frequency (“Repeat”)

      As mentioned previously, you have the ability to control whether an event is
      triggered once per matching record, once per matching “group” of records, or once
      for all matching records.
      Depending on your choice, all of an event’s “response actions” (sending alerts,
      generating reports, and executing workflow/database updates) will correspondingly
      be run once per matching record, once per group of records, or once for all matching
      records.
      Controlling the trigger frequency is done through the use of the
      “{BEGIN*REPEAT}” command.
      Note: The “{BEGIN*REPEAT}” and “{END*REPEAT}” commands can
      appear only once within an event, and may be placed in any one of the following
      tabs:
           Email
           Fax
239                                 Event Designing
          Page
          Webcast
          Create File (within the “Action” tab)
     Important Note: If an event needs to run one response action per triggered record,
     you must not use the {“BEGIN*REPEAT}” command within an event.

Repeating Text in an Event’s Message

     One of the primary uses of the “{BEGIN*REPEAT}” command is that it enables you
     to configure a single alert message that contains the details of multiple triggered
     records. This is true regardless of the message delivery means.
     If you wish to deliver one alert message per triggered record, you must not use the
     “{BEGIN*REPEAT}” command in an event. If, however, you wish to deliver one
     alert message that contains the details of multiple triggered records, you must use the
     “{BEGIN*REPEAT}” function.
     Consider the following event alert message:




                                   Event Designing                                       240
      The following orders were shipped later than the customer's required date:
      Order ID:      {OrderID}
      Company:       {CompanyName}
      Required Date: {RequiredDate}
      Shipped Date: {ShippedDate}
      Salesperson:   {FirstName} {LastName}
      If you leave the message text like this, KnowledgeSync will send out one alert
      message per triggered record. Your other choice, however, is to trigger the event
      once per group or once for all records, and thus send out one alert message
      containing the details of multiple records.
      If you do wish to send out one message with the details of multiple records within it,
      you need to ask yourself the following question:
      “What part of the message do I want to repeat for each matching record?”
      In reviewing the message text, you would probably not want to repeat the opening
      line of the message – “The following orders were shipped later than the customer’s
      required date” – but you would want to repeat the following five lines for each
      matching order.
      Thus you would edit your message text to look like the following:
      The following order was shipped later than the customer's required date:
      {BEGIN*REPEAT}
      Order ID:       {OrderID}
      Company:       {CompanyName}
      Required Date: {RequiredDate}
      Shipped Date: {ShippedDate}
      Salesperson:    {FirstName} {LastName}
      {END*REPEAT}
      The use of the {BEGIN*REPEAT} and {END*REPEAT} commands instruct
      KnowledgeSync as to what part of a message to repeat if the event is triggered by
      multiple matching records.
      The use of these “repeat” commands also tells KnowledgeSync that this event will
      not trigger once for each matching record, but rather once for each group of records –
      or once for all records – that meet the event’s criteria.

Trigger Once for All Matching Records

      If you wish to trigger an event once for all matching records, follow these steps:
           Go to the “Email”, “Fax”, “Pager”, or “Webcast” tabs. Note that you can use
            the “repeat” commands only on one (1) tab within an event.
           In the message text field, position your cursor immediately before the line(s)
            that you wish to be repeated. Note that {BEGIN*REPEAT} does not need to
            be on a line by itself; it may be on the same line as hard-coded text or a field
            value.



241                                 Event Designing
             (If {BEGIN*REPEAT} is on a line by itself, KnowledgeSync will insert a
             blank line before every repeated group of records).
          With your cursor in the position where you wish to insert the “begin repeat”
           label, scroll the list of “Available values for use in message content” to the
           very end and select {BEGIN*REPEAT}.
          Next, position your cursor right after the end of text that you wish to be
           repeated. Note that {END*REPEAT} does not need to be on a line by itself;
           it may be at the end of the same line as hard-coded text and/or a field value.

             (If {END*REPEAT} is on a line by itself, KnowledgeSync will insert a
             blank line after every repeated group of records).
          Go to the list of “Available values for use in message content” and select
           {END*REPEAT}.

Trigger Once Per Group: Options

     In KnowledgeSync, you can “group” an event’s matching records in the following
     three manners:
         1. Per alert recipient. This gives you the ability to group all of the records that
            “belong” to each of an event’s subscribers. Examples would be sending a
            salesrep a single message containing the details of all of their sales
            opportunities, sending a support rep a single message containing all of their
            assigned calls, or sending a customer a single message containing all of their
            orders.
         2. Per alert recipient and by secondary break field. This gives you the
            ability to further divide a recipient’s alert messages into smaller groups.
            Examples would be sending a salesrep one message per region of their sales
            opportunities, sending a support rep one message per priority of their
            assigned calls, or sending a customer one message per order (each order
            containing multiple line items).
         3. Per break field. This gives you the ability to group an event’s records by
            any field you desire. Examples would be sending a sales manager one
            message per opportunity status, sending a support manager one message per
            call priority, or sending a CFO one message listing per client orders.

Trigger Once Per Alert Recipient

     Triggering an event once per alert recipient means that you wish KnowledgeSync to
     take a group of records that are all related to (or assigned to) a specific person and
     trigger the event once (i.e., send one alert message) per each of these recipients.
     To configure an event so that it triggers once per unique alert recipient, follow these
     steps:




                                   Event Designing                                        242
              1. Go into the Query Designer for the query associated with this event.
              2. Go to the “Columns” tab and make sure that the field(s) that contain the
                 delivery addresses (i.e., e-mail address, fax number, etc.) of the
                 corresponding recipients are included as columns for this query.
              3. (Still in the Query Designer) Go to the “Sorting” tab, and make sure that
                 the query sorts the records according to the recipient’s name (or delivery
                 address)
              4. Go into the event that is using this query.
              5. Create your alert message text and include (within it) the “Begin Repeat”
                 and “End Repeat” commands as detailed previously.
              6. Go to the “Subscribers” tab and click on the “Advanced” sub-tab.
              7. In the grid in the lower half of this window, fill in the delivery address
                 value(s) with the corresponding field names that contain these addresses.
                 Note that once you click in these fields you can click on a drop-down list
                 that displays all of the fields that you can choose from.
      When an event that is configured in this manner is triggered, KnowledgeSync will:
               Retrieve all matching records and sort them by recipient
               Generate one alert message per recipient (listing all of that recipient’s
                related records)
               Send each message to the related recipient
               Execute all of the event’s other response actions (such as generating
                reports and/or executing workflow or database updates) once per
                recipient (and not once per triggered record)

Example: Trigger Once Per Recipient

      Scenario: An event that sends each support rep an e-mail message listing their
      open calls.

      Set-Up: The event’s query would include the rep’s e-mail address as one of its
      columns and would use that address as the query’s primary sorting field

      The event mail message text would use “Begin Repeat” and “End Repeat”. In the
      Subscribers “Advanced” tab, the field containing the support rep’s e-mail address
      would be chosen next to the line that reads “Contains Email address to send to”.
      Note that you could have an event that sends each support rep an e-mail message
      listing their open support calls and also sends a Support Manager one e-mail message
      per rep listing that rep’s open support calls. You would follow the steps listed above
      and also specify the Support Manager as a “standard” subscriber.



243                                Event Designing
Trigger Once Per Alert Recipient & Secondary Break Field

     Triggering an event once per alert recipient and on an additional break field means
     that you wish KnowledgeSync to take a group of records that are all related to (or
     assigned to) a specific person and then further divide that group into subsets and then
     trigger the event (i.e., send the alert message) once for each of these subsets.
     To configure an event so that it triggers once per break field within each unique alert
     recipient, follow these steps:
             1. Go into the Query Designer for the query associated with this event.
             2. Go to the “Columns” tab and make sure that the field(s) that contain the
                delivery addresses (i.e., e-mail address, fax number, etc.) of the
                corresponding recipients are included as columns for this query. Also
                make sure that the field that contains the “break value” is also selected as
                a column for the query.
             3. (Still in the Query Designer) Go to the “Sorting” tab, and make sure that
                the query sorts the records according to the recipient’s name (or unique
                delivery address). You should also add a secondary sort on the query’s
                secondary break field
             4. Go into the event that is using this query.
             5. Create your alert message text and include (within it) the “Begin Repeat”
                and “End Repeat” commands as detailed previously.
             6. Go to the “Subscribers” tab and click on the “Advanced” sub-tab.
             7. In the grid in the lower half of this window, fill in the delivery address
                value(s) with the corresponding field names that contain these addresses.
                Note that once you click in this field you can click on a drop-down list
                that displays all of the fields from the underlying query(ies).
             8. In the grid in the upper half of this window, fill in the first field in the top
                grid with the name of the field that you wish to use as your secondary
                break field. Note that once you click in this field you can click on a drop-
                down list that displays all of the fields that you can break on.
     When an event that is configured in this manner is triggered, KnowledgeSync will:
              Retrieve all matching records and sort them by recipient (and optionally
               also be secondary break field)
              Generate one alert message per recipient and per secondary break field
               (listing all of the records related to that recipient and a specific break
               field value)
              Send each message to the related recipient
              Execute all of the event’s other response actions (such as generating
               reports and/or executing workflow or database updates) once per the
               combined value of recipient and break field



                                   Event Designing                                          244
Example: Trigger Once Per Recipient & Break Field

      Scenario: An event that e-mails a client an order confirmation which includes
      the line item details of the order.

      Set-Up: The event’s query would include the client’s e-mail address as one of its
      columns as well as the order number. The query would retrieve order detail records
      (line items) and would sort the records first by client address (or name) and then by
      order number and then by line number.

      The event message text would use “Begin Repeat” and “End Repeat”. In the
      Subscribers “Advanced” tab, the field containing the client’s e-mail address would be
      chosen next to the line that reads “Contains Email address to send to”. You would
      then go up to the top of the Subscribers “Advanced” tab and (in the topmost field)
      specify the field containing the order number value.

Trigger Once Per Break Field

      Triggering an event once per break field means that you wish KnowledgeSync to take
      a group of records that are all have some value in common and execute the event’s
      response actions (including the sending of alert messages) once for each of these
      values.
      To configure an event so that it triggers once per break value, follow these steps:
              1. Go into the Query Designer for the query associated with this event.
              2. Go to the “Columns” tab and make sure that the field that contains the
                 break value is included as a column for this query.
              3. (Still in the Query Designer) Go to the “Sorting” tab, and make sure that
                 the query sorts the records according to the break value field
              4. Go into the event that is using this query.
              5. Create your alert message text and include (within it) the “Begin Repeat”
                 and “End Repeat” commands as detailed previously.
              6. Go to the “Subscribers” tab and choose one or more subscribers for the
                 event.
              7. Click on the Subscribers “Advanced” sub-tab.
              8. In the grid in the upper half of this window, fill in the first field in the top
                 grid with the name of the field that you wish to use as your break field.
                 Note that once you click in this field you can click on a drop-down list
                 that displays all of the fields that you can break on. When an event that is
                 configured in this manner is triggered, KnowledgeSync will:
               Retrieve all matching records and sort them by break field
               Generate one alert message per break field (listing all of the related
                records)
               Send each message to the specified recipients

245                                 Event Designing
              Execute all of the event’s other response actions (such as generating
               reports and/or executing workflow or database updates) once per break
               field

Example: Trigger Once Per Break Field

     Scenario: An event that e-mails a manager one sales forecast report per
     salesrep.

     Set-Up: The event’s query would include the salesrep’s name (or other unique ID).

     The event message text would use “Begin Repeat” and “End Repeat”. In the
     Subscribers “Advanced” tab, the top-most field would contain the field that uniquely
     identifies each salesrep.

“Begin Repeat” Notes

     Please review the following notes in regards to the use of the “repeat” function:
          Since the “repeat” function can appear only once within a single event, you
           cannot have a “repeat” event that sends different alert message content for
           different delivery methods.

             (I.e., if you use “repeat” in an event’s e-mail message text, you cannot use it
             again in the fax, page, or webcast options.)

             You can, however, configure a “repeat” event in which the text in which the
             repeat command appears can also be used in the other delivery methods. If,
             for example, you used the “repeat” command in your e-mail message text
             and you wished to use the same text in your fax or webcast deliveries, you
             would simply type in “=email_message_text” in the message text fields of
             those other delivery methods.
          If you wish to use the “repeat” function but also wish to have different alert
           message text for different alert delivery methods, you will need to have
           multiple copies of the event – one for each delivery method you wish to use.
          If your event is using multiple queries, the “recipient address” and
           “secondary break” fields can refer only to fields from the first query in the
           event’s list of queries.

E-Mail Message Handling Options
     At the bottom of the E-Mail tab there are three checkboxes that allow you to further
     control the content of an outgoing alert message:
            Include Reports as E-Mail Attachments. If an event has one or more
             reports, forms, or documents associated with it, you have the option to
             specify whether the associated items will be attached to the outgoing e-mail
             message.

             When you associate one or more reports, forms, or documents with an event,


                                   Event Designing                                       246
          these items may be delivered to the appropriate recipients via the following
          methods:
                 E-mail (as attachments)
                 Fax (ascii-formatted reports only)
                 Web Browser (“webcast”)
                 FTP (“copy”)
      (Note that if you are using KnowledgeSync to generate and distribute a large
      number of reports, it’s much more efficient to distribute the reports via FTP or
      the web than it is to attach the reports to a large number of outgoing e-mail
      messages)
         Include Files as E-Mail Attachments. If an event has one or more files
          associated with it, you have the option to specify whether the associated files
          will be attached to the outgoing e-mail message or will be faxed (ascii files
          only), FTP’d, or posted to a webcast page.

          Similar to the previous option, this enables you to distribute files without
          having to attach them to every outgoing e-mail message.

          Note that if the event’s related query includes a column called
          “Attachment_Files”, KnowledgeSync will automatically attach those files
          along with any other files that were specified on the “Files” tab.
         E-Mail Notifications Should Wait Until Reports Are Completed. If an
          event has associated reports which are not attached to the outgoing e-mail,
          you can control the timing between when the reports are generated and when
          the e-mail is sent out.

          (Note that if an event has associated reports that are attached to an e-mail
          alert, KnowledgeSync will automatically wait for the reports to successfully
          complete before the e-mail message is sent.)

          If the associated reports are not attached to the outgoing e-mail, you have
          two options regarding when the e-mail alert will be delivered:
                 The e-mail notification should wait until the reports are successfully
                  generated before the e-mail alert is sent out. (Place a checkmark in
                  this option.)
                 The e-mail notification should not wait for the reports to successfully
                  generate before being sent out. (Do not place a checkmark in this
                  option.)
          Note the following:
          If this option is not checked, the e-mail message will be sent immediately,
          and the recipient of the message may not be able to access the associated
          report(s) right away if they take a while to generate.
          If this option is checked and any of the associated report(s) fail to be
          completed successfully, the e-mail message will not be sent out.



247                             Event Designing
             If associated reports are attached to the message and the reports fail to
             complete successfully, the e-mail message will not be sent out.

What Needs to Happen to Send E-Mail Alerts
     In order to send e-mail alert messages from KnowledgeSync, all of the following
     need to be true:
          The event must have an e-mail subject and message text.
          The event must have a valid e-mail sending account
          The event must have at least one subscriber who is to receive alerts via e-
           mail
          The subscriber(s) who are selected to receive alerts via e-mail must be
           “active”, they must have a valid e-mail address specified in their profile, and
           their “delivery times” must be configured to allow message receipt on the
           day/time the event is triggered.
          The KnowledgeSync service and e-mail server must be running
          The event’s associated query must retrieve matching records (e.g., the query
           must be triggered)
          If the event has already been triggered (and no new matching records are
           present), you must: a) remove the previously triggered items (see the
           “Triggered” tab), or, b) the event must be configured to “repeat notifications
           for triggered items”
     Vineyardsoft suggests that you run an “e-mail test” (from the Administrator module)
     to ensure that your e-mail sending account is correctly configured before attempting
     to send mail as a result of a triggered event.

Monitoring the Status of E-Mail Alerts
     When an event triggers the sending of an e-mail alert, you can use the
     KnowledgeSync Monitor to track the status of the delivery of those alerts.
     In the Monitor, you can click on the “Email Delivery” branch, and within that you
     can track:
            Mail messages that are “Pending” delivery.
            Mail messages that have been “Sent” successfully.
            Mail messages with “Errors” that have failed to be delivered successfully.
     If any of your e-mail alerts have failed to complete successfully because of an error
     condition, you may attempt to correct the message delivery, mark the delivery as
     “complete”, or you may manually delete the erroring delivery.
     (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
     branch, and then click on the “Email Delivery Errors” sub-branch.)
     Note that KnowledgeSync will attempt to re-deliver an erroring e-mail message every
     minute.

                                   Event Designing                                        248
Fax Tab
      Access via Navigator:
               Add Fax Message Text: Double-click on the event name, click on the
                “Fax” tab.
               Modify Fax Message Text: Expand the event’s components, expand the
                “Deliverables” branch, and double-click on the Fax branch.
      Note that KnowledgeSync supports faxing via both an embedded faxing technology
      and via Microsoft Fax. The embedded faxing technology uses the “Fax” tab of an
      event, but this technology supports only plain-text (ascii) formatted faxing. Using
      Microsoft Fax is done via the “Actions” tab, uses a VB Script (available from
      Vineyardsoft) and supports more output formats, including rich text (RTF).
      The configuration of a fax alert message is very similar to that of an e-mail message,
      and so the following sections will address only those aspects of fax alert message
      configuration that are different from that of an e-mail message configuration.




                                        EVENT “FAX” TAB

      (Note that no additional hardware or software is required to enable KnowledgeSync’s
      faxing technology; your server simply needs the ability to dial out via a modem.)
      Since you might have multiple accounts defined from which you can send fax alerts,
      the first step in configuring a fax alert message is to select which KnowledgeSync
      faxing account will be used for the sending of this fax message.
      (The configuration of your “Fax Accounts” is done in the KnowledgeSync
      Administration module. Please refer to chapter three, “KnowledgeSync
      Administration”, for details on this subject.)



249                                 Event Designing
    KnowledgeSync will not be able to send alerts via fax unless you have correctly
    configured (and selected) a fax account. Click on the down-arrow next to the field
    titled “Fax Account to Send From” and choose an account.

Enabling the Fax Server

    The KnowledgeSync “Fax” server must be enabled to process if you plan on using
    KnowledgeSync to send out alerts via fax when an event is triggered. To enable the
    fax server, follow these steps:
         Log into the KnowledgeSync Administrator module.
         Click on the “Activity” folder.
         Click on the “Server Status” folder.
         Double-click on the “Fax Server”.
         Place a checkmark in the field called “Allow Server to Process.”
         Click on “Save and Close” at the top-left of your window.
    To disable any alerts from being sent via fax, remove the checkmark from the “Allow
    Server to Process” field for the fax server.
    Note: If you disable the fax server and trigger events that are configured to send fax
    alerts, KnowledgeSync will “queue up” the pending fax alerts (which you can review
    in the KnowledgeSync Monitor). These “pending” alerts may subsequently be
    deleted, or (if you enable the fax server), they may be sent to the appropriate
    recipients at a later time.

Fax Cover Page, Subject, & Message Text

    When designing the content of a fax alert message, you can choose to specify content
    for the fax’s cover page, the fax “subject” field, and for the body of your fax
    message.
    Just as in the design of an e-mail alert message, you can include hard-coded text,
    database field values, and date substitution variables in the fax’s cover page, subject
    field, and body text.
    You can also use the {BEGIN*REPEAT} and {END*REPEAT} functions as
    detailed in the “E-Mail Tab” section. Remember, however, that you cannot use the
    “repeat” function in the fax tab of an event if you have already used it within any of
    the other tabs.
    Please note that the "Fax Comment" section is limited to a maximum of 230
    characters.

Configuring Fax Text to Use E-Mail Content

    If you have created e-mail alert text which you would like to replicate in the fax tab,
    you have two options for doing so:
        1. You may copy and paste the e-mail message text from the Email tab into the
           corresponding fax text field in the Fax tab.
                                  Event Designing                                        250
          2. You may type in the command “=email_message_text” (without the
             quotations) within the corresponding fax text field.

              If you choose to use the second of these options, your fax text would appear
              as follows:




                                FAX TEXT THAT USES CONTENT FROM
                                          THE EMAIL TAB


Fax Message Handling Options

      At the bottom of the Fax tab there are three checkboxes that allow you to further
      control the content of an outgoing alert message:
             Include Text Reports as Fax Pages. If an event has one or more reports,
              forms, or documents that are output to an plain-text format associated with it,
              you have the option to specify whether the associated items will be included
              in the outgoing fax message.

              In situations where you wish to distribute one or more reports via an event,
              but you wish to distribute the reports via the web or via FTP, you might wish
              to use the outgoing fax alert message to notify recipients of the webcast or
              FTP location that the reports were sent to, without actually including the
              reports in the fax message.
             Include Text Files as Fax Pages. If an event has one or more text files
              associated with it, you have the option to specify whether the associated files
              will be included in the outgoing fax message.

              Similar to the previous option, this enables you to distribute files without
              having to include them in every outgoing fax message.

              Note that if the event’s related query includes a column called

251                                 Event Designing
            “Attachment_Files”, KnowledgeSync will automatically fax those ascii files
            along with any other files that were specified on the “Files” tab
           Fax Notifications Should Wait Until Reports Are Completed. If an event
            has associated reports which are not included in the outgoing fax, you can
            control the timing between when the reports are generated and when the fax
            is sent out.

            (Note that if an event has associated reports that are included in a fax alert,
            KnowledgeSync will automatically wait for the reports to successfully
            complete before the fax message is sent.)

            If the associated reports are not included in the outgoing fax, you have two
            options regarding when the fax alert will be delivered:

                   The fax notification should wait until the reports are successfully
                    generated before the fax alert is sent out. (Place a checkmark in this
                    option.)

                   The fax notification should not wait for the reports to successfully
                    generate before being sent out. (Do not place a checkmark in this
                    option.)
            Note the following:
            If this option is not checked, the fax message will be sent immediately, and
            the recipient of the message may not be able to access the associated
            report(s) right away if they take a while to generate.
            If this option is checked and any of the associated report(s) fail to be
            completed successfully, the fax message will not be sent out.
            If associated reports are included in the fax message and the reports fail to
            complete successfully, the fax message will not be sent out.

What Needs to Happen to Send Fax Alerts
    In order to send fax alert messages from KnowledgeSync, all of the following need to
    be true:
         The event must have either a fax header page or fax message text.
         The event must have a valid fax sending account
         The event must have at least one subscriber who is to receive alerts via fax
         The subscriber(s) who are selected to receive alerts via fax must be “active”,
          they must have a valid fax address specified in their profile, and their
          “delivery times” must be configured to allow message receipt on the
          day/time the event is triggered.
         You must have a valid fax port defined in the KnowledgeSync
          Administration module
         The KnowledgeSync service and fax server must be running


                                  Event Designing                                        252
           The event’s associated query must retrieve matching records (e.g., the query
            must be triggered)
           If the event has already been triggered (and no new matching records are
            present), you must: a) remove the previously triggered items (see the
            “Triggered” tab), or, b) the event must be configured to “repeat notifications
            for triggered items”
      Vineyardsoft suggests that you run a “fax test” (from the Administrator module) to
      ensure that your fax sending account is correctly configured before attempting to
      send a fax as a result of a triggered event.

Monitoring the Status of Fax Alerts

      When an event triggers the sending of a fax alert, you can use the KnowledgeSync
      Monitor to track the status of the delivery of those alerts.
      In the Monitor, you can click on the “Fax Delivery” branch, and within that you can
      track:
             Fax messages that are “Pending” delivery.
             Fax messages that have been “Sent” successfully.
             Fax messages with “Errors” that have failed to be delivered successfully.
      If any of your fax alerts have failed to complete successfully because of an error
      condition, you may attempt to correct the message delivery, mark the delivery as
      “complete”, or you may manually delete the erroring delivery.
      (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
      branch, and then click on the “Fax Delivery Errors” sub-branch.)
      Note that KnowledgeSync will attempt to re-deliver an erroring fax message every
      minute.

Using an External Faxing Application

      Although KnowledgeSync includes its own faxing application, you may choose to
      integrate KnowledgeSync with a faxing technology (such as WinFax or FaxRush)
      that your organization already owns.
      In many cases, Vineyardsoft’s Support Department will already have APIs written
      for such external integrations. If you are interested in receiving one of these APIs,
      please contact Vineyardsoft Support.
      In other cases where you wish to integrate KnowledgeSync with an external faxing
      application and an API does not already exist, you can use KnowledgeSync’s VB
      (Visual Basic) Scripting module to create a script that will “call” your external faxing
      application and to “pass” to it all of the details of the triggered event.

Page Tab
      Access via Navigator:


253                                 Event Designing
             Add Pager Message Text: Double-click on the event name, click on the
              “Page” tab.
             Modify Pager Message Text: Expand the event’s components, expand
              the “Deliverables” branch, and double-click on the Page branch.
    The configuration of a pager alert message is very similar to that of a fax message,
    with the definition of the pager message text being identical to that of the text of an e-
    mail message (see “E-Mail Tab” for details).




                                      EVENT “PAGE” TAB

    (Note that no additional hardware or software is required to enable KnowledgeSync’s
    paging technology; your server simply needs the ability to dial out via a modem.)
    Please note that KnowledgeSync’s paging technology supports SMS (“Short
    Messaging System”).

Using Email to Send Pager Text Messages

    Although KnowledgeSync can send messages directly to a paging device, some
    organizations will prefer to use the Email function to deliver text message alerts to
    pagers. Whether to use this approach tends to depend on the paging service vendor
    you are using, and whether they allow pager messages to be sent to intermediate
    email addresses.
    For example, one paging service uses the following format:
    yourphonenumber@page.nextel.com
    And another uses:
    yourphonenumber@vtext.com
    Please contact the paging vendors that you will be using to learn the appropriate
    paging address format and then set your subscribers up accordingly.

                                   Event Designing                                        254
Enabling the Page Server

      The KnowledgeSync “Page” server must be enabled to process if you plan on using
      KnowledgeSync to send out alerts via pager when an event is triggered. To enable the
      page server, follow these steps:
           Log into the KnowledgeSync Administrator module.
           Click on the “Activity” folder.
           Click on the “Server Status” folder.
           Double-click on the “Page Server”.
           Place a checkmark in the field called “Allow Server to Process.”
           Click on “Save and Close” at the top-left of your window.
      To disable any alerts from being sent via pager, remove the checkmark from the
      “Allow Server to Process” field for the page server.
      Note: If you disable the page server and trigger events that are configured to send
      pager alerts, KnowledgeSync will “queue up” the pending pager alerts (which you
      can review in the KnowledgeSync Monitor). These “pending” alerts may
      subsequently be deleted, or (if you enable the page server), they may be sent to the
      appropriate recipients at a later time.

Pager Message Text

      When designing the content of a pager alert message, you can place as much or as
      little text as you wish in the body of your pager message.
      Just as in the design of an e-mail alert message, you can include hard-coded text,
      database field values, and date substitution variables in the pager message text.
      You can also use the {BEGIN*REPEAT} and {END*REPEAT} functions as
      detailed in the “E-Mail Tab” section. Remember, however, that you cannot use the
      “repeat” function in the pager tab of an event if you have already used it within any
      of the other delivery method tabs.

Pager Message Handling Options

      At the bottom of the Page tab there is one checkbox that allows you to further control
      the content of an outgoing alert message:
             Pager Notifications Should Wait Until Reports Are Completed. If an
              event that is sending a pager alert has associated reports, you can control the
              timing between when the reports are generated and when the pager message
              is sent out.

              You have two options regarding when the pager alert will be delivered:

                     The pager notification should wait until the reports are successfully
                      generated before the pager alert is sent out. (Place a checkmark in
                      this option.)

255                                 Event Designing
                    The pager notification should not wait for the reports to successfully
                     generate before being sent out. (Do not place a checkmark in this
                     option.)
             Note the following:
             If this option is not checked, the pager message will be sent immediately, and
             the recipient of the message may not be able to access the associated
             report(s) right away if they take awhile to generate.
             If this option is checked and any of the associated report(s) fail to be
             completed successfully, the pager message will not be sent out.

What Needs to Happen to Send Pager Alerts
     In order to send pager alert messages from KnowledgeSync, all of the following need
     to be true:
          The event must have pager message text.
          The event must have at least one subscriber who is to receive alerts via pager
          The subscriber(s) who are selected to receive alerts via pager must be
           “active”, they must have a valid pager address specified in their profile, and
           their “delivery times” must be configured to allow message receipt on the
           day/time the event is triggered.
          You must have a valid pager port and pager service(s) defined in the
           KnowledgeSync Administration module
          The KnowledgeSync service and page server must be running
          The event’s associated query must retrieve matching records (e.g., the query
           must be triggered)
          If the event has already been triggered (and no new matching records are
           present), you must: a) remove the previously triggered items (see the
           “Triggered” tab), or, b) the event must be configured to “repeat notifications
           for triggered items”
     Vineyardsoft suggests that you run a “pager test” (from the Administrator module) to
     ensure that your paging service and port are correctly configured before attempting to
     send a page as a result of a triggered event.

Monitoring the Status of Pager Alerts

     When an event triggers the sending of a pager alert, you can use the KnowledgeSync
     Monitor to track the status of the delivery of those alerts.
     In the Monitor, you can click on the “Pager Delivery” branch, and within that you
     can track:
            Pager messages that are “Pending” delivery.
            Pager messages that have been “Sent” successfully.
            Pager messages with “Errors” that have failed to be delivered successfully.
                                   Event Designing                                       256
      If any of your pager alerts have failed to complete successfully because of an error
      condition, you may attempt to correct the message delivery, mark the delivery as
      “complete”, or you may manually delete the erroring delivery.
      (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
      branch, and then click on the “Pager Delivery Errors” sub-branch.)
      Note that KnowledgeSync will attempt to re-deliver an erroring pager message every
      minute.

Webcast (Dashboard Alerts) Tab
      Access via Navigator:
               Add Webcast Message Text: Double-click on the event name, click on
                the “Webcast” tab.
               Modify Webcast Message Text: Expand the event’s components,
                expand the “Deliverables” branch, and double-click on the Webcast
                branch.
      Note: KnowledgeSync’s webcasting (aka “dashboard alerts”) module requires a few
      additional steps for initial configuration. Please refer to the chapter titled
      “Webcasting/Dashboard Alerts” for complete details on the set-up of this module
      before you configure the Webcast tab for an event.




                                     EVENT “WEBCAST” TAB

      The configuration of a webcast alert message is almost identical to that of an e-mail
      message, and so the following sections will address only those aspects of webcast
      alert message configuration that are different from that of an e-mail message
      configuration.
      (No additional hardware or software is required for the webcasting technology.)
257                                 Event Designing
Sample Webcast Output

    Since “webcasting” is a message delivery method that is unique to KnowledgeSync,
    you may find it helpful to see what a sample webcast output window looks like.
    The following illustration is of a webcast screen; it is important to note that the
    “template” behind this window is customizable, so you can include your own
    organization’s graphics, logos, et cetera.




                                 SAMPLE WEBCAST DASHBOARD

    Note that webcasting can also be configured to be a web-based listing of those events
    that you have received alerts about. Please refer to the chapter on Dashboard Alerts
    for more details.

Enabling the Webcast Server

    The KnowledgeSync “Webcast” server must be enabled to process if you plan on
    using KnowledgeSync to send out alerts via webcast when an event is triggered. To
    enable the webcast server, follow these steps:
         Log into the KnowledgeSync Administrator module.
         Click on the “Activity” folder.
         Click on the “Server Status” folder.
         Double-click on the “Webcast Server”.
         Place a checkmark in the field called “Allow Server to Process.”
         Click on “Save and Close” at the top-left of your window.
                                   Event Designing                                        258
      To disable any alerts from being sent via webcast, remove the checkmark from the
      “Allow Server to Process” field for the webcast server.
      Note: If you disable the webcast server and trigger events that are configured to send
      webcast alerts, KnowledgeSync will “queue up” the pending webcast alerts (which
      you can review in the KnowledgeSync Monitor). These “pending” alerts may
      subsequently be deleted, or (if you enable the webcast server), they may be sent to
      the appropriate recipients at a later time.

Webcast Subject & Message Text, & Options

      Please refer to the chapter titled “Dashboard Alerts”.

Monitoring the Status of Webcast Alerts

      When an event triggers the sending of a webcast alert, you can use the
      KnowledgeSync Monitor to track the status of the delivery of those alerts.
      In the Monitor, you can click on the “Webcast Delivery” branch, and within that you
      can track:
             Webcast messages that are “Pending” delivery.
             Webcast messages that have been “Sent” successfully.
             Webcast messages with “Errors” that have failed to be delivered
              successfully.
      If any of your webcast alerts have failed to complete successfully because of an error
      condition, you may attempt to correct the message delivery, mark the delivery as
      “complete”, or you may manually delete the erroring delivery.
      (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
      branch, and then click on the “Webcast Delivery Errors” sub-branch.)
      Note that KnowledgeSync will attempt to re-deliver an erroring webcast message
      every minute.

Action Tab
      Access via Navigator:
               Add Workflow Actions: Double-click on the event name, click on the
                “Actions” tab.
               Modify/Remove Workflow Actions: Expand the event’s components,
                expand the “Actions” branch, and double-click on the corresponding
                action branch.
               View/Modify Script Definition: To view or modify a Visual Basic
                script’s definition, right-click on the script branch and select “Edit”.
      Important Notes:



259                                 Event Designing
     1. An event’s “actions” will be executed once for each triggered record if the
        “repeat” function is not used. If the “repeat” function is used, an event’s actions
        will be executed once per group of triggered records, or once for all triggered
        records (see “Controlling Trigger Frequency” earlier in this chapter.)
     2. Since an event’s “actions” often include the adding or updating of records within
        an application database, please use this option with caution to ensure that an
        event is not accidentally (or erroneously) creating or adding database records.
     3. Make sure that none of your actions reference mapped drives. The
        KnowledgeSync service cannot translate mapped drives, and so you need to
        replace any such references with the full UNC location and filename.
     It is suggested that you use KnowledgeSync’s “User Authorization” settings
     (accessed within the Administration module) to disable the “Action” tab for any users
     who do not have the knowledge and permission to utilize such functions.

Actions & the “Repeat” Function

     Through the use of the “Begin Repeat” and “End Repeat” command, you can specify
     whether you wish to trigger an event once for each matching record, once per group
     of matching records, or once for all matching records.
     If your event does not use the repeat function, KnowledgeSync will execute the
     action(s) that you specify once for each triggered record.
     If your event does use the repeat function, KnowledgeSync will execute the action(s)
     that you specify once per group of triggered records or once for all triggered records
     depending on how the repeat function is configured.

Enabling the Action Server

     The KnowledgeSync “Action” server must be enabled to process if you plan on using
     any of the action functions. To enable the action server, follow these steps:
          Log into the KnowledgeSync Administrator module.
          Click on the “Activity” folder.
          Click on the “Server Status” folder.
          Double-click on the “Action Server”.
          Place a checkmark in the field called “Allow Server to Process.”
          Click on “Save and Close” at the top-left of your window.
     To disable any actions from taking place, remove the checkmark from the “Allow
     Server to Process” field for the action server.

The Six Types of “Actions”

     When an event is triggered, KnowledgeSync may execute any one or any
     combination of the following six types of actions:
            Create a file that contains content from a triggered event.

                                   Event Designing                                       260
             Submit one or more SQL (structured query language) statements that add,
              update, or delete records from one or more underlying database(s).
             Submit one or more stored procedures that add, update, or delete records
              from one or more underlying database(s).
             Run one or more executable programs.
             Run one or more VB (Visual Basic) scripts.
             Run KnowledgeSync’s Integration Wizard for the SalesLogix or GoldMine
              applications
      All of these actions may incorporate data from the corresponding triggered event.

The Order of Action Execution

      The order in which KnowledgeSync actions will be executed is:
             File creations
             SQL statements
             Stored Procedures
             Executable Programs
             The GoldMine and SalesLogix API Wizards
             VB scripts

Monitoring the Status of “Actions”

      When an action is triggered by an event, you can use the KnowledgeSync Monitor to
      track the status of the action’s execution.
      In the Monitor, you can click on the “Actions Taken” branch, and within that you can
      track:
             Actions that are “Pending” execution.
             Action that are “Completed” successfully.
             Actions with “Errors” that have failed to complete successfully.
      If any of your actions have failed to complete successfully because of an error
      condition, you may mark the action as “complete”, or you may manually delete the
      action.
      (Go to the KnowledgeSync Administration module, click on the “Corrective Actions”
      branch and then click on the “Action Errors” sub-branch.)

Referencing an Event’s Files Within “Actions”

      If an event has associated files (from the “Files” tab) or if the event’s related query
      includes a column called “Attachment_Files”, KnowledgeSync will automatically
      make those files available to any of the actions that can be triggered by the event.



261                                  Event Designing
Create a File Containing Event Data

     The first type of action that KnowledgeSync can execute is to take information from
     a triggered event and write it out to a flat file.




                               EVENT ACTION “CREATE FILE” TAB

     This action can be used in such manners as:
            To create one or more files of data that will be imported into another
             application (such as files with “today’s invoices”)
            To create “log” files of triggered event data
            To create a file that will be sent (e.g., e-mailed) to a business partner or
             mailing house for future processing
     Similar to designing an event’s alert message, the file that you create can contain
     hard-coded text, database field values (triggered event data), and even
     KnowledgeSync date substitution variables.
     Before you can create the format of a file that will contain triggered event data, you
     need to fill in the following fields:
            File Specification. Key in the location and name of the file you wish
             KnowledgeSync to create. Note that a file name may:
                    Be hard-coded (e.g., “orders.txt”)
                    Include field values (e.g., “{OrderID}.dat”)
                    Include date substitution variables
                     (e.g., “orders_{%Current_Date%}”)



                                   Event Designing                                          262
             Append Content to File Specification, if it Already Exists

              Or:

              Overwrite File Specification, if it Already Exists
             Select either of these two checkboxes to indicate how you want
              KnowledgeSync to act if the event is triggered and the corresponding file
              already exists.
      Once you have responded to these fields, you are ready to begin formatting the file
      that will contain triggered event data. Follow these steps:
           Click in the empty box beneath the heading “Contents of the File that will be
            Created.” Your cursor will now be positioned in the left-most column of the
            first row of this file.
           If your file will begin with hard-coded text (such as “OrderID”), key that text
            directly into the file formatting box.
           If your file will begin with a database field value, or with a date substitution
            variable, select the appropriate value from the list of “Available values for
            use as file content”. You may double-click on the appropriate value, or single
            click on it and then click on the “Use Selected Value” button.
           Once you have added a field from the list, go back to the file formatting box
            and click your mouse again to position your cursor for the next value.
           You can continue to add hard-coded text, field values, and date substitution
            variables until your file format is complete.

File Creation Notes

      Note the following about the KnowledgeSync “File Creation” action:
             You can use the {BEGIN*REPEAT} and {END*REPEAT} labels in your
              file. This will allow you to create a file that contains multiple records from a
              single triggered event. Note the following about using these commands in the
              “File Creation” option:

              You can use the “repeat” function in the creation of a file only if the repeat
              function is not also being used in any of the corresponding alert messages.

              If you use the “repeat” function in file creation, you cannot also send alert
              messages for individual triggered records. (It is suggested that if an event
              uses the “repeat” function within file creation, it should not also send out
              alert messages; instead, you should configure a similar event that sends out
              alerts.)
             You can create a comma separated file simply by manually typing in a
              comma after each selected database field value.
             You can create a tab-delimited file simply by pressing your CTRL/Tab key
              after each selected database field value.
             You can use the field formatting commands (detailed earlier in this chapter)
              to further control the appearance and format of the data in a file.

263                                 Event Designing
Execute a SQL Statement???

    The second type of action that KnowledgeSync can perform as a result of a triggered
    event is to submit one or more SQL statements that add, update, or delete specific
    records from one or more application databases.
    Before configuring SQL statement actions, please be aware of the following:
    1. Be careful when configuring a KnowledgeSync event to issue SQL statements
       against an application database. Please verify that the syntax of your SQL
       statement is correct before submitting it against a live database.
    2. Many sales, support, and CRM applications depend on “data synchronization” to
       update local and remote users of the application. Unless otherwise stated by the
       application vendor, it is usually not suggested that an organization use SQL
       statements to update such an application, as it will disrupt the synchronization
       process.
    3. KnowledgeSync’s SQL statement submission function does not have an assumed
       “where clause” in the SQL statement. You must be sure to specify the
       appropriate “where clause” to ensure that a SQL statement affects the appropriate
       record(s) within a database.
    4. If an event is going to update (or insert) records, make sure that your event does
       NOT make use of “{BEGIN*REPEAT}” and “{END*REPEAT}”. Any event
       that uses these commands does not have the ability to execute one insert (or
       update) per matching triggered record.
    Depending on the type of applications you are working with, the ability to issue SQL
    statements (such as “insert” and “update” statements) as the result of a triggered
    event can be one of the quickest and easiest ways to add to (or update) an application
    database.




                             EVENT ACTION “SUBMIT SQL” TAB
                                 Event Designing                                       264
      SQL statements can be used to perform such actions as:
             To add order records to a financial database when an opportunity is closed in
              a sales application
             To update a record in one database when the corresponding record is
              changed in another database
      It is very important to understand that the SQL statement(s) that you specify in this
      option will be executed once for every triggered record in the event. For example, if
      an event runs and is triggered by 10 “orders that were shipped later than their
      required date,” each SQL statement that is associated with this event will be executed
      10 times – once for each triggered record.
      A single event may trigger the execution of one or multiple SQL statements; these
      statements may perform actions against the database in which the triggered event
      occurred, and/or the statements may perform actions against any other ODBC-
      compliant databases.
      All standard SQL commands (such as “insert”, “update” and “delete”) are supported
      in the SQL action tab.

SQL “Where” Clause

      It is very important to note that the SQL statements that KnowledgeSync executes
      from the “Action” tab have no implied “where” clause.
      Thus, even though an event’s query(ies) may restrict the records that are retrieved to
      a specific set, the conditions that the query(ies) have applied are not automatically
      applied to the SQL statements that are executed.
      Therefore, to make sure that your SQL statement(s) act on the same record (or
      records) that an event’s query(ies) retrieves, you must be sure to include a “where”
      clause in your SQL that identifies precisely which records are to be affected.

Specifying Your SQL ODBC Connection

      The first step in defining a SQL statement that will be executed when an event is
      triggered is the specification of the “connection record” (ODBC driver, as defined in
      KnowledgeSync) that will be used when this statement is executed.
      (Connection records are typically defined in KnowledgeSync at the time when you
      create a new application in the Event Manager. Refer to chapter one, “Installation &
      Configuration” for details.)
      If you wish to use a SQL statement to update an application that is not currently
      defined within KnowledgeSync, you can configure a connection record for that
      application directly from the SQL tab.
      To select a KnowledgeSync ODBC connection record that is already defined, follow
      these steps:
           Click in the column titled “Connection Information” and a list button will
            appear.


265                                 Event Designing
          Click on the list button to display the “Application Connection Selection”
           window.
          Click on the list button under the heading “Please select the connection
           information for submitting SQL” to display your existing connections.
          Choose the appropriate connection and click on “OK.”
     To create a KnowledgeSync ODBC connection record, follow these steps:
          Click in the column titled “Connection Information” and a list button will
           appear.
          Click on the list button to display the “Application Connection Selection”
           window.
          Click on the “New Connection” button.
          Key in a description of the ODBC source that you will be using for the
           execution of this SQL statement.
          Choose (from the drop-down list) the ODBC source that will allow
           KnowledgeSync to connect to the underlying database.
          (If needed) Specify the username and password that will allow
           KnowledgeSync access to this database.
          Leave the remainder of the fields with their default values.
          Click on “Save and Close” at the top-left of your window and then click on
           “OK” from the previous window.
     If you add or change the definition of an ODBC source (from your ODBC
     Administrator) while you are in the KnowledgeSync Event Manager, you will have to
     exit from the Event Manager and re-enter it in order for it to recognize the new or
     modified ODBC sources.
     Note that an event that checks for a specific condition in application ‘a’ may use SQL
     statements to update data in applications ‘b’, ‘c’, ‘d’, and so on.

Entering Your SQL Syntax

     Once you have specified the ODBC connection that you will be using, you are ready
     to begin entering the syntax of your SQL statement. Here are some guidelines
     regarding the creation of your SQL statements:
            You can use any of the data fields from the triggered event in your SQL
             statements.
            You can use any of KnowledgeSync’s date substitution variables in your
             SQL statements.
            Do not forget to include a “where” clause on the end of your SQL statement
             so that KnowledgeSync knows exactly which records to act on.
            You cannot use {BEGIN*REPEAT} or {END*REPEAT} in a SQL
             statement.
            Keep in mind that a SQL statement will execute once for each record that is
             triggered by an event.

                                  Event Designing                                       266
             You can use the field formatting commands (detailed earlier in this chapter)
              to further control the appearance and format of the data in your SQL
              statements and/or stored procedures.
      Your SQL syntax will look like the following:
      update sysdba.ACCOUNT set sysdba.ACCOUNT.TYPE = 'Dead' where
      sysdba.ACCOUNT.ACCOUNTID = '{ACCOUNTID}'
      Note that the “where clause” in this SQL update statement makes using of the
      “account ID” field from the triggered record so that KnowledgeSync knows which
      record in the underlying database it is to update.

Delaying SQL Execution Until Reports Are Complete

      The last item you need to specify when configuring SQL statement actions pertains to
      whether the corresponding event has any Crystal reports associated with it.
      If the corresponding event has no associated reports, you may ignore the checkbox
      titled “Wait for Reports to Complete.”
      If the corresponding event does have associated reports, you may wish for the reports
      to finish being generated before your SQL statement is executed. (For example, you
      may wish to run a report on data that is subsequently modified by your SQL
      statement.)
      If you do wish for your SQL to wait for the report generation, place a checkmark in
      the “Wait for Reports to Complete” box. If you wish for the SQL to be executed right
      away, leave this field blank.
      Please note that if this option is checked and any of the associated report(s) fail to be
      completed successfully, the corresponding SQL statement will not be executed.

Executing SQL and “Begin Repeat”

      Based upon how the event is configured (i.e., how it uses the “repeat” function),
      KnowledgeSync will execute SQL (or stored procedures) once for each triggered
      record, or once for each group of triggered records, or once for all triggered records.
      Consider the following scenario:
      You have an event that identifies clients who have not been contacted within the last
      14 days. In the e-mail tab, this event uses the “repeat” function to send one alert
      message (e.g., to a manager) listing all of the clients who meet this criteria.
      If you configure SQL/stored procedures to execute along with this event, the
      SQL/stored procedures will execute just once for all the triggered records because the
      “repeat” function is enabled. If you want the SQL/stored procedures to execute once
      per triggered record, you must not use the “repeat” function within this event.
      (The solution is to use two events – one that sends the summarized alert message to a
      manager, and another event that triggers the SQL/stored procedures for each
      triggered record.)



267                                  Event Designing
Submit a Stored Procedure

    The third “action” that KnowledgeSync can perform as a result of a triggered event is
    to submit one or more stored procedures.
    If you wish to trigger a stored procedure in response to a KnowledgeSync event
    being triggered, follow these steps:
         Choose the “connection” for the database that you wish to run your stored
          procedure against.
         Type in the procedure name, as in “dbo.myprocedurename”
         To pass parameters into your procedure, use the following syntax:
                    “dbo.myprocedurename param1,param2,param3”

Run a Program

    The fourth “action” that KnowledgeSync can perform as a result of a triggered event
    is to run one or more executable programs. You can specify which programs you
    wish to run within the “Run Program” tab.




                            EVENT ACTION “RUN PROGRAM” TAB

    By executing a program as a result of a triggered event, you can do such things as:
           Use the program to add or update data in an underlying database
           Call an external application (such as a non-Crystal reporting application) and
            pass the appropriate data to that application
           Call an external utility (such as a synthesized voice unit) and pass triggered
            event data to that program


                                  Event Designing                                       268
Selecting a Program to Run

      To choose a program that KnowledgeSync will run when the corresponding event is
      triggered, click in the “Program to Run” field and then click on the list button that
      appears there. You will get a dialog box from which you can select the “.exe”
      program you wish KnowledgeSync to execute.
      Note that KnowledgeSync can run multiple programs in response to the triggering of
      a single event.

Allow Multiple Tasks

      The “Allow Multiple Tasks” checkbox allows you to specify whether
      KnowledgeSync will allow only a single copy of this task to run at any one time, or
      will allow multiple copies of this task to run simultaneously.
      The primary consideration here is system performance; consider (for example) if you
      had an event that was triggered by closed sales and you had an action that ran a
      program for each of those sales.
      If “Allow Multiple Tasks” is enabled and the event is triggered by 1,000 matching
      sales, you will have 1,000 copies of the same program running in your system’s
      memory at the same time. This would impact your server’s performance.
      (If, however, you have an event that returns a small set of triggered records, and the
      program that you wish to run is relatively resource non-intensive, you may choose to
      allow multiple iterations of that program to run at the same time.)
      The suggested setting for this field is blank (i.e., do not allow multiple tasks).

Command Line Parameters

      The manner in which data from a triggered event can be passed to an executable
      program is via command line parameters.
      All of the fields of data from a triggered event, plus all of KnowledgeSync’s date
      substitution variables, are available for use as command line parameters.
      To add (or edit) command line parameters, click in the “Command Line Parameters”
      field, click on the list button that appears there, and you will be presented with an
      editing window from which you can enter (or modify) your parameters.
      Click on the “OK” button from this editing window when you are done.

Delaying Program Execution Until Reports Are Complete

      The last item you need to specify when configuring executable program actions
      pertains to whether the corresponding event has any Crystal reports associated with
      it.
      If the corresponding event has no associated reports, you may ignore the checkbox
      titled “Wait for Reports to Complete.”


269                                  Event Designing
     If the corresponding event does have associated reports, you may wish for the reports
     to finish being generated before your program is executed. (For example, you may
     wish to run a report on triggered event data, and then modify that data using your
     program.)
     If you do wish for your program to wait for the report generation, place a checkmark
     in the “Wait for Reports to Complete” box. If you wish for the program to be
     executed right away, leave this field blank.
     Please note that if this option is checked and any of the associated report(s) fail to be
     completed successfully, the corresponding program will not be executed.

Program Execution Notes

     Note: The program(s) that you run must not need any user input in order to
     complete. As a server-based application, there is no “user” present to respond to any
     such input.
     If you are running KnowledgeSync under Windows NT, XP, 2000, or 2003 and need
     to have an event run a program that requires desktop interaction, you must modify
     how the KnowledgeSync Service is run to allow the service to interact with the
     desktop of the server on which KnowledgeSync is running.
     To modify the KnowledgeSync service in this way, go to your system’s Control
     Panel (the “Services” option), choose the KnowledgeSync service, click on the “Log
     On” tab, and check on the 'Allow Service to interact with Desktop' option. Please be
     aware that the KnowledgeSync Action Server will be held in a “waiting” state until
     the required interaction with the desktop is complete.
     Note: If your program will be calling any “dll’s”, please ensure that these dlls (or
     copies of them) are located in the “windows/system” directory.
     Also Note: You can use the field formatting commands (detailed earlier in this
     chapter) to further control the appearance and format of the data in your program’s
     parameters.

Program Execution and “Begin Repeat”

     Based upon how the event is configured (i.e., how it uses the “repeat” function),
     KnowledgeSync will execute a program once for each triggered record, or once for
     each group of triggered records, or once for all triggered records.
     Consider the following scenario:
     You have an event that identifies clients who have not been contacted within the last
     14 days. In the e-mail tab, this event uses the “repeat” function to send one alert
     message (e.g., to a manager) listing all of the clients who meet this criteria.
     If you configure a program to execute along with this event, the program will execute
     just once for all the triggered records because the “repeat” function is enabled. If you
     want the program to execute once per triggered record, you must not use the “repeat”
     function within this event.
     (The solution is to use two events – one that sends the summarized alert message to a
     manager, and another event that triggers the program(s) for each triggered record.)
                                    Event Designing                                         270
Run a Basic Script

      The fifth, and one of the most common actions that is run as the result of a triggered
      event, is the ability to run one or more Basic (also called “Visual Basic” or “VB”)
      scripts.




                             EVENT ACTION “RUN BASIC SCRIPT” TAB

      VB scripts in KnowledgeSync are similar (in concept) to programs in that the scripts
      can use any data from a triggered event in the script’s execution.
      Because of the expertise required for the creation of VB scripts, the setup of the VB
      scripts that can be executed within KnowledgeSync is performed in a separate option.
      This option is called “Basic Scripts” and is located on the main Event Manager
      window, beneath the options to configure an application’s queries, events, and
      reports.
      Please refer to the chapter of this guide titled “Visual Basic Scripting” for complete
      details on how to configure these scripts.
      Once your scripts are configured, however, you can then use the “Run Basic Script”
      option within an event’s “Actions” tab to link one or more of your scripts to a
      KnowledgeSync event. To do so, follow these steps:
           Click in the field called “Basic Script Name” and click on the list button that
            appears there to get a listing of all the scripts that are currently available for
            use as a response to a triggered event.
           Select the script you wish to use. Note that KnowledgeSync supports both
            “front-end” scripts (those that are used instead of a query) and “back-end”
            scripts (those that are used as an action in response to a triggered event). The
            list that you will see will include only back-end scripts.
           Once selected, KnowledgeSync will display the name and file specification
            of the selected script.
271                                 Event Designing
     Repeat these steps for each script you wish to associate with an event.
     Remember: A KnowledgeSync script may be executed once for each triggered
     record, once for all triggered records, or once per group of triggered records. Please
     review your event (and in particular your use of the “repeat” function) to verify how
     many times your scripts will be executed by a triggered event.

VB Script Notes

     Note: The script(s) that you run must not need any user input in order to complete.
     As a server-based application, there is no “user” present to respond to any such input.
     If you are running KnowledgeSync under Windows NT, XP, 2000, or 2003 and need
     have an event run a script that requires desktop interaction, you must modify how the
     KnowledgeSync Service is run.
     To modify the KnowledgeSync service in this way, go to your system’s Control
     Panel (the “Services” option), choose the KnowledgeSync service, click on the “Log
     On” tab, and check on the 'Allow Service to interact with Desktop' option. Please be
     aware that the KnowledgeSync Action Server will be held in a “waiting” state until
     the required interaction with the desktop is complete.
     Note also that you can use the field formatting commands (detailed earlier in this
     chapter) to further control the appearance and format of the data in your scripts.

Scripts and “Begin Repeat”

     Based upon how the event is configured (i.e., how it uses the “repeat” function),
     KnowledgeSync will execute a script once for each triggered record, or once for each
     group of triggered records, or once for all triggered records.
     Consider the following scenario:
     You have an event that identifies clients who have not been contacted within the last
     14 days. In the e-mail tab, this event uses the “repeat” function to send one alert
     message (e.g., to a manager) listing all of the clients who meet this criteria.
     If you configure a script to execute along with this event, the script will execute
     just once for all the triggered records because the “repeat” function is enabled. If you
     want the script to execute once per triggered record, you must not use the “repeat”
     function within this event.
     (The solution is to use two events – one that sends the summarized alert message to a
     manager, and another event that triggers the scripts for each triggered record.)

Run the SalesLogix or GoldMine API Wizard

     The sixth action that KnowledgeSync can execute as a result of a triggered event is to
     update either the SalesLogix or the GoldMine customer relationship management
     (CRM) applications.
     This actions enables an organization that is using either of these applications to do
     two things:


                                   Event Designing                                        272
          1. Take information from a triggered event and create a GoldMine or
             SalesLogix contact history record.
          2. Take information from a triggered event and create a GoldMine or
             SalesLogix scheduled activity record for a contact.
      This action is limited to the creation of either (or both) history and activity records.
      (To update and/or complete a record, an event would need to use a KnowledgeSync
      Basic script.)
      Note that the GoldMine wizard supports only through version 5 of the GoldMine
      application.

The Wizards and “Begin Repeat”

      Based upon how the event is configured (i.e., how it uses the “repeat” function),
      KnowledgeSync will execute the API wizards once for each triggered record, or once
      for each group of triggered records, or once for all triggered records.
      Consider the following scenario:
      You have an event that identifies clients who have not been contacted within the last
      14 days. In the e-mail tab, this event uses the “repeat” function to send one alert
      message (e.g., to a manager) listing all of the clients who meet this criteria.
      If you configure one of the wizards to execute along with this event, the wizard will
      execute just once for all the triggered records because the “repeat” function is
      enabled. If you want the wizards to execute once per triggered record, you must not
      use the “repeat” function within this event.
      (The solution is to use two events – one that sends the summarized alert message to a
      manager, and another event that triggers the individual updates.)

Sample Use of the Wizards

      Consider the following event:
      You have an event that monitors clients who have pending sales opportunities but
      have not been contacted within the past week. When the event is triggered, it sends an
      e-mail alert message to the salesrep who is responsible for each corresponding
      account.
      Now consider how the GoldMine or SalesLogix Wizards can increase the value of
      this event by updating your database with the details of what has happened and
      what has to happen to address the triggered condition:
      History Update: When the event is triggered, KnowledgeSync updates the client’s
      history (in GoldMine or SalesLogix) with the details of when the client was last
      contacted as well as the details of when and how the salesrep was reminded.
      Activity Update: When the event is triggered, KnowledgeSync will update GoldMine
      or SalesLogix with a scheduled a phone call to be made by the salesrep to the
      corresponding client who has not been contacted.


273                                 Event Designing
Triggering External Updates

     It’s very important to note that the SalesLogix and GoldMine wizards can be
     executed by events that are triggered by conditions of data that exist outside of the
     SalesLogix or GoldMine applications.
     For example, you might be using SalesLogix with the MAS90 financial application
     and wish to update SalesLogix when certain conditions occur in MAS90.
     Using the KnowledgeSync API for SalesLogix, you could create an event that checks
     to see if a client has any overdue invoices in MAS90. If so, the event could update
     the client’s history (in SalesLogix) with the details of the overdue invoices, and the
     event could also schedule a phone call (in SalesLogix) for the account manager to
     contact the client and discuss the overdue invoices.

Identifying the Records to Update

     In both the SalesLogix and GoldMine applications, account and contact records are
     identified by a unique “ID”; without knowing this ID it is impossible to tell
     KnowledgeSync which records to update.
     Thus if you wish to use either of the SalesLogix or GoldMine APIs in a
     KnowledgeSync event, you should be sure that the event contains the database fields
     that uniquely identify the SalesLogix or GoldMine record for which the history or
     activity records are to be created.
     (In SalesLogix, you would need to make sure that an event includes the “contact ID”
     field, and in GoldMine, you would need to make sure that an event includes the
     “account number” and “contact name”.)
     If you were configuring an event that updated SalesLogix or GoldMine based on
     conditions in another application (e.g., MAS90), your event would need to include
     one query that identifies the MAS90 conditions, and a second query that identifies
     the corresponding record in SalesLogix or GoldMine that you wished to update.

Specifying the API Login Information

     In both the SalesLogix and GoldMine applications, you must provide the appropriate
     login information for KnowledgeSync to access the corresponding database and
     insert the resulting records.
     You can specify this information either within each event (within the API entry
     window), or you can do so just once by specifying this information within the
     application’s “Properties”. (In the Event Manager, highlight the branch that contains
     the application’s name, click on the “Properties” button at the top of the Event
     Manager window, and then click on “Edit Connection” button.)
     Regardless of which option you choose for the entry of this data, you must specify
     the username and password of the account that KnowledgeSync will use to access the
     corresponding database.
     Please note that for SalesLogix the “Database” name that you are prompted for must
     be one of the following:

                                   Event Designing                                       274
          SalesLogix V4.x or V5.x: The BDE alias name.
          SalesLogix V6.x or Greater: The data source link name

Accessing the GoldMine API Wizard

      To access the GoldMine API Wizard, follow these steps:
          Click on the “Run Program” sub-tab within the “Action” tab.
          Click in the “Program to Run” field.
          Type in “GM5S32.DLL” (do not include a disk and/or folder specification).
           This dll (or a copy of it) must reside in the Windows System32 folder.
          Leave the “Allow Multiple Tasks” checkbox blank.
          Click in the “Command Line Parameters” field and click on the list button
           that appears there. You will be taken into the GoldMine API Wizard, with
           the default window enabling you to create a scheduled activity within the
           GoldMine database.

             At the top right-hand section of this window is an option to create a
             GoldMine history record for a specific account and contact. Note that you
             can choose one option or the other; if an event needs to create both a
             GoldMine scheduled activity and a GoldMine history record, you will need
             to create two records in the “Run Program” tab; both records would execute
             the “GM5S32.DLL” function.

             The GoldMine API Wizard window will look like the following:




                EVENT ACTION: GOLDMINE API WIZARD (SCHEDULE ACTIVITY)


Accessing the SalesLogix API Wizard

      To access the SalesLogix API Wizard, follow these steps:
275                               Event Designing
          Click on the “Run Program” sub-tab within the “Action” tab.
          Click in the “Program to Run” field.
          Type in “SLGXAPI.DLL” (do not include a disk and/or folder specification).
           This dll (or a copy of it) must reside in the Windows System32 folder.
          Leave the “Allow Multiple Tasks” checkbox blank.
          Click in the “Command Line Parameters” field and click on the list button
           that appears there. You will be taken into the SalesLogix API Wizard, with
           the default window enabling you to create a scheduled activity within the
           SalesLogix database.

             At the top right-hand section of this window is an option to create a
             SalesLogix history record for a specific account and contact. Note that you
             can choose one option or the other; if an event needs to create both a
             SalesLogix scheduled activity and a SalesLogix history record, you will need
             to create two records in the “Run Program” tab; both records would execute
             the “SLGXAPI.DLL” function.

             The SalesLogix API Wizard window will look like the following:




                          EVENT ACTION “SALESLOGIX API WIZARD”

Choose “Add History” or “Schedule Activity”

     The API Wizards for both GoldMine and SalesLogix are designed identically; they
     both contain option boxes at the top of your window where you can specify whether
     you wish to create a history record or an activity record.
     It is important to note that a single event can both update a contact’s history and
     schedule an activity.




                                   Event Designing                                         276
      To create both, you will have to create two “Run Program” records, both of which
      call the GoldMine or SalesLogix API. This way, one record can create history
      records, and the other can create activity records.

Specify Application Login Information

      Once you have chosen the type of action you wish to perform, the next step is to
      identify the appropriate application login information (database name and/or location,
      and username and password) that KnowledgeSync will require in order to gain access
      to either GoldMine or SalesLogix and create the corresponding records.
      After you have filled in this information, you are ready to begin specifying how
      KnowledgeSync will “fill in” information about the corresponding history or activity
      record that is created.

Identify the Contact You Wish to Update

      The main part of configuring a GoldMine or SalesLogix Wizard action is the
      identification of what data will be written to each field within a history or activity
      record.
      In both GoldMine and SalesLogix, a history or activity record contains a standard set
      of data fields – information such as the contact ID or name, the type of history or
      activity record to be created, and the scheduled date, time, and duration.
      The most important of these fields is the contact ID (for SalesLogix) and the contact
      name and account number (for GoldMine). KnowledgeSync needs to know which
      contact within GoldMine or SalesLogix to create the history or activity record for.
      The only way to do this is to “map” the corresponding contact information from the
      triggered event to the API wizard.
      This is where the design of your underlying query is extremely important (and may in
      fact have to be modified). If your query does not contain the field(s) that uniquely
      identify the contact, KnowledgeSync has no way of knowing which contact within
      GoldMine or SalesLogix to update.
      Assuming that your query does contain the corresponding client fields, all you need
      to do is to “map” those query fields to the appropriate fields within the GoldMine or
      SalesLogix record.
      For example, here are the steps that you would follow if you were creating a
      SalesLogix history record:
           Assume that you have a field in your query called “{ContactID}”
           Go to the left-hand column of the SalesLogix API Wizard (the column that
            reads “To History Column”)
           Look for the row that is called “Contact ID”
           Move to the right-hand column (the one that reads “From Field/Text”)
           Click in that field
           Click on the list-button that appears
           Select “{ContactID}” from the list.

277                                  Event Designing
      And here are the similar steps that you would follow if you were creating a GoldMine
      history record:
           Assume that you have a field in your query called “{Accountno}”
           Go to the left-hand column of the GoldMine API Wizard (the column that
            reads “To History Column”)
           Look for the row that is called “Account Number”
           Move to the right-hand column (the one that reads “From Field/Text”)
           Click in that field
           Click on the list-button that appears
           Select “{Accountno}” from the list.
      Having mapped the client’s unique identifying data into the API Wizard, you are now
      ready to continue filling in the rest of the values of the activity or history records you
      are creating.

Updating from Non GoldMine or SalesLogix Apps

      If an event is to use the GoldMine or SalesLogix API wizards, you need to know the
      GoldMine or SalesLogix contact ID (and account number, for GoldMine) in order to
      correctly update the right record. If, however, your event is monitoring data outside
      of GoldMine or SalesLogix (e.g., in Great Plains), you will not have these GoldMine
      or SalesLogix data fields within this event’s query.
      This is where you need a two-query event.
      Your first query will monitor the Great Plains data (or data in any other DB) for the
      specific conditions you are interested in.
      Your second query will be a GoldMine or SalesLogix query; this query will take the
      customer information from the first query and will link it to the appropriate
      GoldMine or SalesLogix contact. By so doing, you will now have access to the fields
      that enable you to link these wizard actions to a specific record in either GoldMine or
      SalesLogix.

Identify History/Activity Data Field Values

      Once you have successfully mapped the data field(s) from an event’s query(ies) to
      the corresponding contact fields in an activity or history record, you may proceed
      with filling in the data for the remainder of the fields.
      Note the following about placing values in a history or activity record’s data fields:
             You can take the value of a database field from a triggered event and map it
              into a field in the corresponding activity or history record (e.g., fill in the
              “Opportunity” field with the value “{Opportunity_ID}”)
             You can take the value of multiple database fields from a triggered event and
              map them into a field in the corresponding activity or history record (e.g., fill
              in the “Regarding” field with the value “{Call_ID} {Call_Description}”)

              (Note that if you are mapping multiple database fields into a single activity or
                                     Event Designing                                        278
              history record field, you may select the first field from the drop-down list,
              but all successive fields must be manually typed in.)
             You can take hard-coded text and map it into a field in the corresponding
              activity or history record (e.g., fill in the “Priority” field with the value
              “High”)
             You can take both hard-coded text and the value of database fields from the
              triggered event and map them into a field in the corresponding activity or
              history record (e.g., fill in the “Regarding” field with the value “Call ID:
              {Call_ID} Re: {Call_Description}”)
             You can map the same database field value to multiple fields in the
              corresponding activity or history record field (e.g., map the “{Call_ID}” field
              to both the “Regarding” and “Notes” fields.
             You can load any of KnowledgeSync’s date substitution variables (such as
              “{%Tomorrow Date%}”) into any of the fields for an activity or history
              record.
             You can combine date substitution variables with hard-coded times, as in
              “{%Tomorrow Date%} 9:00 AM” to indicate something that is scheduled for
              tomorrow at nine in the morning.
             Both GoldMine and SalesLogix have a few fields in the activity and history
              records that need to be responded with in either a “true or false” or “yes or
              no” manner. In the SalesLogix Wizard, you will see both “T” and “F” listed
              as a potential field value; in the GoldMine wizard you will see both “1” (for
              “yes”) and “2” (for “no”) listed as potential field values.
             You can use the field formatting commands (detailed earlier in this chapter)
              to further control the appearance and format of the data in your API updates.

GoldMine & SalesLogix “Types” and “Codes”

      Both GoldMine and SalesLogix categorize activity and history records according to
      specific “types” or “codes”.
      You must be careful to enter a valid “type” or “code” in these fields when adding a
      corresponding record. Both GoldMine and SalesLogix identify these types/codes
      using a pre-defined set of internal values; it is important that you know what these
      values represent and that you select an appropriate type/code for each record you are
      creating.
      (Please refer to your GoldMine or SalesLogix documentation for a list of the valid
      activity and history types/codes.)

SalesLogix Wizard Notes

      In SalesLogix, every activity or history record must have a valid “type”. The values
      of these fields are site-defined and are typically represented by specific numeric
      values (such as "262145", "262146", and "262147").
      In addition to the “type” field, every activity or history record that KnowledgeSync
      creates should have a valid "contact ID," and "regarding" field value.


279                                 Event Designing
     For an activity record, be sure to include the “scheduled user” and “scheduled
     date/time” values.

GoldMine Wizard Notes

     The "record type" field is very important. Be sure to include a valid record type for
     each activity or history record you create. By default, KnowledgeSync loads an "O"
     (for "other") into the record type field, but values such as "A" (for appointment), "C"
     (for scheduled call), and "D" (for to-do) are all valid entries, as are site-specific
     values.
     In GoldMine, you may also wish to ensure that every activity or history record has a
     valid “activity code.” The values of these fields are site-specific.
     In addition to the “record type” and “activity code” fields, every activity or history
     record that KnowledgeSync creates should have a valid "account number," "for
     GoldMine user," and “account name” field value.

Delaying Wizard Execution Until Reports Are Complete

     Once you have completed your field mapping and have returned to the “Run
     Program” tab, there is one last item you need to specify. Located to the right of the
     “Command Line Parameters” field, this pertains to whether the corresponding event
     has any Crystal reports associated with it.
     If the corresponding event has no associated reports, you may ignore the checkbox
     titled “Wait for Reports to Complete.”
     If the corresponding event does have associated reports, you may wish for the reports
     to finish being generated before your Wizards are executed. (For example, you may
     wish to run a report on triggered event data, and then add to that data using your
     Wizards.)
     If you do wish for your Wizard to wait for the report generation, place a checkmark
     in the “Wait for Reports to Complete” box. If you wish for the Wizard to be executed
     right away, leave this field blank.
     Please note that if this option is checked and any of the associated report(s) fail to be
     completed successfully, the corresponding Wizard will not be executed.

Subscribers Tab
     Access via Navigator:
              Add Subscribers: Double-click on the event name, click on the
               “Subscribers” tab.
              Modify/Remove Subscribers: Expand the event’s components, expand
               the “Subscribers” branch, and double-click on the corresponding
               subscriber branch.
              View/Modify Subscriber Profile: To view or modify a subscriber’s
               profile, right-click on the subscriber branch and select “Edit”.

                                    Event Designing                                        280
      The “Subscribers” tab allows you to specify who will receive alerts about a triggered
      event and via what means each subscriber will be notified (e-mail, fax, pager, copy
      (FTP), or webcast).




                                   EVENT “SUBSCRIBERS” TAB

      The subscribers tab is divided into two sub-tabs; the “Standard” tab (which is the
      default), and the “Advanced” tab.
      The “Standard” tab is used when an event will notify a pre-defined group of
      subscribers, such as “John Smith”, “Mary Reynolds”, and “Pat Crowley”.
      The “Advanced” tab is used when an event will notify people based on the records
      that have been triggered. An example of this would be an event that identifies all
      “opportunities that are due to close this week” and notifies each salesrep associated
      with these events.
      Note that a single event may send alerts to a combination of “standard” and
      “advanced” subscribers.


Monitoring the Status of Alert Messages

      When an alert message is triggered by an event, you can use the KnowledgeSync
      Monitor to track the status of the message’s delivery.
      In the Monitor, go to the “Application Events” branch and then click on any of the
      “Triggered” branches. Once you locate the triggered event whose alert messages you
      wish to track, follow these steps:
           Highlight (single-click on) the triggered event whose messages you wish to
            track.
           Click on the “Deliverables” button at the bottom-left of the Monitor window.
            This will show you a listing of all the subscribers for that event.
281                                 Event Designing
          Review the details of each subscriber; you will see who was supposed to be
           notified, via what method, when the message was delivered, and whether the
           delivery was successful.
     Note that you can also view the details (text) of the actual outgoing alert message by
     simply going up to the triggered event record and pointing your cursor at the
     appropriate column (in the grid) that contains the e-mail, fax, pager, or webcast text.
     (The grid will automatically expand to display the full text of the alert message.)

Standard Subscribers

     Note: Before you select subscribers for an event, you must define your subscribers
     within the KnowledgeSync database. See the chapter titled “Subscribers” for details.
     There are four types of standard subscribers:
            Individual people
            Groups of people
            Individual computers
            Groups of computers
     People can be notified via e-mail, fax, copy/ftp, pager, and webcast.
     Computers can be notified via copy/ftp only.
     Note that copy/ftp notifications refer to KnowledgeSync’s ability to take the reports
     and/or files that are associated with a triggered event and to “copy” (or FTP) them to
     a specific location (computer, directory, and folder).

Adding a Standard Subscriber

     To add a standard subscriber to an event, follow these steps:
          Click on the “Add Subscriber” button. You will be shown a list of all your
           subscriber groups.




                                    Event Designing                                        282
                            EVENT SUBSCRIBER SELECTION WINDOW
           If you wish to send alerts to all the members of a specific group, click in the
            checkbox to the left of the group’s name.

              (Note that if you do select a group, all of the members of the group will be
              notified via the same delivery method.)
           If you wish to send alerts to specific subscribers, expand the group to which
            that subscriber belongs until you can see the subscriber’s name. Then, place a
            checkmark in the box to the left of the subscriber’s name.
           Continue to repeat this process for each group or subscriber you wish to
            notify. A single event can notify any combination of groups and individual
            subscribers.
      Note that if KnowledgeSync is configured to perform subscriber linking (see chapter
      on “Subscribers”), then you may have to wait a few seconds to display the members
      of a “linked” group, as KnowledgeSync must dynamically retrieve this information
      from an external database.
      When you are done selecting subscribers, click on the “Add Subscriber” button to
      return to the “Standard” tab.

Choosing a Subscriber’s Delivery Methods

      Once you have selected your “standard” subscribers, you may proceed with choosing
      the method(s) by which each subscriber will be alerted about the corresponding
      event.
      By default, each selected subscriber has “E-Mail” selected as their only alert message
      delivery method. You can keep (or remove) e-mail as one of the selected methods for
      each subscriber, and you can add any of the other four methods for each subscriber.
      Note that computers may be notified only via the copy/ftp method.



283                                Event Designing
     Be careful to select only those delivery methods that have alert message text
     associated with them. Also, be sure that the subscribers you have selected have a
     valid delivery address for the methods you have chosen for them.

Removing an Event’s Subscribers

     To remove a subscriber from an event, simply highlight (single-click on) the
     subscriber record you wish to remove, and click on the “Remove Subscriber” button.
     To remove all of the selected subscribers for an event, click on the “Remove All
     Subscribers” button.

Advanced Subscribers & Message “Breaking”

     The “Advanced” subscribers tab is divided into two sections:
            Upper Grid. This grid has two purposes:
                     Choosing subscribers who are identified through the presence of a
                      unique “database value” within a triggered record.
                     Specifying the “break field” for creating messages that contain user-
                      definable groups of matching records (such as an event that creates
                      one message per region, one message per item category, etc.)
            Subscribers whose address is contained in a field within a triggered record.
     To use either of these functions, you need to click on the “Advanced” tab within the
     Subscribers tab.




                             EVENT SUBSCRIBeRS “ADVANCED” TAB

     Regarding the identification of a “break field” for an event; please refer to the earlier
     sections of this chapter titled for more details on this function.

                                    Event Designing                                        284
Delivering to Subscribers Using a “Database Lookup Value”

      Consider the following scenario:
      You have a customer support application that tracks which calls are assigned to
      various support reps. Each support rep is identified by a unique ID as well as a non-
      unique “group” code (such as the “Frontline” group).
      The support application does not store the corresponding rep’s e-mail and other
      notification addresses anywhere in the application.
      When a support call meets a condition that warrants an alert to the corresponding
      support rep, you need the following to occur:
             KnowledgeSync looks at the triggered record and finds the corresponding
              rep’s “ID” and “group name”.
             KnowledgeSync “looks up” the matching KnowledgeSync subscriber record
              (based on the rep’s ID) and the matching subscriber’s group (based on the
              rep’s group name) in the KnowledgeSync subscriber database
             KnowledgeSync alerts the corresponding support rep and/or group
      If the application(s) that an event is linked to requires this look-up ability, it is at the
      top of the subscriber “Advanced” tab that you can specify the fields (in each
      triggered event record) that contains the subscriber’s ID and their group name.
      Please note that the database fields that contain the subscriber’s ID and the
      subscriber’s group name must be included as columns in the event’s associated
      query(ies).
      Using the previous example, if the field that contains a support rep’s ID is called
      “Rep ID”, and the field that contains the rep’s group name is called “Rep Group”,
      you need to make sure that {Rep_ID} and {Rep_Group} are both selected as
      columns in the associated query.
      As long as these fields are present in the event’s associated query(ies), you can
      instruct KnowledgeSync to use these values as illustrated in the following steps.
      To deliver an alert to an individual subscriber (user) based on the subscriber’s unique
      ID:
           In the first line of the top-half of the “Advanced” tab, click on the list button
            in the “Database Field” column.
           Choose the database field that contains a subscriber’s unique ID (and
            contains the same value as is present in the “User Lookup Key” field within
            the subscriber record in the KnowledgeSync database)
           Choose whether subscribers will be notified via one or any combination of e-
            mail, fax, copy, page, or webcast.
      To deliver an alert to everyone in a KnowledgeSync subscriber group based on the
      subscriber group value in a triggered record:
           In the second line of the top-half of the “Advanced” tab, click on the list
            button in the “Database Field” column.


285                                   Event Designing
          Choose the database field that contains the subscriber group’s name. Note
           that the value must exactly match (including case-sensitivity) the name of a
           subscriber group in the KnowledgeSync Subscriber database in order for all
           members of that group to be notified.
          Choose whether the subscribers in a group will be notified via one or any
           combination of e-mail, fax, copy, page, or webcast.
     (For more details about the use and configuration of a subscriber’s “database lookup
     values”, please refer to the chapter titled “Subscribers.”)

Delivering to Subscribers Using an Address in the Triggered Event

     One of the most common KnowledgeSync alert scenarios is one where an alert
     message needs to be delivered to a person associated with a triggered event record.
     For example:
            Notify the support rep to whom an escalated call is assigned
            Notify the salesrep who has an overdue activity
            Notify the manager of a person who hasn’t responded to a customer call
            Notify a client about their order
     In all of these cases, you cannot “hard-code” the alert recipient because the recipient
     will vary based on the records that are causing the event to trigger.
     As long as the record that is causing an event to trigger can contain the address (e-
     mail address, fax number, pager number, etc.) of the person who should receive the
     notification, KnowledgeSync can send the alert accordingly.
     In order to make this function work, you must be sure to include the field(s) that
     contain a recipient’s delivery address(es) within the query(ies) associated with the
     event.
     (In other words, if you wish to send e-mail alerts to a support rep, the first thing you
     need to do is identify what field contains the rep’s e-mail address and include this
     field as one of the query’s columns.)
     The delivery of an alert to an address that is contained within a triggered event is
     done from the bottom-half of the subscriber “Advanced” tab.
     Depending on which method (or methods) you wish to send alerts by, you will need
     to “map” fields from your event’s query to supply the recipient’s e-mail address, fax
     number, pager number, pager PIN, and webcast name.
     To do so, simply go to the five fields on the lower half of the “Advanced” tab and
     click on the list button in the “Database Field” column. Choose the field(s) that
     contain the corresponding subscriber’s delivery addresses. For every address
     mapping field that you fill in, the corresponding subscribers (as determined by the
     triggered event) will get notified via those methods.

Delivering to Multiple Addresses from the Triggered Event

     Note that when you opt to send an alert to an address that is located within a database
     field, you can specify only a single database field for each of the corresponding
                                   Event Designing                                          286
      delivery methods in the lower half of the Subscribers “Advanced” tab. If an event
      needs to send alerts to multiple addresses contained within the underlying database,
      you need to (within the event’s query) concatenate these address fields together into a
      single database field.
      When you perform such concatenation, please be sure to separate each e-mail address
      from the next with a comma (‘.’) and be sure to limit the total length of all e-mail
      address to no more than 255 characters.
      Note that the above rules apply also to the ‘CC” and ‘BCC’ e-mail address fields.

Schedule Tab
      Access via Navigator:
               Add Schedule for an Inactive Event: Double-click on the event name,
                click on the “Schedule” tab.
               Modify/Remove a Schedule for an Event: Expand the event’s
                components and double-click on the branch that shows the selected
                schedule for the event.
      The last step in the configuration of a KnowledgeSync event is the specification of
      the schedule (or frequency) that determines how often you wish to check to see if the
      event’s corresponding conditions are met.
      The “Schedule” tab looks like the following:




                                     EVENT “SCHEDULE” TAB

      Every event has its own schedule; you can check to see if an event has been triggered
      as often as every ‘x’ minutes, and as infrequently as once a day, week, month, or
      year.

287                                 Event Designing
    (Note that you may also configure an event to check “continuously”. To do so, you
    would use the KnowledgeSync Utility that allows an event to be “called” from
    outside of the KnowledgeSync application. Using this utility, you would create a job
    that calls a specific KnowledgeSync event, and – once that event completes – the job
    would loop back to the beginning and re-submit the same job all over again.)
    KnowledgeSync includes approximately a dozen pre-configured schedules; you may
    edit these schedules as well as create additional schedules of your own.

Monitoring the Status of Scheduled Events

    When an event is scheduled to be checked by KnowledgeSync, you can use the
    KnowledgeSync Monitor to track the status of the event’s scheduled submission.
    In the Monitor, go to the “Scheduler” branch and then click on the “Next Run
    Date/Times” branch. You will see a list of all scheduled events that are pending for
    execution.
    Once an event is submitted by the KnowledgeSync Scheduler, you may then proceed
    to the “Application Events” branches and monitor whether the event has been
    successfully checked and/or triggered, and whether any error has occurred.

Choosing a Schedule

    To select a schedule that will control how often KnowledgeSync will check to see if
    an event is triggered, click on the list button in the “Choose a Schedule to Use” field.
    You will receive a list of pre-configured schedules; if you see the schedule that you
    wish to use, select it; if you do not see the schedule that you require, you will need to
    create it.
    Note that the schedule called “When Email Arrives” is reserved for use only with the
    KnowledgeSync E-Mail Response System.
    Note also that you may choose a schedule of “None” if you wish to configure an
    event but not have KnowledgeSync schedule it. This is particularly useful for events
    that you wish to run on an ad-hoc or on-demand basis.

Creating/Editing a New Schedule

    To create a new schedule or edit an existing schedule, follow these steps:
         Click on the “Create New Schedule” or “Edit This Schedule” buttons.




                                  Event Designing                                        288
                              EVENT SCHEDULE DEFINITION WINDOW
           Type in a description of the schedule you are creating or editing (e.g.,
            “Everyday at 3 PM”)
           If you are creating a schedule for events that should not be submitted until
            after a specific date (e.g., a schedule for events that should not be submitted
            until January 2nd of the following year), key in the appropriate date (in the
            format XX/XX/YYYY HH:MM) in the field called “Should not run until
            after date/time”.

              If events using this schedule will be eligible to be submitted immediately
              (when this schedule is next due to run), leave this field blank.
           Choose a reoccurring frequency for this schedule. Your choices are:
                     Every ‘n’ minutes
                     Hourly
                     Daily
                     Weekly
                     Monthly
                     Annually
                     None (used only for events that have no schedule)
              (The frequency called “When Email Arrives” is reserved for use only with
              the KnowledgeSync E-Mail Response System.)
           Based on the frequency you choose, you will be prompted to supply
            additional scheduling details, such as the time of day to run, the day of the
            week, et cetera.
      When you are finished filling in this information, you can continue by clicking on the
      “Allowed Range” tab.


289                                Event Designing
Configuring a Schedule’s “Allowed Range”

     There are three components to the configuration of a schedule’s allowed range:
         3. The months of the year during which the schedule is eligible to be submitted
            (place checkmarks in eligible months)
         4. The days of the week during which the schedule is eligible to be submitted
            (place checkmarks in eligible days)
         5. The hours of the day during which the schedule is eligible to be submitted
            (specify the beginning and ending times between which the schedule may be
            submitted) Note that these times are inclusive.




                              EVENT SCHEDULE “ALLOWED RANGE”

     When you are done defining the allowed range for your schedule, click on the “Save
     and Close” button at the top-left of your window and you will be returned to the
     Event Manager “Schedule” tab.

Schedule Holiday Handling

     In the KnowledgeSync Administration module you have the option to identify those
     dates that are designated as holidays for your organization. As a result, you have the
     ability to specify (on an event-by-event basis) whether or not an event should be
     submitted on a date that is identified as a “holiday.”
     In the checkbox titled “Should this run on a holiday”, place a checkmark in this field
     if you do want an event to run if it is scheduled on a holiday, and do not place a
     checkmark in this field if you do not want an event to run if it is scheduled on a
     holiday.

Event Dependencies

     When configuring KnowledgeSync events, you may come across a situation such as
     the following:
                              Event Designing                                    290
              If event ‘a’ is triggered, immediately submit event ‘b’
              to see if it also is triggered.
      In this example, event ‘b’ is referred to as dependent on event ‘a’.
      KnowledgeSync has two ways to accommodate this scenario; one manner is through
      the use of the Dependency function on the “Schedule” tab, and the other manner is
      defining an event “job stream” which is defined within the Navigator module as
      detailed further on in this chapter.
      The difference between these two methods is as follows:
           Using dependencies, if event ‘a’ is triggered, event ‘b’ will be submitted
            immediately – even if event ‘a’ has not completed all of its alerts, reports, or
            actions.
           Using job streams, if event ‘a’ is triggered, event ‘b’ will be submitted – but
            only after event ‘a’ has completed processing of all of its components,
            including reports, alerts, and workflow actions.
      Note that when you link events together via dependencies, the events can be
      associated with different applications. (Thus you may have event #2 based on
      conditions in application ‘b’, dependent on the triggering of event #1 which is based
      on conditions in application ‘a’.)

How to Configure a Dependent Event

      By definition, a dependent event (such as event ‘b’ in the preceding example) is one
      which you want to execute only if its dependency (event ‘a’) has been triggered.
      As a result, event ‘b’ should not have its own schedule; you should give event ‘b’
      (the dependent event) a schedule of “None” so that the only times it will be submitted
      will be if its dependency is met.
      It is also important to note that a single event (such as event ‘b’) can be dependent on
      any one of a number of other events, but a single event cannot be dependent on a
      combination of other events (e.g., event ‘c’ cannot be dependent on both events ‘a’
      and ‘b’ triggering).
      To specify that an event’s submission is dependent on another event’s triggering,
      follow these steps:
           Make sure that you are working with the dependent event.
           Give the dependent event a schedule of “None”.
           In the “Schedule” tab, click on the “Add Dependency” button.
           You will get a list of events for the application to which the current event is
            associated. If you wish to make the current event dependent on another event
            within this application, select the event that the current event will be
            dependent on.
           If you wish to make the current event dependent on another event within a
            different application, click on the “Select Another Application” button and
            select the application that contains the event you wish to make the current


291                                 Event Designing
             event dependent on.

          Once you have selected the other application, you will get a list of events for
           that application and you may select the event that the current event will be
           dependent on.
          The selected event will now appear in the list of events that the current event
           is dependent on.
          Repeat the preceding steps if you wish to add other events that the current
           event is dependent on. Remember that you cannot make a single event
           dependent on a combination of multiple others.

Removing an Event’s Dependencies

     To remove an event from the list of dependencies, simply highlight (single-click on)
     the event you wish to remove, and click on the “Remove Dependency” button.
     To remove all of the selected dependencies for an event, click on the “Remove All
     Dependencies” button.

How to Configure a Job Stream???

     An event “job stream” is a collection of multiple events that need to run in a
     sequential fashion, one after another. Job streams have the following unique
     characteristics:
          There is only a single submission time for all of the events in a job stream.
           That submission time (or schedule) indicates when the first job in the stream
           will be submitted by KnowledgeSync.
          Each job (event) in a job stream must fully complete before the next event in
           the stream begins. Note that the “completion” of a event is defined as its
           successful execution -- regardless of whether the event is triggered or not.

             Thus regardless of how many components an event has – reports that need to
             be generated, alerts that need to be sent, or workflow actions that need to be
             executed – the next job in a stream (as well as any subsequent events) will
             not begin until all of the components in any preceding events are successfully
             completed.

Job Streams and KnowledgeSync Processing

     It is important that you understand the order in which KnowledgeSync events are
     executed. An event that runs every hour, for example, does the following:
     1) Check to see if the event’s conditions are met. If the event’s conditions are NOT
        met, but the event completes successfully, the next event in the stream will be
        executed.
     2) If the event’s conditions ARE met, the event must generate any corresponding
        forms, documents, and/or reports.


                                   Event Designing                                       292
      3) If the event’s conditions ARE met, the event must deliver alerts (including items
         generated in step #2) to the appropriate recipients
      4) Execute workflow actions, such as adding or updating information in a database
      The responses of an event execute in precisely this order – generate forms,
      documents, or reports first, deliver alerts second, and execute updates third.
      But consider a scenario where, for example, you need to first update information in a
      database and then send alerts (which may or may not include reports).
      Because a single event generates reports and alerts first and then executes updates,
      the preceding scenario cannot be handled by a single event. Two events are needed,
      and it is imperative that the first event start – and complete – before the second event
      is initiated.
      Job Streams are invaluable when:
           An initial event has multiple Reports, Forms, or Documents that it needs to
            generate and you want to make sure that all of the reports get successfully
            generated before you have KnowledgeSync use a subsequent event to move
            and/or deliver them to their intended recipients.
           An initial event executes Workflow Actions to write data into one or more
            other application databases and you need to make sure that these Actions
            complete successfully for all of the records that need to be created in the
            other database before another program can be run on that imported data.
           You have a series of events that need to be submitted in a specific order, such
            as an event that logs a support ticket from an incoming email, and then –
            once the ticket is created – triggers ensuing alerts, et cetera. In this scenario,
            event #1 would have a query that is based on the receipt of an incoming
            email, and event #2 would have a query that is based on the presence of a
            new support ticket in the underlying database.
           You have a group of events that are all related to the same business
            condition, such as a “new hire”. Although the events that correspond to this
            process might not need to be dependent on each other, they are all related to
            the same business process. Job streams are an excellent way to group all such
            events together, and easily manage them.
           You have a sophisticated business process that involves decision branching.
            Using a job stream, you can create a stream that includes events that may –
            or may not – get executed based on mutually exclusive conditions. For
            example, a job stream may trigger alerts based on the priority of a logged
            support ticket; that single stream may contain both an event that triggers
            alerts to person ‘a’ if the event is high priority, as well as an event that
            triggers alerts to person ‘b’ if the event is low priority. Both events will
            always be run, but only one will ever be triggered for a given ticket.

Job Stream Example

      Job streams are designed to handle scenarios whereby after one event is done
      running, another event should immediately begin execution, and – after that event is
      done – another event follows that one, and so on.
293                                 Event Designing
Remember – an event in a stream does NOT have to be triggered in order to
“complete”. An event whose conditions are not met is considered complete once the
event finishes “checking” for the matching conditions. And an event whose
conditions ARE met is considered complete when all of its alerts, reports, and actions
have been successfully finished.
One typical example of using a job stream in KnowledgeSync would be to monitor
and process leads that come into an organization via email. An organization might
wish to follow a process such as this one when a new lead is received:
Step #1: A lead comes into your organization in the form of an email message.
KnowledgeSync takes information from that email and creates a contact record in
your CRM database and assigns that contact to a salesperson.
Step #2: Send an acknowledgement back to the lead contact, thanking them for their
inquiry and providing contact details for the salesperson to whom the lead has been
assigned.
Step #3: Alert the appropriate salesperson that a new lead has come in and requires
their attention.
Step #4: Generate a “New Lead Report” for the newly-created lead and deliver that
report to the sales manager.
This scenario would be replicated in a 4 event job stream. The first event would
monitor for incoming emails and create the lead record in your CRM database. The
second event would monitor the CRM database for new lead records and send out
acknowledgements to the lead contact.
The third event would send an alert message to the salesperson to whom the lead was
assigned, and the fourth & final event would generate a lead report about the new
lead and deliver that to the sales manager.
The following shows how such a job stream would be presented within
KnowledgeSync:




                             Event Designing                                      294
                                       JOB STREAM EXAMPLE




Event Schedules in Job Streams

      Every event that you create (and activate) is eligible to be used within a job stream.
      However – for the purpose of clarity – it is strongly suggested that when you create
      an event to be used in a job stream, that the event be configured to use a schedule of
      None.
      Since job streams have their own schedule (one schedule for the entire stream), it can
      be potentially confusing if you have a job stream (for example) that is scheduled to
      run every day at 9 AM but has an event within the stream that is itself configure to
      run every 30 minutes.
      (A job stream’s overall schedule will override the schedule that is associated with an
      individual event.)
      So – if you do have one or more events that need to run in both a standalone
      configuration and as part of a job stream, it is strongly recommended that you create
      two events – a standalone event with its own schedule, and an event with a schedule
      of “None” which is what will be included in the appropriate job streams.




295                                 Event Designing
Viewing the Components of a Job Stream

     To view the components (events, reports, et cetera) within a job stream, follow these
     steps:
             1. Open the Navigator module.
             2. Expand the “Job Streams” branch.
             3. Locate the job stream whose components you wish to view and then
                click on the plus sign (+) to the right of that stream to see the events that
                it consists of.
     Once you display event-level detail for a job stream, you may continue by drilling-
     down further into those events by double-clicking (or right-clicking) on the
     corresponding event component in order to view (and optionally modify) its
     configuration.
     (See the earlier sections of this chapter for details on viewing and/or modifying an
     event’s configuration.)

Creating a New Job Stream

     To create a new job stream, open the Navigator module, right-click on the “Job
     Streams” branch and select the menu option called “New Job Stream”. When you
     select this option, the following window will appear:




                                 JOB STREAM CREATION WINDOW

                                   Event Designing                                        296
      Fill out the fields as detailed in the following sections.

Editing an Existing Job Stream

      To edit an existing job stream, expand the “Job Streams” branch and locate the job
      stream whose configuration you wish to modify. Double-click on that job stream to
      be taken into its details in “edit” mode.

Job Stream Name, Description, & Schedule

      The first components of a job stream are its name and description as well as the
      frequency with which KnowledgeSync will submit this stream for execution. This
      information includes:
      1. Job Stream Name: Enter a name that uniquely identifies this job stream, such as
         “New Order Processing Job Stream” or “Lead Entry, Matching, & Follow-Up”.
      2. Schedule: If you wish to allow this job stream to be scheduled to run, click on
         the list button in this field and choose a schedule frequency for this stream. If you
         leave this field blank, you can still create the stream, but it will not be scheduled
         to run.
      3. Notes: Key in a more detailed description of the purpose of (or components of)
         the stream you are creating.

Adding Events to a Job Stream

      A single job stream can contain events from one – or from multiple – applications.
      To add an event to a job stream, follow these steps:
              1. In the window titled “Applications to Select”, single-click on the
                 application that contains the event which you wish to add to the job
                 stream.

                   After you select an application, the window titled “Events and Scheduled
                   Reports to Select” will show you a list of all active events and scheduled
                   reports for the selected application.
              2. Double-click on the event which you wish to add to the job stream; this
                 event will then appear in the window titled “Job Stream Order”.
              3. Repeat steps #1 and #2 for each event that you wish to add to the stream.
              4. Click on “Save and Close” to retain the events you added to the job
                 stream.

Re-Ordering Events in a Job Stream

      Once you have selected events for a job stream, you may wish to change the order of
      their execution. To do so, follow these steps:
          1. (If necessary) Double-click on the job stream to edit its configuration.


297                                  Event Designing
         2. Single-click on (highlight) the event whose order of execution within the
            stream you wish to modify
         3. Using the “Move Up” and “Move Down” buttons on the lower right-hand
            side of the job stream configuration window, change the order of the event in
            the stream according to your requirements.
         4. Repeat these steps for any other events within the job stream.
         5. Click on “Save and Close” to save your changes to the order of the events in
            the job stream, or cancel to not retain your changes.

Removing Events from a Job Stream

     Once you have selected events for a job stream, you may wish to remove one or more
     of those events. To do so, follow these steps:
             1. (If necessary) Double-click on the job stream to edit its configuration.
             2. Single-click on (highlight) the event you wish to remove from the stream
                and click on the “Remove” button.
             3. Repeat these steps for any other events which you wish to remove from
                the stream.
             4. Click on “Save and Close” to save your changes to the stream, or click
                on cancel to not retain your changes.

Deleting a Job Stream

     To delete a job stream, expand the “Job Streams” branch and locate the job stream
     you wish to remove. Right-click on that job stream and select the option called
     “Delete Job Stream”. You will be asked to confirm your selection and then (after you
     confirm) the job stream will be removed from the KnowledgeSync database.

Running a Job Stream Right Now

     To execute (run) a job stream right now, expand the “Job Streams” branch and locate
     the job stream you wish to run. Right-click on that job stream and select the option
     called “Schedule This Job Stream Now”. You will be asked to confirm your selection
     and then (after you confirm) the job stream will be submitted to run.




                                  Event Designing                                       298
                              RUNNING A JOB STREAM RIGHT NOW




The “Tracking” Tab
      Access via Navigator:
              View/Remove Tracking Data: Double-click on the event name, click
               on the “Tracking” tab.
      The “Tracking” tab lets you see whether the current event has been checked, whether
      it has been triggered, and the “unique” IDs of all of the triggered records.




                         EVENT TRACKING DATA (TRIGGERED RECORDS)


299                               Event Designing
    The primary use of this tab is to enable you to “un-trigger” or clear out the triggered
    records for an event and thus enable it to be triggered again. You can clear out all of
    the triggered records for an event, or you can clear out only selected records.
    Note that the “Tracking” tab will show you the date and time that the event was last
    checked, the date and time that the event was last triggered, and the value of the
    “unique” field (as defined in the event’s query) for each record that was triggered.

Clearing Triggered Records

    To clear (or “un-trigger”) a specific triggered record for an event, simply highlight
    (single-click on) the record whose triggering you wish to clear, and click on the
    “Remove Tracked Item” button.
    To clear all of the triggered records for an event, click on the “Remove All Tracked
    Items” button.
    (Note that in some cases you may need to click off of the “Triggered” tab and back
    onto it to visually verify that all triggered items have been removed.)


If Your Event Isn’t Triggering . . .

    The most common call that comes into Vineyardsoft support is that an event “is not
    getting triggered” or that an alert message “is not getting sent.”
    If this happens, the first thing to do is to check the KnowledgeSync Monitor and
    locate the event – see if it appears under “Application Events” that are “pending”,
    “checked”, “triggered”, or have recorded “errors”.
    The most typical scenario is that an event is being “checked” but it is not being
    triggered or it has been triggered but an alert is not getting sent out.
    Here is the top list of reasons why this may happen:
        1. (If the event is not triggering) The event’s conditions might not be met. Go
           into the event’s query (or queries) and click on the “Preview” tab to ensure
           that the query is retrieving at least one matching record.
        2. (If the event is not triggering) The event is already triggered. Many events
           are configured to send only one alert per “triggered record.” Go into the
           “Triggered” tab for the event and see if any triggered records are listed. If so,
           this may be why the event is not triggering again. (You can either remove the
           triggered records, or you can turn the “repeat” function on from the event
           “Description” tab.)
        3. (If an e-mail alert message is not getting sent) The e-mail sending account is
           either missing or is not correctly configured. Check the “Email” tab to ensure
           that the “Sending Account” field is not blank. Also, perform an e-mail test
           (from the KnowledgeSync Administrator) to see if this account is configured
           to successfully send an e-mail message.
        4. (If an alert message is not getting sent) The method by which the alert is
           being sent (e.g., e-mail) does not have any corresponding alert message text.
           If there’s no text, no message can be sent!
                                  Event Designing                                         300
          5. (If a specific subscriber is not receiving an alert message) The subscriber
             (recipient) who is to receive the alert message does not have an address
             defined for the corresponding method (i.e., an event that sends an alert via e-
             mail requires that the subscriber have a valid e-mail address)
          6. (If the event is not getting checked) The event is not “active” (check the
             ‘Active’ checkbox on the “Description” tab of the event).
          7. The subscriber(s) selected for the event have not had the corresponding
             delivery method (e.g., “e-mail”) selected for them.


If Your Event Is Triggering Over and Over . . .

      Check out the event query’s “Unique” value. If a query doesn’t have a unique, the
      corresponding event will trigger over and over again, until the query’s condition is no
      longer met.
      You might also look at the setting of the event’s “Repeat Notification for Triggered
      Items” checkbox (located on the event “Description” tab). If this box is checked on,
      the event will continue to be triggered (and send alerts) over and over.


Schedule an Event to Run “Right Now”

      Access via Navigator:
               Right-click on the event name and select “Schedule This Event Now”.
      As you configure KnowledgeSync events, one of the most frequently-used functions
      in the Event Manager is the ability to run a specific event “right now”.
      This is particularly useful, as you can configure an event to use a specific schedule
      (such as hourly, daily, or weekly), but still have the ability to submit the event right
      away to confirm that it will execute successfully.
      The “Schedule This Now” function is also useful as it enables you to submit “ad-
      hoc” executions of a specific event. For example, you may have an event that runs
      once a week (on Mondays), but your server might have been shutdown (for
      maintenance) on that day. Using the “Schedule This Now” function, you could
      manually submit specific events to run on Tuesday that were originally scheduled to
      run on Monday.
      To schedule an event to run “right now,” follow these steps:
           Make sure that the KnowledgeSync service (or server manager) is running.
           In the Navigator window, right-click on the event you wish to run right now.
           Choose the option called “Schedule This Event Now”.
           You will be asked to confirm the submission of your selected event. Click on
            “Yes.”
           The event will be scheduled for immediate execution, and may be tracked in
            the KnowledgeSync Monitor.
301                                  Event Designing
Test an Event

   Access via Navigator:
            Right-click on the event name and select “Test This Event Now”.
   One of the most useful options in the Event Manager is the ability to simulate the
   running of an event by using “test mode” – this does not actually run the event, it
   does not trigger any records, and nor does it send out any alert messages, but it does
   generate a “results file” whose contents you can review to ensure that the event is
   running correctly.
   To test an event, follow these steps:
        Make sure that the KnowledgeSync service is running.
        From the main Navigator window, right-click on the event you wish to test.
        Choose the option called “Test This Event Now”.
        You will see a web browser appear, and (in a few seconds) the results that
         this event would produce. You will see the name of the event, the translated
         SQL syntax that was submitted, and the alert message text for each alert
         method for which you have a message defined. (Note that you may need to
         “refresh” your web browser to see the full details of the test run.)
   You can run repeated tests on the same event as often as you require.




                                 Event Designing                                       302
                                                           CHAPTER 7
                                         Viisuall Basiic Scriiptiing
                                         V sua Bas c Scr pt ng


Visual Basic Scripting

    Key to KnowledgeSync’s ability to “auto-respond” to a triggered event is the ability
    to update the business applications that people use with the details of the event that
    took place and the follow-up actions that need to be executed.
    KnowledgeSync includes a wide variety of tools that enable you to configure an
    event that adds or updates data within one or more application databases (see the
    “Actions” section of the Event Designing chapter), but the most powerful of these
    tools is a “VB” (Visual Basic) scripting module.
    This chapter will outline the manner in which the VB scripting module is designed
    within the KnowledgeSync solution, and will address the capabilities and benefits of
    this module to KnowledgeSync clients.


Requirements

    Although KnowledgeSync includes a number of sample scripts that an organization
    can use, most companies’ site-specific requirements will necessitate the creation of
    one or more site-specific scripts for their needs.
    KnowledgeSync includes a sophisticated VB scripting design tool, complete with
    pre-defined script templates, on-line documentation and help text, and script syntax
    testing facilities and debugging tools.
    It should be noted, however, that the scripting module should be reserved for use
    only by those individuals who are familiar with the Visual Basic scripting language,
    and have some experience in writing VB scripts.


VB Scripting Support

    Vineyardsoft’s Customer Support department will answer questions about how the
    KnowledgeSync VB Scripting engine works, and will also provide assistance in
    terms of how to design an event to trigger a VB script. However, KnowledgeSync
    Customer Support does not provide custom script design support or debugging
    services. Please contact your Business Partner or Vineyardsoft’s Professional
    Services department for details on the cost associated with these services.

                                     Event Monitor                                      303
“Front-End” Versus “Back-End” Scripts

    KnowledgeSync scripts can be designed to be utilized in two places:
           As a back-end response action that is executed after an event is triggered.
            Once an event is triggered, all of the data about the triggered event (including
            the application data that corresponds to the records that were triggered) is
            made available to one or more scripts that you wish to execute.

            This is referred to as a back-end script because it executes after an event has
            been triggered. Note that a single event may trigger the execution of one or
            more back-end scripts.
           As the front-end means to check for a condition that is not related to
            information in an ODBC-compliant database.

            Although KnowledgeSync typically uses database queries to identify whether
            an event’s conditions have been met, queries cannot identify data that resides
            outside of an ODBC-compliant database, or outside of an incoming e-mail
            message.

            To identify conditions outside of application databases or e-mail messages
            (such as conditions within your Operating System, such as low disk space, a
            process that is not running, or a file that has been updated), KnowledgeSync
            enables a VB script to be used in the place of a query.

            This is referred to as a front-end script because it determines whether or not
            an event will be triggered.
    Note that a single event that uses a front-end script to determine whether an event
    will be triggered can also use one (or more) back-end scripts to respond to the
    triggered event.

Sample Back-End Scripting Scenarios
    Here are ten scenarios where KnowledgeSync’s back-end scripting functions could
    be used:
        1. Condition:       A client places more than two orders with you this month.
           Script:          Update the client’s status to “Very Active”
        2. Condition:       A client has more than $50,000 in their 90 Days receivables
           Script:          Change the client’s credit status to “On Hold”
        3. Condition:       A client sends an email message to your Support mailbox
           Script:          Create a support call in your help desk application
        4. Condition:       A client closes an opportunity in a CRM application
           Script:          Create a sales order in a financial application
        5. Condition:       A client updates a contact in a financial application
           Script:          Update the corresponding client in a CRM application


                                     Event Monitor                                        304
        6. Condition:        A client is placed on credit hold in a financial application
           Script:           Update all of the client’s opportunities in a sales application
        7. Condition:        An account is de-activated
           Script:           Close all of the open activities for that account
        8. Condition:        A client sends in an e-mail “unsubscribe” request
           Script:           Remove the client from your mailing list
        9. Condition:        A new prospect sends e-mail requesting product information
           Script:           Add the prospect to your CRM and financial applications

Sample Front-End Scripting Scenarios
    Here are six scenarios where KnowledgeSync’s front-end scripting functions could
    check for conditions outside of ODBC-compliant databases, and to send alerts and
    take appropriate response actions:
        1. Check if available disk space on your database server drops below 55 MB.
        2. Check to see if SQLServer is still running
        3. Check to see if critical files have been received and/or have been updated
        4. Check to see if an application’s Sync Server is still running
        5. Check the NT Event Log for security breaches
        6. Check for data conditions in a non-ODBC compliant database


Sample VB Scripts

    Vineyardsoft has many examples and templates for both front-end scripting and
    back-end scripting which are available for free to all KnowledgeSync clients and
    partners. If you are interested in receiving one or more of these scripts, please contact
    Vineyardsoft’s Technical Support department and ask them to email you copies of
    the requested scripts.
    Please be sure to include the following information with your script request:
             Whether the sample you desire is for front-end scripting or back-end
              scripting
             The name(s) of the application(s) you wish to use your scripts with
             An overview of the function that you would like your script(s) to perform
             The email address where you would like the scripts sent to


Back-End Scripting Set-Up

    The following pages will guide you through the process of setting up a back-end
    script and linking it to an event. Following these steps will be a brief discussion on
    how you can configure front-end scripting within the KnowledgeSync application.
                                      Event Monitor                                      305
Prepare Queries
    To begin using back-end scripts in KnowledgeSync you must decide what you want
    the scripts to do. The best way to approach this is to look at your events and figure
    out which events need to write data back into one or more application databases.
    Once you have identified such an event, you are ready to begin thinking about the
    corresponding query(ies) and script(s) you will require.
    Once you have located an event that requires the use of one (or more) scripts, the
    very first thing you should do is go to the query(ies) that the event uses and make
    sure that the queries retrieve all of the necessary fields (columns) of data that you
    might wish to use in your script.
    This is a very important step – just as you must be careful (when designing queries)
    to choose those fields that you wish to place in an outgoing alert message, you must
    likewise be careful to choose those fields whose values you wish to pass into the
    script(s) that an event will trigger.
    If you wish to have access to a field within an event’s script, you must be sure to
    select that field as a column for the query(ies) that are associated to that event. If the
    column does not appear in the event’s query, you cannot use it within a script for that
    event.

Create the Back-End Script
    Once you have ensured that the query(ies) that an event uses will make available the
    necessary information to the event’s script, you are ready to begin designing your
    script.
    KnowledgeSync scripts are associated with one or more specific events, as shown in
    the following illustration:




                          AN EVENT’S SCRIPT (OPPORTUNITY UPDATE)




                                      Event Monitor                                         306
Adding a New Back-End Script

    To add a new back-end script, open the Navigator and right-click on the branch of the
    application you wish to add the script to and choose “New Basic Script”.
    You will be taken into the Script Definition window and a script template will
    automatically be loaded into the script editor for you as follows:




                              BASIC SCRIPT CREATION WINDOW

    Note that by default, KnowledgeSync automatically stores your scripts in a special
    “Scripts” directory where the application is installed, but you may override this
    location according to your needs.
    The two buttons in the middle of this window are most important. The right-hand
    button (“Edit/Test Script”) lets you edit and modify the script’s contents as well as
    run the script from the edit window.
    The left-hand button (“Check Script Syntax”) lets you invoke an automated process
    that checks your script for any syntax errors. When you click on this button, you will
    either be informed of any script syntax errors that exist, or you will be informed that
    your script’s syntax has been successfully verified.

Editing a Script
    Once you fill in the general information about the script you are creating, you may
    click on the “Edit/Test Script” button to begin editing the content of your script. It is
    advised that you have a list of the customized names of all the fields of data that you
    wish to pass from the corresponding event into this script.
    (A field’s “customized name” may be located by going into the query for the
    corresponding event and clicking on the “Columns” tab. The customized name will
    appear to the right of each field that is selected for that query.)



                                      Event Monitor                                      307
Once you click on the “Edit/Test Script” button, you will be presented with a script
template that begins with an area for script author details and general purpose
overview.




                                 Event Monitor                                    308
Script Part I: General Info
The first part of a script is where you can specify the purpose of the script, your name
(as the script author), and date the script was created and the date it was last
modified.
This part of your script will look like the following:


'   Script   Name               :   Template.bas
'   Script   Author             :   Development
'   Script   Purpose            :   This script serves as a template
'   Script   Creation Date      :   2/5/2001
'   Script   Modified by        :
'   Script   Modified Date      :
'   Script   Modifications      :
'
'
'   The following declared functions are available
'   to the script author in order to interact
'   more closely with KnowledgeSync 2000. All are optional
'
'   Scripts may be executed by KnowledgeSync in two ways.
'
'   1) As an action to a triggered event.
'
'   2) In place of a query in order to have the script
'      trigger events.
'
'   A script used as an action cannot trigger events.




                                    Event Monitor                                   309
Script Part II: Retrieve General Event Data

     The second section of a script instructs you on how you can retrieve general
     information about the triggered event such as the event’s description and the name of
     the application to which the event is associated.
     This part of your script will look like the following:



     ' The following functions are used when a script is executed
     ' as an action.
     '
     Declare Function KSGetEvent App ( ByVal s As String ) As String
     '
     ' This function retrieves specific data about the event that
     ' has triggered.
     '
     ' The available values that can be passed to KSGetEvent in
     ' order to retrieve data are as follows:
     '
     ' lookup    Returns the Lookup key as defined in
     '               the Event Manager
     ' application     The application that the event belongs to
     ' description     The description of the event
     ' id        The id of the event
     ' dns       The ODBC datasource name of the application
     ' username        The username for the connection of the app
     ' password        The password used for the connection
     ' apiname         The optional API name set in the connection
     ' apiusername           The optional API username
     ' apipassword           The optional API password
     ' report pending        How many reports are left to process
     ' report files          The comma separated list of report
                 files (the output)
     ' existing files        The comma separated list of files from
                 the Files tab in the event




                                       Event Monitor                                   310
Script Part III: Retrieve Alert Message Text

     The third section of a script details how you can retrieve the texts that are associated
     with the various alert messages for the triggered event:
     This part of your script will look like the following:

     '
     Declare Function KSGetPackage App ( ByVal s As String ) As
     String
     '
     ' This function retrieves data about the package that was
     ' created for delivery by KnowledgeSync. The values that
     ' can be passed to KSGetEvent in order to
     ' retrieve data are as follows:
     '
     ' email subject     The subject of the email for delivery
     ' email message     The email message text for delivery
     ' page message      The pager message text for delivery
     ' fax subject       The fax subject text created for delivery
     ' fax message       The fax message text create for delivery
     ' fax comments      The fax comments text created for delivery
     ' webcast subject The webcast subject text for delivery
     ' webcast message The webcast message text for delivery




                                       Event Monitor                                      311
Script Part IV: Retrieve Query SQL Syntax

    The fourth section of a script details how you can retrieve the SQL syntax from the
    queries that are associated with the triggered event. Note how if an event uses
    multiple queries, you can retrieve the SQL syntax from any one or all of the
    corresponding queries.
    This part of your script will look like the following:


    Declare Function KSGetSQL App ( ByVal l As Long ) As String
    '
    ' This function retrieves the SQL from the query that was used
    ' to trigger the event.
    ' You pass a number of the query used.
    ' For example if the event has only one (1)
    ' query, then you would pass the number 1
    ' Example: mysql=ksgetsql(1)
    ' retrieves the sql from the first query
    '




                                      Event Monitor                                   312
Script Part V: Retrieve Event Data Fields

     The fifth section of a script describes the method by which you can retrieve the
     values from individual fields (columns) that were specified within the query(ies)
     associated with the triggered event.
     This part of your script will look like the following:

     Declare Function KSGetData App ( ByVal s As String ) As String
     '
     ' This function retrieves columns of data from the queries
     ' that triggered the event. You pass the customized
     ' column name as defined in the query builder to
     ' retrieve that information.
     ' Example: print ksgetdata("companyname") ' prints
     ' company name from the query data
     '




                                       Event Monitor                                     313
Script Part VI: Run Subsequent Events

    (Note: The section that refers to using a script to trigger an event is not applicable to
    back-end scripting.)
    The sixth section of a script allows you to “call” other events for execution. This is
    very useful, as it enables you to immediately run one or more other events upon
    conclusion of this script.
    This part of your script will look like the following:


    Declare Function KSScheduleEvent App ( ByVal lookup As String)
    As String
    '
    ' This function immediately schedules the event matching the
    'lookup string on the description Tab of the Event Manager.
    '
    ' The parameters are as follows:
    '
    ' lookup
    ' The lookup string that uniquely identifies the Event in the '
    ' Event Manager
    '         Returns a string error message if unable to schedule
    '         event. Returns empty string if Event is scheduled.
    '




                                      Event Monitor                                       314
Script Part VII: Specify Return Status Codes

     The seventh section of a script contains details on how you can specify what
     information the script will return to KnowledgeSync if the script fails to complete
     successfully.
     This part of your script will look like the following:



     Global KSReturnStatus As Long
     '
     ' Set this value if you want to return an error status number.
     ' If you don't set this value, then the script is assumed to
     ' have worked successfully and is stamped completed by KS.
     '
     Global KSReturnMessage As String
     '
     ' Set this value if you want to return an error message
     '
     Global KSReturnComplete as long
     '
     ' Set this value to -1 if you want the script to complete even
     ' if there’s an error. Normally, when scripts error, the
     ' Action server will attempt to execute them again in 1 minute
     ' until they complete without error.
     '
     On Error Resume Next
     '
     ' Tell KS how things went by setting the return status
     ' Set this to a non-zero if there was an error. This will be
     ' Seen in the monitor in the errors section or corrective
     ' actions in the administrator

     KSReturnStatus = 0

     ' Set return message string. Place error message in this
     ' variable if there was one, This will show up in the monitor

     KSReturnMessage = "Success"




                                       Event Monitor                                       315
Script Part VIII: Enter Your Script Syntax

     The final section of a script is where you can type in the syntax of the script actions
     you wish to execute.
     This part of your script will fall between the lines “Begin your script here” and “End
     your script here as is shown below:



     ' Begin your script here




     ' End of your script is here

     End




                                       Event Monitor                                      316
Link The Script to an Event
    When you are finished editing your script (and checking the script syntax for any
    errors), you are ready to link the script to one or more events. (Keep in mind that a
    carefully constructed script can be used with multiple events, as long as the events
    make the necessary columns of data available to the script.)
    To link a script to an event, follow these steps:
         Use the Navigator to locate the event you wish to link the script to.
         Double-click on the event name and then click on the “Actions” tab.
         Click on the “Run Basic Script” tab.
         Click in the “Basic Script Name” field.
         Click on the List button and choose the script you wish to link to this event
         (Repeat the preceding two steps for any additional scripts you wish to link to
          this event)
    Your resulting event should appear much like the following:




                           LINKING A BACK-END SCRIPT TO AN EVENT




                                      Event Monitor                                     317
Front-End Scripting Set-Up

    Front-end scripting is handled through the same Script Maintenance option as back-
    end scripting; the primary difference is that instead of passing information from an
    event’s query to a script, a front-end script contains the instructions to check for a
    specific condition of data and then identify those elements of data that need to be
    passed back into the event.
    It is very important to note that a single script can not be used in both front-end
    scripting and back-end scripting; a script must be designed either for front-end use or
    for back-end use.

Identify the Script’s “Application”
    When designing a front-end script, you must first decide which KnowledgeSync
    “application” you wish to associate the script to. If the script is associated with a
    specific application (e.g., SalesLogix or Great Plains), you might wish to create that
    script within the “Basic Scripts” branch of that particular application.
    However, if that script is not related to an application currently in the
    KnowledgeSync Event Manager, you might wish to create an entirely new
    application and store that script there.
    In the following illustration, note how an application called “System Alerts” has been
    created and the corresponding front-end scripts have been placed within it:




                         AN “APPLICATION” FOR FRONT-END SCRIPTS




                                     Event Monitor                                      318
Step #2: Design the Front-End Script
    As mentioned previously, a front-end script can perform whatever sort of “checking”
    you need it to – whether it’s monitoring the status of hardware devices (such as disks
    that are low on free space), checking the revision dates of files, scanning for critical
    processes that must be running, or retrieving data from a database that is not ODBC-
    compliant.
    So – the first step in using KnowledgeSync’s front-end scripting module is to create
    the script you wish KnowledgeSync to use to check for a certain condition of data.
    To add a new front-end script, open the Navigator and right-click on the branch of
    the application you wish to add the script to and choose “New Basic Script”. You
    will be taken into the Script Definition window and a script template will
    automatically be loaded into the script editor for you.
    (The following illustration shows the details of an existing front-end script.)




                                  SAMPLE FRONT-END SCRIPT

    The “Edit/Test Script” button lets you edit and modify the script’s contents as well as
    run the script from the edit window.
    The “Check Script Syntax” button lets you invoke an automated process that checks
    your script for any syntax errors. When you click on this button, you will either be
    informed of any script syntax errors that exist, or you will be informed that your
    script has been successfully verified.




                                      Event Monitor                                     319
Script Part I: General Info

     The first part of a script is where you can specify the purpose of the script, your name
     (as the script author), and date the script was created and the date it was last
     modified.
     This part of your script will look like the following:


     '   Script   Name               :   vs_sample_diskspace.bas
     '   Script   Author             :   Development
     '   Script   Purpose            :   Check available disk space
     '   Script   Creation Date      :   2/20/2001
     '   Script   Modified by        :
     '   Script   Modified Date      :
     '   Script   Modifications      :
     '
     '
     '   The following declared functions are available
     '   to the script author in order to interact
     '   more closely with KnowledgeSync 2000. All are optional
     '
     '   Scripts may be executed by KnowledgeSync in two ways.
     '
     '   1) As an action to a triggered event.
     '
     '   2) In place of a query in order to have the script
     '      trigger events.
     '
     '   A script used as an action cannot trigger events.
     '




                                         Event Monitor                                   320
Script Part II: Use the Script to Trigger an Event

     Since some of the next few sections of the KnowledgeSync template script contain
     information on designing a back-end script, they can be skipped in regards to the
     creation of a front-end script.
     The front-end scripting instructions begin in the following section:


     ' The following function is used to trigger events
     '
     ' Scripts used to take action cannot trigger events.
     ' Only scripts used instead of queries can trigger events.
     ' Please see the Event Manager
     ' help file while on the QUERIES tab.
     '
     Declare Function KSTrigger( ByVal ukey As String) As Boolean
     '
     ' This function triggers the event in the Application Server.
     ' This function is called when the script is used instead of a
     ' query and you want to trigger an event.
     '
     ' The parameters are as follows:
     '
     ' ukey The data that uniquely identifies this triggered item.
     '       Passed as a string. You may pass an empty string if
     '       you do not want KS to track triggered items.
     '




                                      Event Monitor                                  321
Script Part III: Specify Return Status Codes

     The sixth section of a script contains details on how you can specify what
     information the script will return to KnowledgeSync if the script fails to complete
     successfully.
     This part of your script will look like the following:


     Global KSReturnStatus As Long
     '
     ' Set this value if you want to return an error status number.
     ' If you don't set this value, the script is assumed to have
     ' worked successfully and is stamped completed by KS.
     '
     Global KSReturnMessage As String
     '
     ' Set this value if you want to return an error message
     '
     Global KSReturnComplete as long
     '
     ' Set this to -1 if you want the script to complete even if
     ' there is an error. Normally, when scripts error, the Action '
     ' server will attempt to execute them again in 1 minute until
     ' they complete without error.
     '
     On Error Resume Next
     '
     ' Tell KS how things went by setting the return status
     ' Set this to a non-zero if there was an error. This will be
     ' seen in the monitor in the errors section or corrective
     ' actions in the administrator

     KSReturnStatus = 0

     ' Set return message string. Place error message in this
     ' variable if there was one, This will show up in the monitor

     KSReturnMessage = "Success"




                                       Event Monitor                                       322
Script Part IV: Enter Your Script Syntax

     The final section of a script is where you can type in the syntax of the script you wish
     to execute.
     This part of your script will fall between the lines “Begin your script here” and “End
     your script here as is shown below:


     ' Begin your script here




     ' End of your script is here

     End



Sample Front-End Script
     On the following two pages is an example of a script that checks for low disk space.
     Note the following items about this front-end script:
            It identifies specific fields that will contain information about the disks that
             are checked and their available space
            It does not check the CD-ROM drive (an organization might need to edit this
             script and specify the appropriate CD-ROM drive letter)
            It lets you assign script “variables” that contain information about the
             triggered event and thus can be used both in the outgoing alert messages
             about this event and (if needed) can be passed into one or more back-end
             scripts that this event executes.
            It lets a script editor specify the disk space threshold (500 MB in this
             example)
            It loops through multiple disk drives
            It sets a successful “return status message” if no errors were encountered




                                       Event Monitor                                       323
Example: Check for Low Disk Space




    Declare Function GetDiskFreeSpace Lib "kernel32" Alias
    "GetDiskFreeSpaceA" _
    (ByVal lpRootPathName As String, lpSectorsPerCluster As Long,
    lpBytesPerSector As Long, lpNumberOfFreeClusters As Long,
    lpTtoalNumberOfClusters As Long) As Long

    Dim   strDrive As String
    Dim   lngSectorsPerCluster As Long
    Dim   lngBytesPerSector As Long
    Dim   lngNumberOfFreeClusters As Long
    Dim   lngTotalClusters As Long
    Dim   lngSts As Long
    Dim   DS
    Dim   IntLoop As Integer
    Dim   dblSpace As Double

    'These variables can be 'seen' from the event email message
    screen because they are global By declaring these, they can be
    used as content when we send email, faxes or pages...

    Global   DiskDrive As String
    Global   FreeSpaceBytes As Double
    Global   FreeSpaceMegs As Double
    Global   FreeSpaceFormatted As String
    Global   FreeSpaceMessage As String
    Global   MinMegs As Long

    MinMegs=50000      'This is our threshold. Less than 500 MB




                              Event Monitor                       324
Example: Check for Low Disk Space (con’t)


    For IntLoop = 67 To 90
          strDrive = Chr$(IntLoop) & ":\"     ' Ensure path is at
    the root.
          lngSectorsPerCluster=0
          lngBytesPerSector=0
          lngNumberOfFreeClusters=0
          lngTotalClusters=0
          lngSts = GetDiskFreeSpace(strDrive, lngSectorsPerCluster,
    lngBytesPerSector, lngNumberOfFreeClusters, lngTotalClusters)
          If lngSts <> 0 Then
                FreeSpaceBytes = CDbl(lngSectorsPerCluster) *
    CDbl(lngBytesPerSector) * CDbl(lngNumberOfFreeClusters)
                FreeSpaceFormatted = Format$(FreeSpaceBytes,
    "###,###0")
                FreeSpaceFormatted = FreeSpaceFormatted & " bytes
    are free."
                FreeSpaceMegs = FreeSpaceBytes / 1000000
                If FreeSpaceMegs < MinMegs Then     'Less than
    MinMegs is BAD
                      DiskDrive=chr$(intloop) & ":"
                      If DiskDrive <> "D:" Then     'Don't check
    the cdrom drive.
                            FreeSpaceMessage = "Disk " & DiskDrive
    & " has less than " & MinMegs & "mb free."
                            x= KSTrigger(DiskDrive) 'Low space on
    this drive
                      End If
                End If
          End If
    Next IntLoop
    'Tell KnowledgeSync 2000 no errors happened
    KSReturnMessage=0       'Clean as a whistle.
    End   'End of Script




                            Event Monitor                       325
Link the Script to an Event
    Just as a back-end script must be linked to an event (via the “Action” tab), a front-end
    script must also be linked to an event. In the case of a front-end script, however, you
    need to indicate that the script will take the place of one or more queries that the
    event would normally use to trigger an event.
    To link a front-end script to an event, edit the corresponding event and navigate to
    the “Queries” tab. In the middle of this tab you will see a check box called “Use
    Script Instead of Query.” Place a checkmark in this box. Then, to the right of this
    field, click on the “Select Script” button to display a list of scripts that you can
    choose from.
    (Be certain to choose a front-end script and not a back-end script.)




                         LINKING A FRONT-END SCRIPT TO AN EVENT

    With this step you are finished with the set-up of a KnowledgeSync event that uses a
    front-end script.




                                     Event Monitor                                      326
                                                        CHAPTER 8
                                              Naviigator Modulle
                                              Nav gator Modu e


The KnowledgeSync Navigator

   The KnowledgeSync Navigator module is a navigational aid that gives you the ability
   to quickly view, add, or modify KnowledgeSync events.
   The Navigator presents you with following options:
       Add, view, & modify events (or event components)
       View events that are currently scheduled to be submitted to run
       View events that are currently in the process of being executed
       View & correct any errors that have occurred in the execution of
        KnowledgeSync events
       Add, view, and modify Event Job Streams. (detailed at the end of the chapter
        on “Event Designing”)
       Add, view, and modify subscriber (alert recipient) records.


Accessing the Navigator

   To access the KnowledgeSync Navigator module, double-click on the
   KnowledgeSync icon called “Navigator” or select this option from the
   KnowledgeSync Programs Group.
   The following window will appear:




                                  Event Monitor                                   327
                                KNOWLEDGESYNC NAVIGATOR


Scheduled Events

   The branch called “Scheduled” shows you those events that are currently scheduled
   to be submitted by KnowledgeSync. In this regard, this option shows the same details
   as are available from the KnowledgeSync Monitor, using the Monitor option called
   “Scheduler / Next Run Dates/Times”.
   Scheduled events are grouped according to their schedule – thus when you click on
   the plus sign to expand the “Scheduled” branch, you are shown a list of schedules
   that have events within them that are currently scheduled to run. To drill-down into
   the details of specific events, click on the plus sign next to the schedule whose events
   you wish to view – as shown in the following illustration:




                            EVENTS THAT ARE SCHEDULED TO RUN
                                    Event Monitor                                      328
    When you expand a specific schedule, you are shown a list of the applications that
    have currently scheduled events. From here, you may expand an application to see
    the individual events that are scheduled to run. For information on viewing the
    various components of an event, please refer to the corresponding sections in this
    chapter.

Adding a New Schedule
    To add a new schedule to the KnowledgeSync system (such as a schedule that runs
    every 20 minutes, or a schedule that runs every Wednesday at 9 AM), right-click on
    the Scheduled branch. This will present you with an option to “Create New
    Schedule” (shown below) from which you can define the settings (working days,
    working hours, frequency, etc.) of the schedule you wish to create.
    (See the Event Designing chapter for more details on Schedule Creation.)




                         KNOWLEDGESYNC – CREATE NEW SCHEDULE

Edit a Scheduled Event
    You have the ability to edit an event that is currently scheduled to run by right-
    clicking next to the name of the event and choosing “Edit”. Please refer to the section
    of this chapter titled “All Events” which details the various event editing options.

Schedule An Event to Run Now
    To schedule an event to run (one time) right now, follow these steps:
    1. Expand the “Scheduled” branch and navigate to the event you wish to run right
       now.

    2. Right-click on the event and choose “Schedule This Event Now”.


                                     Event Monitor                                     329
    3. You will be prompted to confirm that you wish to run the event right now, and
        then will receive a confirmation that the event has been submitted.
    Please refer to the KnowledgeSync Monitor to review the status of this event once it
    has been submitted to run.

Test An Event
    To test the execution of an event, follow these steps:
        1. Expand the “Scheduled” branch and navigate to the event you wish to test.

        2. Right-click on the event and choose “Test This Event Now”.
        3. You will be prompted to confirm that you wish to test the event right now,
            and then will be presented with a web browser window in which the details
            of the tested event will appear.


In Progress Events

    The branch called “In Progress” shows you those events that are currently being
    executed by KnowledgeSync. This option will show the same content as is available
    from the KnowledgeSync Monitor, using any of the Monitor “Pending” options, such
    as “Application Events / Pending”, “Email Delivery / Pending”, “Report Generation /
    Pending”, and so on.
    “In progress” (or pending) events may be in progress for two reasons. First, the
    events may be currently executing, but not finished running. Second, the events may
    have encountered an error (such as an email server being down, the failure for a
    Crystal Report to have run, etc.). When such errors occur, KnowledgeSync
    automatically re-queues the event for submission and thus the event appears as “in
    progress”.
    Because of this, the number of sub-branches that you will see under “In Progress”
    events will vary – depending on whether you have any pending events, email
    messages, fax messages, reports, actions, and so on. If, for example, you have
    pending events, pending email alerts, and pending Crystal Reports, then you will see
    3 sub-branches beneath “In Progress” – one branch for application events, one for
    email delivery, and one for actions. Next to the title of each of these branches will be
    a number that shows how many “in progress” items there are in each of these
    categories.
    For example:




                                      Event Monitor                                      330
                            EVENTS THAT ARE IN PROGRESS


When you expand any one of these sub-branches, you will be shown a list of the
applications for which these pending records exist. If you then expand any one of
these application branches, you will be shown a listing of the specific items that are
in a pending state. You can drill-down into the details of the pending records and see
the following information about them:
     The name of the event that is related to the pending item
     More details about the specific item that is pending. This information will
      vary, based upon the pending item; for example, pending email messages
      will show you such details as the content of the alert as well as the email
      address of the account that the alert is to be sent from. Pending reports,
      however, will instead show you the name and location of the Crystal Report
      source file that the report is being generated from.
When you expand the In Progress branch, all sub-branches are expanded
automatically, so you can quickly and easily see all pending events. Since there are
usually not many events in a pending state, this gives you instant access to see what
(if any) events are pending, and why.
Note the following:
1) The “In Progress” branch will show you sub-branches only for those
   KnowledgeSync servers that are currently enabled and active. Thus if your Fax
   Server is not enabled, you will not see an In Progress sub-branch for Faxes.
2) If an In Progress sub-branch has no “In Progress” items, the branch will show
   with a zero (‘0’) next to it.
3) The “In Progress” branch will show no results if the KnowledgeSync Service is
   not currently running.

                                 Event Monitor                                     331
Event Exceptions

   The branch called “Exceptions” shows you those events that are currently in an
   “Error” state in KnowledgeSync. This option will show the same content as is
   available from the KnowledgeSync Monitor, using any of the Monitor “Errors All”
   options, such as “Application Events / Errors All”, “Email Delivery / Errors All”,
   “Report Generation / Errors All”, and so on.
   Event “exceptions” occur because of an error in the processing of an event. Errors
   can be caused by such things as an email server being down, the failure for a Crystal
   Report to have run, an invalid pager number, and so on.
   Like the “In Progress” tab, the number of sub-branches that you will see under
   “Exceptions” will vary – depending on whether you have any event errors, email
   errors, fax errors, reporting errors, action errors, and so on. Next to the title of each of
   these sub-branches will be a number that shows how many “exception” items there
   are in each of these categories.
   For example:




                     EVENTS THAT ARE IN AN “EXCEPTION” (ERROR) STATE


   (Note that since KnowledgeSync automatically re-queue events that are in an erroring
   state, all items that are listed as “exceptions” will also automatically appear within
   the “In Progress” branch of the Navigator.)
   When you expand any one of these sub-branches, you will be shown a list of the
   applications for which these exception items exist. If you then expand any one of
   these application branches, you will be shown a listing of the specific items that are
   in a pending state. You can drill-down into the details of the exception records and
   see the following information about them:

                                      Event Monitor                                        332
         The name of the event that is related to the exception item
         A box with a red exclamation mark in it which describes the error that is
          occurring* (see notes below)
         More details about the specific item that is in an error state. This information
          will vary, based upon the item; for example, email errors will show you such
          details as the content of the alert as well as the email address of the account
          that the alert is to be sent from. Reporting errors, however, will instead show
          you the name and location of the Crystal Report source file that the report is
          being generated from.
    Exceptions will appear only for those items that have encountered an error message
    or error number. You will not, for example, see Email Exceptions if you have an
    event that fails to generate a Crystal Report which is then to be emailed to a recipient.
    If the Crystal Report fails, the report record will appear under “Exceptions” – but the
    email message itself will not, even though it has not been successfully delivered.
    Note the following:
        1. The “Exceptions” branch will show you sub-branches only for those
           KnowledgeSync servers that are currently enabled and active. Thus if your
           Fax Server is not enabled, you will not see an Exceptions sub-branch for
           Faxes.
        2. If an Exceptions sub-branch has no “Exceptions” items, the branch will show
           with a zero (‘0’) next to it.
        3. The “Exceptions” branch will show no results if the KnowledgeSync Service
           is not currently running.

Correcting Event Exceptions
    When a KnowledgeSync event encounters an error, KnowledgeSync automatically
    re-queues the event and if the error is something that is self-correcting (such as an
    email server that is down), the error will eventually go away once the event
    successfully runs. However, there are other error conditions which are not self-
    correcting (such as an invalid query, an error in a Crystal Report, an invalid pager
    number, and so on), and in these cases you have the ability to “correct” the error that
    is occurring.
    To correct an error, you would begin by using the “Exceptions” branch to navigate to
    the particular error/exception that you wish to correct. You have two choices as to
    how to correct an exception:
         Correct the erroring information. This could involve re-entering a corrected
          email address, modifying a pager number or PIN, specifying a different fax
          number, and so on.
         Manually setting the status of the exception record to “complete”. This keeps
          the exception record in the KnowledgeSync history database, but since the
          status of the exception is “complete”, this record no longer appears under the
          “Exceptions” branch.
    To take either of these actions, follow these steps:
                                      Event Monitor                                      333
        Go to the Exceptions box with the red exclamation mark in it – this is the box
         that contains the details of the error condition that is occurring
        Double-click on this box. A window titled “Edit/Complete Error Status” will
         appear. From here you will see full details of the error that is occurring as
         well as have the ability to correct or manually override the completion status
         of this event.
   Please note that only certain kinds of exception/error conditions are able to be
   “corrected” from this window. Errors within a report, within an event’s query, or in
   other places may be correctable only by going into that corresponding record and
   making the appropriate modifications.
   Once you are finished correcting or completing an exception record, simply click on
   the “OK” button at the bottom of this window to save your entry and return to the
   main window.


Add/View/Edit Events in the Navigator

   In general, if you wish to add a new record to the KnowledgeSync database (such as
   a new application, a new query, a new event, a new report, or a new Basic Script),
   you will go to the branch called “All Events” and right-click on that branch to get the
   options to add these new records.
   If you wish to add, view, or remove a component from an existing event (such as
   adding a report or removing a query), you would expand the branch called “All
   Events” and then locate the application containing the event to work with, as follows:




                                 LISTING OF APPLICATIONS


   You would then expand that application to display the events within it:


                                    Event Monitor                                     334
                         LISTING OF EVENTS FOR AN APPLICATION


   And then expand the event you wish to view or work on.


How Event Details are Displayed

   For each event, you will be shown up to five components – depending on how the
   event is configured – as shown below:




                                AN EVENT’S 5 COMPONENTS

      1. Active Status & Schedule. Whether the event is “active” or “inactive” and
         what the event’s schedule is (how often it is scheduled to run)
      2. Query. The query (or queries) associated with the event which determine
         what conditions will cause the event to trigger. If an associated query has
         trigger parameters (i.e., thresholds that are specified on the event level), then
         a query branch will have a plus sign to the right of it.
      3. Deliverables. The “Deliverables” include all the content that an event could
         possibly deliver to one or more recipients. This includes all alert messages
         (email, fax, pager, etc.), any associated Crystal Reports, and any associated
         files that are linked to the event.



                                   Event Monitor                                       335
          4. Subscribers. This includes individual alert recipients, groups of recipients,
             and any “dynamic” recipients – such as the salesrep who is associated with a
             client’s order and/or the client themselves.
          5. Workflow Actions. This includes the following types of actions: the
             exporting of triggered event data to a flat file, the execution of SQL
             Statements and/or Stored Procedures, the execution of any of
             KnowledgeSync’s wizard APIs, and the execution of Visual Basic Scripts.


Adding New Records
(Queries, Events, Report Definitions, Scheduled Reports, & Basic Scripts)


      To add any of the above items to the KnowledgeSync system, expand the All Events
      branch and click on the Application you wish to add the corresponding item to. Then,
      right-click on the Application name and you will be presented with options to add
      each of the above-referenced items as shown below:




                                      ADDING NEW RECORDS

      For detailed instructions on adding any of these records, please refer to the
      corresponding section of this guide.


Viewing & Modifying Events

      The following sections detail how to locate, view the details of, and modify the
      configuration of an event that already exists within the KnowledgeSync application.

Editing an Application’s “Connection”
      To view or modify an application’s Connection record (where ODBC connection
      information is contained), follow these steps:
          1. Expand the “All Events” branch.
                                       Event Monitor                                   336
        2. Right-click on the application whose connection you wish to view or modify.
           Choose “Properties” as shown below:




                          ACCESSING AN APPLICATION’S CONNECTION

        3. Choose “Edit Connection” to view or modify this application’s connection
           properties, or “New Connection” to create a new connection record for this
           application.
        4. Click on Save and Close (and then on OK) to retain your work, or click on
           Cancel to exit from this option without saving your entries.

Enabling / Disabling an Event
    To enable or disable a specific event, follow these steps:
    1. Expand the “All Events” branch.
    2. Expand the application that contains the event you wish to work with.
    3. Expand the event to show its “active status” and schedule. Double-click on the
       event’s active status and schedule branch. You will be brought to the following
       window:




                                     Event Monitor                                  337
                         AN EVENT’S “ACTIVE” STATUS & DESCRIPTION

    4. Set the event’s “Active” checkbox accordingly and save your changes.

Changing an Event’s Schedule
    To view the details of (or modify) the schedule that an event uses, follow these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event whose schedule you wish to access. Right-click on the
           event’s schedule and choose “Edit” as shown below:




                                    EDIT EVENT SCHEDULE


                                     Event Monitor                                     338
        4. You will be brought to the following window:




                                 EVENT SCHEDULE PROPERTIES

        5. Make whatever changes are required and click on “Save and Close” to retain
           your changes, or “Cancel” to ignore any changes.

General Processing Parameters
    To change the name of an event, its priority, and whether the event should trigger just
    once for a matching record or repeatedly (until the record no longer meets the event’s
    criteria), follow these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Double click on the name of the event as shown below:




                                     Event Monitor                                     339
                      AN EVENT’S GENERAL INFORMATION



4. This will bring you to the “Description” tab of the event, with access to all
   the settings mentioned previously. Make whatever changes are needed.




                      AN EVENT’S GENERAL INFORMATION

5. To save your changes, click on the “Save and Close” button at the top-left of
   your window.

                             Event Monitor                                     340
        6. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.
    Once you are on the “Description” tab of an event, you may click on any of the other
    tabs associated with the event if you wish to view or make additional changes to
    other components of this event.

Adding/Changing/Removing Event Queries
    The following sections detail how to add, change, or remove queries from
    KnowledgeSync events.

Adding a Query to an Event

        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Double click on the name of the event as shown previously.
        4. Click on the “Queries” tab.
        5. Add queries as needed.
        6. To save your changes, click on “Save and Close” at the top-left of your
           window.
        7. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.

Changing a Query’s Trigger Parameter Values

    Some queries are parameter-driven, such as a query that identifies all invoices that
    are at least ‘x’ days old. The ‘x’ is considered a trigger parameter for the event, and
    the value that is specified for this parameter (such as ‘30’ for “30 days old”) is
    referred to as the event’s trigger parameter value.
    To change an event’s trigger parameter values, follow these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its query(ies).
        4. Locate the query whose parameter value you wish to modify; the plus sign
           next to the query indicates that it is parameter-driven as shown below:




                                      Event Monitor                                      341
                     AN EVENT WITH A QUERY PARAMETER



5. Click on this plus sign to the right of the query to view the query’s
   parameters’ descriptions and current values as shown below:




                        THE QUERY PARAMETER VALUE


6. Double-click on the parameter branch you wish to change. You will be taken
   into the following window:




                             Event Monitor                                 342
                            QUERY PARAMETER MAINTENANCE



      7. Make all necessary changes. To save your changes, click on the “Save and
         Close” button at the top-left of the window.
      8. If you have not made any changes (or do not wish to save your changes),
         click on the “Cancel” button.

Removing a Query from an Event

      1. Expand the “All Events” branch.
      2. Expand the application that contains the event you wish to work with.
      3. Expand the event so that you can view its query(ies).
      4. Locate the query you wish to remove and double-click on it.
      5. Highlight (single-click on) the query you wish to remove and click on the
         “Remove Query” button..
      6. To save your changes, click on “Save and Close” at the top-left of your
         window.
      7. If you have not made any changes (or do not wish to save your changes),
         click on the “Cancel” button.




                                  Event Monitor                                      343
Changing a Query’s Configuration

    A query is typically configured to retrieve only certain fields of data as well as data
    that meets certain criteria, such as sales opportunities that have a status of “Open”. If
    you wish to change the configuration of a query, you would need to modify the
    query’s configuration as follows:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its query(ies).
        4. Right-click on the branch that contains the name of the query you wish to
           work on and select “Edit Query” as shown in the following illustration:




                         HOW TO ACCESS THE QUERY’S CONFIGURATION



        5. This will take you into the details of the associated query’s definition as
           shown below. Make all necessary changes.




                                      Event Monitor                                       344
                             QUERY DEFINITION MAINTENANCE



       6. To save your changes, click on the “Save and Close” button at the top-left of
          your window.
       7. If you have not made any changes (or do not wish to save your changes),
          click on the “Cancel” button.

Adding/Changing/Removing Event Reports
    The following sections detail how to add, change, or remove reports from
    KnowledgeSync events.

Adding a Report to an Event

       1. Expand the “All Events” branch.
       2. Expand the application that contains the event you wish to work with.
       3. Double click on the name of the event.
       4. Click on the “Reports” tab.
       5. Add reports (and their parameter values, if required) as needed.
       6. To save your changes, click on “Save and Close” at the top-left of your
          window.


                                    Event Monitor                                   345
        7. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.

Changing a Report’s Parameter Values

    Some reports are parameter-driven, such as a report that generates invoices for
    newly-entered orders. The report parameter will be the value of a field coming from
    the event’s query (such as a field called “{order_no}”), and this parameter is referred
    to as the event’s report parameter value.
    To change an event’s report’s parameter values, follow these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Deliverables.
        4. Expand the Deliverables so that you can view the associated report(s).
        5. Locate the report whose parameter values you wish to modify; the plus sign
           next to the report indicates that it is parameter-driven as shown below:




                             AN EVENT WITH REPORT PARAMETERS



        6. Click on this plus sign to the right of the report to view the report’s
           parameters’ descriptions and current values as shown below:




                                     Event Monitor                                     346
                      THE REPORT PARAMETER VALUE


7. Double-click on the parameter branch you wish to change. You will be taken
   into the following window:




                     REPORT PARAMETER MAINTENANCE



8. Make all necessary changes. To save your changes, click on the “Save and
   Close” button at the top-left of the window.
9. If you have not made any changes (or do not wish to save your changes),
   click on the “Cancel” button.
                           Event Monitor                                   347
Changing a Report’s Output Format

    Reports can be configured to generate output in a variety of formats, including PDF,
    HTML, and so on. If you wish to change the format of a report associated with an
    event, follow these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Deliverables.
        4. Expand the Deliverables so that you can view the associated report(s).
        5. Double-click on the branch that contains the name of the report whose output
           format you wish to change as shown below:




                     SELECTING A REPORT TO CHANGE ITS OUTPUT FORMAT



        6. This will take you into the details of the report’s generation for this event as
           shown below. Make all necessary changes.




                                     Event Monitor                                       348
                             REPORT OUTPUT FORMAT MAINTENANCE



         7. To save your changes, click on the “Save and Close” button at the top-left of
            your window.
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Viewing/Editing the Report’s Definition

     A report is configured to use a specific Crystal Reports “.rpt” file, and can also be
     configured to generate output according to a specific naming convention. If you wish
     to change either the definition of the “.rpt” file or the name of the report output file,
     you would need to modify the report itself using this option:
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Deliverables.
         4. Expand the Deliverables so that you can view the associated report(s).
         5. Right-click on the branch that contains the name of the report whose
            definition you wish to edit or view, and select “Edit” as shown in the
            following illustration:




                                       Event Monitor                                      349
                HOW TO ACCESS THE REPORT’S CONFIGURATION



6. This will take you into the details of the associated report’s definition as
   shown below. Make all necessary changes.




                      REPORT DEFINITION MAINTENANCE



7. To save your changes, click on the “Save and Close” button at the top-left of
   your window.



                             Event Monitor                                        350
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Removing a Report from an Event

         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Deliverables.
         4. Expand the Deliverables so that you can view the associated report(s).
         5. Double-click on the branch that contains the name of the report you wish to
            remove.
         6. Highlight (single-click on) the report you wish to remove and click on the
            “Remove Report” button.
         7. To save your changes, click on “Save and Close” at the top-left of your
            window.
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Adding/Changing/Removing Event Files
     The following sections detail how to add, change, or remove files from
     KnowledgeSync events.

Adding a File to an Event

         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Double click on the name of the event.
         4. Click on the “Files” tab.
         5. Add reports (and corresponding settings) as needed.
         6. To save your changes, click on “Save and Close” at the top-left of your
            window.
         7. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Changing or Removing Event Files

     To change the configuration of a file (ore remove a file) associated with an event,
     follow these steps:
         1. Expand the “All Events” branch.

                                        Event Monitor                                      351
2. Expand the application that contains the event you wish to work with.
3. Expand the event so that you can view its Deliverables.
4. Expand the Deliverables so that you can view the associated File(s).




                    AN EVENT WITH AN ASSOCIATED FILE



5. Double-click on the file branch you wish to change or remove. You will be
   taken to the following window:




                            Event Monitor                                  352
                                    EVENT FILE MAINTENANCE



         6. Make all necessary changes. To save your changes, click on the “Save and
            Close” button at the top-left of the window.
         7. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Adding or Changing the Event Email Alert Message
     The following sections detail how to add or modify the email alert message that is
     associated with a KnowledgeSync event.

Adding Email Alert Text to an Event

     These steps are required only if an event does not have an email alert message
     already configured.
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Double click on the name of the event.
         4. Click on the “Email” tab.
         5. Add the email alert message text as well as the other email settings as
            needed.
         6. To save your changes, click on “Save and Close” at the top-left of your
            window.
         7. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Viewing/Editing an Event’s Email Alert Message

     To view or edit the email alert message that is associated with an event, follow these
     steps:
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Deliverables.
         4. Expand the Deliverables so that you can view the associated Email alert
            message as shown below.




                                      Event Monitor                                       353
                      AN EVENT’S EMAIL ALERT MESSAGE



5. To view the contents of the email alert message, simply place your cursor
   over the Email branch. The text of the email alert message body will pop up
   automatically within the Navigator window.
6. To view/edit the email alert message content and configuration, double-click
   on the Email branch. This will take you into the “Email” tab of the associated
   event as shown below.

    From here, you may view and/or change the email sending account, the
    reply-to account, the email message subject and body content, and the email
    attachment options.




                            Event Monitor                                    354
                              EMAIL ALERT MESSAGE MAINTENANCE



         7. To save your changes, click on “Save and Close” at the top-left of the
            window.
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.
     Please note that no email record will appear for an event in the Navigator if the email
     message “subject” field is left blank.
     Note also that once you are on the “Email” tab of an event, you may click on any of
     the other tabs associated with the event if you wish to view or make additional
     changes to other components of the event.

Adding or Changing the Event Fax Alert Message
     The following sections detail how to add or modify the fax alert message that is
     associated with a KnowledgeSync event.

Adding Fax Alert Text to an Event

     These steps are required only if an event does not have a fax alert message already
     configured.
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
                                      Event Monitor                                     355
        3. Double click on the name of the event.
        4. Click on the “Fax” tab.
        5. Add the fax alert message text as well as the other fax settings as needed.
        6. To save your changes, click on “Save and Close” at the top-left of your
           window.
        7. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.

Viewing/Editing the Event’s Fax Alert Message

    To view or edit the fax alert message that is associated with an event, follow these
    steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Deliverables.
        4. Expand the Deliverables so that you can view the associated fax alert
           message as shown below.




                                AN EVENT’S FAX ALERT MESSAGE



        5. To view the contents of the fax alert message, simply place your cursor over
           the Fax branch. The text of the fax alert message body will pop up
           automatically within the Navigator window.
        6. To view/edit the fax alert message content and configuration, double-click on
           the Fax branch. This will take you into the “Fax” tab of the associated event
           as shown below.

                                     Event Monitor                                       356
            From here, you may view and/or change the fax sending account, the fax
            message subject, cover page, and body content, and the fax attachment
            options.




                               FAX ALERT MESSAGE MAINTENANCE



        7. To save your changes, click on “Save and Close” at the top-left of the
           window.
        8. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.
    Please note that no fax record will appear for an event in the Navigator if the fax
    message “subject” field is left blank.
    Note also that once you are on the “Fax” tab of an event, you may click on any of the
    other tabs associated with the event if you wish to view or make additional changes
    to other components of the event.

Adding or Changing the Event Pager Message
    The following sections detail how to add or modify the pager alert message that is
    associated with a KnowledgeSync event.




                                     Event Monitor                                        357
Adding Pager Alert Text to an Event

     These steps are required only if an event does not have a pager alert message already
     configured.
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Double click on the name of the event.
         4. Click on the “Page” tab.
         5. Add the pager alert message text as well as the “wait for reports” setting as
            needed.
         6. To save your changes, click on “Save and Close” at the top-left of your
            window.
         7. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.

Viewing/Editing the Event’s Pager Alert Message

     To view or edit the pager alert message that is associated with an event, follow these
     steps:
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Deliverables.
         4. Expand the Deliverables so that you can view the associated page alert
            message as shown below.




                               AN EVENT’S PAGER ALERT MESSAGE



                                       Event Monitor                                    358
        5. To view the contents of the pager alert message, simply place your cursor
           over the Page branch. The text of the pager alert message body will pop up
           automatically within the Navigator window.
        6. To view/edit the pager alert message content and configuration, double-click
           on the Page branch. This will take you into the “Page” tab of the associated
           event as shown below.

            From here, you may view and/or change the pager message content, and
            whether the pager alert should wait for reports associated with the event to
            finish running before the pager message is delivered.




                             PAGER ALERT MESSAGE MAINTENANCE



        7. To save your changes, click on “Save and Close” at the top-left of the
           window.
        8. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.
    Note that once you are on the “Page” tab of an event, you may click on any of the
    other tabs associated with the event if you wish to view or make additional changes
    to other components of the event.

Adding or Changing the Event Webcast Message
    The following sections detail how to add or modify the webcast (dashboard) alert
    message that is associated with a KnowledgeSync event.



                                     Event Monitor                                     359
Adding Webcast Alert Text to an Event

    These steps are required only if an event does not have a webcast alert message
    already configured.
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Double click on the name of the event.
        4. Click on the “Webcast” tab.
        5. Add the webcast alert message text as well as the other webcast settings as
           needed.
        6. To save your changes, click on “Save and Close” at the top-left of your
           window.
        7. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.

Viewing/Editing the Event’s Webcast Alert Message

    To view or edit the webcast alert message that is associated with an event, follow
    these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Deliverables.
        4. Expand the Deliverables so that you can view the associated webcast alert
           message as shown below.




                             AN EVENT’S WEBCAST ALERT MESSAGE




                                     Event Monitor                                       360
       5. To view the contents of the webcast alert message, simply place your cursor
          over the Webcast branch. The text of the webcast alert message body will
          pop up automatically within the Navigator window.
       6. To view/edit the webcast alert message content and configuration, double-
          click on the Webcast branch. This will take you into the “Webcast” tab of the
          associated event as shown below.

           From here, you may view and/or change the webcast message content as well
           as the other webcast settings, such as expiration days, color-coding, and
           whether to handle attachments as URL links.




                          WEBCAST ALERT MESSAGE MAINTENANCE



       7. To save your changes, click on “Save and Close” at the top-left of the
          window.
       8. If you have not made any changes (or do not wish to save your changes),
          click on the “Cancel” button.
   Note that once you are on the “Webcast” tab of an event, you may click on any of the
   other tabs associated with the event if you wish to view or make additional changes
   to other components of the event.

Add/Change/Remove Event Actions (Workflow)
   The following sections detail how to add or modify the workflow actions that are
   associated with a KnowledgeSync event.
   There are up to five kinds of Actions that can be associated with an event. They are:


                                    Event Monitor                                     361
        The creation of a file containing triggered event data
        The execution of SQL Statements and/or Stored Procedures
        The execution of one of KnowledgeSync’s Wizards
        The submission of Executable Programs
        The execution of one or more Visual Basic Scripts
    All of these workflow types are shown under the “Actions” branch of an event as
    shown below:




                          AN EVENT’S 5 WORKFLOW ACTION TYPES




Adding Actions (Workflow) to an Event

       1. Expand the “All Events” branch.
       2. Expand the application that contains the event you wish to work with.
       3. Double click on the name of the event.
       4. Click on the “Actions” tab.
       5. Specify the event’s actions as needed.
       6. To save your changes, click on “Save and Close” at the top-left of your
          window.
       7. If you have not made any changes (or do not wish to save your changes),
          click on the “Cancel” button.


                                   Event Monitor                                      362
View/Edit/Remove the Event’s Actions (Workflow)

    To view, edit, or remove the workflow actions associated with an event, follow these
    steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Actions.
        4. Expand the Actions so that you can view the associated workflow. (Note that
           each of the five types of actions referenced above will be uniquely
           identified.)




                              AN EVENT’S WORKFLOW ACTIONS



        5. To get a summary of an action, simply place your cursor over the
           corresponding Action branch. An overview of the action will pop up
           automatically within the Navigator window.
        6. To view/edit the full action configuration, double-click on the corresponding
           Action branch. This will take you into the “Action” tab of the associated
           event as shown below.

            From here, you may view, change, or remove the action definition. Note that
            only technically experienced people should be allowed access to this option.




                                    Event Monitor                                    363
                                WORKFLOW ACTION MAINTENANCE



         7. To save your changes, click on “Save and Close” at the top-left of the
            window.
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.
     Note that once you are on the “Actions” tab of an event, you may click on any of the
     other tabs associated with the event if you wish to view or make additional changes
     to other components of the event.

Viewing/Editing the Script Definition

     When you double-click on a Script associated with an event, you are taken to the
     KnowledgeSync option where the script is linked to the corresponding event. From
     here you may view the details of this link as well as delete this link, if appropriate.
     If you wish to view the definition of this script (including viewing, editing, or testing
     the actual source code of the script), follow these steps:
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Actions.
         4. Expand the Actions so that you can view the associated workflow.
         5. Right-click on the script and select “Edit” as shown below:




                                       Event Monitor                                       364
                HOW TO ACCESS THE SCRIPT’S CONFIGURATION



6. This will take you into the details of the script’s definition. From here, you
   may view, test, and/or edit the script’s source code as shown below:




                      SCRIPT DEFINITION MAINTENANCE



7. To save your changes, click on “Save and Close” at the top-left of the
   window.
8. If you have not made any changes (or do not wish to save your changes),
   click on the “Cancel” button.

                             Event Monitor                                      365
Add/Change/Remove Event Subscribers
    The following sections detail how to add or modify the subscribers who will receive
    alerts related to a specific KnowledgeSync event.
    There are three types of subscribers that can be associated with an event. They are:
         Specific users (as defined by their names)
         Dynamic users (users who are related to the event being triggered)
         Specific groups of users (as defined by their group name)
    All of these subscriber types are shown under the “Subscribers” branch of an event as
    shown below:




                               AN EVENT’S 3 SUBSCRIBER TYPES




Adding Subscribers to an Event

        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Double click on the name of the event.
        4. Click on the “Subscribers” tab and choose to add either “Standard” or
           “Advanced” subscribers.
        5. Select the event’s subscribers as needed.
        6. To save your changes, click on “Save and Close” at the top-left of your
           window.


                                     Event Monitor                                     366
        7. If you have not made any changes (or do not wish to save your changes),
           click on the “Cancel” button.

Changing/Removing a Subscriber for an Event

    To change the delivery method(s) for a subscriber, to remove a subscriber for an
    event, or to change the message “breaking logic” associated with an event, follow
    these steps:
        1. Expand the “All Events” branch.
        2. Expand the application that contains the event you wish to work with.
        3. Expand the event so that you can view its Subscribers.
        4. Expand the Subscribers so that you can view the associated alert recipients.
        5. Double-click on the subscriber record you wish to change or remove as
           shown in the following illustration:




                                  AN EVENT’S SUBSCRIBERS



        6. You will be brought into a Subscriber Maintenance window as shown below.




                                    Event Monitor                                       367
                                EVENT SUBSCRIBER MAINTENANCE



         7. Make all necessary changes. To save your changes, click on the “Save and
            Close” button at the top-left of the window.
         8. If you have not made any changes (or do not wish to save your changes),
            click on the “Cancel” button.
     Note that the alert message “breaking logic” is defined in the “Advanced” tab of
     Subscribers. Please refer to the Event Designing chapter of this guide for details on
     specifying the message “breaking logic”.

Viewing/Editing a Subscriber’s Profile

     If you wish to view the profile of a subscriber (including their delivery addresses, and
     other delivery details), follow these steps:
         1. Expand the “All Events” branch.
         2. Expand the application that contains the event you wish to work with.
         3. Expand the event so that you can view its Subscribers.
         4. Expand the Subscribers branch so that you can view the associated alert
            recipients.
         5. Right-click on the subscriber whose profile you wish to view and/or modify
            and select “Edit” as shown below:




                                      Event Monitor                                      368
                   HOW TO ACCESS A SUBSCRIBER’S PROFILE



6. This will take you into the details of the subscriber’s profile. From here, you
   may view and/or edit the profile as shown below:




                     SUBSCRIBER PROFILE MAINTENANCE



7. To save your changes, click on “Save and Close” at the top-left of the
   window.


                             Event Monitor                                     369
       8. If you have not made any changes (or do not wish to save your changes),
          click on the “Cancel” button.


Subscriber Maintenance

   To add or update an alert recipient (subscriber) to the KnowledgeSync system,
   expand the Subscribers branch to see a list of all currently-defined Subscriber Groups
   such as the following:




                                    SUBSCRIBER GROUPS

   To add a subscriber, right-click on the Group that you wish to add the subscriber to,
   and choose New User. Please refer to the “Subscribers” chapter of this guide for
   complete details of all subscriber-related data fields.
   To view or update an existing subscriber’s record, expand the group to which the
   subscriber belongs and you will be presented with a window such as the following:




                                    Event Monitor                                     370
                                SUBSCRIBERS WITHIN A GROUP

    Double-click on the subscriber’s record you wish to view or modify.
    Click on Save and Close when done adding, viewing, or modifying this subscriber.

Subscriber Group Maintenance
    To create or modify the description of a subscriber group, follow these steps:
    1. Right-click on the Subscribers branch and select the option to add a “New User
       Subscriber Group” as shown below:




                              CREATE NEW SUBSCRIBER GROUP


    2. This will present you with a window from which you can create a new group.

        Please note that you must first create a subscriber group (and save that record)
        before you can specify subscriber linking for that group. (See following section.)

Subscriber Linking
    To set-up, modify, or remove “Subscriber Linking” for a group of subscribers, follow
    these steps:
    1. Expand the Subscribers branch to see a list of all currently-defined Subscriber
       Groups.
    2. Right-click on the Group whose Subscriber Linking you wish to access. Choose
       “Properties”.
    3. Click on the “Subscriber Linking” button and follow the instructions in the
       “Subscribers” chapter of this Guide.


                                     Event Monitor                                       371
                                                           CHAPTER 9
                                                          Event Moniitor
                                                          Event Mon tor


Event Monitor

   The KnowledgeSync Event Monitor is a real-time “dashboard” or “Operator’s
   Console” that you can use to keep track of the status of the events that you are
   checking for, the alerts that have been (or need to be) delivered, and the response
   actions (such as database updates or the generation of Crystal Reports) that have been
   executed.
   Using the Monitor, you can keep track of:
          The status of the application servers that KnowledgeSync uses to check for
           events and send alerts
          The events that are scheduled to be checked and those that have been
           triggered
          The alerts that have been sent out (or are about to be sent out), including
           whom they are sent to, via what means, and whether they were successfully
           delivered
          The full text of the outgoing alert messages
          The status of any Crystal reports that have either been triggered by database
           conditions or are scheduled for distribution
          The status of event response actions that add or update records within one or
           more underlying application databases
          Whether any kind of errors have occurred that would prevent
           KnowledgeSync from either checking for events or responding to them
   Please note that the Monitor is an informational display only; you cannot use the
   Monitor to modify any of the information that appears within it.


KnowledgeSync Event “WatchDog”

   In addition to the Event Monitor, KnowledgeSync also contains the ability to monitor
   itself. This function does not use an extra "connection" license, and so it free to every
   KnowledgeSync client.
   The ability for KnowledgeSync to monitor itself allows you to:


                                     Event Monitor                                      372
           Trigger alerts when an event errors

           Trigger alerts if KnowledgeSync is unable to deliver an alert (e.g., an event
           has an invalid pager PIN)

           Trigger alerts if too many events or alerts are being triggered

           Trigger alerts if one person is receiving too many alerts

           Trigger alerts if a report fails to generate successfully

           Trigger alerts if an application update ("action") fails to complete

           Generate a list of all events using a specific query, report, or script

           Generate a list of events, reports, alerts, or actions that are pending or have
           been pending for more than 'x' minutes
   These events are just a small collection of the events that are included in a
   Vineyardsoft-created EventPak called the "Event WatchDog". This EventPak is
   available (for free) from Vineyardsoft Corporation. Please contact Vineyardsoft’s
   Customer Support department in order to receive a free copy of this EventPak.


Logging In to the Event Monitor

   The KnowledgeSync Event Monitor is a separate module within the KnowledgeSync
   application, and so the first step is to log into that module.
        Log into the Event Monitor (default user name is “Admin” and no password
         is required), and you will see the main Monitor window as shown in the
         following illustration.




                                     Event Monitor                                       373
                         KNOWLEDGESYNC MONITOR INITIAL WINDOW

    The first branch of information that is shown to you is the “Server Status” branch
    (within the “Activity” folder) and this is detailed in the following sections.

Monitor Display Sorting Order
    You can control the order in which records are displayed in the Monitor by clicking
    in the heading for any field in the Monitor window. For example, to display most-
    recent records first, go to the date “Created” column, point your cursor at that
    heading, and click once. Clicking again will reverse the order that records are
    displayed.

Resizing the Display Grid
    The grid that is displayed in the Monitor is a standard KnowledgeSync component
    that is used in many places within the KnowledgeSync application. In some cases,
    you will find the need to expand or contract the width of specific columns within the
    grid. To do so, follow these steps:
         In the heading line of the grid (the line with the column titles in it), position
          the cursor at the vertical dividing line between the columns whose width you
          wish to adjust.
         The cursor will change into a two-headed arrow.
         Click your left mouse button and hold.
         Drag your mouse to the right or to the left to enlarge or decrease the width of
          the corresponding columns. Release your mouse button when the size is to
          your liking.
    Note that the re-sized grids will be in effect as long as you are in a specific branch in
    the Monitor. Once you exit from a branch, the grids will return to their default
    widths.



Activity Folder

    The KnowledgeSync Activity folder tells you about the current processing and user
    activity occurring within the application.

Server Status
    This will display the current status of all the servers used by the KnowledgeSync
    application. The possible status states are as follows:
           Shutdown: The server is not running at this time. Among the possible
            reasons for this are:



                                      Event Monitor                                       374
              The KnowledgeSync service could be shutdown. (On NT, this is done
               via the control panel by selecting NT services, clicking on
               KnowledgeSync 2000 service and clicking on Stop.)
              The server is flagged not to run. This is done in the KnowledgeSync
               Administrator, by double-clicking on the specific server and un-checking
               the checkbox that allows the specific server to perform as required.

               You can control which servers will be allowed to run. If you know that
               your site will not be performing certain types of notifications (e.g.,
               faxing), you can disable the corresponding server to conserve system
               resources.

               By default, KnowledgeSync is shipped with all servers enabled except
               for the Paging, Faxing, Reporting, Copying, Webcasting & Action
               servers.
          Idle: The server is running and in memory but is not processing any data.
           The server is in this state if there is no data to process.
          Processing: The server is processing event data.
          Startup: The server is in initialization and startup mode.
          Linking: (For the application event server only) KnowledgeSync is using its
           “subscriber linking” function to retrieve alert recipient data from an external
           database.

KnowledgeSync Server Descriptions

    KnowledgeSync uses the following servers:
          KnowledgeSync Service: This server initiates all of the other servers.
          Scheduler: This server keeps track of when events are scheduled to be
           executed. When an event is due for execution, this server sends the
           corresponding task to the appropriate event server (e.g., the application event
           server).
          Application Event: This server executes application events.
          Report: This server generates Crystal reports, forms, and documents.
          E-Mail: This server delivers e-mail messages.
          Fax: This server delivers fax messages.
          Page: This server delivers pager messages.
          Webcast: This server delivers webcast messages.
          Copy: This server copies and delivers files and Crystal reports via FTP.
          Action: This server executes event “response actions” including database
           updates.

KnowledgeSync Server Notes

    Please note the following about the KnowledgeSync servers:

                                    Event Monitor                                     375
          If any of the first three servers are shutdown or paused, KnowledgeSync will
           not be able to check for events, send notifications about triggered events, or
           execute event response actions.
          If any of the notification servers (i.e., e-mail, fax, pager, copy, or webcast)
           are shutdown or paused, KnowledgeSync will not be able to send
           notifications via that particular delivery means.
          If the “Action” server is shutdown, KnowledgeSync will not be able to add
           or update database records.
          When data is being processed by a server, the server will show a status of
           "processing." When there is no data to be processed, the server will show a
           status of "idle."
          For each server, you are shown its status, the error message (if any) that
           prevents the server from running, the name of the computer and user account
           from which the server is running, the server computer’s operating system and
           version, and the date and time the server was last started.

Current User Logins
    The Current User Logins option tells you who is currently logged into the
    KnowledgeSync application. By selecting an individual user, you can display the
    following information:
          The KnowledgeSync module the user is logged into. This will display either
           the “Administrator”, “Event Monitor”, or “Event Manager.”
          The user’s computer and user names
          The user’s operating system and platform
          The date and time that the user last logged into the application
          The date and time of the user’s last activity




                                     Event Monitor                                       376
Scheduler Folder

   The “Scheduler” folder has one branch within it – “Next Run Date/Times” – and this
   allows you to see what events are due to be submitted next.




                       EVENTS “NEXT SCHEDULED RUN DATE/TIMES”

   For each event that is shown, you can display:
          Event ID (internally-assigned by KnowledgeSync)
          The application to which the event belongs
          The name of the event
          The event’s next scheduled run date and time
          The frequency that the event is submitted (e.g., “Monthly”)
          A description of the frequency (e.g., “The 1st of the Month”)




                                   Event Monitor                                  377
Application Events Folder

   The “Application Events” folder enables you to track the status of application events
   that are due to run, have already run, or have failed to run successfully because of an
   error.




                           APPLICATION EVENTS: CHECKED TODAY

   Application events are divided into four categories:
          Pending. A pending event is one that has not been submitted either because
           its time has not yet arrived, or because the event failed to complete
           successfully. (See note about “How to Handle Event Errors”.)

           It is important to understand that an event is placed into a pending state at the
           minute it is due to be submitted, and thus does not remain in a pending state
           for very long (unless the event errors).
          Checked. A checked event is one that was successfully executed. A checked
           event may or may not be “triggered”, depending on whether its conditions
           were met. (See note about “Keeping Last Checked Record”.)
          Triggered. A triggered event is one that was successfully executed and
           whose conditions were met. Note that a single event can create multiple
           triggered records (see “Triggered Records”).

           A triggered event often results in either alerts being sent (see “Deliverables
           Button”), actions being taken (see “Actions Taken Folder”), and/or reports
           being generated (see “Report Generation Folder”).
          Errors. A record will show up under the “errors” branch if KnowledgeSync
           has been unable to successfully check the event. An event that fails to be
           checked successfully will automatically be placed back into the “Pending”
           branch.
                                    Event Monitor                                       378
How to Handle Event Errors
    Event errors can occur for a number of different reasons, including an error in the
    configuration of the event, and KnowledgeSync’s inability to access a database on a
    server that may be down.
    When an application event fails to complete successfully because of an error, three
    things happen:
           The event will appear in the “Errors” branch under “Application Events”.
           The event will appear in the “Pending” branch under “Application Events”.
           KnowledgeSync will re-submit the event every minute until:
               The event successfully executes
               The event error is corrected
               This run of the event is deleted
    Note that KnowledgeSync will retain only one (1) iteration of an event that is
    erroring. (Thus even if you have an event that runs every five minutes and it fails to
    run successfully for 30 minutes, KnowledgeSync will retain only one copy of that
    event in the pending and error branches.)
    If the event is erroring because of a condition that will correct itself (such as an
    applic