Preface

to be written (origin and concept, Advokit1 history, thanks, etc)

Introduction to Advokit 2.0

Advokit is a web application that helps small to medium-sized grassroots campaigns conduct carefully managed yet completely decentralized voter contact, supporter identification and get-out-the-vote activities. Your volunteer activists and leaders can work from any internet connected computer, whether it be at campaign headquarters, in their home or office or school, or anywhere else. They can get names of voters to contact one at a time, or create contact lists that can be printed out and used away from any computer., After speaking to each voter, they can record information from that conversation (typically by filling out a questionnaire). Leaders can recruit and organize their activists into teams, give them jobs and monitor their efforts in real-time.

Advokit is free, open source software that anyone can download and deploy in support of their political efforts. It is licensed under the Affero General Public License. The requirements to install and run Advokit for a small to medium-sized campaign are reasonable: a web server with Linux, Apache, MySQL and PHP. In addition, a unix shell-account and Perl are required for running the voter data import utility (see the online documentation at advokit.net, or the read me documentation included with the advokit installer for detailed system requirements). Finally, Advokit is not very useful without a database of voters - you will need to obtain voter data for your target population. Countless web hosting companies offer hosting packages adequate to run a modest Advokit campaign of, say, 50,000 voters and 50 users, often costing as little as a few dollars per month.

There are almost as many kinds of campaigns as there are campaigns. Advokit supports a wealth of organizing and voter outreach scenarios, which means that it is extremely important to set up Advokit for the way you want to conduct your campaign. It also means that there will never be a perfect fit to your expectations. If you are expecting Advokit to be a functional equivalent to to some commercial software system that you have used before, you will quickly lose that misaprehension as you start to work with it! Advokit is what it is, and while it is quite powerful and adaptable, and while it's open source code can be freely tinkered with, it will definitely pay to understand how Advokit is designed to work before you sprint out of the starting blocks. In this guide we will not only try to describe in detail how Advokit can be made to work for you, but we will also describe some typical campaign scenarios and detail some best-practices for organizing with Advokit for each of those scenarios. Take the time to read this guide carefully so that you understand how Advokit can best be used to suit your campaign!

How long will it take to get Advokit set up before you can start handing out user accounts and making phone calls? There is not a simple answer to this question since every campaign is different; much depends upon your familiarity with the options that you will need to choose among when configuring your campaign in Advokit; and of course a lot depends upon how well you understand what you need to do politically and organizationally to have a successful campaign. There is no substitute for experience in this regard! But in all cases there are several boiler-plate configuration steps that need to be performed, such as configuring job types, defining tasks and tags, setting up a few top-level teams, creating questionnaires, adding filters to teams, etc. These things can easily be done in well under an hour if you know exactly what you need to do. However, since you're reading this guide we can probably assume that you are still learning! In that case, it's probably a good idea to allot yourself at least several days to work out your configuration, perhaps starting with a small number of core volunteers using the system, before you promise a high number of phone calls being made!

In the first part of this guide, we will introduce you to how Advokit can work in a simple campaign. In the second part we will methodically survey the functionality of Advokit. Finally, we will consider a few campaign scenarios, and suggest some best practices with Advokit that can be used to support them. In appendix A, we provide a checklist of decisions to make and configurations to perform that any campaign leader will need to go through when setting up Advokit to run a campaign.

This guide is intended for prospective campaign organizers who would like to use Advokit, or are actively preparing to do so. However...

• This is not a guide to installing and trouble-shooting Advokit installations. We assume that you already have a clean, working installation of Advokit. For information on installing Advokit, performance considerations, etc, consult documentation, user forums and email listservs found at www.advokit.net.
• This is not a guide to finding, preparing, and loading voter data (though we do discuss some kinds of voter data you may want for different campaign scenarios). We recommend that you familiarize yourself with public and private sources of voter data in your area of interest. In many places, public voter data is available to political campaigns for free or at low cost.

An introductory scenario - setting up and running a community campaign with Advokit.

to be written

First Steps: Job-Types

Voter-contact jobs initiate contact with voters and are the campaign's primary way to interact with voters. Voter-contact job type definitions control basically three things:

1. How an activist gets the names of voters to contact
2. What options an activist has for managing his/her "portfolio" of voters to contact (contact lists)
3. What information is visible and what privileges an activist may have when he or she pulls up a contact sheet for a given voter.

Advokit supports three scenarios for how activists get the names of voters to contact:

1. one-click get-next-voter or household which automatically selects one name from the voter pool and immediately brings up a contact sheet for that voter or household (no contact list)
2. one-click addition of a set number of automatically selected names from the voter pool to an existing or new contact list
3. searching by name, address or other attributes of voters and then browsing the search results to manually add names to a contact list

Which scenario(s) or variations on them you choose for your campaign will depend upon a number of considerations, some having to do with campaign strategy, some having to do with how to utilize your campaign's human resources most effectively. Advokit provides three preset activist job types that provide a good starting point, and correlate with the three scenarios just listed. They are shown as "online phone banker", "offline phone banker" and "friends and neighbors" in a drop down menu on the add and edit job type screens.

A menu on the add/edit job type page shows three preset voter contact job types - "online phone banker", "offline phone banker" and "friends and neighbors" - in addition to task handler job types corresponding to the task types currently defined.

Online phone banker:

A phone banker is an activist who calls voters that have been assigned to him/her by the campaign. An online phone banker is one who works at computer that is connected to the internet while making phone calls. An online phone banker has no need to manage contact lists, and is simply presented with one voter or household at a time to call (if you have multiple voters at the same phone number, we strongly recommend that you enable the "Select all voters in household" option, otherwise you can have different activists trying to call different voters at the same number at the same time or in rapid succession). To get a new voter or new household, the activist clicks a "Get next voter" (or "Get next household") link. Since there are no contact lists to manage, the "online phone banker" job type presents the simplest interface to the user.

Offline phone banker:

