[[PageOutline]]
= Recruiting and retaining volunteers =

The following is a list of suggestions for getting more people to participate in your project. Much of this is based on [http://boinc.berkeley.edu/poll_results.php the results of the BOINC user survey]; study this yourself.

Most of these suggestions involve writing prose to be read by the general public. If (like many scientists) you are not good at this or avoid doing it, find someone who is good at it. This could be one of your students, a friend of a friend, or a professional writer.

English is the most widely-spoken language among BOINC participants, and you should probably use it as the main language for web materials and email. BOINC provides mechanisms for [TranslateIntro Web site translation]; it's generally easy to get volunteers to do this.

== Project web site ==
Your project's web site has a large role in attracting participants. Some suggestions:

    * Present your project's credentials: the educational credentials of its leaders, its research track record, and the status of its institution.
    * Describe what your project is doing: its high-level scientific goals, its methods, the details of the computation being done using volunteers, and the (non-distributed) computations that precede and follow this. How will your research affect the lives of everyday people now and/or 50 years from now?
    * Who owns the intellectual property that arises from volunteer computations? Will it be released to the public? When, and under what terms?
    * Show all the scientific results of the computation so far, and any publications that arise from these results. ([http://depts.washington.edu/~bakerpg/publications.html Rosetta@home] and [http://folding.stanford.edu/papers.html Folding@home] provide good examples of this). Announce new results and publications on the News column. Make sure your News column is being properly published as an RSS feed.
    * Give some personal information about your team members: their names, background, interests, and preferably a photograph. This will 'humanize' your project in the eyes of potential participants.
    * Take an active role in your web site's message boards. Read them frequently, and respond quickly to any negative threads that arise. Make a periodic posting giving 'insider info' on your project.
    * Make sure your the web site has clear navigation, so that the above information is easy to find from the front page. Do a user study - show your web site to a strangers, ask them to browse it and/or to find particular information, and get their feedback (you may be surprised).
    * If possible, create a graphical identity (logo, color scheme, etc.) for your project. Your web site should project professionalism and inspire confidence and interest in prospective volunteers. 

== Publicity ==
The world will not beat a path to your door. You need to work hard to spread the word about your project.

    * Get in the mass media (newspapers, magazines, radio, television) as much as possible. If your institution has a PR director or media spokesperson, contact them while you're developing your project, and again any time your project has major news. If no such person is available, call local media outlets yourself.
    * Exploit existing organizational relationships. If you work at a University, try to get your project running on the PCs in the teaching labs, and on the PCs of students, faculty and staff. If you have connections with organizations with PR capabilities (i.e., web sites or newsletters), enlist their support for your project, and get them to publicize it. A typical example: professional organization in your subject area.
    * The BOINC web site will generally announce new projects. Also, make sure your project is listed on [AccountManagers account managers] like !GridRepublic and BAM!
    * Use the web. Announce your project in forums like Slashdot, and on the message boards of the major cross-project teams like BOINC Synergy, Overclockers UK, Team Anandtech, etc. 

== Email-based mechanisms ==

BOINC provides PHP-based tools for sending three types of email to participants:

    * ''Newsletters''. These are periodic (perhaps every few months) and are sent to all participants. Typically you would use them to summarize your project's results, to discuss its future plans, to make announcements, etc.
    * ''Reminders''. These are sent to participants who seem to have stopped computing to your project, or who signed up but never got any credit. Typically they would be short messages, encouraging the participant to take a specific action.
    * ''Friend-to-friend''. These are sent by participants to their friends and family, to tell them about your project and urge them to join. The sender can add an optional message. 

Effective use of all types of email is critical to maintaining and growing your participant base. In the absence of any email, participation typically decreases by a few percent every month. BOINC supplies the framework, but you must write the actual emails, or modify BOINC's samples as needed for your project.

The newsletter and reminder scripts provide the following features:

    * They let you send different emails to different 'classes' of participants. For example, you can send a different newsletter to participants who haven't computed for your project in a while.
    * They let you personalize emails, e.g. by inserting the participant's name or their total credit.
    * They provide a mechanism for inserting a secure 'opt-out' link. Note: You should ALWAYS include an 'opt-out' link at the bottom of emails (both HTML and text). It may be illegal for you to do a mass email without one. Make sure you test this link.

The scripts requires that you use [http://phpmailer.sourceforge.net/ PHPMailer], a PHP function for sending mail that is more full-featured than the one built into PHP. Download it, put it in `html/inc`, and set the `USE_PHPMAILER`, `PHPMAILER_HOST`, and `PHPMAILER_MAILER` variables in [WebConfig your project.inc file].

All of the tools let you send multipart HTML/text messages. We recommend that you use this feature - and HTML message can include your logo and/or institutional insignia, can include hyperlinks, and can look more attractive.

The general procedure for using each scripts is:

    * Create a directory (mass_email, reminder_email, or ffmail) in your `html/ops/` directory. In that directory, create separate files for the text body template, HTML body template, and subject line to be sent to each class of participants. NOTE: the HTML files are optional; if you leave them out, text-only emails will be sent.
    * Run the script in testing mode (see below) to ensure that the emails are as you intend.
    * Once testing is complete, run the script in production mode. Typically, the newsletter script is run from the command line. The reminder script is typically run as a [ProjectTasks periodic task], every 24 hours or so.

The newsletter and reminder scripts use the recent-average credit (expavg_credit) field in the user table. To make sure this value is accurate, run [ProjectTasks update_stats] manually if you're not running it as a periodic task.

=== Personalizing emails ===

The newsletter and reminder scripts replace the following macros in your email bodies (both HTML and text):

 `<name/>`:: 		User name
 `<create_time/>`:: 	When account was created (D M Y)
 `<total_credit/>`:: 	User's total credit
 `<opt_out_url/>`:: 	URL for opting out (this URL includes a salted version of the participant's account key, and so is different for every participant).
 `<lapsed_interval/>`:: The number of days since user's client contacted server (defined only for lapsed users, see below).
 `<user_id/>`:: 	The user ID (use this to form URLs)

=== Avoiding spam filtering ===

Your email is less likely to be rejected by spam filters if:

    * Your HTML and text versions have the same text.
    * Your HTML version either contains no images, or has at least 400 words.

== Newsletters ==

The script [source:boinc/html/ops/mass_email_script.php html/ops/mass_email_script.php] is for sending email newsletters.
Run it from the command line.
The optional arguments are:
 --userid N:: send only to the user with the given ID
 --send:: actually send the email (this is an option to reduce the chance of accidents).
 --show_email:: show what would be sent rather than sending it
 --explain:: print a line describing each email
 --idfile name:: read user IDs from the given file (one per line, increasing order).
 --nocurrent:: don't sent emails to "current" users.
 --batch N:: limits size of database query.

The script categorizes participants as follows:

    * ''Failed'': zero total credit. These people failed to download and install the client software, or failed to get it working (e.g. because of proxy problems) or uninstalled it before finishing any work.  Email to them should include a link to the BOINC help page (http://boinc.berkeley.edu/help.php) or other help resources.
    * ''Lapsed'': nonzero credit, but their computers have not contacted your server in > 60 days. 
    * ''Current'': These are your active participants.

To use the script, create the following files in html/ops/mass_email:

 `failed_html`:: HTML message sent to failed users. Example:
{{{
<html>
<body bgcolor="ffffcc">
Dear <name/>:
<p>
Test Project continues to do pioneering computational research
in the field of Submandibular Morphology.
In recent months we have discovered over 17 new varieties of Frombats.
</p>
<p>
Our records show that you created a Test Project account
on <create_time/> but that your computer hasn't completed any work.
If you had problems installing or using the software,
you can get help from <a href="http://boinc.berkeley.edu/help.php">online volunteers</a>.
Please try again!
</p>
<p>
<small>
To not receive future emails from Test Project,
<a href="<opt_out_url/>">click here</a>.
</small>
</p>
</body>
</html>
}}}
 `failed_text`:: Text message sent to failed users. Example:
{{{
Dear <name/>:

Test Project continues to do pioneering computational research
in the field of Submandibular Morphology.
In recent months we have discovered over 17 new varieties of Frombats.

Our records show that you created a Test Project account
on <create_time/> but that your computer hasn't completed any work.
If you had problems installing or using the software,
go here to get help from online volunteers:
http://boinc.berkeley.edu/help.php
Please try again!

To not receive future emails from Test Project, visit
<opt_out_url/>
}}}
 `email_failed_subject`:: 	Subject line sent to failed users. Example: 'Test Project News'.
 `lapsed_html`:: 	HTML message sent to lapsed users
 `lapsed_text`:: 	Text message sent to lapsed users
 `lapsed_subject`:: 	Subject line sent to lapsed users
 `current_html`:: 	HTML message sent to current users
 `current_text`:: 	Text message sent to current users
 `current_subject`:: 	Subject line sent to current users

=== Testing ===

It's important to send the right email to the right people,
and to do it only once.
We recommend testing as follows.
First send to yourself (say, user ID 5).
{{{
mass_email_script.php --userid 5 --show_email
}}}
It will print (to stdout) the contents of all three email types (failed, lapsed, and current). Verify that the subject, HTML and text are correct.

Then run
{{{
mass_email_script.php --userid 5 --send
}}}
You'll get three emails; check them.

Now type
{{{
touch email_log
mass_email_script.php --explain | more
}}}
You'll get a list of what type of email will be sent to each user.
Make sure that each user is being sent the right type of email.

When you're sure that everything is correct, type
{{{
truncate email_log
mass_email_script.php --send
}}}
It will now send mass emails. Depending on the size of your user table, it may take hours or days to complete. You can control-C it and restart whenever you want; it automatically picks up where it left off (see below).

=== Checkpoint/restart ===

`mass_email_script.php` manages checkpoint/restart when dealing with large numbers of participants. Mails are sent in order of increasing user ID. The file `email_log` has a list of IDs that have been processed. On startup, the script reads this file, finds the last entry, and starts from there.

If you are starting a mass email from the beginning, empty the file mass_email/log; i.e.
{{{
truncate email_log
}}}

== Reminder emails ==

The script `html/ops/remind.php` is for sending reminder emails.
Run it on the command line.  Options are:

 `--lapsed`:: send emails to lapsed users
 `--failed`:: send emails to failed users
 `--userid N`:: send both lapsed and failed emails to the user with the given ID
 `--send`:: actually send the email (this is an option to reduce the chance of accidents).
 `--show_email`:: show what would be sent rather than sending it
 `--explain`:: print a line describing each email

The script categorizes users as follows.

    * Failed: the account was created at least 14 days ago, has zero total credit, and hasn't received a reminder email in 30 days. These people typically either had a technical glitch, or their hardware and/or preferences didn't allow sending them work, or the application crashed on their host. The reminder email should direct them to a web page that helps them fix these problems.
    * Lapsed: the user has positive total credit, hasn't done a scheduler RPC in the past 60 days, and hasn't been sent a reminder email in the past 30 days. They probably stopped running BOINC or detached this project. The reminder email should gently prod them to start running BOINC and attach to this project again. 

The numbers 14, 30, and 60 are all parameters in the script; edit it to change them.

To use the script, create the following files in `html/ops/reminder_email/`:

 `failed_html`:: 	HTML message sent to failed users
 `failed_text`:: 	Text message sent to failed users
 `failed_subject`:: 	Subject line sent to failed users
 `lapsed_html`:: 	HTML message sent to lapsed users
 `lapsed_text`:: 	Text message sent to lapsed users
 `lapsed_subject`:: 	Subject line sent to lapsed users

`remind.php` can be run as often as you like. We recommend running it every 24 hours, specifying it as a task in [ProjectTasks config.xml]. When it sends email to a user, it stores the time in their database record, and won't send them another email for at least 30 days. For this reason, it has no checkpoint/restart mechanism.

The procedure for testing your reminder email is similar to that for email newsletters (see above).

== Friend-to-friend emails ==

The web page `ffemail_form.php` lets users send emails to their friends. To use this feature, you must create the following files in `html/ops/ffmail/`:

 `subject`:: 	The subject line used for friend-to-friend emails
 `html`:: 	HTML template for friend-to-friend emails
 `text`:: 	Text template for friend-to-friend emails

Samples are supplied for each of these. The following macros are substituted in the message bodies:

 `<fromname/>`:: The name of the sender
 `<toname/>`:: 	The name of the recipient
 `<comment/>`:: The comment supplied by the sender