_________________________________________________________________ |_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_| |_|\ _________________________________________________________ /|_| |_| | | |_| |_| | | |_| |_| | MN: (WebBoard) Moderator Notification System | |_| |_| | | |_| |_| | By: Rog | |_| |_| | Date: Apr 06 '00 | |_| |_| | | |_| |_| |_________________________________________________________| |_| |_|'_______________________________________________________ ___`|_| |_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_|_| [This plain-text document should be printed in a fixed-spaced font.] 0. Purpose/rationale 1. Configuration -- ASPTear and FormMail 2. Configuration -- The rest of the system 3. Configuration -- Setting up the demon and other install issues 4. Running the system for the first time (running in test mode) 5. Setting up multiple copies of the system for different boards 6. Diagnosing errors, and overview of processing/internal files 7. Clock skew errors, etc. 8. Reusable code 9. Author contact info. 10. Version history info. ==================== 0. Purpose/Rationale ==================== WebBoard has a feature that allows users to be notified when there are new messages posted to a conference, but this doesn't seem to serve the needs of all cases in which conference moderators have to "moderate" messages. (In WebBoard, this "moderation" process consists of clicking on a red check mark next to the message. After doing so, the message is new "viewable" by the non-staff users on the board. In WebBoard terms, this is known as "verification" of messages.) While there are many workarounds to this limitation, they aren't always appropriate for all circumstances. This system allows: * The sending of "moderator notification" messages to be entirely under the moderator's control. A special WebBoard user name is set up for each moderator who wishes to receive these notifications (and this user must be a moderator for the conference-in-question). Once the user name has been set up, the moderator can control the frequency with which messages are sent out. For example, if the moderator changes their login name to: "Joe_Verify_1", this will ensure that notifications are sent out for all unverified messges that are more than 15 minutes old at the time that the system runs. The string "verify" can be in upper or lower case. All that's required is that it be followed by an underscore and a sequence of digits. The latter is interpreted as a number which controls the number of 15-minute intervals. If the moderator goes on vacation for a week, then changing his or her login name to: "Joe_Verify_700" will ensure that their email box doesn't fill up with notifications. Since login names aren't always convenient to change, the system allows moderators to use their first names, last names, or countries in the same way (this is the order in which the user fields are examined--the first qualifying one is selected). The moderator can turn off notification entirely simply by ensuring that none of the four fields has the required string "verify" followed immediately by an underscore and a digit string. The "from" field in the email message (which normally indicates the sender's name) is set to the appropriate WebBoard user field that was used to determine the notification frequency. For example, if the moderator's login name is "RogS" with a first name of "Rog" and a last name of "S.", but a country of "Rog_Verify_100" (requests notifications about once a day), then the sender's name in the notification message will be "Rog_Verify_100". This reminds the moderator of their notification frequency. So when a moderator returns from vacation, s/he will immediately realize how often the notifications are being sent (and may wish to change them. The generated e-mail text also includes the moderator's login name and WebBoard user ID# (the IDENTITY field in the Users table). This helps to clarify any questions that may arise concerning which moderator was responsible for the generated e-mail message. Note that a particular message can only generate one notification for a moderator. * If there are multiple boards that require messages to be verified (in conferences that the moderator moderates), then as many as possible will be listed in the notification message. * There's no need to combine the "data crunching" and SMTP functions on the same server as WebBoard. As long as "data crunching" server can run OSQL.Exe (MS's command-line SQL interface), the notification system can be installed on this secondary server. * Only moderators get notifications. Virtual board managers and administrators don't. If a user in the latter categories desires notifications, s/he needs a separate user ID. This user ID must be set up as a moderator for all the relevant conferences. ======================================== 1. Configuration -- ASPTear and FormMail ======================================== a. ASPTear ---------- ASPTear.Zip is included with the install. ASPTear is a freeware interface to MS's Internet Transfer Control (ITC normally requires Visual Studio or Win2K to run). You can unzip that file and follow the instructions in the AspTear.HTM, or simply unzip ASPTear.Dll, move it into your windows/system or winnt/system32 folder, and register it by running this command from Start | Run: RegSvr32 ASPTear.DLL b. Formmail or Form2Mail ------------------------ If you want to install FormMail (Unix), you're on your own. You can get it from Matt's Script Archive. The configuration is essentially the same is it is for Form2Mail. Form2Mail (the version for MS OSs) is included in this system as Form2ML4.Zip. Just look for the section entitled "USER DEFINEABLE VARIABLES". You need only configure your e-mail server name, your server port, and the IPs that can access the CGI. ========================================== 2. Configuration -- The rest of the system ========================================== Create a new folder for the system. I recommend that you use a subfolder under the WebBoard directory. IF YOU PLAN TO RUN THE SYSTEM FROM STARTUP, DON'T INSTALL THE SYSTEM IN A FOLDER SUBSTRUCTURE THAT DOESN'T USE "8Dot3" NAMES. (Otherwise, you'll have a devil of a time finding the proper way to configure the folder name in MN_MAIN0.Bat.) Unzip the system into this new folder, and be sure to either copy in OSQL.Exe, or make it available via your DOS PATH (you could simply copy it into windows\command or winnt\system32). Now modify the 3 files that configure the operation of the system. Each file contains extensive modification instructions (comments are permitted): * MN_EURL.Cfg -- The URL to formmail or form2mail * MN_ESubj.Cfg -- The subject of the generated notification message * MN_ETxt.Cfg -- The text of the notification message ================================================ 3. Configuration -- Setting up the demon process ================================================ The system can be run in either of 2 ways: a. Running the system as a scheduled task ----------------------------------------- If so, then the executable which gets run is a DOS icon that calls MS_Main.Bat. You need to run it once from Start | Run in order to get the DOS window. At that point, right-click on the DOS icon and select "properties". Check the "close" on exit box. This will ensure that the DOS window always closes after the system runs. b. Running the system from the Startup folder --------------------------------------------- If you wish to do this, then MN_Main0.Bat must be executed instead. You'll have to directly configure the number of seconds between each run, and the lines which specify the drive and folder name. Look for the lines of asterisks in MN_Main0.Bat. ====================================================================== 4. Running the system for the first time (and running it in test mode) ====================================================================== a. Setting up the moderator, conference, and post ------------------------------------------------- Set up a test moderator ID and a test conference. Make sure that the conference requires "moderation" (or "verification of new posts," in WebBoard terms). Now do a post to the new conference from a WebBoard user that's *not* a moderator of the conference, or the manager of the virtual board, or a WebBoard administrator. Now login as the moderater. Do a post to that conference. You won't be able to "expand" it until you do. (This is a WebBoard bug, which has to do with what WB considers to be the # of "new" messages.) Now expand the conference. Does the original post have a red check mark next to it on the topics frame? If so, you're ready to test. What about the moderator? S/he won't get messages unless the login name, first/last name, or country is in the correct format. Remember the system expects to see "verify" (in upper, lower, or mixed-case) followed by an underscore, and a sequence of one or more digits. That can be part of the login name, the first name, the last name, or the country. b. Testing the parts of the system ---------------------------------- 1. First, verify that the SQL query is working properly. Set up a DOS prompt desktop icon that starts in the system's working directory. In W2K this may require that you open up Windows Explorer (not IE), right click on command.com, and choose "create shortcut". Once the shortcut is on your desktop, you can right-click on it, select "properties" and request that the program start in the right folder. To test the SQL query, simply type: MN_SQLEx You'll see a bunch of stuff happening, and you should see appropriate messages. At the end of the process, the file "MN_SQLEx.Dat" should have the fields that the system relies upon dumped out in "commas- n'-quotes" format. You should at least see one record there for the message that you posted previously. 2. Next, test the "comparison" part of the system. First, concatenate mn_cmp1.js and mn_cmp2.js with this DOS command (to be entered at the DOS prompt): Copy MN_Cmp1.js+MN_Cmp2.js MN_Cmp.js Then run this DOS command: CScript MN_Cmp.js //I //NoLogo >>MN_Log.Txt Take a look at MN_Log.Txt. You should see "EXECUTION SUCCESSFUL" at the very end. If you scroll up, you'll see the text of the generated e-mail message for this moderator. 3. Finally, see whether email messages can be sent. CScript MN_Eml.js //I //NoLogo >>MN_Log.Txt You should see "EXECUTION SUCCESSFUL" at the very end. Moreover, the email message to the moderator should've been generated. If not, you should see appropriate error messages. ================================================================ 5. Setting up multiple copies of the system for different boards ================================================================ Unfortunately, the system doesn't allow you to have a different MN_Txt.Cfg (text of email message) or MN_Subj.Cfg (subject of e-mail message) file for different virtual boards. This can make life difficult when different virtual boards are owned/rented/used by different firms, and each demands that the notification messages contain "branding." If your customers require this level of customization, you can specialize the query in MN_SQLEx.Qry, so that it only picks up the messages from a given board. Take the last line: (F.BoardID = B.BoardID) ) and replace it with something like this (for one board): (F.BoardID = B.BoardID) AND (B.BoardID = 12 ) ) or (for multiple boards): (F.BoardID = B.BoardID) AND ((B.BoardID = 12 ) OR (B.BoardID = 14 ) ) ) At that point, you have a copy of the system that's restricted to a given board or set of boards. Since the system doesn't have any registry entries or other "global" data, there won't be any conflict between the multiple copies. =============================================================== 6. Diagnosing errors, and overview of processing/internal files =============================================================== a. Errors are in MN_Log.Txt --------------------------- Errors are faithfully recorded in MN_Log.Txt. The system will never "stop" or "hang" unless SQL (MSDE) isn't started (in that case, it will wait, and print a message to the DOS window which indicates that a control-C can be used to stop the processing). See the earlier section on running the system in "test mode" for more information about how to test the parts of the system. b. Overview of processing and internal files -------------------------------------------- All data files for the system are ASC format, and can be opened with Windows Notepad, Wordpad, DOS EDIT, or any other editor. Be sure to avoid editing these files with an editor that puts a control-Z (DOS EOF) character at the end. There are really only 3 steps in the system: 1. MN_SQLEx.Bat's sole purpose in life is to create the file MN_SQLEx.Dat. This file contains one record for the cross product of each message that's potentially available for "moderation" (verification) and each moderator that might be able to verify it. 2. MN_Cmp.JS (which is the concatenation of MN_Cmp1.JS and MN_Cmp2.JS) simply reads this file and "compares" it against MN_Hist.Dat MN_Hist.Dat is the "moderator history". It contains one record for each moderator that has ever been notified in the system's lifetime. Each moderator is known by their WebBoard user ID#, and the system records the last run time of notification. For completeness, it also lists the moderator's login name, first/last names, and country. MN_Cmp.JS will write out MN_Hist.New (the next cycle's MN_Hist.Dat), and MN_Eml.Dat (the list of email notification requests). 3. MN_Eml.Dat is in turn read by MN_Eml.JS, which will process each email request by using ASPTear for a "POST" request to formail.pl (or form2mail.pl). That will actually send out the notification. *. If no errors have been detected, MN_Hist.New will replace MN_Hist.Dat. That ensures that a moderator will never be notified twice for the same post (or set of posts). If you're interested in the temporary and other files used by the system, take a look at Step 1 of MN_Main.Bat. ========================== 7. Clock skew errors, etc. ========================== For a particular moderator who's requested notification, the algorithm for determining notifications breaks into only two cases. Suppose the "demon" runs every hour, and the moderator got a notification on the last run. If the moderator's requested notifications every two hours, then the system will look for messages with a time later than two hours plus the last run time. But that's not going to happen ordinarily ... since the last run time was only an hour ago! If so, you'll see a message in the log file underneath the moderator's name that says: "(In this case, the moderator was last notified so recently, that this run won't pick up any notifications unless the system clock has been moved in an unexpected way.)" Alternatively, suppose the moderator's asked for notifications every 15 minutes. In that case, you'll see a message in the log file that says: "(In this case, the moderator was last notified so long ago that any new messages posted since then qualify.)" However, in both cases, the system will check the actual time of posted messages. Note that in the first case, it's theoretically possible to see a notification, *iff* the time on the posted message is actually greater than the current run time. That could occur if the system clock was set back after the most recent message was posted. It could also occur if there are two servers involved, and the system time on the "data crunching" server is earlier than the system time on the server that's running SQL. ================ 8. Reusable code ================ If you're a programmer, you might want to use MN_Eml.js for other applications. There's an extensive comment block at the beginning which explains how it can be used as a general HTML "grabber" to extra pages from the web, or to submit POST requests. MN_Cmp1.js contains a number of objects for imposing "record" structure on "ASC files" which can be read and written by WSH (Windows Scripting Host) JS files. ======================= 9. Author contact info. ======================= Raj Seshu 122 S. 9th St. Lafayette IN USA flagger14@hotmail.com (also on MSN) ICQ#15600913 (765) 742-6705 (765) 423-1896 (voice mail) (765) 417-0664 (bEEper) ========================= 10. Version history info. ========================= This is version 1.0, released April 7 '01