An offline phone banker is an activist who is given a list of voters to call - a contact list. Though he or she could work through her list of voters while working on a computer, there is no requirement to do so, and could just as readily work from a printed copy of the list. Also, since he or she is not tethered to a computer, there is no real reason he or she should be tethered to the phone either. So notwithstanding the "phone banker" name we gave this preset job type, this activist could take the printed contact list and use it to walk door to door. In either case, anyone who works offline will need to have the results of their voter contact work entered into Advokit in a reasonably timely fashion. There is no requirement that contact results need to be recorded by the activist. You could decide to have the team leader or another activist stand-in for the activist, when creating the list of voters to contact, and/or when entering the results afterwards. In this way, you can effectively utilize volunteers without requiring them to be technologically-abled.

Friends and neighbors:

A friends and neighbors activist is instructed to create a contact list of people he or she knows personally or with whom he or she otherwise has some kind of affinity (e.g. neighbors, co-workers, etc). Since there is no practical way that an automatic system can be devised to create such a list for each activist, Advokit provides search capabilities to enable activists to find individuals by name, address, or other attributes. The activist browses the search results and either manually selects individual names (or households), or chooses a selected number of the voters found by the search, to add to a contact list. Because of the need for friends and neighbors activists to use the search tools in Advokit to find particular voters, this is not a role that is performed performed by persons who are not technology-abled. At the very least, the activist needs to have their contact list creation directly facilitated by someone, e.g. a team leader. The activist could meet with that person who has an internet-connected computer, and together perform the searches to build a contact list and, later, enter the results of their contacts.

Comment: One of the most important questions a campaign leader faces with respect to conducting voter contact is one of quantity vs. quality. Voters contacted by personal friends are at least an order of magnitude more likely to be identified as a supporter than those contacted by someone they don't know. If you could have every voter in your target population contacted by a close personal friend, clearly that would be preferable to each voter receiving a call from a rank stranger. If your activists come from the same community as the voters that are your target population, and if your objective is to identify the maximum number of supporters for your cause as possible, then a strong case can be made for using a "friend to friend" approach, where your activists are instructed to search out their friends and neighbors to contact. Though they probably will not contact nearly as many voters as compared with a phone banking or precinct walking style operation, it is quite likely that each activist will identify at least as many supporters. Obviously this approach depends upon there being a pool of voters who have some kind of social connection with your pool of activists. But it does not to be an either-or proposition. You could start your campaign with a "cherry-picking" phase where your activists are told to build contact lists of people they know, perhaps also instructing them to recruit friends to become activists in the campaign at the same time. Later, you can tell them to use automated methods to create new contact lists in order to achieve more systematic coverage of the voter pool.

The three presets I have just described provide a starting point for defining your job types based on general functional requirements. Once you have selected one of those preset configurations, you will need to carefully adjust all the individual options in light of your own requirements. Some options have to do with how activists get the names of voters to contact and how they manage their contact lists. Other options have to do with what privileges they have with voter information, whether they can recruit a voter to become an activist. Choosing different presets will cause the add/edit job types screen to show different sets of options, as is explained below.

Task-handling jobs respond to requests for some kind of action that are generated through voter-contacts. A typical example would be when a voter-contact activist talks to a voter and determines that the voter should be sent some campaign literature. The voter-contact activist could create a task that instructs someone in the campaign to send the literature to the voter. A task-handling activist would then handle that request. Task handling jobs do not have lists of voters to contact. Rather, all instances of a particular task-handling job type, regardless of where they are in the team structure of the campaign, share responsibility for a list of pending tasks.

There is no configuration available for task-handler job types. You just select the task that this job type will handle from the list in the available presets menu (you need to have first created the task types by clicking Configure > Task Types).

To create a new job type, first, click on Configure > Job Types

This brings up a browse job definitions screen, which displays any job types that you have already created. Click on the "Add a new type of job" link.

Here is what the add job type screen looks like before you have entered anything.

The only required elements in this form are a title for the job type and a selection from one of the available presets. The description that you provide, which will appear on the activist's job details page, should clearly explain the expectations for activists who have this type of job.

If your campaign utilizes Advokit's self-registration feature, you will probably want to enter information into the Ad Title and Ad Body fields. This information will appear when the prospective registrant views the list of available jobs. The Description and the Ad Body are both composed as WYSIWYG HTML, using the TinyMCE Editor forms.

