I'm just getting started on writing documentation for Advokit 2.0. This "Advokit 2.0 Guide" is envisioned as a comprehensive guide for campaign leaders in how to set up and run a campaign using Advokit. I hope to be adding and editing pages frequently over the next couple months. - Pat
to be written (origin and concept, Advokit1 history, thanks, etc)
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...
to be written
Before any activist jobs can be created on teams and before any users can be plugged into activist jobs, the campaign leader must define one or more activist job types. By defining job types, a campaign leader determines what different kinds of activists will be expected to do and what functions they will have available when they log on to Advokit. (A job type is not the same thing as a job. A job can be thought of as an instance of a job type on a particular team.)
Job types are critical to determining how your campaign uses Advokit, and creating them in such a way as to accurately describe what is expected and to provide the tools for the work you want your activists to be doing is one of the most important steps in setting up a campaign in Advokit. Defining your job types should be part-and-parcel with your overall campaign strategy. If you are unsure how to set up your job types, and even if you think you are sure, you may want to consider an early "testing phase", where you unleash a limited number of activists in order to guage the way you have things set up, prior to a wider rollout. This period would also give you a chance to tune other things like your questionnaires, your voter filters, etc.
Note that what we are discussing here are activist job types. There is also such a thing as a leader job type, which is what applies when you are given a job as a leader of a team, operation or the campaign. Leader job types do not have any configuration options and are not listed among these configurable job types - they are already "built-in".
There are two classes of activist job types: voter-contact and task-handling.
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:
Advokit supports three scenarios for how activists get the names of voters to contact:
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 (
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.
|
Frequently, when a voter has been contacted by an activist in a campaign, there may arise as a result of that contact some followup task that needs to be completed by someone else in the campaign. A common example is when a voter needs to be sent some materials by the campaign: literature or registration forms, perhaps, where it makes sense to keep inventory and expense tracking in one place. Other common examples include: a follow up phone call from someone better equipped to respond to a voter's question; distributing lawn signs; arranging rides to the polls or child care; etc. In Advokit, these cases are best handled through Tasks.
The process of creating and handling tasks goes like this:
To enable this to happen, there are a small number of configuration steps that must be completed first.
Where you put your task handling jobs in your team hierarchy is entirely up to you. Tasks are not sensitive to organizational structure - they will appear on the pending tasks list for any job of that task-handler job type, regardless of where the task handler job is located, or where the voter-contact job was that created the task. One good practice is to create a separate operation just for task-handling jobs. That way, the supervisory relationships for task handlers are consistent and clear, and they do not get lost in the rest of your organizational structure.
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.
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.
to be written
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:
Some things to know about questions:
A few tips about questions - keep it simple:

When you are ready to have the questionnaire appear on contact sheets, be sure to activate it by clicking on the ACTIVATE link!
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:
![]() |
|
Question options:
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
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.
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...
For questionnaires, you can...
If you click 'EDIT', you will see a screen like this
On this screen you can
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.
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.
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.
to be written
to be written
Add activist, Recruit voter, Self registration
to be written
to be written
to be written
to be written
to be written
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