Table of Contents

Recruiting and retaining volunteers

Personalizing emails
<name/>
<create_time/>
<total_credit/>
<opt_out_url/>
<lapsed_interval/>
<user_id/>
Avoiding spam filtering

Newsletters

--userid N
--send
--show_email
--explain
--idfile name
--nocurrent
--batch N
failed_html
failed_text
email_failed_subject
lapsed_html
lapsed_text
lapsed_subject
current_html
current_text
current_subject
Testing
Checkpoint/restart

Reminder emails

--lapsed
--failed
--userid N
--send
--show_email
--explain
failed_html
failed_text
failed_subject
lapsed_html
lapsed_text
lapsed_subject

Friend-to-friend emails

subject
text

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 the results of the BOINC user survey; study this yourself.

Most of these suggestions involve writing prose to be read by the general public. Find a good writer. 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 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. (Rosetta@home and 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

To get volunteers, you must publicize your project.

Get in the mass media (newspapers, magazines, radio, television). 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 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 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/phpmailer, and set the USE_PHPMAILER variable in 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 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 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 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 (https://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="https://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:
https://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 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. You can define default text for these emails by creating the following files in html/ops/ffmail/:

`subject`

subject line

`text`

message body

Samples are supplied for these in html/ops/ffmail.

Home