When you select one of the available presets, options that are appropriate for that job type will appear. Here are four examples.

	A task handler job has no configuration options.
	Because the "online phone banker" type of job does not have contact lists, options relating to contact lists do not appear. Select all voters in household - When the job is of the "online phone banker" type, enabling this setting causes the available cohabitants of the current voter to be listed on the contact sheet for that voter. Enabling this option is highly recommended for online phone banker jobs for a couple reasons. 1) If someone else in the household answers the phone, the activist can quickly switch to the contact sheet for that person by clicking on their name on the contact sheet. 2) It prevents another activist from getting another member of the household to call at the same time. Default voter recontact interval (days) - When an activist clicks on the link on the contact list to "record unsuccessful or incomplete contact attempt", a "recontact in __ days" form is displayed. This option sets the default value that appears in that form. Enable basic voter editing - If this option is checked, the activist will be permitted to edit name, address, and a few other fields for the voter. A pencil button appears on the contact sheet. Enable advanced voter editing - If this option is checked, the activist will be allowed to edit all information about the voter, as well as mark the voter as deceased or moved away. A pencil button appears on the contact sheet. Enable adding new voters - If checked, Actions > Add Voters is enabled for the activist. Enable recruiting of voters to be activists - If checked, the activist can give the voter an account on the system by clicking the key button (). Note that the voter is not given a job, and will be unable to log in until a leader does put him or her into a job. Enable phone number editing - If checked, voter phone numbers and email are editable directly on the contact sheet. Enable creating and viewing followups - Followups are another way of recording comments and information about a voter. They do not work very well and are not very useful, so unless you have a specific need to use followups, it's probably best to leave this option unchecked. Enable creating and viewing tasks - If your campaign wants activists in this job type to be able to create tasks that are followed up by other activists in a task-handling role, check this option. Optional Display - You may select up to two optional fields that will be displayed on the contact sheet. For example you could display a voter's occupation and party affiliation.
	Offline phone banker and friends and neighbors jobs have contact lists. There are several options for configuring settings for contact lists in addition to the options described above. Offline phone bankers, by default, have a single contact list, use the one-click method for adding voters to the contact list, and do not use voter searching. Enable multiple contact lists - If checked, the activist can create and delete contact lists. Otherwise, they have exactly one list and cannot delete it. Enable one-click adding new voters to contact list (with option to set the number to be added with each click) - This provides a quick way for activists to get a batch of voters to call from the voter pool. Enable searching voters to add to contact list - When this option is enabled, a search field appears in the activist's sidebar where a voter name or street may be entered. There is also an "advanced search" link that connects to more powerful searching tools. Auto populate contact list when filling this job (with option to set the number of voters that are automatically populated) - When an activist is added to this job for the first time, if this option is enabled, the selected number of voters will be added to a contact list on that job. This is particularly useful if you wish to have activists getting started making calls with little or no intervention by leaders. When they log on for the first time, they will already find a contact list of voters to call. Days of inactivity before voters are removed from contact list - This option does not work and may be ignored. Max number of voters that can be on contact lists for this job - When a voter is on a contact list, they are unavailble to be contacted by activist elsewhere in the operation. It is probably wise to set this at a fairly high number, but not astronomical, in case you have an activist who intentionally or inadvertantly tries to grab your entire voter pool.
	Friends and neighbors jobs are identical to offline phone banker jobs except that they have different options enabled by default. Multiple contact lists and voter searching are enabled by default.

First steps: Tasks

To add or edit task types, click on Configure > Task Types.

A list of any already existing task types will be displayed, along with a link that lets you add a new task type.

Advokit comes with a "Undefined" task category predefined. This category cannot be deleted or edited. You can add, edit and delete your own categories. Clicking the "Add a category" link brings up a simple form where you can provide a name and description for a new task category.

Select the Configure > Job Types link.

Consult documentation on creating job types.

Consult documentation on creating teams and jobs on teams.

First steps: Tags

Voter tags function similarly to questionnaires, custom fields, and even tasks and followup comments. They're each a different way to record information about voters. Tags are appropriate where you wish to be able to record and display simple information for any voter in a fairly ad-hoc way right at the top of the contact sheet.

When one or more voter tags are defined, they will appear as a list of tags on a voter's contact sheet which can be individually checked on or off. In this sample screenshot there are two voter tags that have been defined for this campaign: "Environment" and "Schools". The small tag symbol (), labeled "A" below, is a button, that when clicked causes a small form to appear with check-list of the possible tags for voters, labeled "B" below. Checking one or more check-boxes and saving changes by clicking the green check-button causes those attributes to be "tagged" to that voter. In this sample, John Q Public is having the "Schools" tag added to the "Environment" tag that he is already tagged with.

Voter tags are treated like voter attributes that can be searched and filtered on. You could, for example, set up a team whose job it is to contact all voters with the "Environment" tag. Or you could create a saved search for all voters with the "Schools" tag in order to extract a mailing list.

Activist tags, also known as "Interests", are similar to voter tags in that they appear as a simple check-list, and they are used to record simple information about an activist. Typically, they would be used to record information about the kinds of work that an activist is interested in helping with.

An individual activist's tags are edited from the activist's profile page and - when enabled - the activist self-registration page.

Activist tags can be used to filter the activists shown on the Browse > Users page:

In this way you could when looking for activists to fill a job of a particular type, filter by an interest that would be appropriate for that job type. In this example, you might be looking to fill a job that involves making lists of friends and contacting them.

First steps: Operations and top level teams

to be written

First steps: Questionnaires

Advokit's primary mechanism for gathering information from voter contacts is through questionnaires. Questionnaires appear on contact sheets as a series of questions that you define (usually). Voter contact status is a function of questionnaire completion status - when all questionnaires are completed, then the voter contact status is considered completed.

-- a typical questionnaire as it appears on the voter's contact sheet

Some things to know about questionnaires:

• A questionnaire can have zero, or one or more questions (a questionnaire without questions is considered a "checkbox questionnaire", which means that the only information you are interested in is whether it is completed - more information is provided below).
• A questionnaire is created on a team, where it applies to that team and any teams below it. Typically, a questionnaire would be created on an operation, and would apply to all teams in that operation. A questionnaire can only be edited on the team were it was created, and only by a leader with rights for that team.
• There can be more than one questionnaire applicable on a team, either because there is more than one questionnaire defined on the team, or because questionnaires from above that team "trickle down".
• When questionnaires are created, they are disabled by default. A questionnaire must be enabled in order to appear on contact sheets and in order to figure into voter contact status.
• Questionnaires may be made to apply to only certain voters by creating a voter filter for the questionnaire. For example you might want a 'GOTV' questionnaire to only appear if you have determined through another questionnaire that the voter supports your cause.
• Scripts can be attached to questionnaires - these are files that the activist can view or download and are typically used for things like call-scripts.

Some things to know about questions:

• There are a number of question types depending upon the type of information you want to collect. They are described in detail in the question formats section below.
• The question text is edited in a WYSIWYG HTML editor panel.
• It is possible to link individual responses to a multiple choice question to another question on the questionnaire, or to the next or previous questionnaire. When the choice is selected, the window will scroll to the "jump to" question. One type of question - a navigation question - does not record any response. It is just used to jump to the appropriate next question. Tip: It is best to keep the number of questions to a minimum
• Multiple choice questions can be configured accept just one response (the default) or to accept multiple responses. In the first case (single response), radio buttons are used; in the second case (multiple responses), check boxes are used.
• A question may have a goal number, which is used on the Progress Summary > Voter Responses page to provide a benchmark against which to display voter response performance. For example, if your objective on a question is 2,000 yes responses, then you could set the goal number as 2000.
• Each possible response on a multiple choice question can be given a defined score, which is used to count performance on that question. Numeric response questions use the value of the response for their score. Other questions simply score one (1) for any response.
• You may set completion of a question for a voter as required in order for the questionnaire to be counted as completed for that voter.

