BioMail Version 0.71 WARNING: In versions from 0.62 and higher a new Mailing module is used to make BioMail more compatible with Debian GNU/Linux and MS Windows. You will need to install Net::SMTP module from libnet package instead of Mail::Mailer (required for previous versions). LICENSE Copyright (C) 2000-2003 Dmitry Mozzherin This program 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 (License_GPL.txt); if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. DESCRIPTION BioMail is a web-based application for medical researchers and biologists. It is written to automate searching for recent scientific papers in the PubMed database. It regularly e-mails references for articles that have recently appeared in the PubMed/MEDLINE databases according to the search patterns chosen by the user. You can use BioMail without installing it on your computer. It is running at www.biomail.org INVENTORY The package consists of the following files. users.pl -- web-based GUI for creating, modifying, and deleting accounts from the BioMail database BioMail.pm -- a module, which contains GUI subroutines for users.pl biomail.conf -- the default configuration file biomail.pl -- a stand-alone mailing program. It can be used without the web-based interface, if you make the biomail database by hand (It requires the classes dbflat.pm, Mails.pm, and pubwww.pm). biomail-admin -- a script which searches the password database for a user's password, dumps all users and their emails to a text file, gets quantity of users. biomail-dbdump -- dumps all information from biomail databases to an xml file biomail-dbrestore -- uses the xml file produced by biomail-dbdump to restore biomail database on the same or different computer. biomail-mailall -- allows to send an arbitrary mail to all users of a BioMail site. INSTALL.UNIX -- instructions how to install BioMail on Linux/Unix INSTALL.NT -- instructions how to install BioMail on MS Windows NT or 2000 INSTALL-Virtual_Host -- instructions how to install BioMail without root access README -- the file you are reading now License_GPL.txt -- text of the GPL license BioMail/dbm.pm -- a class, which handles calls to BioMail's databases BioMail/dbrefs.pm -- a class which handles calls to Reference treasury database BioMail/EventReporter -- a module which is used to show/email reports about different events BioMail/locale -- a module with locale-specific functions BioMail/Mails.pm -- a class, which handles all mailing functions BioMail/pubwww.pm -- a class, which handles all connections to PubMed BioMail/conf.pm -- a module for parsing settings from biomail.conf BioMail/Vars.pm -- contains global BioMail variables html/biomail.css -- (optional) cascading style sheets for changing the style of the BioMail page to fit your needs. html/head -- (optional) an html template which may contain your banners, logos, etc... html/tail -- (optional) the second part of the html template, which is added after the BioMail application, but before the disclaimer. This file may also contain your web-design. lang/en -- this file contains all text which appears in web-based user interface and in BioMail letters. It can be translated to other languages lang/ru_koi8 - Russian translation of lang/en in koi8-r coding lang/ru_win - Russian translation of lang/en in MS windows coding lang/es -- Spanish translation of lang/en lang/fr -- French translation of lang/en lang/it -- Italian translation of lang/en lang/tr -- Turkish tranlsation of lang/en man/biomail-admin.1 a manual page for biomail-admin man/biomail.pl.1 a manual page for biomail.pl REQUIREMENTS BioMail requires two perl modules from CPAN: LWP::Simple and Net::SMTP which comes with libnet. To install them on your system type (as root): perl -MCPAN -e 'install LWP::Simple' and follow instructions. Then perl -MCPAN -e 'install Bundle::libnet' It also requires an http server for the web-based interface (I use Apache), and SMTP server (local or remote) for sending e-mails. INSTALLATION 1.Uncompress and untar BioMail tar.gz file: tar zxvf biomail-0_71.tar.gz 2. To install biomail: go to the BioMail distribution directory and edit install.conf 3. Type 'make install' 4. Edit biomail.conf (IMPORTANT) biomail.conf is located by default in /usr/local/etc/biomail/ directory under UNIX and C:\biomail\conf\ under MS Windows NT/2000. It contains important settings, like webadmin email address, URL of the local BioMail site, proxy information (if needed), maximum amount of searches, etc... To uninstall biomail type 'make uninstall' Read more about installation in INSTALL file. If you want to install BioMail on virtual server without root access read INSTALL-Virtual_Host USAGE The web-based part of the program is located by default at: http://your.host.name/cgi-bin/biomail/users.pl BioMail will create 'users' and 'biomaildb' files automatically. Also it will convert databases from old versions of BioMail to the new standard. It will try to guess the e-mail address of the webmaster and the URL of the site for users.pl. biomail.pl is a mailing script: biomail.pl [options] -h help message -q quiet (minimal output) -s silent (no output) -t program reacts as if it is the time for the weekly searches (for debugging) -l keeps log of served users in /tmp/biousers.txt file -u starts searches AFTER the entered user name, for example: 'biomail.db -u derby' (will start from the user next after the user 'derby' ) -r stops searches BEFORE the entered user name example: 'biomail.db -r pcrgod' (will end on user sorted by alphabet right before the 'pcrgod' user). Note: you can enter a non-existed user without problems for both -u and -r options. It will use the path to databases determined in the $DBPATH variable in the dbflat.pm module.If you want another path, change the value of the variable. Launching biomail.pl by itself does not make much sense. The program will perform Medline searches only on every Tuesday, Friday, 1st day, and 15th day of the month. You have to use cron to launch biomail.pl automatically every day. To launch it automatically add a line like this to the /etc/crontab: 30 2 * * * root /usr/local/bin/biomail.pl -q Now biomail.pl will start every day at 2:30am, and will connect to Medline on the appropriate dates. Note: For many distributions you should enter the full path to biomail.pl, if you launch it as root. (Check your cron: you may have to remove 'root' from the line) If you want to use it from a computer without a permanent connection to the Internet, you have to set cron to launch a script, which will start an Internet connection first, and then start biomail.pl Administrator scripts: biomail-admin -- Finds a password of a user, writes users and their emails into a file, keeps a file with quantity of users. Use 'biomail-admin -h' for help biomail-mailall -- Allows to send a message to all biomail users. Use 'biomail-mailall -h' for help biomail-dbdump, Are useful for moving your database from one computer to biomail-dbrestore another, make a backup of your databases. biomail-dbdump saves all information from databases to an XML file. biomail-dbrestore uses this XML file to populate biomail databases. Use -h option for both programs to learn how to use them HTML 'SKINS' Styles for links, headers, some tables, etc... can be modified by changing the biomail.css file in /usr/local/biomail/html/. If this file is absent, BioMail uses default settings. Not everything can be changed yet (for example if you change the background of the body to anything except white, the BioMail pages will be ugly). However, it will be totally customizable eventually. Your can wrap BioMail into your own web design by using 'head' and 'tail' html templates. The 'head' file will be located on the page right before the BioMail application, the 'tail' will be located after the main part of BioMail, but before the legal information and disclaimers, which are at the very end of the Biomail web page. The 'head' and 'tail' files are in plain html language. A very simple example of each is supplied with distribution (/usr/local/biomail/html). If you don't want any additional design, just remove (or don't install) the whole /usr/local/biomail/html directory. --------------------------------- TROUBLESHOOTING 1. On May 23rd, 2003, Pubmed developers modified HTML representation of their site. As a result BioMail versions 0.70 and earlier stopped working. To continue using BioMail you have to install version 0.71 or later. 2. New versions of Perl don't have NDBM_File.pm module and as a result perl generates an annoying, but harmless warning message in error log, or on the top of the web page: "Can't locate NDBM_File.pm in @INC (@INC contains:..." To fix this problem uncomment the line #BEGIN { @AnyDBM_File::ISA = qw(DB_File GDBM_File SDBM_File NDBM_File ODBM_File) } at the beginning of the dbm.pm file located in the BioMail directory. 3. If you use BioMail version 0.50 or higher, DON'T USE biomail-scrub from older versions of BioMail! biomail-scrub was written to cope with empty accounts in older versions. Versions of BioMail 0.5 and higher do not need this script, because they do not create empty accounts. biomail-scrub, if used with the biomaildb file from BioMail 0.50 or higher will not understand the new database format and WILL DESTROY SEARCH PATTERNS FROM biomaildb. Go to your /etc/crontab file and delete the line which schedules the launch of biomail-scrub. 4. Database format for versions > 0.50pre1 is slightly incompatible with versions 0.44 and older. When you start the web-based interface and it finds an old biomaildb database it converts it to the compatible format ('KEYS' change to 'SEARCH') and will ask to start the users.pl again. 5. If you moved BioMail to a new computer and found that your databases cannot be recognized by Perl anymore return back to your older BioMail site, install there BioMail 0.71 or later and use biomail-dbdump script to save data from your database to an xml file. Move this xml file to your new machine, install BioMail 0.71 or later, initialize databases by opening your BioMail site with a browser, use biomail-dbrestore to move data to new databases. AUTHORS Dmitry Mozzherin (dim@pharm.sunysb.edu) - coding, documentation Holly Miller (miller@pharm.sunysb.edu) - editor, documentation Alfonso Ali Herrera (alfonso.ali@cigb.edu.cu) - coding ACKNOWLEDGEMENTS Many, many thanks to everyone who sent great supportive letters, comments, bug reports and criticisms! Thanks to PubMed for their Medline service, and to SourceForge and VA Linux Systems for hosting BioMail's homepage. _______________________________________________________________________________ Changelog: 0_71 Search engine uses EUtilites API (PubMed webservice) instead 22/09/03 of webparsing of the PubMed website. Database locking is fixed. Databases dump/resore functionality. Ability to send email to all registered users. Dump of all users and their emails to a text file. New translations: French, Italian, Spanish, Turkish. Searches can be accessed through the PubMed website as well. 0_70 A major release. Multilanguage support is added, searches with 12/03/01 MeSH-terms are now possible. There is a new 'HTML in attachment' format which allows to use the full functionality of BioMail with any email client. Users now can receive all their searches from one day in one email letter. This version includes the Russian translation of the BioMail. 0_63 Mostly bug fixes. A feature to temporaly suspend user's account 10/17/01 Is added. More information in online FAQ. 0_62 Searches are not redundant anymore. Now search pattern will return 03/14/01 only unique references. BioMail is now compatible with MS Windows NT/2000. Mail is now handled by Net::SMTP module instead of Mail::Mailer. The plain text database biomaildb was substituted by dbm database bioml.db. This hopefully will also remove a locking problem which sometimes crashed BioMail's web interface under heavy loads. Many configuration variables are located in biomail.conf file now. Common variables are moved to module Vars.pm, configuration file is parsed by module conf.pm, redundancy prevention is handled by conf.db database. 0_61 Output with abstracts is added. Bug fixes. Compatibility problems 08/03/00 with Sun Solaris are solved. New options for biomail.pl 0_60 Reference treasury was added. Now references can be stored in the 06/18/00 user's account. Many changes in GUI. Minor security problem was fixed. Minor problems, which generated warning messages in code were fixed. 0_52 Installation script was added. Bug fixes, urls for each reference 04/18/00 were added for the text-formatted e-mails. Option to stop getting empty e-mails was added. 0_51 Deals with changes at Pubmed page, which rendered all previous 03/23/00 versions of BioMail nonfunctional. See 'troubleshooting' in this document to learn how to fix the problem in previous versions manually. A new output format (comma separated values, or CSV) was added. This format is useful for import into various databases and spreadsheets. 'Skins' were added which allow BioMail to be wrapped into a custom web-design. It is now possible to change text styles by editing a provided cascading style sheet file. Also many small changes were made to the GUI. 0_50 (stable version). All tcp interactions with PubMed are moved 03/12/00 to a new class -- BioMail::pubwww. Bug fixes, cosmetic changes, a disclamer from NCBI is added, a simple checking of e-mail address format is added. Pod documentation for BioMail::Mails 0_50pre2 (development version). Bug fixes, small improvements in GUI, 02/22/00 Documentation for dbflat.pm 0_50pre1 (development version). Major rewrite with a lot of changes. 02/14/00 More object-oriented. All database handling was moved to the dbflat.pm class. This will make future development of interfaces with other types of databases (like SQL) much easier. biomail.pl now shares modules with users.pl. Changes in GUI include the ability to change the quantity of searches (now between 1 and 10), and to change the maximum quantity of references (now 20 to 400). A text area for the user to write a note to the authors was added. Changes for administration: there are no longer empty accounts, an account can be saved only if it has something in one of the search fields. v.0_44 Several insecure lines have been fixed. Now databases use locks 02/01/00 to prevent simultaneous writing access by several users. biomail-admin does not send emails with forgotten passwords anymore (this function has been moved to the www-interface). A new tool was added (biomail-scrub) to handle empty entries in the database. OPTIMIZATION text was added to the README file. v.0_43 Changes in GUI: 'Forget password' button was added, 'Change password' 01/20/00 button was added, 'Submit' and 'Delete' buttons were moved closer to the start of the configuration page, Test buttons now also work as submit buttons (I found that many people use them and think that they have finished configuration, so I decided to go with the flow). v.0_42 First public release 01/17/00