Latin American Researcher Registry ===================================== Version 0.11 Copyright (C) 2002 Ted Pedersen, tpederse@d.umn.edu Brian Rassier, rass0028@d.umn.edu University of Minnesota, Duluth 1. Introduction: ---------------- The Latin American Researcher Registry package is a package of cgi scripts which work together to form a registry. The registry is designed for users to input their contact information, as well as research information. Users can then search the registry to look for people with similar research interests in certain areas of the world. This README continues with brief notes about the Latin American Registry package, and how a user would typically use this site. There are also notes on how a site administrator can maintain the registry. 2. Setup: --------- -The first step in setting the registry up on a site is to download it into a www directory. If the package is not in a www directory, it can not be viewed on the Internet. If the package was not downloaded into a www directory, it should be moved to one before setup continues. -Set the permissions of driver.csh. To set up these permissions simply type: chmod 755 driver.csh This will allow the driver to be executable. -Run driver.csh. For best results, use the bash shell. To get into the bash shell simply type the command: bash Then, to run this script type the command: ./driver.csh This script will set up all the permissions for the scripts and directories that were included in the registry package. If the permissions are set correctly, the message "Permissions Set Up" will appear after running driver.csh. -Run setup.pl. To run setup.pl simply type the command: perl setup.pl This script will change the email options in the registry. It will prompt users to enter an email address. This address will be used to send registry related messages to. If the email address was changed successfully, the message "email address changed in code" will be displayed. NOTE: In the event that setup.pl does not run, check the first line of the program. This line tells where the perl libraries are, and may be different on different machines. Change this line to fit your directory scheme. If problems still result, try visiting www.perl.org or www.cpan.org for more assistance. -The final step is setting up password protection for the approval script. The registry allows a maintainer to approve or reject additions/updates to the registry. This is a web-based approval/rejection system, and only the maintainer should have access to this option. In order to restrict access, password protection must be set up. There are three steps to setting up password protection. A.) Setting up a .htaccess file: Change directories to the "secure" directory. Next, create a new file named .htaccess in the secure directory. To create this new file, simply type: emacs .htaccess In the .htaccess file copy the following information: AuthUserFile *****/secure/.htpasswd AuthGroupFile /dev/null AuthName "Authorized Users Only" AuthType Basic require valid-user Where there are 5 asterisks in this information, enter the location of the "secure" directory. This is different for each user, depending on where the registry package was downloaded. Save this file and exit. B.) Setting up a .htpasswd file: The htpasswd utility is needed to set up the .htpasswd file. This utility is included with most servers, and is usually in the support directory. If the registry is being set up on UMD's server, the utility is located at /usr/apache/bin/htpasswd. To enter a user in the password file, enter the following: htpasswd -c *****/secure/.htpasswd username1 [you are then prompted for the password for usrname1] htpasswd *****/secure/.htpasswd username2 ... The -c option is only necessary for the first username. The option creates the new .htpasswd file. Where there are five asterisks in the commands above, type the location of the "secure" directory. This is the same directory path used in the .htaccess file for step 4a. NOTE: Only add usernames and passwords for those people that are to have access to the approve/reject portion of the web site. This will typically only be the registry maintainer. C.) Change the permissions of .htaccess & .htpasswd: The permissions for .htaccess and .htpasswd must be set up so that people who are not supposed to view the files cannot view them. It is also necessary to set them up so casual Internet surfers cannot view them if they type the address of the files into the browser. This would defeat the purpose of password protecting the site. To set up these permissions correctly type the commands: chmod 644 .htaccess chmod 644 .htpasswd *NOTE* Once the registry is set up, the content of automated emails should be changed. The registry sends automated emails when an entry is approved (additions and updates). This email should include a link to the user's entry that was just approved. This will allow users to simply click this link in the automated email to check their entry for accuracy. This link is not something that can be hard-coded because the link will change, depending on where the registry resides. This is something that the maintainer must change. It must be changed in two places within approve.cgi, which is inside the secure directory. These places are documented, and an example link is available for help. Another thing that the maintainer may want to change is the content of the introduction remarks on the root page of the registry. This must be done within registry.cgi, and the area to change is documented. 3. Registry Use: ---------------- A.) Joining the registry: From the main page of the registry press the "Join the Registry" button. This will display an informational form page. Users should enter all relevant information here. The only optional fields are: -address line 2 -personal homepage -departmental/group homepage -alternate email address All fields must be entered besides these four. The form may be cleared by pressing the "Clear Form" button at the bottom of the page. Users can go back to the main page of the registry by pressing the "back" link at the bottom of the page. When all fields are filled out press the "Submit Form" button. The program will then check the fields to see if all required fields were filled out. The program will also check the syntax of email addresses and web pages. Users will be prompted to change information if anything was entered incorrectly. If a status of "Student" or "Other" is given, users will be asked for additional information relating to these statuses. Once all fields are filled out and additional information is added, a confirmation page is displayed. Users should double check the information and press the "Submit Entry" button if everything is correct. This will send the entry for approval, and will add it to the registry if approved. If the information is not correct and only a small number of corrections are needed, press the "Make Corrections" button. This will bring users back to the form with the fields already filled out. Make the corrections necessary, and submit it again. If many corrections are needed, press the "Start Over" button from the confirmation page. This will start users with a clear form to be filled out. B.) Searching the registry: From the main page of the registry press the "Search/Update" button. A page will be displayed with three fields, which are for different searching options. The first field is empty, and is a keyword search. Any word can be entered here, and the registry will be searched for this word. Results will be displayed below the search fields. The next field is for country of residence. It is a drop-down menu with the countries of residence of all entries in the registry. Select the country of interest, and press the "Submit Search" button. The results will be shown below the search fields. The final field is for country of origin. It is identical to the country of residence option, except it displays the relevant countries of origin. There is an option of browsing by last name on the search page. There are letters below the search fields, which symbolize the last names of the entries in the registry. Select a letter, and the entries whose last names start with that letter will be displayed. When matching entries appear from a search, only a short version of their entry is displayed. If the entries have a personal web page, then the name in the short entry is a hyperlink to that page. There are two options with this short entry. One is to view the entire entry. If this option is chosen, users will be sent to a new page with this full entry only. The other option is to update the entry. This should only be done by the person who originally entered this entry. Updates to entries will be discussed in detail later in the README. C.) Browsing the registry: Press the "Browse Registry" button from the main registry page. This displays a page with the same browse by last name links as the search page. The last name links have the same functionality explained above, and allow users to narrow how they browse the registry. There is also a listing of the whole registry here. All short versions of the entries are displayed in alphabetical order. This way users can browse through the entire registry quickly. There is also a link at the bottom of all the entries that users can press to go back to the main page of the registry. The short versions of the entries are the same as the search page. They have the "Full Entry" and "Update Entry" options, and the name is a hyperlink to a personal web page if applicable. D.) Updating an entry: To update an entry, go to the search or browse pages. Then look for the entry that is to be updated. When the short version appears, choose either the "Update Entry" option or the "Full Entry" option. If the "Full Entry" option is chosen, there is an "Update Entry" option at the bottom of the full entry. Both options will bring users to the same page. The update page will have the same informational form as entering a new entry. The fields will have all previously entered information. Change the necessary information. If mistakes are made, press the "Start Over" option. This will re-populate the fields with the old information. If this is not where users want to be, there is a "Back Home" link at the bottom. This will bring users back to the main registry page without updating any entries. Once updates are made, press the "Submit Update" button. Fields will be checked similar to when a new entry is added. If the status is "student" or "other", users will be given a chance to change the information from the old entry. Once data checking is complete, users will be asked to confirm the information. Make corrections if necessary by pressing the "Make Corrections" button from the confirmation page. Otherwise press the "Submit Update" button. The update will be applied to the registry upon approval. If multiple updates are added to the registry for the same user, different results may occur. If all updates are approved, the most recent update will be how the entry appears in the registry. If old updates are approved and the more recent are rejected, then the most recent approved update will be how the entry appears in the registry. E.) Sending Comments: Press the "Send Us Your Comments" button. A page will be displayed with name, email address, and comments fields. The name and email address are optional. Enter name and email if desired, then enter the comments that are to be sent to the site maintainer. These comments will be sent via email. The comments feature is designed to give the maintainer feedback and improvement information about the registry. 4. Site Maintenance: -------------------- A.) Directory structure: There are six directories that are used for registry entries and updates. They are pendingadd, pendingupdate, approvedadd, approvedupdate, rejectedadd, and rejectedupdate. In each of these directories is a text file with the name of their respective directory (e.g. pendingadd.txt within pendingadd). There is another file named registry.txt within the approvedadd directory. This file contains the most current version of the registry. There are also transaction files within these six directories, which will be explained in section C. B.) Transaction format: There are two types of transactions. One is an addition, and the other is an update. An addition signifies a new entry being added into the registry. The transaction itself has the following format: Professor|Doe|John|U of M|CS|123 Main St||St. Paul|MN|55812|United States|www.umn.edu/jdoe||jdoe@umn.edu||Artificial Intelligence|United States|15:20:8,9-28-2002|umn1-2.umn.edu-122.122.122.12 This shows every field from an entry, deliminated by a "|" or pipe symbol. This entry would be for Professor John Doe, who added his information on 9-28-02. This information is what will be in a transaction file, as well as the entries in pendingadd.txt, approvedadd.txt, and rejectedadd.txt. The other type of transaction is an update. This signifies an existing entry being updated, and has the following format: Professor|Doe|John|U of M|CS|123 Main St||St. Paul|MN|55812|United States|www.umn.edu/jdoe||jdoe@umn.edu||Artificial Intelligence|United States|15:20:8,9-28-2002|umn1-2.umn.edu-122.122.122.12 Professor|Doe|John|U of M|CS|321 Main St||St. Paul|MN|55812|United States|www.umn.edu/jdoe||jdoe@umn.edu||Artificial Intelligence|United States|15:20:8,9-28-2002|umn1-2.umn.edu-122.122.122.12 This entry is very similar to the addition shown earlier. It is actually two transactions. The first is the original entry. The second is the updated version of the original entry. The only difference between the example is the address (123 Main St changed to 321 Main St). The original information is needed so a decision can be made about whether to approve or reject the update. This information is what will be in an update transaction file, as well as entries in pendinupdate.txt, approvedupdate.txt and rejectedupdate.txt. C.) Transaction trail: Every time a user enters an update or addition to the registry a transaction file is made. The transaction file is named based on the member number that the user is assigned, and the time/date of the update/addition. For example "12-12:11:46,10-5-2002.txt" is a transaction file for member number 12, for the change to the registry at 12:11:46 on October 5, 2002. A transaction file starts out in the pendingupdate or pendingadd directory, depending on its type. An addition is made to pendingupdate.txt or pendingadd.txt respectively. The addition is recording the update/addition information, simply to make a paper trail. This records every transaction that occurs, and records them in pendingupdate.txt and pendingadd.txt. If an addition is approved, the transaction file is moved from pendingadd to the approvedadd directory. An entry in approvedadd.txt is made showing that this transaction has been approved. In pendingadd.txt, the transaction is marked with a "A:", symbolizing its approval. The addition is also made in registry.txt which actually adds the entry to the main registry. If an addition is rejected, the transaction file is moved from pendingadd to the rejectedadd directory. An entry in rejectedadd.txt is made showing that this transaction has been rejected. In pendingadd.txt, the transaction is marked with a "R:", symbolizing its rejection. If an update is approved, the transaction file is moved from pendingupdate to the approvedupdate directory. An entry in approvedupdate.txt is made showing that this transaction has been approved. In pendingupdate.txt the transaction is marked with a "A:", symbolizing its approval. The update is also made within registry.txt, which changes the old version of the entry to the updated version. If an update is rejected, the transaction file is moved from pendingupdate to the rejectedupdate directory. An entry is made in rejectedupdate.txt showing that this transaction has been rejected. In pendingupdate.txt the transaction is marked with a "R:", symbolizing its rejection. This directory and transaction structure creates a large trail of all transactions. This process helps to locate any errors, and helps maintain the structure of the registry. D.) approve.cgi use: D1) Location of approve.cgi Within the "secure" directory is a script named approve.cgi. This script is a web-based approval site, and is the one that should be set up with password protection. If the setup section was done correctly, the site should already be password protected. When the site is entered in a browser, users will be prompted to enter a username and password. Enter that information, and start approving and rejecting registry transactions. D2) View all functionality From the main approval page there are two view all options, "View All Additions" and "View All Updates". If these are pressed a list of all additions/updates will be displayed. This is used to help the maintainer. It allows the maintainer to see how much work needs to be done in order to completely update the registry. The views of the additions are simply showing all the information for the new entries. The views for the updates show all the information, but also highlight any information that was changed from the original entry to the update. This will help the maintainer decide if the update should be allowed or not. D3) Approve/Reject functionality The main purpose of the approval site is with the "Approve Additions" and "Approve Updates" options. Both give the maintainer the ability to approve or reject additions/updates in the same manner. Choose one of the options, and the first addition or update will appear. If the addition/update looks good to add to the registry, simply press the "Approve" button. This will make the necessary changes to the registry, and move on to the next addition or update. If the addition or update should not be added to the registry, press the "Reject" button. This will bring up a new screen. Once the "Reject" button is pressed, the addition/update is already rejected. DO NOT press the browser's back button to try to undo the rejection. From the rejection screen the maintainer has the option of rejecting with or without sending the owner of the entry a message. The email address of the owner of the entry is given on this page. If the address does not look real, reject without a message. If there was some problem with the addition/update, simply type the comments in the message field. Press the "Send Message" button, and the message will be sent to the owner of the entry. The maintainer's email address will be in the "reply-to" area of the email. These additions and rejections can be done continuously until all the additions/updates are taken care of. This interface makes upkeep of the site convenient and quick for the maintainer. 5. Problems/Future Enhancements: -------------------------------- 6. Copying: ----------- This program package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Note: The text of the GNU General Public License is provided in the file GPL.txt that you should have received with this distribution.