A few tips about questions - keep it simple:

• It is best to keep your questions short and to the point to avoid unecessary verbiage and space on the contact sheet. Use a separate script instead of lengthy question text to instruct your activists on what to say on the phone. Once an activist has made half a dozen calls, they will tire of scrolling through the same screen content over and over just to get to the places where they record the voter's answers.
• Keep the number of questions as small as possible. Questions should be used to collect campaign-critical information. It's OK to have just one question! It may be tempting to collect a lot of information as long as you have the voter on the phone but it will slow down your calls, frustrate your callers, and perhaps most importantly, antagonize the voter on the other end.
• Though Advokit supports navigation questions and jump-to links from multiple-choice questions to create branching lines of questioning (and even loops!), unless the core purpose of your contact with voters really is to perform extensive gathering of information, it is best to avoid using branching in your questionnaire as it will at the very least require more training and oversight of activists and will substantially increase the amount of time and work needed per voter.

Adding a questionnaire

1. Click the Questionnaires tab on the team where you want to create the questionnaire
   
   
2. Click 'ADD QUESTIONNAIRE' and give the new questionnaire a name (e.g. "Supporter Identification").
   
   
3. Click the 'ADD QUESTION' link if you want to add questions
   
   

When you are ready to have the questionnaire appear on contact sheets, be sure to activate it by clicking on the ACTIVATE link!

 

Adding questions

This is what the add question form looks like:

You will need to select the question format, type in the text of your question, and change any options as appropriate.

Question formats and options

Question formats:

Multiple choice questions can have two or more possible answers. Yes/No, True/False, Support, Comparative, and Frequency are simply preset kinds of multiple choice questions. In any case, you can add, remove and edit answers after creating the question. Short Text questions accept text responses up to around 50 characters in a one-line text field. Long Text questions accept longer responses in a multi-line text box. Integer, Decimal Number, and Currency questions take numbers as responses in a text field. Date questions utilize a date-picker popup window. Voter Data questions allow an activist to edit intrinsic voter data from a question on a contact sheet instead of requiring that he or she have voter editing privileges and use the edit voter screen. When this question type is selected, the Voter Data Field menu to the right will become enabled, allowing you to select from a dozen or so voter data fields. Navigation questions can be used to jump to another question on the questionnaire, depending upon which "answer" is chosen. No response is recorded to a navigation question - it is just used to move around in a questionnaire.

Question options:

• Possible answers - For multiple choice questions, indicate the number of answer choices you will be defining in the next step.
• Additional answers - If you want to add answers to an already existing multiple choice question, enter the number of answers you want to add here. When you click "apply changes", you will be taken to a screen where you can define those answers.
• Goal Number - Used when graphically displaying the campaign's performance on this question.
• Accept multiple responses - If this option is checked, then instead of a multiple-choice question appearing as a set of radio buttons where only one answer may be selected, it will appear as several check-boxes, any number of which may be checked and recorded as the voter's response.
• Require a response - When this option is checked, the questionnaire will be considered unfinished and the contact status of the voter will not be displayed as completed until a response is recorded for this question (note that this is not retroactive unless the reset contact status option is checked).
• Display progress - If checked, this option causes reporting on this question to appear on the Progress Summary > Voter Responses page.
• Reset voter contact status - If this is checked, when you apply these changes, all voters that this questionnaire applies to and who may have been regarded as "contacted" will have their contact status reset to be "not contacted".

Adding a question: example

In this example, we're creating a simple yes/no question: "Do you support our cause?"

After clicking "Add New Question" the Edit question form appears, which looks very much like the screen we just saw, except that now we see our answers in a form at the bottom of the page.

Here we can

• Modify the answer text
• Set the score that will be counted each time this response is recorded for a voter
• Change the order of the answers (clicking on the small up and down indicators)
• Select a jump-to question
• Delete an answer

We can also add answers by entering a number in the additional answers field near the top of the form

In all cases, click the "Apply Changes" button to save your changes.

Managing questionnaires

After you have added a question or two, your team's Questionnaires tab might look something like this...

There are a number of links and buttons. For questions, you can...

• Change the order of questions on the questionnaire by clicking on the up and down indicators (small greenish triangles).
• Click on the question to edit it
• Click on the 'x' to the right of a question to delete it.

For questionnaires, you can...

• Click on 'EDIT' to modify its properties, voter filters and scripts.
• Click on 'ACTIVATE' to make the questionnaire active and able to appear on contact sheets.
• Click on 'DELETE' to remove the questionnaire and all its questions.

If you click 'EDIT', you will see a screen like this

On this screen you can

• Edit the name or description of the questionnaire.
• Turn on reporting of the number of questionnaires completed, and also, optionally, provide a goal number for the number of questionnaires you want to complete.
• Add/edit/delete voter filters.
• Add/edit/delete questionnaire scripts.

Questionnaire voter filters

If you would like a questionnaire to appear on contact sheets for only certain voters, you can create and apply a voter filter to that questionnaire. You can make a voter filter as simple or as sophisticated as you like. For example, you could have a filter that displays questionnaires only for voters registered in a particular party. Or you can have a filter that only allows a questionnaire to appear for voters who have answered a particular way on another questionnaire!

To add a voter filter to a questionnaire, click on the 'ADD' link for voter filters. This will bring up the same "filter builder" interface that is used for creating voter filters for teams and jobs.

For detailed information on building a voter filter, see the help topic on Voter Filters.

Once a questionnaire voter filter has been created, there will be links on the questionnaire properties page to edit (using the filter builder interface), edit sql (where you directly edit the database query), and to delete it.

Questionnaire scripts

A questionnaire script is perhaps not clearly named since it is simply a way to make a link appear on a questionnaire that lets the activist view or download a file that you have uploaded to the server. The "script" idea comes from the fact that campaigns typically have a need to provide the activist with a call script which they follow when they call a voter. However, any kind of file may be attached to a questionnaire. If it is a type of file that is viewable in the user's browser, it will be displayed. Otherwise the user will be asked if he or she wishes to download it.

Note: It is usually best to create a script file in a format that any user's browser can display, rather than requiring that they download the file and open it in a particular application. Avoid using MS Word (*.doc) files, for example. The safest choices are plain text (*.txt) and html (*.htm, *.html). PDF (Adobe Portable Document Format) files are also very good, though there are some rare users who do can not read them.

As can be seen above, a "script" link appears on the questionnaire when there are one or more files attached to it. To attach a file to a questionnaire, go to the team where the questionnaire was created; click the Questionnaires tab; click on the EDIT link for the questionnaire; then click "ADD A SCRIPT" on the edit-questionnaire page. You will now see a form that looks like this...

Give the script a name, an (optional) description, and click the "Browse..." button. This brings up a file selection window which you can use to find the file that you want to attach. Finally, click "Add New Script". The script attachment will be created and the file will be uploaded to the server.

Now when the activist opens up the questionnaire for a voter, the "script" link will appear. Clicking on it will bring up a popup window that lists the attachments to the questionnaire, like this...

When the activist clicks on the link for the attachment, if the file is displayable by his or her browser, it will display in a new popup window. Otherwise, a dialog box will appear asking if the user would like to download the file.

 

One-click questionnaires

Sometimes. the only thing you want to know is whether contact was made with the voter. A common example is the get out the vote call on election day. You're not gathering any information, so there are no questions to ask. A way to approach this in Advokit is to create a questionnaire that has no questions! When you do so, it will appear on contact sheets like this...

Furthermore, if this is the only questionnaire remaining to do for this voter, then a checkbox will appear at the top of the contact sheet next to the voter's name. Clicking it will immediately mark the voter as "done".

Also, again if this is the only remaining incomplete questionnaire for the voter, there will be a checkbox next to the voter's name on the contact list which likewise works to mark the voter as "done" when it is clicked.

With this feature, it is possible to rapidly work through a contact list without needing to pull up contact sheets for each voter that is called.

 

First steps: Voter filters

to be written

Getting going: Adding people to your organization

to be written

Add activist, Recruit voter, Self registration

Getting going: Being a Leader

to be written

• Viewing jobs and activists
• Adding jobs
• Adding sub-teams
• Adding activists and leaders

Now we're cooking: Searches and Queries

to be written

Now we're cooking: Contact lists

to be written

Now we're cooking: Contact sheets

to be written

Best Practices: Three campaign scenarios

to be written

Appendix A - Advokit configuration checklist

to be written

A checklist of decisions to make and configurations to perform that any campaign leader will need to go through when setting up Advokit to run a campaign

First-time installation

AdvoKit runs on a web server with PHP and a MySQL database server. Before you can install or upgrade AdvoKit, you must have information for accessing the MySQL database; where the application files will go; and where the web root is found.

There are three steps that must be accomplished, in no particular order, before starting up the AdvoKit installer: Setting up a database; Figuring out where files will go; and installing the installer!

Database setup:

You will need to work with your hosting service or local system administrator to create a MySQL database that you have access to. To set up AdvoKit, you will need to know:

• the web address for the MySQL server
• the database name
• a valid user name and password on that MySQL server with privileges to create tables in that database.

File system setup:

Take a minute or two to understand the directory structure on your host machine. If you are installing on a remote server, use your FTP client to take a look at how the hosting service has organized your directories. Typically, in your top level directory or perhaps one level down, there is a folder called "public_html" or "htdocs" or some such, which is where your publicly accessible web pages are served from. This folder is known as the "web root". The advokit-installer will need to put some files under that directory. You can decide if you want AdvoKit to run directly from the web root, or from a folder somewhere under the web root, e.g. "../public_html/advokit".

Most of the AdvoKit files will be placed in a location that is NOT under the web root, so that prying eyes or mischief-makers cannot get into them. The most typical approach is to create a folder called "advokit" at the top level of your directory structure (above that web root) for the advokit-installer to use to place all the application files and private data files.

Getting ready to run the installer:  

The advokit-installer compressed archive will need to be decompressed and uploaded to your web server. Most efficient is to upload the archive to your server and then decompress it from the command line. If you do not have shell access, then decompress the archive on your PC (using e.g. WinZip), and then drag the advokit-installer folder to your web server using your FTP client. Make sure you place it under your web root, where it can be accessed by a web browser.

After you have decompressed and placed the advokit-installer folder under your web root, point your web browser to <your.domain>/advokit-installer.

Assuming this is a new installation, click on the button labeled "Install advokit, deleting any existing installation >"

Step 1: Entering database connection information

• Database Host: either localhost, if the database server is on the local machine, or the url to a MySQL server somewhere on the internet.
• Database Port: Usually 3306. If you don't know what to change it to, then probably it should be left alone.
• Database Name: this is the name of the database on the MySQL server where AdvoKit data will be stored. You must have an account (username and password) for this database. If you are using a web hosting service, this information would have been provided to you when you signed up for the database service.
• Database User: enter the username that you have been assigned to access this database. Note that this probably will not be the same as your other web host account usernames.
• Database Password: enter the password for access to this database account. Again, this usually will not be the same as you would use to access other parts of your internet service.

It doesn't hurt to select "transaction safe tables", though most MySQL servers do not support them.

• Table prefix: Since a given MySQL database may be holding data for a number of applications, it is generally best to give your AdvoKit tables a readily distinguished identifier. A typical strategy for someone just trying out AdvoKit is to create a test instance, and then when they have messed around and are comfortable, create a real production instance. Using a different table prefix for the test instance will ensure that you do not inadvertantly damage good data when you are learning to use AdvoKit.

At this point you can click "continue". If the database connection information was valid, then you will see a screen like this

Step 2: Database setup continued

If the database connection is successful, click "continue". If it was not successful, click "go back one step" and carefully check the information as entered.

Step 3: Database setup continued

Now a long list appears, showing what database tables the AdvoKit installer plans to create. If any of these tables already exist, they will be dropped, and any data in them will be lost permanently. If you are installing over a pre-existing AdvoKit database, that data will be lost.

If you are installing AdvoKit for the first time, you might want to choose to have some sample voter data installed. This loads a small voterfile that you can use while exploring your way around AdvoKit. If you do not have any voterfile data, this is a great way to learn about AdvoKit. Do not choose to install this sample data if you intend to upload real voterfile data and begin to run a real campaign, however you can get rid of the sample data at any time just by re-running the AdvoKit-installer. Note that the option to load sample data is off by default, and appears at the bottom of this long page, requiring scrolling down to see it.

Step 4: Database setup concluded:

If you now choose to continue, the installer will proceed to install the more than fifty database tables needed to run AdvoKit. This should only take a minute. A lengthy log of results for each SQL insert statement should scroll rapidly past as each table is created. If there are any errors, the installer will usually stop and display an error message. However it is a good idea to to quickly scan the results display for any highlighted text that may indicate a warning or error message. Most warnings can be safely ignored. An error message stops installation, and should be resolved and the import run again.

Step 5: Application files installation:

Once the database installation is successful, the installer turns to setting up the application files and configuring the advokit.ini file that binds everything together. To do so, you must provide the installer with information about where your installation will be found on the world wide web, and where its files will be found on the machine that will be serving your site..

• Installation URL: This is the address that people will be able to type into their browsers to use your site. For example: "http://www.mydomain.org/advokit". The installer fills this field in for you, but you can change it if desired.
• Filesystem path: This is the path to the directory on the host machine that corresponds to the URL above. The installer will likewise fill this field in for you, but you can edit it if necessary.

The following five items expect you to provide an absolute path for locations to place AdvoKit application files - folder locations on the host machine. In a remote hosted environment, the complete path may not be apparent to you, since you can usually only see the file structure below your private home directory. However, the advokit-installer does provide some help for you. If you look at the filesystem path above that was filled out by the installer, it shows the complete filesystem path to where the web-accessible portion of AdvoKit is found in your web directory. Since your web directory is normally located below your private home directory, you can pull out the portion of the path that shows where your private home directory is. For example, if

Filesystem path is "/home/.zachheater/janedoe/public_html/advokit", then it's easy to figure out that the private home directory is "/home/.zachheater/janedoe". Now if you created a folder called "advokit" under your private home directory (see "File system setup above), then you would just need to substitute "/home/.zachheater/janedoe" for "\NON-WEB\PATH\TO" in the following paths.

• Uploads: This directory is where some uploaded files are stored (not used much, if at all).
• Voterfiles: This is where you will want to put voter data that you have uploaded in preparation for importing into AdvoKit.
• Application files: This is where all the executable code for AdvoKit is located. Several folders are created under this directory.
• Templates: The Smarty templates that actually create the AdvoKit pages go here.
• Log directory: Log files are generated and saved here.

Carefully double-check all the entries in this page before clicking "Continue >". You will next see a scrolling list of the files that are being copied to your application folders. Watch for error messages, usually shown in bold red type. If there are errors, try to resolve them and then reload this page, or go back one step.

Upgrading an existing AdvoKit installation

Until something better is written, see this FAQ entry.

A mechanism for adding custom pages

1. Create a HTML file with the content that you wish to show in the main display panel of Advokit. (Important - use the ".html" extension, ".htm" won't work.)
2. Put a copy of that file into the ../templates/raw/ directory of your Advokit installation.

1. Edit the template file named "custom_sidebar_section.tpl". You just need to remove the comments "{{*" and "*}}" to activate this template. It will be displayed as a new section in the sidebar immediately above the "My Account" section. Here is a sample
   

   <h4 class="sidebarsectionhead">The Issues</h4>
    <p class="alist">
    <a href="index.php?display=CustomHtml&heading=Eight Talking Points&html_name=talkpts">
   Eight Talking Points</a>
    <br>
    <a href="index.php?display=CustomHtml&heading=Spin&html_name=spin">The Spin</a>
    </p>

   The first line causes a section header to be displayed with the name "The Issues". Below that are the links, separated by breaks (<br>).
   
2. You can put any kind of link you want into this code, but note in this example the link to a display called "CustomHtml". This is how you can have your HTML page displayed inside AdvoKit. The "heading" argument determines what will appear as a title for this display in the header area. The "name" argument is the name of your HTML file, minus the ".html" extension.

Customize the look of your Advokit website

1. Changing the page title displayed by the browser
• In your advokit.ini file, look for where the "title_override" configuration variable is set. By default it is blank, which causes Advokit to use the product name and version number. However you can enter any text here, and it will be substituted for the page title.
2. Changing the logo
• To use your own logo, the simplest thing is to name it "logo.gif" and upload it to the "images" directory under your Advokit installation's web root - replacing the original "logo.gif". You can use a different file name and/or location, or not use a logo at all by editing the "logo_url" variable in advokit.ini. Here is the documentation for that. (Not using a logo might be desirable if you intend to use a css background-image - see the next section).

  ; Enter a url here to use for the logo image (relative url is from
  ; web root of application, exclude the leading slash). If left blank then
  ; the default AdvoKit logo will be used. If "none" is entered, no logo will
  ; appear. Examples:
  ;  logo_url = ""
  ;  logo_url = "images/logo.gif"
  ;  logo_url = "http://www.a_domain.com/advokit/images/logo.gif"
  ;  logo_url = "none"
  logo_url = ""
  

3. More extensive changes
• Most of the graphical appearance of Advokit is determined by the stylesheet "advokit.css" which is installed at the Advokit web root. There are a couple additional stylesheets that occasionally come into play as well.
• The HTML code that you see displayed is created by Smarty templates, of which there are a large number! However only a few templates are used for "wrapping up" page content. These are generally  identified with lower-case file names in the /templates/raw/ directory. For example, "browse-header.tpl" controls the appearance of the tops of browser pages. The sidebar is created by the "activist-sidebar.tpl", "admin-sidebar.tpl" and "anonymous-sidebar.tpl" files.

Importing County Voting Records Into Advokit - by John Barta, Morro Bay , California

Advokit works with many tables and fields of data within those tables. The Advokit system is highly structured. Unfortunately, local voter files come in all shapes, sizes, and qualities. So, you will first use your own computer to put that information into shape before it can be imported into Advokit. The process involves getting your local data and then your conversion of that data into a "comma separated values" (CSV) file that is usable by Advokit. The county data must be cleaned up and often parsed in order for Advokit to be able to convert and import it without error into the Advokit system data file which is a MySQL file. You upload your "cleaned up" CSV file to the proper location on the web server where it can be acted upon. The actual importation of data from the CSV file to the MySQL file is done on the web server using a perl script called "import.pl" which is part of the Advokit utilities.

The basic steps in the process are as follows:

1. Obtain the voter file from your registrar of voters. In our case the county provided the file on a CD in a "tab delimited" format. You may also wish to get from the county a printout or other copy of the file structure. This will contain valuable information when you start playing with the data on your personal computer. Sometimes the county information is kept in more than one data table. For example the voter information may not be in the same table as the precinct and district information. If you can get the district and precinct information table from the county you should do that to as it will be useful when later figuring out which candidates are running in which precincts within that jurisdiction. In our case the county voter file only contains information about which local precinct the voter is located in. The information about which districts contain that precinct is contained in a separate file. Keep a friendly relationship with your local voter registrar, it may pay dividends down the road.

2. Study the structure of the local voter file. You should try to understand what the information in each (of the about 60) fields represents. In our case I was able to speak to the "computer guy" at the county office and he was quite helpful in my understanding the purposes of each field in the file. Make a written description of the structure of the county file and each field that it contains. Explain what each field is used for. Once you look around at the data within the file, you will have a much better idea of how it is designed to work. You may find that some fields have no data inside at all. You may also find that two similar-sounding fields actually are not 100 percent the same data. This a good time to ask questions of your registrar because you may make a mistake if you rely on one field and later learn that the data is not exactly what you thought it was.

3. Study the fields that are requested in the Advokit mapping utility. You will need to know what Advokit is looking for so you can make the best of your local voter file data before trying to import it into Advokit.

The fields that Advokit will ask you about for its use in the "_voter", "_residence", "_mailaddress", and "_respolis" tables are as follows:

• _voter
• _residence
• _mailaddress
• _respolis

As you study the Advokit field information compare it to what your local voter file is offering. It is highly likely that you will discover that you'll have to make some changes to your local voter file data in order to use it with Advokit. For example, our local data has a single field for birthdate. This will need to be turned into 3 fields of data – birthyear, birthmonth, and birthdayofmonth. Advokit turns these three fields into the simple birthdate field itself. Also, it turns out that Advokit only stores party affiliation as a single letter – the first letter shown in the CSV field for party affiliation. Locally we have two affiliations that begin with the letter "D" Democrats (DEM) and "Declined to State" (DTS). So, we better change the DTS data in the local file to some other letter or we'll have an inaccurate picture of the number of Democrats in our county. Anyway, there will very likely be a number of opportunities to optimize the local data to make things work better for Advokit.

When you feel confident about what you need to do to your local data you should be able to list what massaging you will want to do to the local voter data before sending it off to Advokit.

4. Clean the county file. This is not the massaging that was mentioned above. It is the process of finding out-of-place or troublesome characters in the local data file. For example, local data containing double-quote (") could be extremely troublesome during the CSV process since the double-quote character is used extensively in that process. The advokit documentation has a link to the CSV standard which is useful. What I discovered is that if I cleaned out the double-quotes, single-quote (apostrophe)('), percent (%) character, semicolon(;), etc. I did not have a problem later. The CVS standard allows quite a number of things to remain in the file, but why take a chance on the odd stuff since it is easy to clean and rare or non-existent anyway?

Open the county file on your personal computer. In our case I used Microsoft Word to load the file. Our file was about 50 megabytes at that point in time and so the operations were a little slow at first. Since the tab character was only used as a field delimiter I was able to search through all fields of the entire file to look for "dirty" data – characters that might cause problems later in the process. The one thing that will for sure cause problems is the double-quote character " The other things I searched to eliminate were the tilde~, the backward apostrophe `, the semi colon; and the apostrophe '. The Advokit help files point you to a CSV standard which will show that most of these are okay, but I didn't want to take chances on how they might be handled by MySQL after being imported into Advokit, so I removed them from the file, too. Once I finished cleaning the file in MS Word I saved it for use by my local database program. In my case, I prefer to use good old Dbase for data manipulation. You may want to use some other program – Access or a local copy of MySQL, for example. Just make sure you save it in the correct form so that it can be imported by your data base program. In my case I saved it in Word as a "Text-only" file that was comma-delimited (with double-quotes around the data for each field).

[Note on how you clean your county file – Use your choice of programs to accomplish that goal, but beware that your early choices can create issues later, if you aren't careful. For example, I could import a tab-delimited county file directly into MS Access but Access will make certain assumptions about the type of data that is being imported – fields that always have numbers in them will be assumed to be integers and not text, for example. So, if you are importing into Access, you need to specify that all fields are text fields and not other data types (date and time, integer, floating, etc.) before or during the importation into Access. Access will not export the data later to a workable CSV file if the fields are not defined as text going in.]

5. Massage/Parse the clean local data file. Once you have loaded your local data into your personal database manipulation program you can start optimizing it for use by Advokit. This is where you will make the changes you planned for at the end of Step 3, previously. So, go in – split the birthdates into three fields, makes adjustments to the party affiliation codes, etc. This is the step where you will be able to add some real value to the county data by good parsing or concantation, etc. If you plan to add additional fields of data, this is the time to do it. In my Dbase case I saved my successful command lines in a file. I was able to then turn this file into a Dbase program script. So, the next time I need to massage the county file I'll be able to save much time by just running the Dbase program. If you use Access to do the local data work – be sure that you end up with all of the data in text fields – otherwise you will not end up with a usable CSV file.

[Note on the CSV standard – the standard calls for each field of data to be separated from the next field with a comma. If the data within the field is text data it is supposed to be surrounded by double quotes. If it is integer data there are no double quotes around the data. Here's the rub – The Advokit import utility wants to receive all of the data as text, regardless of its final disposition. So, a usable CSV file will be in the form of "field1data","field2data","field3data","field4data" etc. If you create a (perfectly legal) CSV file that looks like this: "field1data","field2data",field3data,"field4data" you will have problems (note that field3data is not surrounded by quotes because it was presumably an integer value). You need to be careful to export the data from your database program as all text with no integer, numeric, etc data types in it.]

6. Do final preparations for loading the CSV file onto the server. Make sure that the first record in the CSV file contains all of the field names in CSV format, i.e. "fieldname1","fieldname2","fieldname3", etc. Also, make sure that there are no extra carriage returns at the end of the last record – it may cause problems at the end of the import process. Load the CSV file onto the server. In my case I used a freeware FTP program to upload it into the appropriate directory (/voterfiles/). My file was 80 MB and this took about 45 minutes to upload to the server on my cable connection. It would have taken considerably longer on a dialup connection.

7. Download and alter the import.pl file Use your text file editor to include the information which may be unique to your situation- near the top of the file you will add appropriate information to the

lines. (Several of these parameters are unlikely to change. I.e. 'localhost', 3306, 'root' are examples of information that is not likely to change).

When you have completed editing the import.pl file – save it (it's a text file) and upload it to the server.

8. Mapping your data to the Advokit standard MySQL data. Log into Advokit as a Team Leader. This should have been set up previously from an administrative level. When you are logged in as a Team Leader you will see an option on the left menu bar to "Upload Voterfile". Take the link and follow your nose. You will first identify the CSV file that you uploaded to the server. When you click the "proceed" button you will be presented with a mapping utility. On the left side will be a list of all of the fieldnames from your CSV file. (Folks who have more fields will have a longer list.) This is when your knowledge about the Advokit fields will come in very handy. Using the selection lists in each column you can show the connection between specific fields in your CSV datafile and the fields that Advokit has arranged. When you are done you will click your way through (You'll have to confirm a check box along the way). This is also where you can add some custom fields if your CSV file has them in it. When you have completed the mapping process Advokit will have created a text file with the extension ".map" in the /voterfile/ directory where you previously had the CSV file and the import.pl file.

[Note on Mapping file: If you take a look at your map file you will see that all Advokit did was to create a CSV list of several columns – one column for each of the four tables and an extra one for the custom fields if you added them. Here's the first row of that file in my case:

"csv_column","respolis_column","residence_column","mailaddress_column","voter_column","custom_column"

what follows is a whole list of every field in the CSV file followed by the various Advokit fieldname(s) that correspond to that field in the order shown above. Thus, if you were a careful text editor of your mapping file, you could bypass the Mapping utility]

9. Time to Rock and Roll. All of the pieces are now in place to do the import itself. This is best done from the command line of the server by the server administrator due to permissions issues and server security policies which might interfere or make impossible your executing the command. It may be possible to arrange a Cron job to do this, if you have the appropriate permissions on the server. In our case we were on a shared hosting server with many other accounts. So, for simplicity, we emailed the system administrator and asked them to run the perl command from the server's command line. We gave them the exact command syntax to make it easier for them to just cut and paste the command onto their command line. The basic syntax is:

perl import.pl <mappingfilename.map> <csvfilename.csv>

(note the three spaces in this commandline)

In practice, the command can be quite long since it needs to have path information in it. Ours (ignore the wrapping, but not the spaces) was:

/usr/bin/perl /home/httpd/vhosts/ourdomain.org/aboverootdirectory/advokit/voterfiles/import.pl /home/httpd/vhosts/ourdomain.org/aboverootdirectory/voterfiles/SLOcsvTestSnippet060205.csv-2006-02-05-17-54-16.map /home/httpd/vhosts/ourdomain.org/aboverootdirectory/voterfiles/SLOvotersAll060206.csv

That's It! The import.pl script will do its thing and report what is/has happened on the system. This may take some time, so be patient. I am told that really long files can take some time to handle (ones in the hundreds of thousands of voter and up category) If all goes well you will be in business with voter data at that point. Our file had 150,000 records in it and it took about 50 minutes. (There were no complaints about how long it took from the system administrator, so we assume it was a background task. We also asked him to run it in the middle of the night)

10. Examine the results. When you have been notified of the outcome of the import.pl script, log on to the server and open phpMyAdmin where you can look at the data and all of the Advokit tables. You should see the same number of voters in the "_voters" table as your CSV file if this is your first upload. Note that the number of records in the "_residence" "_mailaddress" and "_respolis" tables will be a lesser number. This is because Advokit only stores one record in "_residence" for each house. Thus, because there are often several voters at the same address – that address will only appear once in the "_residence" table. Make sure the data is in the right places. Congratulations!

Voter Tables