Free Software?

CiviCRM is Free Software - this means it is developed by a community and licensed in a generous way so you can use it for free for whatever you want.

Free Software (sometimes also referred to as Free and Open Source Software,  FLOSS, FOSS, Software Libre,  or Open Source) is software that anyone can download, share, and -- significantly -- change in any way they want. Practically speaking, you might never want to change the software, or even have a staff person who can read the source code (the instructions written by programmers). But the ability to change the software protects you in many ways:

That may be enough for you, but for the sake of completeness we'll offer some widely used definitions:

"Free software or software libre is software that can be used, studied, and modified without restriction, and which can be copied and redistributed in modified or unmodified form either without restriction, or with minimal restrictions only to ensure that further recipients can also do these things and that manufacturers of consumer-facing hardware allow user modifications to their hardware. Free software is available gratis (free of charge) in most cases."
(from: http://en.wikipedia.org/wiki/Free_software)

"Open source software (OSS) is defined as computer software for which the source code and certain other rights normally reserved for copyright holders are provided under a software license that meets the Open Source Definition or that is in the public domain. This permits users to use, change, and improve the software, and to redistribute it in modified or unmodified forms. It is very often developed in a public, collaborative manner."
(from: http://en.wikipedia.org/wiki/Open_source_software)

Nearly any software that qualifies as free also qualifies as Open Source, and vice versa. The main reason that two different terms exist is that "free software" emphasizes the freedom aspect (that you aren't under the control of the original programmers) whereas "open source software" emphasizes the convenience and potential for innovation provided by having the source code available.

When you install and use CiviCRM, you'll notice there's no annoying click-through software license imposing a thousand things that you can or cannot do with it. That's because free software doesn't limit your right to do with the software whatever you want. Free and open source software have licenses, but they're simpler than and quite different from proprietary software ('closed software') licenses. CiviCRM itself is available under Affero General Public License version 3.0, one of the popular free software licenses used by many other projects.

Free Software and non-profits

Explaining all of the possible considerations on using FOSS in non-profit and advocacy work might take a really long time, so let's focus on the most important highlights:

Apart from the quite practical advantages listed above, there is also a more philosophical approach to answering the question of importance of FOSS for non-profits and advocacy organisations. Without getting too deep into philosophical discussions, there is a great overlap between values shared by non-profit organisations and these shared by Free and Open Source Software communities. By working with the community of users, providing your feedback, contributing your changes back into the project, you're actually strengthening the non-profit sector.

Further Reading

Free Software Foundation
http://www.fsf.org/

The Free Software Definition
http://www.gnu.org/philosophy/free-sw.html

Open Source Initiative
http://www.opensource.org/

The Open Source Definition
http://www.opensource.org/docs/osd

GNU Affero General Public License v3
http://www.opensource.org/licenses/agpl-v3.html

Choosing and Using Free and Open Source Software: A primer for nonprofits
http://www.nosi.net/projects/primer

ACTIVITIES

Activities are a key concept in CiviCRM. Activities track interactions between the organisation and its staff, volunteers, clients or other contacts at a specific point in time. All of CiviCRM's components make extensive use of activities, such as recording contributions, event attendances, membership subscriptions, and emails and for each of these an activity is automatically created.

Several activities are included by default but you can create additional activity types to define specific things that your organisation does and you can add custom fields to activity types to allow specific data to be collected around some these activity types. So you might create activity types: training and interview and set up a custom field set that includes information such as funder, project, etc. for each of these activities. This would enable you to produce reports of all the activities undertaken for a particular funder or as part of a particular project. You could also create a custom field for a particular activity type so that you could classify meetings as staff meeting, client meeting, other organisation's meeting etc. For more on creating custom fields refer to the Custom Fields chapter. For details on producing reports, see the Reporting section.

Activities have the following attributes by default:

Activities and groups. There can be some overlap between the use of these two. For example you could choose to record a membership packet being sent to a contact as an activity or simply add the contact to a group "received membership packet". It would probably be better to record this as an activity as then you can record when the membership pack was sent, who sent it, any notes about what the person requested, and so on. You could also use the activity to schedule sending membership packs by setting the status to scheduled.

Activities and events. It's also important to understand this distinction. For example should training be recorded as an activity or an event? That probably depends on whether the trainings are delivered to multiple people on a predetermined date or to individuals on a date that is negotiated. Also in contrast to a scheduled event that people attend, an activity can record something that happened in the past or is scheduled in the future. It's nearly always the right choice to record interaction between a staff person and someone contacting your organisation for service.  

Creating new Activity Types

Go to the Activity Type Options page Administer -> Option Lists -> Activity and click on Add Activity Type. Fill in the name and select the component you want to use this activity with: simply for contacts or for use in Cases (for more about Cases refer to that section). Finally enable the activity. Changing the weight will make the activity appear higher up or lower down the list of activity types.

 

Setting up Custom Field Sets for Activities 

When setting up custom fields for an activity, you can choose which activity types the custom field set should apply to. 

 

Activity Status Options

The default set of status options is 

If you need to add more options this is possible although there is no direct menu link to do so. The path to reach this page is /civicrm/admin/options/activity_type?group=activity_status&reset=1. 

However, before you add too many status options, remember that all status options show up on all activity types so think carefully about what you need to add.

 

Bug Reporting

Like all software there will be times when you use CiviCRM when things don't work the way you expect them to.

A good first step is to search the forums (http://forum.civicrm.org) for similar problems and follow advice given there.  If your problem hasn't been addressed, posting to the forum is probably the right thing to do.

Before posting its a good idea to look on the forum for good posting guidelines and spend a bit of time writing your post. Make sure you are detailed and specific about what software you are using (i.e. the version of CiviCRM, which CMS platform and its version, and which browser and its version), what you are trying to do and how you are trying to do it. For example letting people know the url you are using (with any confidential details removed) may cause them to realise that you are configuring the wrong page. Unclear posts are less likely to get good replies.

Using older versions of CiviCRM

If you are using an older version and the problem you are experiencing is a bug that has been fixed in the lastest release, be prepared for the answer "that it is time to upgrade to the latest version." Although the CiviCRM community tries to be as helpful as possible, and we recognize that upgrading puts a burden on your organisation, it is difficult to support multiple versions simultaneously.

What causes problems with CiviCRM?

Check the following possible sources of problems before you report something on a forum. You can save yourself and a lot of people trouble by isolating the problem. CiviCRM forums try to be friendly and don't criticise you for misjudging a problem, but you'll certainly get more help and resolve problems faster by doing some checking of your own first.

Recreating your problem on the demo site

Recreating your bug on one of the demo sites (http://demo.civicrm.org and select the demo site that matches your CiviCRM version) helps determine whether your problem is a result of a bug in the source code, or as a result of changes on your site. If you can show us that the code on the demo site turns up your bug, it's very likely that the CiviCRM source code is the problem, and your demonstration will help us find and fix it.

Still, no demo site can cover all possibilities. Issues involving email output or payment processing cannot be recreated on the demo sites.  So even if you can't reproduce your bug there, it might still be a bug in CiviCRM. It is, however, probably triggered by your server setup or other customisations.

Write to the forum and explain the problem you are experiencing. If the bug was reproduced on the demo site, describe exactly what you did there, and copy the demo site's URLs to document the steps you used. If not, include as much information about your server setup as you feasibly can. Configuration files from the web server, CMS, and CiviCRM will be valuable, but be careful to not including sensitive information such as your database log-in.

If the forum suggests you discovered a bug in CiviCRM, you can report it to the CiviCRM issue tracker (http://issues.civicrm.org/jira/browse/CRM).

Writing good bug reports

The best bug reports give lots of background and context.  Don't forget that the way you are using CiviCRM is most likely very specific to your organisation.  The more background you can give on the bug, the better.

The best bug reports clearly state:

Fixing bugs

The amount of time taken for the bug to be fixed depends on the severity and complexity of the bug.  It could be as quick as the same day, but it could take much longer.

To get bug fixes, the easiest way is just to download and install the latest revision of CiviCRM. Downloading bug fixes between releases and fixing, called patching, your existing software is possible. If you have technical abilities, then refer to the CiviCRM Developer's Guide for instructions on applying a patch, otherwise, seek out technical assistance to provide tests and a patch for the issue.


Set-up

This chapter will help you to set up with CiviCampaign so that it enhances the effectiveness of your organization's campaigns.

Enable CiviCampaign

First, you need to enable the CiviCampaign component.

  1. Go to Administer > Configure > Global Settings > Enable CiviCRM Components.
  2. Select CiviCampaign and click Enable. 


Once CiviCampaign is enabled, it will show up as a new menu item Campaigns along the top of your CiviCRM screen.


Add a New Campaign Type

CiviCampaign provides three default campaign types:

You can add any campaign type that is appropriate for your work (and disable those that aren't). 

To add a new campaign type:

  1. Go to Administer > CiviCampaign > Campaign Types. 


      
  2. This will display a list of existing campaign types:

  3. Click on Add Campaign Type, and give the new type a label and a description (optional).
  4. Optionally, change the default weight: this affects the order in which this new event type appears in drop-down menus (smallest numbers appear highest).
  5. Click Save.

The next time you add a new campaign, this campaign type will be available to assign to your new campaign.

Campaign Status

Assigning a status to your campaign makes it possible to update campaign activities in the database and track how the campaign is proceeding. 

  1. Go to Administer > CiviCampaign > Campaign Status. 


    The default statuses are Planned, In Progress, Completed, and Cancelled.
  2. Click Add Campaign Status, give it a name and, optionally, a description. 
  3. Changing the weight is not necessary but will affect the order in which this new status appears in drop-down menus. 
  4. Click Save and the new status will then be availble to assign to campaigns. 

Engagement Index

CiviCampaign allows you to track an individual's level of interest/engagement in a particular activity. The Engagement Index can be recorded for general activities or actions, i.e. Send an Email, Meeting, Phone Call, Interview, and any additional custom activities/actions you create. To find out more about how to record an activity to an individual, see Contacts in the Organising Your Data section.

To configure the Engagement Index:

  1. Go to Administer -> CiviCampaign -> Engagement Index.
  2. Configure the engagement index as a number, e.g. 1 is a high level of engagement, and 5 is low level of engagement. 
This information can supplement your outreach employees' or organizers' assessment of member engagement/interest in your organization. 

EVERYDAY TASKS

This chapter describes everyday tasks related to managing campaigns with CiviCampaign.

Managing Campaigns

The Campaign Dashboard allows you to create, configure, manage and view your campaigns.  You can also manage surveys and petitions via the Campaign Dashboard (refer to the following chapters on Surveys and Petitions for specific information).

To view the Campaign Dashboard, go to Campaigns > Dashboard > Campaigns.


From the Campaign Dashboard, you can then Edit, Disable and Delete existing campaigns, and create new campaigns.

Create a New Campaign

To create a Campaign:

  1.  Go to Campaign > New Campaign.
  2. Enter information about your campaign:

What You Need To Know

Before you create a campaign, it's a good idea to review the concepts in this chapter to understand how CiviCampaign can best help you manage your work, and consider the key questions in relation to your organisation's specific needs. 

Key Concepts

Your organisation will likely have its own campaign strategies and processes. CiviCampaign is a tool that you can use in conjunction with your existing methods, to streamline and automate certain processes. 

Campaign Goals and Revenue

Define and document the concrete goals of the campaign, and what you hope to raise in funds (if applicable), and record it in the campaign information. This will enable you to use reports to analyze the effectiveness of a campaign at its conclusion.

Planning Your Campaign Activities

As you plan the strategy of your campaign and identify your target audience, determine what activities and information can be recorded within CiviCRM. Make sure that all recorded activities and information is connected to the campaign, so that you can track all efforts and individuals' activities related to the campaign. This allows you to to make periodic and overall evaluations of the effectiveness of your activities, strategies and outreach efforts.

Key Questions 

Answer these questions in the context of your organisation or a specific campaign:

CiviEngage and CiviCampaign

CiviEngage is another component that enhances CiviCampaign with more functionality for surveys and pre-configures your installation of CiviCRM with custom data sets, profiles and enhancements to reports. See the section Civic Engagement for more details about CiviEngage. 

REPORTS AND ANALYSIS

There a few searching and reporting tools at your disposal to report and analyse your campaigns.

Campaign searches

All searches for components that can be part of a campaign have a campaign filter so that you can search for events, contributions, etc. based on campaign.  Similarly the tabs for components in advanced search also have a campaign filter so you can search for contacts based on their participation in campaigns.  

Campaign reports

The most useful report in CiviCRM for campaign analysis is the activity report.  The activity report can be configured to show the campaign that this activity was part of and also the engagement index for the activity. The activity report can also filter by campaign. 

 

What is CiviCampaign?

CiviCampaign lets you link together events, mailings, activities, and contributions under one "umbrella" so that you can track the progress of all your efforts towards one programmatic goal or campaign. This enables organizations to measure and analyze the effectiveness of their outreach and mobilization efforts.

CiviCampaign allows you to:

CiviCampaign is integrated with other CiviCRM components so that you can select which activities are part of of the overall campaign or goal.

For Drupal sites, the CiviEngage module enhances CiviCampaign by providing a package of custom fields that enable the Survey and Petition features of CiviCampaign. Read more about CviEngage in the Civic Engagement section.

Scenario: Year-long mobilization campaign

To kick off a year-long campaign to mobilize community members, the Townsville Organisation For Tenants (TOFT) held a protest at the Capitol. The campaign organizers use CiviCampaign to associate all related campaign activities together over the course of the campaign.

The lead organizer created a campaign called "Mobilize the Masses 2011" to link a series of related activities including communications about the mobilizing event, participation and financial contributions for transport and food during the action.

Using CiviCampaign, the organisers:

Periodically throughout the campaign, the program lead searches all of the activities related to the campaign, and/or individuals who have activities related to the campaign, to monitor the effectiveness of their outreach and fundraising efforts, and if necessary adjust strategies.

Organizers can relate subsequent events, mailings, and other activities with the same campaign as it proceeds over the course of the year. At the end of the campaign this information can be reviewed within the context of the whole campaign.

Reports and analysis

There are a number of techniques for reporting on and analysing your casework.  The case dashboard gives a very useful quick overview of your current cases, with rows for each case type and columns that show current totals for each status. Clicking through any number (0 will not be linked) will take you a list of all the cases of that type in that status.

[insert screenshot]

That's a good start and can provide a good overview for an administrator but there are a couple of ways that you can create more detailed and customised views of the data for case workers and administrators using CiviCRM's search features and CiviReport. 

CiviCase Reports

There is no report template specifically for cases, but since cases are made up of  activities the Activity report will usually play an important part here. The Activity report template is particularly useful for providing a dashlet for each user involved in casework so they can track all activities assigned to them. Given that these case activities will be displayed alongside other non-case based activities, you may want to implement a protocol for activity names which include some kind of case reference.

Printing Case Reports

To print a report that lists all case and case activity data:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click Print Case Report in the Case Summary section.

Your installation may define additional reports for audit or quality assurance purposes. If so, you will see them listed in the "Run QA Audit/Redact" dropdown menu.

Searching based on cases

There is a Find Cases search which allows you to search on Case Type and Status as well as by client name or email. This is a useful quick search to identify a few cases that may need specific input if the case dashboard is quite large and cluttered in your instance.


The Advanced search provides these options combined with all the other normal search criteria so you can find case types filtered by location or custom fields applied to the contact


Also useful can be the Activity Search which is located under Search -> Custom Searches -> Activity Search.   Unlike Advanced search, this is just based on activities and not contacts.

Further analysis

If the combination of Case Dashboard, CiviReport and the contact and activity searches aren't giving you want you want, consider commissioning a new report or custom search.  Read the CiviReport section and the 'Search and actions' chapter for more information.

Real World Examples

CiviCRM is used by all shapes and sizes of organisations that are located all over the world. Some have no paid employees, while others might have several hundred. Their needs range from very simple to fairly complex. In this chapter, we will have a look at real world examples of how organizations are using CiviCRM.

Throughout this chapter you will see references to CiviCRM features such as CiviEmail, CiviMember, CiviPledge, CiviCRM Profiles and others. These are all components of CiviCRM and we have included references to them so you can become familiar with the language of CiviCRM; however, it's not important to understand the finer detail of these features at this point.

A Spectacular Performance

garland_logo

This example shows how clubs can use CiviCRM for summer camps, regular classes and other events.

Wellington Circus Trust in Wellington, New Zealand is run entirely by volunteers. They have a mailing list of 500-600 people and run blocks of classes in circus skills such as trapeze and hula hoop. They also host events. For safety reasons, the Trust needs to gather information about who to contact in the case of a student being injured. The Trust processes about 200 enrolments a year.

Prior to using CiviCRM, the Trust maintained a Microsoft Access database, but data entry was time-consuming, keeping information up-to-date was difficult and emailing the resulting contact information to the tutors on a regular basis was challenging. The treasurer wanted members to be able to maintain their own details and wanted the tutors and volunteers to be able to access member's contact details from anywhere.

What They Did

After some research, the Trust decided that CiviCRM could enable them do the things they needed to do, and as soon as the system was up and running they began to make the most of it.

The Results

Simply by implementing CiviCRM, tutors and volunteers can now access and manage information from anywhere in the world where they have internet connectivity.

By implementing CiviEvent with a payment processor and custom data fields, people are able to enroll in and pay for classes online and provide the important emergency contact information at the same time. Allowing people to sign-up online has greatly reduced the amount of time spent on data entry.

By integrating CiviCRM with Drupal and setting up user accounts, contacts are able to maintain and update their own information, greatly reducing administration time and improving the accuracy of the data.

Implementing CiviMail has made it easy to email tutors, volunteers and students, and removed the administrative burden of manually updating the mailing list and contact information because contacts can do their own updates. The treasurer also found that it saved her from having hundreds of sent items in her email client, which used to be the result of using Microsoft Office mail merges to send out email newsletters.

Prior to implementing CiviGrant, the Wellington Circus Trust had not been effective at tracking the status of grant applications. By using CiviGrant, they are now able to see at a glance what grant applications had been sent and the status of each application.

All up, the Trust estimates that installing CiviCRM has saved hundreds of volunteer hours over the course of a year.

After moving to CiviCRM, the Trust found that both contact management and class registration were easier. One issue they encountered was that some people were confused about having to reset their Drupal passwords. The Trust thinks that putting more effort into the way they explained this on their website would have helped. Another issue was the standard PayPal interface which was initially implemented as a payment processor; people found this difficult to use, and after six months the Trust invested in developing a payment processor more appropriate to New Zealand.

They also learned that a cheap hosting provider is not always the best option: quite a bit of time was wasted before they switched from a free provider to one that costs them approximately $NZD20 per month and provides significantly better service.

Suffering Relieved!

afsc_1

The American Friends Service Committee (AFSC) is a large, Quaker-based, peace and social justice organisation with over 400 employees. Worldwide, they run programmes that work to relieve and prevent suffering through both immediate aid and long-term development, and they seek to serve the needs of people on all sides of violent strife.

Their main headquarters are located in Philadelphia, Pennsylvania. They have nine regional headquarters located throughout the United States, some 50 area offices also located in the USA, and numerous international field offices located in Africa, Asia, Europe, Latin America, the Caribbean and the Middle East.

Lists of constituents are maintained by each office. The specific CRM system needs of each office vary but the general needs are: searching for constituents that meet certain criteria; sending emails, newsletters, postal mail and announcements; and collecting the contact information of people who sign online petitions and register for events online.

Through a survey conducted by the AFSC Information Technology Department, it was revealed that AFSC staff were using a variety of systems to keep track of their constituents. It also became obvious that these systems were not working effectively: repositories of data were everywhere, contact information was duplicated, staff were having a hard time managing their contacts and the IT Department was unable to provide adequate support.

The survey also found that staff members were frustrated with the systems they were using because they lacked the necessary functionality for them to effectively communicate and do outreach. Specifically: search capability was limited; there was no ability to send high-volume emails which meant that it was not possible to send newsletters or announcements; and there was no ability to collect information online.

After investigating several database systems, the IT Department finally decided that, all things considered, CiviCRM might be the best fit for the AFSC.

What They Did

Initially, CiviCRM sites with CiviMail, managed by an external vendor, were established for offices in Los Angeles, Rhode Island, San Francisco and Seattle. Los Angeles also chose to use the CiviEvent component to track event registrations and the CiviMember component to track contact information of committee members.

After implementation, an LA staff person discovered that certain functionality was missing from the CiviMember export component and this was preventing them from being able to compile a membership directory. AFSC talked to the CiviCRM Core development team and contracted them to add the missing functionality. This was a win-win situation: AFSC got the functionality they needed and because it was integrated back into the CiviCRM product, the entire CiviCRM community was able to benefit from the addition. An extra advantage for AFSC is that because the functionality became a standard part of CiviCRM they don't have to worry about compatibility with future upgrades.

The Results

The decision to have their sites hosted and managed by an external vendor turned out not to be a good one when the vendor ran into difficulties and was not responsive to issues or in providing the services that had been promised, such as timely updates for CiviCRM. Once the hosting issue was resolved, staff were able to take full advantage of the capabilities of CiviCRM and do all of the things that they had previously been unable to do.

The Los Angeles office is in full swing, using CiviCRM as the main repository to track their constituents, board, committee members and volunteers. Their constituents are able to sign up for events and petitions online, and staff can send volume emails for newsletters and announcements.

Getting rid of their old system and being able to send out a monthly newsletter was the main goal for the Colorado office, who came on board with CiviCRM a little later in the process. They are now able to identify newsletter subscribers and send the newsletter to them via CiviCRM. They couldn't be happier!

The AFSC currently has nine CiviCRM sites and the IT Department is now recommending CiviCRM as the "database of choice" for all of its offices. Support from the CiviCRM community is excellent and CiviCRM itself is improving every day, as more and more functionality being added. AFSC staff are now able to access their data from any place that has internet access, run complex searches, manage online event registrations and send online newsletters and postal mailings. CiviCRM has enabled them to better manage their constituents. This makes their life easier and in turn, is of great benefit to AFSC.

Activating the Community

heal

The Healthy Environment Alliance of Utah (HEAL) is a grassroots environmental organisation working to protect Utahns from nuclear and toxic waste. Before moving to CiviCRM, they were stuck with a Microsoft Access database. They may have called it a database, but in fact it was a glorified spreadsheet that did little to facilitate their day-to-day operations. The goal for the CiviCRM project was to move to a system that would centralise all of their information across their organisation including email lists, volunteer tracking, donor history and more. As an advocacy and community action organisation, effective engagement with their supporters and tracking the relationships they build with their constituency over time is critical to their mission. They needed a tool to support that mission.

What They Did

HEAL has been using CiviCRM since the early days of the software and CiviCRM is now the central place to track all donors, volunteers, legislators, foundations and contacts. They use CiviCRM for donor management, email communications, event management, volunteer tracking, and advocacy.

The Results

There is no question that CiviCRM streamlined and consolidated HEAL Utah's data management and saved the organisation valuable resources. It is interesting to note that over the last several years their advocacy campaigns have been more successful and their impact in their community more noticeable - perhaps in part because they have been able to redirect limited resources away from administration and into the real work.

The biggest lesson that CiviCRM has brought to HEAL is to force them to always think about what role technology will play in their outreach and organising work.

A CRM Education

Schoolhouse_Supplies_medium72dpi

Schoolhouse Supplies (SHS) is a Portland, Oregon, USA-based non-profit organisation which gathers and distributes school supplies to students and teachers.

Prior to implementing CiviCRM, SHS used a combination of software programmes including Exceed, EROI, Constant Contact, Salesforce, Auction Pay (for online contributions) and, of course, hundreds of spreadsheets. In addition, SHS had a custom web application for managing its online store inventory and processing in-kind donations.

What They Did

By moving to CiviCRCM, SHS has centralised their operations and the management all their constituent data, and been able to unify and coordinate several of their core business processes.

All data from each source has been migrated to CiviCRM Standalone (an installation that is not integrated with either Drupal or Joomla! CMS). CiviContact and CiviContribute have replaced Exceed and Auction Pay. CiviMail has replaced EROI and Constant Contact. Salesforce data was moved into CiviCRM and the custom e-commerce application it supported was integrated with CiviCRM. Lastly, the inventory and in-kind management system was integrated with CiviCRM. Spreadsheets have been imported.

The Results

Each business process at SHS can now take advantage of their full constituent database and business activities are easily coordinated. More importantly, SHS is now in the process of taking manual business processes (such as volunteer coordination) and moving them to CiviCRM. New campaigns are now being planned and executed which would previously have been impossible or prohibitively expensive.

Growing Satisfaction

nysnla

The New York State Nursery Landscape Association (NYSNLA) is a member-based association providing resources and advocacy support for nursery and landscape professionals throughout New York State. The organisation seeks to advance the interests of New York State's nursery and landscape businesses and professionals by promoting sound business practices, expanding state and local markets, and exercising leadership in the development of sustainable communities.

Prior to migrating to CiviCRM the Association went through several iterations of member-management solutions, beginning with a series of spreadsheet documents and later moving to a Microsoft Access database. The move to CiviCRM was prompted by the desire to consolidate data, provide members real-time access to contact details, and to create a searchable member directory to website visitors who may be looking for a nursery or landscape professional.

What They Did

Working with a CiviCRM consultant, NYSNLA began the process of analysing the structure and content of their existing database and mapping the various functions to CiviCRM structures. They determined that they would use CiviMember, CiviEvent, CiviContribute, and CiviMail to address their core database needs, and would consider using CiviPledge at some point in the future for soliciting contributions to their associated non-profit, the Nurserymen's Foundation.

One data area that required particular attention was their Certified Nursery Landscape Professional program (CNLP). CNLP is an intensive, on-going educational programme designed to increase the skills of garden and landscape employees. The programme was designed by members of the nursery and landscape industry with assistance from Cornell University. Interested individuals must apply to the programme and successfully pass a test. Certification lasts two years, after which time the individual must recertify.

NYSNLA used CiviCRM's membership functionality to track the status of CNLPs. The ability to define a rolling-period membership and to gauge when they are nearing expiration perfectly met their management needs. The initial application process, which also must be carefully tracked, was handled through CiviEvent, as an application to the programme is essentially a registration to attend one of the bi-annual test events.

The Association also took advantage of CiviCRM's open source platform to make some interface customisations that improved the way they view contact records. Because of the importance of the CNLP programme, they wanted to be able to look at all employees for a certain nursery/landscape company and quickly know if any of them are CNLPs or Lifetime CNLPs. They also needed to easily find out which employees are authorised to manage the company's records.

The Results

The Association has worked hard to communicate to the public the importance of using a qualified landscape professional. Essential to this effort was the inclusion of a searchable member directory on their website. Using CiviCRM, they were able to create a search page that included geographic segmentation (the Association divides members into 8 regions state-wide) and a list of services provided by members (using CiviCRM's tags feature). The resulting search tool, because it is directly connected with their contact data, ensures website visitors are always looking at current information. The Association is also able to provide members direct access to their own contact details so they can update and maintain their list of services provided and other information.

Campaigning for Efficiency

Newlogo_1

The Green Party has been the third largest party in New Zealand politics for most of the last decade, with strong roots in the Values Party (the world's first national Green party) of the early 1970s. They achieved parliamentary representation in 1996 and after the 2008 election had 9 Members of Parliament, 5,000 financial members and some 50,000 contacts. The Party has more than 50 branches around the country and contest elections across all 67 electorates in the last election.

Prior to adopting CiviCRM, the Party and its parliamentary units employed a range of systems for managing members, donations, contacts, campaigning, media and advocacy.

The Green Party policy states:

What They Did

CiviCRM was adopted by the Party in 2007 (version 1.7), with a switch to Drupal as a parallel project. This was inspired in part by work done by the Canadian Greens on developing a voter canvassing module for Drupal. A Party database was set up using CiviCRM and online donations, memberships and event registrations were instigated.

The Greens have over 100 different issues that they generate media releases about. These were reconstructed as a check-box custom data field, and Smart Groups were built for each of these, for use when sending out media releases via CiviMail.

The highly complex access control requirements of the party necessitated the development of an alternative approach to the use of ACLs (Access Control Lists) in order to provide a more easily managed, highly granular system. This approach has now been incorporated as a hook (something that can be utilised by developers to extend CiviCRM) into the core code.

For the 2008 election campaign, a look-up function was developed so that when new contacts were added to the database, addresses were checked against a table containing the Electoral Roll, and links were created where matches were made. "Soft" matches were also recorded.

The Results

In the 2008 election campaign, the Party made extensive use of online fundraising and greatly exceeded previous online income. Membership renewal has been streamlined with more online renewals occurring.

As of May 2009, the Party was still using CiviCRM v2.0 on Drupal 5 and therefore had not yet benefited from the many features that became available through the 2.1 and 2.2 releases. An upgrade was in progress at the time.

In a complex organisation such as the Green Party, training can be a limiting factor, as well as the need to nurture more in-house super-users. New features in CiviCRM have led to some rethinking about the Party's usage of custom data fields, particularly with regard to the use of CiviMail for media releases. New options for both nested groups and Drupal Organic Groups suggest that a more time effective approach may soon be possible.

Quest for Success

quest_bridge_logo

QuestBridge is dedicated to helping bright, motivated low-income high school students get accepted to and able to pay for college. QuestBridge recruits high school juniors throughout the USA and invites them to fill out the QuestBridge application online. QuestBridge also partners with the USA's most selective colleges and universities with the aim to increase the socio-economic diversity of their student bodies. QuestBridge's college partners accept the QuestBridge application in lieu of their own admissions application.

What They Did

QuestBridge has built most of its business processes around CiviCRM. They wrote their online admission application using CiviCRM and extended it using the PHP scripting language. CiviCRM is used to store biographical and application information and communication histories about the students.

The Results

QuestBridge

In the 2008-9 school year, QuestBridge helped more than 1200 students get accepted and pay for college at its 25 partner schools. They accomplished their goals in a very efficient manner, in part thanks to their effective implementation of CiviCRM. QuestBridge is currently planning to upgrade to the latest version of CiviCRM in order to take full advantage of the new email features.

If Questbridge were to start over they would have invested more in training on CiviCRM up-front.

Changing with the Times

SFS

The San Francisco School (SFS), is a Preschool through 8th grade coeducational school with a diverse student body of about 270 students. Like all schools, communication between the school and families is very important. Whether it's updating a home phone number, email address or allergy, it is essential in meeting the needs of the students. The head of school was a strong supporter of the project from the beginning which led the staff and parents to be able to make a strong commitment to help the project move forward.

What They Did

They used CiviCRM to create a Parent Portal to:

To ease the transition of the school community, each of the above features were shown gradually rather than all at the same time.

The Results

Enabling parents/guardians to view their contact information meant that they could confirm what the school sees and hence notify the school of any changes. Also, they could view their child's after school fees and view a record of what classes their child is signed up for. Online sign ups allow parents the flexibility to schedule parent/teacher conferences and after school classes on their own time. Changing the existing school systems to an online system allowed both parents and staff to work together, view the Parent Portal so that contact information is current, parent teacher conferences are scheduled in a timely manner, and that access to the information is widely accessible.

Who is CiviCRM?

CiviCRM has a unique and diverse community centered around developing, using, and documenting the software. Our community includes the CiviCRM core team, people at the non-profits that use CiviCRM; consultants working with a number of non-profit organizations; programmers and developers, power users, volunteers and community organizers! We are also closely related to many other open source projects.

Each member of the community interacts with CiviCRM in their own way, working to improve the software and how we organize ourselves. The strength of community comes from this diversity and the ease with which someone can join us, and means that we are constantly changing and improving, often in unexpected ways.

Like all communities your membership is characterised by your interactions. If you treat others well, have some fun, and help others, then you can expect to enjoy being a member of the CiviCRM community. But if you are prone to complaining or don't use a respectful tone in communications, or if you see the community just as a resource and not as a collection of very kind, generous and clever people, then you are probably not going to get much of a response. Treat people well and you can find the CiviCRM community fun and rewarding.

History

CiviCRM started in 2004 by Dave Greenberg, Donald Lobo and Michal Mach. The founders had a lot of previous experience working with non-profit organizations and tools. The group was influenced very early by Zack Rosen and Neil Drumm, who convinced them to use Drupal as a fundamental cornerstone for CiviCRM. This decision has meant that the developers have been able to leverage a lot of the functionality that Drupal provides, freeing the team up to focus on building the features necessary to make a great CRM.

In 2005 the first version of CiviCRM was released with two of the core modules in place: CiviMail and CiviContribute (you can read more about these later).

Since those early days CiviCRM has built a large community of users and contributors (there are now over 8000 installed sites), the software has gone from strength to strength (there are now 8 core modules and additional third party components), and the core team has expanded to 8 members. There is also a large ecology of free software contributors around the project and high-profile non-profit organisations such as Wikipedia, Creative Commons, Mozilla, and Amnesty International use CiviCRM.

It's good to talk

CiviCRM is an open and learning community, and people are ready to hear your ideas. If you have a good idea, there's nothing to stop you carrying it out - but the best way to start, is to start talking about it.

If you're not sure where to start, the best place is probably the community forum (http://forum.civicrm.org/). Ask people what they think about your idea. There's a wealth of experience on the forum, and with a bit of luck, someone will have tried something similar before. CiviCRM people are a friendly bunch and their guiding philosophy is collaboration.

Depending on your idea, you'll be directed to the next best place - maybe an article on the blog (http://civicrm.org/blog/), a page on the wiki (http://wiki.civicrm.org/), a teleconference or a meeting up with another community member in real life, yes that's right, REAL LIFE!

Be the change

So you have a great idea. Now you need an equally great action plan to accompany this idea and then you'll need to implement it. Although the CiviCRM community is friendly and supportive and will like to be involved and updated about your project, you'll need to be the driver. How will you get the resources together for your project? How can you fit it in with your day job? Finding a way to simultaneously achieve your own objectives and benefiting the CiviCRM community is the best way of getting things done.

And finally...

If you're a CiviCRM user who has an ongoing relationship with a consultant, there's nothing to stop you from also being an active member of the community. The community really benefits from direct feedback from end users - your consultant is only one person or organization - by asking on the forums you're opening yourself up to help and input from the entire community.

About this book

Understanding CiviCRM - A Comprehensive Guide is written for CiviCRM version 3.3. The majority of the content is applicable for both older and current versions of CiviCRM.

Cover Art (faces) by Kapor Creative: Jake Mix & Trevor Parham (Jake created the illustrations, and Trevor developed the concept of the civi logos as eyes). Cover Art is CC-BY-SA

Content and structure

This book aims to be a comprehensive guide to using CiviCRM for a wide range of audiences. It covers core CiviCRM functionality and CiviCRM's components. Both the book, and the component-specific sections of the book, have the following structure:

Contributing

Like all other aspects of CiviCRM, this book is a collaborative and community-led project which you can contribute to and participate in. Instructions on how to contribute are at the end of this book.

Is CiviCRM for You?

This chapter will help you to decide whether CiviCRM is the right tool for your organisation.

CiviCRM is powerful software and has the potential to help your organisation reach its goals - but it won't be the right choice for every organisation. Here are some ways that you can find out whether CiviCRM is right for your organisation:

Demonstration sites

CiviCRM hosts two demo sites - one for each of the two supported Content Management Systems (CMS) - Drupal and Joomla!. The demo sites present a working copy of the latest stable version of CiviCRM with sample data. You can use them to play around with CiviCRM but be aware that they are publicly viewable so you shouldn't enter personal data.

The demos are available at:

Other people are likely playing on the demo sites at the same time as you, so they may be configured strangely, missing functionality or appear in different languages.

The demos have some limitations - you can't send emails from them, you can't set permissions for Drupal users or do a full exploration of online payment options.

If you are having trouble working on a demo site, contact the CiviCRM core team via the forum or IRC.  If you want a more controlled evironment for exploring CiviCRM, install your own test site.

Test installations

If you have technical skills or are feeling adventurous, you can download and set up a local version of CiviCRM, that is a version that is stored on your local computer rather than on a server on the internet. You'll still access it through a browser, but it will only be visible on your computer. The advantage of a test installation is that you can configure CiviCRM in the way that you want to use it, and experiment with your data.

Up-to-date information for installations (including troubleshooting tips) is maintained at http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades.

Talking to others who use CiviCRM

If you know of another organisation that uses CiviCRM, talk to them about their experience. Obviously the more similar they are to your organisation, the better. If you don't know anyone that is using CiviCRM, have a look on the CiviCRM forums, at case studies on the wiki, or try your local non-profit technology mailing list.

The CiviCRM forums (http://forum.civicrm.org) have a few boards for people who are new to CiviCRM, such as "Pre-installation Questions" (http://forum.civicrm.org/index.php/board,5.0.html). Remember that the forums are staffed mainly by volunteers so you will get a better response if you spend some time formulating an easily answerable question. You can also search the forums and browse for questions that others have asked. If you wish to ask questions or contribute to the discussions you must register first.

Talking to CiviCRM Consultants

Another option to help you understand CiviCRM is to make use of a professional. The CiviCRM website lists professional vendors and consultants that can walk you through CiviCRM (http://civicrm.org/professional), and there are many others; you may find a local website company who has experience with CiviCRM. Consider hiring a consultant for a day to discuss with you how CiviCRM could help your organisation.

Identifying Your Needs?

This chapter covers some basic strategies for identifying your organisational needs, and how they could be met by CiviCRM. It doesn't go into detail about CiviCRM functionality or how CiviCRM stores data (you will find that in other chapters). Instead, we encourage you to first take a step back and think about your organisation.

Your organisational goals and practices

For now, forget about technology and focus on your organisational goals and processes. Here's a list of questions to start you off:

Understand your "contact relations"

The CRM in CiviCRM stands for Contact Relationship Management. By contact, we mean an individual, household or organisation that your organisation has contact with (you may call them members, constituents, clients or some other term).

Many organisations make the mistake of not thinking about who their contacts actually are. Spend some time identifying all the people involved with your organisation. What different types of people do you interact with, and how do they differ from each other? The better you understand them and their interactions with your organisation, the better you can model them in CiviCRM. Anecdotal or systematic feedback from your contacts may be useful here.

Take advantage of institutional knowledge

In thinking about your contacts and their interactions with your organisation, talk to your co-workers, including those who have been around the longest and those who have just joined. Talk to as many people as possible to get a complete picture of their interactions with all kinds of contacts.

As well as talking to people, look at your organisation's data repositories: your databases, spreadsheets, file servers, address books, and any existing stored information you may have that can help you understand who your contacts are and how they interact with your organisation.

Map your needs to CiviCRM

CiviCRM has been designed to be flexible and adaptable, based on feedback from many different non-profits, but it may not map exactly to the ways that your organisation currently works. Doing things the CiviCRM way could mean adapting your workflow and adopting best practice in non-profit technology. Be pragmatic and flexible and consider whether your current working practices need to change.

It's worth remembering that CiviCRM offers many opportunities to interact with your contacts in ways that you have not previously had. Taking advantage of these new possibilities can lead to positive changes and improvements.

Project management

This chapter outlines the parts that typically make up a CiviCRM project and should be read by people about to embark on a CiviCRM project. Some of this information may be obvious to experienced project managers. A comprehensive guide to project management is beyond the scope of one chapter but we have outlined things that are typically encountered in a CiviCRM project and provided pointers on some things to watch out for.

First, some pop philosophy courtesy of Cynthia Tarasco:

"Life is a series of making decisions. Some decisions are easy because they do not require a substantial investment of time or money. Deciding which flavor ice cream to buy fits into this category: if you get vanilla today you can always get chocolate tomorrow. Other decisions are much more difficult because they require substantial investments of resources, and you will be living with your choice for the foreseeable future. Adopting a new CRM fits into this category, so planning and project management are vital".

When you start out on a new CiviCRM project you should spend time thinking about:

People and the project team

Including a wide range of people that represent the different parts of your organisation will help with delivery of your project. A mixture of management and day-to-day staff helps the team to keep an eye on the big picture as well as ensure that the project is ultimately useful to frontline staff.

You'll be exploring new territory with your CiviCRM installation and this can sometimes be stressful. It might be helpful to share project management of the project with others who can give you a different perspective and moral support when you need it!

Managing a CiviCRM project will require a major time investment from people within your organisation, even if you employ an external consultant. Organisations often under-estimate the amount of time that will be required from their staff in implementing an IT project - such as training, modifying existing processes and providing new or updated information to relevant people. It's not something that can be tacked on to the end of an already busy schedule and this should be taken into consideration.

Business goals

You should have a good idea of the business goals for implementing CiviCRM. This could be something like: reduce administrative work in managing events with 25% or manage 25% more donations with the same staff. The goals should be SMART (specific, measurable, attainable, relevant, time-boudn)!

These business goals will help you in directing and managing your project. For example, if the project group for example want some customization that requires budget and effort, your business goals will help you decide one way or the other. The business goals will help you to focus on why you are implementing CiviCRM and what you want to achieve in the long run.

Development

It often makes sense to break development up into smaller more manageable sections, which can be implemented in discrete stages or iterations. A common first phase of development is to choose something simple to implement in CiviCRM, or specific functionality for a team who can then act as CiviCRM evangelists within the organisation.

Implementing in stages allows staff to get used to changes gradually without feeling overwhelmed, and gives the developer or implementer the ability to be responsive to feedback from users during the development process.

Another reason that people choose to develop iteratively is that it is very hard for users to correctly or fully articulate their requirements at the start of the project. Giving users hands-on experience of an early version of the system helps them understand how it works and what is possible. They can then provide valuable feedback and might articulate requirements that they haven't thought of previously.

Implementing your CMS (Drupal or Joomla!) either before or after implementing CiviCRM is another convenient way to split up a CiviCRM project. As well as the normal advantages of breaking up the development into manageable chunks, this helps staff understand the important differences between a CMS and a CRM.

Pilot projects

Pilots help to reduce risk during a project implementation. For example, rather than moving your organisation's entire event management infrastructure to CiviCRM, run one pilot event using CiviCRM and evaluate it. You can then incorporate the learning back into the development process.

Ongoing support and development

It is a mistake to think about a CiviCRM project as a one-off development that will meet the needs of your organisation for the foreseeable future. Organisations constantly change and evolve and your CRM should evolve with you, otherwise it will eventually become out-of-sync with the organisation.

Once you have been using CiviCRM for a while and staff are comfortable with it, you will likely want to take advantage of other functionality. Each improvement or new piece of functionality that you decide to implement in CiviCRM will take resources, so you'll need to plan for these.

Even if your organisational needs don't change, there are ongoing support implications, including:

Training

Training is a significant aspect of most CiviCRM projects. Your training could take many shapes and sizes depending on your users, but it often makes sense to spend resources on formal and reusable training resources (user guides, lesson plans and so on).

CiviCRM's range of functionality can be overwhelming at first (especially to the less technically-minded). Remember that staff who were not involved in the project's early stages will need to have concepts explained clearly to them - things that are obvious to you may be quite foreign to others. 

Trying to cover everything in one training session probably won't be effective; your staff will need time to digest the new ideas. Instead, hold smaller training sessions that introduce concepts and specific functionality, followed by periods of testing, piloting and feedback. Tailor your training for your audience: not everyone needs to sit through a two-hour training session on how to manage events if there is a single person responsible for event management and planning. And where possible, involve staff in training other staff members as this increases the sense of ownership and helps to embed learning.

Training is also ongoing. New staff will need to be trained, users familiar with the system can benefit from learning about more advanced topics, and staff will need further training when there are significant upgrades or new functionality added. If you plan to use CiviCRM for any large or mission-critical events, allow adequate time for additional staff training and testing. 

Hosting and infrastructure

Hosting is a key aspect of any CiviCRM project. You will need to provide maintenance of the server on which CiviCRM is stored, and have someone available to fix problems that inevitably occur from time to time. If your site needs to be accessible 24 hours a day, you should have a support agreement with your ISP that covers this. Ensure that your budget is sufficient for appropriate hosting, and that effective backup procedures and policies are in place.

Keep in mind that in the hosting provider world, you get what you pay for. In many cases, cheap hosting providers keep their prices down by limiting the services or flexibility they provide. CiviCRM doesn't work well on cheap hosting, and under-budgeting for hosting may lead to other problems. Similarly, make sure that the computers your staff are using are powerful enough to provide a good experience with CiviCRM.

Change management

Introducing a new (or the first) CRM will cause changes in work flow and processes at your organisation. These changes may be "political", practical or technical. Either way, a lot of change at the same time can be difficult and stressful.

To mitigate this, give staff time to accept and support each change so that they share in ownership of the new system rather than feeling as if something has been forced on them. Focus on simple tasks at the beginning of deployment and introduce more difficult tasks as staff understanding of the system grows. Show staff how the new system will make their work easier and where their feedback has been incorporated.

Good planning can minimise the risks around change, but it is important to be flexible within your plan; unforeseen things often occur, and a rigid plan could prevent you from reaching the best solution.

How data is organised

This chapter covers the main building blocks that CiviCRM uses to store data, and describes their intended usage. It is recommended reading for working out how you should organise your data in CiviCRM. 

A successful CiviCRM installation depends on having your data stored in the right place. This chapter goes through all of the places that you can store data and helps you to understand why you would store data in one place and not another.

Equally important to understanding the different building blocks presented below is understanding how they can be extended using custom data (described in the next chapter).

Contacts

Contacts are the main building block of CiviCRM. There are three types of core contacts in a standard installation:

Contacts hold contact information, including:


All of the other building blocks of CiviCRM such as relationships, contributions and groups are connected to contacts in some way, so you can see events that a contact has attended, or what contributions they have made.

You can define further contact types to suit your needs, for example "students", "farms" or "churches".  Each contact type you define is based on one of the three core contact types. For example, students would based on individuals, and farms could be based on organisations, or perhaps on households, depending on your situation.

A contact can be only one contact type. For example, they can't be a student and a teacher (but contact types are not the only way to differentiate your contacts).

All users of your content management system are also stored in CiviCRM as individuals. Their contact record in CiviCRM is linked to their user record in the CMS (Drupal or Joomla!). Note that only individuals can be linked to user records in your CMS. Organisation and household records in CiviCRM cannot be directly linked to user records in your CMS.

Relationships

Relationships are a way to connect two contacts to each other. Two out-of-the-box relationship types in CiviCRM are the "employer - employee" and the "parent - child" relationship types.

There are always two ways to describe a relationship in CiviCRM: one describes the relationship of A to B, and the other of B to A. For example, Adam is Bernard's son and Bernard is Adam's father. Sometimes both descriptions will be the same: Charlie is Diane's friend and Diane is Charlie's friend.

CiviCRM comes with a number of relationship types in the standard installation. You can define further relationship types to meet your needs, for example you might define a relationship type of "vicar - church".

It may be helpful to compare relationships to groups: relationships connect two contacts, while groups contain two or more contacts who have something in common.

Groups

Groups are useful to identify two or more contacts with something in common. For example, the advisory board of your organisation could be modelled as a group.

Groups are often used as mailing lists. For example, you could create a group containing all your newsletter subscribers, then use the group to send an email newsletter.

A group can be the "child" of a "parent" group. When a group is a parent, selecting the contacts in that group will also select contacts that are in the child group.

For some groups, such as your advisory board, you might want to capture other types of relationships than a simple "belong to" (eg. president, vice-president, member, substitute). Instead of creating a group, you might want to create a new type, "board", and a contact, "advisory board", then add the members of the group as relationships to that contact. For mailing purposes, you might want to create a smart group with all the related individuals (no matter the type of relationship) of that board.

Groups are also used in many other situations. For example, a search can be saved as a group (or a smart group) and groups can be used to provide permissioning. To find out more about groups and how they are used, read the chapter on groups and tags.

Tags

Tags are in many ways similar to groups, but as well as being used to identify contacts they can also be applied to activities and cases that have something in common. To find out more about tags, and how they are different from groups, read the chapter on groups and tags.

Activities

Activities are a key concept in CiviCRM. Activities track interactions between the organisation and its clients or contacts at a specific point in time. All of CiviCRM's components make extensive use of activities, such as to record contributions, event attendances, membership subscriptions, and emails.

You can create additional activity types to define specific activities that your organisation carries out, for example, "completed annual survey".

Activities have the following characteristics (most of these should be filled in for each activity and those in bold on the form are required):

Compare activities to groups. Would you choose activities or groups to record a membership pack that was sent to a contact? You could add all contacts that have received a membership pack to a group "received membership pack", but it would probably be better to record this as an activity. That way, you can record when the membership pack was sent, who sent it, any notes about what the person requested, and so on. You could also use the activity to schedule sending membership packs by setting the status to scheduled.

Contributions

Contributions are a type of activity, and a fundamental concept of CiviCRM. Contributions are used whenever there is a financial element to an interaction. A contribution will be created for each donation or campaign contribution, for paid events and for membership fees.

CiviCRM comes with several predefined contribution types (including donations, campaign contributions, membership fees and event fees). You can define additional types to meet your needs. 

Contributions have different statuses which reflect the process of receiving a contribution. Some of these statuses are are set automatically by payment processors.

For more information, see the section on CiviContribute.

Memberships and membership types

Memberships are another type of activity. As well as the usual activity fields, they contain extra fields used for tracking memberships, such as start and end dates.

CiviCRM allows you to define different membership types with fees, start and end dates, and other settings. You can define the types that meet your organisation's needs.

Memberships can be renewed. When this is done, the start and end date will move on by the specific time period but the join date will remain the same (i.e. the same as the first membership start date).

If the membership has a fee associated with it, this will be recorded as a contribution and linked to the membership.

For more information see the section on CiviMember. 

Events and event attendances

CiviCRM has a building block for events which contains fields to add events and give these events, times, locations, fees and other information.

When a contact registers for an event, a participant record is created linking the contact to the event. A participant record is a type of activity.

For more information see the section on CiviEvent.  

Cases

Cases are a way to logically connect a series of activities. You can define different case types and associate a predefined series of activities with them. When you create a new case, you typically create a series of scheduled activities that need to be completed as part of that case. As the case progresses, you can record new activities, or series of activities, as part of the case.

For more information see the section on CiviCase.

Extending core data

This chapter explains how you can extend the core building blocks (or objects) in CiviCRM by adding custom fields that represent the data that you want to collect. For example, you can extend organisations with a set of check-boxes about the clients that they serve. You can also restrict custom fields to certain types of that object. For example, you might have a custom field for one type of contact, students, listing the subjects they study.

Custom data fields are always stored in CiviCRM in custom field sets.  Therefore, adding custom data is a two-stage process:

  1. Create a custom field set for an object.
  2. Add custom fields to this set. (You may find it helpful to read the information about custom fields first, but you will need to create the field set before you create the fields in it). 

To clarify, a field is a unit of information entered into the database, such as someone's primary spoken language, or high school graduation date. A field set is a group of fields containing data about a common object or area.

Custom field sets

Custom fields are always part of custom field sets, and each set has a scope as wide or as narrow as you choose. For instance, you might associate a custom field set called "nationality" with all contact types, another set such as "immigration status" with a specific contact type (e.g. Individuals), and yet another set with a specific component (CiviMember, CiviEvent), or with other elements such as Relationships and Groups. The scope of a custom field set is one of the few decisions that is irreversible (you will not be able to change it after creating it) so it is important to consider carefully what you want to associate your custom field set with when you start.

When creating custom field sets, you should ask:

Taking the time to think through these questions helps keep your application screens as relevant and clear of superfluous fields as possible. For example, if your custom field set contains contact characteristics such as a field for the "color of eyes", you should associate them with the Individual contact type rather than the generic Contacts option, as this field would be irrelevant to Organization and Household contact types. Another example would be if custom data is specific to a particular event registration page. You should create this custom data for an Event type Participant for the specific Event.

Depending on how many custom fields you are creating, you should also consider grouping the fields topically. For example, you may associate 20 custom fields with Individual contacts, 12 of which fields relate to an online membership directory. Rather than group all 20 fields in a single custom field set, you may want to split them into two sets - one for the directory-related fields, and a second for more general Individual details.

To create a custom field set and custom fields, go to: Administer CiviCRM > Custom Data > New Set of Custom Fields. This form lets you assign a title to the field set, specify what type of records it will be used for, select the display characteristics, and enter help text. The form appears in the following image, and we'll describe each field.

NewCustomFieldSet 

Set Name

For custom field sets which are displayed inline, this name appears as the legend of the field set. If this set uses the tab display style, the name appears as the navigation tab label.

Used For

You can use this option to ensure that the fields appear only where they are relevant. The choices are:

Order

This controls the order in which your custom field sets are presented when you have created more than one set. Lower numbers (1, 2) are displayed above higher numbers (8, 9).

Multiple records

Each field usually contains a single option. For example, a person has either blue eyes or brown eyes, not both. However, some fields are more complex and may require multiple entries, such as a person's educational history. A single person may have multiple educational degrees, so a custom field set about educational history should allow multiple records.

CiviCRM provides this functionality for custom field sets assigned to contacts (whether to all contact types or to a specific type). To use this option, select the "Does this Custom Field Set allow multiple records?" option. This option has several restrictions:

Display style

Custom field sets for Contact records are displayed either "inline" on the contact summary page (the Summary tab), or as a new tab at the top of the contact record, along with Summary, Contribution, Group, Note, etc. We suggest using tab display for infrequently accessed fields and large sets of fields.

Custom field sets used for components, relationships, or other resources are always displayed inline. Also note that custom field sets configured to handle multiple records will be displayed in the Summary tab.

Is this Custom Field Set active?

If a custom field set is active, its fields can be viewed and changed. Otherwise, the fields are in the CiviCVRM  system but hidden from the user interface. This option can be valuable for managing your data, especially if you are migrating from an existing database system.

For example, your existing database may have fields you would like to transfer to CiviCRM for historical data keeping purposes, but plan to then deprecate or migrate to a new data structure. Suppose you are importing membership records from an MS Access database. Each record in Access has a unique ID (key) field, which has no direct benefit in CiviCRM. Rather than ignoring it altogether, you could create a custom field to hold the value, import the records, and then disable (keep the Activate option unchecked) the field, thereby hiding it from view and minimising the interface clutter.

Though not visible to users, the field value is stored in the system and can be referenced at a later date. For instance, if you ever need to investigate archived data for a possible discrepancy or compare the field value with a printed record.

Individual fields can be made inactive in the form defining those fields, once the custom field set is active.

Pre-form Help and Post-form Help

If you enter text in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field. Use help at this level to provide instructions related to the entire set of custom fields.

Other settings

You can specify that you want the custom field set to be "collapsed" on initial display. If you check this box, only the title for this field set is displayed when the page is initially loaded, because the fields are hidden. This is helpful for field sets that are infrequently used because it reduces the screen real estate taken up when the page opens. A similar "collapsed" property is available for the display of custom data in Advanced Search.

Custom fields

Once you have created a custom field set, you can create custom data fields within the set. Click "View and Edit Custom Fields" followed by "New Custom Field" and you will see the screen in the image below. We'll explain each of the options in this section.

After completing the field configuration options, click Save to record the field and return to the field listing for your current custom field set, or click Save and New to save the field and begin defining a new field. You can view a listing of all the custom fields in a custom field set at any time by navigating to Administer > Customize > Custom Data and clicking View and Edit Custom Fields.

With the exception of the data and input field type selection, all of the configuration options may be modified after your initial creation of the field. You may also find it useful to preview your custom fields, as well as the whole set of custom fields, as you are defining them. This is particularly useful for checking the layout of radio button and check-box fields with a large number of choices.

customdatafield.png 

Field label

What you want to appear next to the field when it is displayed to the user. The text you enter here is also the label shown when you export data. When using fields in a profile, you can overwrite the Field Label.  So on this screen you can choose names that are suitable for administrators, and give more user-friendly names when exposing them in profiles.

Type

Custom fields can be of many different types, many of which you've probably encountered when you have filled out forms on web sites. When you create a custom field, CiviCRM shows you a dropdown list of types from which you can choose the type that best represents the data you plan to store. The menu on the left (shown open in the following figure) indicates what kind of data you want to store, whereas the menu on the right indicates the way you want to interact with the user.

datainputfieldtype.png

The types of fields are:

We suggest you experiment with creating different field types to get an idea of how they behave. Different options have implications for use. For example, check-boxes enable you to use OR as well as AND searches in Advanced Search, whereas multi-select will not.

Database Field Length

The database field length allows you to specify the number of characters that this field will contain.  You should normally leave this at the maximum.  In certain cases (for example if you are dealing with extremely large field sets) it might make sense to shorten this field to improve performance and decrease storage space, but setting a shorter length won't make any difference to the vast majority of users.

Order

Controls the order in which the fields appear. You may assign the order in the field edit form, or use the up/down icons on the main field listing table to adjust the field presentation. By default, new fields appear at the bottom of the field list within a set.

Default Value

Where applicable, you may designate a default value for a field. This value is automatically displayed or selected when users go to a form containing this field. Note the format required for date fields (YYYY-MM-DD).

Pre-form Help and Post-form Help

Ideally, your field name is self-explanatory and users will immediately know what to enter. But in those cases where there is some ambiguity, or where you wish to help regulate how a certain field is used, you may enter help text here. If you enter it in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field.

You help text identified appears in all uses of the field in administration pages and is inserted as the default help text when fields are assigned to a profile. The person creating the profile can remove or change the help text there without impact on the original custom field definition.

Required

When selected, this means that a value must be provided for this field before the form can be submitted. Failure to do so will result in an error message directing the person to complete the required fields.

If you want a field to be required only when a user fills out a particular profile, you can leave this box unchecked but check the Required field in the profile.

Is this Field Searchable?

Makes this field appear in a panel of custom fields in CiviCRM's Advanced Search page. While you may be tempted to mark every field as searchable, doing so may unnecessarily clutter the Advanced Search custom field panel, when in fact certain fields will probably never be used in that way. You may toggle this option on or off at any time, so don't be overly concerned about arriving at a final decision when you first define a custom field.

Active

As with the active check-box in the form defining the custom field set, this box determines whether the field is disabled or enabled when CiviCRM shows it to the user.

View Only

This allows you to designate a field as visible but uneditable. There are two general uses for this field:

Multiple choice options

For field types that involve selecting from a set of multiple options (such as Select, Radio, Check-box, Multi-select and Advanced Multi-select) you are given the choice of either using an existing set of options that you've already created for another custom field or creating a new set. You can enter these values while creating the field, and you can enter the values later. The option's label is displayed on the form, while the option's value is stored in the contact record. The label and value may be the same or different.

If you choose to use the same set of options for several fields, you will be notified when making any changes that this will affect an option set used by several fields.

When you create a new set, you have the option of initially entering up to ten multiple choice options in a table. If you need more than ten options, you can create an unlimited number of additional choices after saving this new field by using the Edit Multiple Choice Options link. Go to: Administer > Customize > Custom Data > View and Edit Custom Fields > Edit Multiple Choice Options.  You can go to this screen at a later date to modify the label, order and active status of any multiple choice option, as well as add more choices. 

CustomMultipleOptions 

If desired, you can also mark one of the choices as the default option.

Inactive options are hidden when the field is presented.

Choosing between fields, groups and tags

Data fields, groups and tags are three major ways to associate information with contacts. Although it can be tempting to just create a custom data field for every attribute of your data, take time to learn about the alternatives. They offer powerful functionality that you may miss out on if you rely only on custom data. Furthermore, using data fields for information stored more appropriately as groups or tags can slow your system. Finally, proper use of groups and tags makes it much easier for administrative staff to maintain the records.

Some tips that may help you choose are:

Using CiviCRM Profile

A profile is a collection of fields (both predefined and custom) from your database. By creating a profile you are able to take only those fields relevant for a specific purpose, such as collecting information about a person registering for an event or displaying a directory of members on your website. The diagram below provides a visual explanation of how existing fields are assigned for use in a profile.

Profiles

Scenarios

Profiles provide powerful tools for collecting information from your constituents as well as sharing that information through your website. These features can save significant staff time by allowing people to update their own data, and you can display up-to-date information from your database in a variety of ways.

For example, a membership-based organisation can provide a searchable membership directory on their website that is updated as soon as a new member joins. Another example is a form where people can sign up to receive emails from your organisation. Once submitted, they are automatically added to the correct email list. Profiles can also be embedded in online contribution or event pages to collect additional information about the constituent.

This section will outline how to use profiles for both collecting and sharing data.

Overview

Profiles provide an flexible set of options for creating forms, directories, and much more. Think of a profile as providing a window into your data. Just as you can have many windows in a house giving different views of the various objects inside, you can have multiple profiles which refer to the same or different fields.

There are many ways that profiles can be used:

Another important point about profiles is that the same profile can be reused in multiple ways.

Collecting data from constituents

This section reviews the different methods by which you can use profiles to collect information from your constituents. A later section will discuss how to share information from CiviCRM with your constituents.

Volunteer sign-up form

Let's walk through an example of a profile used as a volunteer sign-up form. This simple form includes fields for First Name, Last Name, and Mailing Address. It also includes a reCAPTCHA widget to protect your site from automated abuse (described further below).

Picture_4_200

To build a a form similar to this one:
  1. Go to: Administer > Customize > CiviCRM Profile and click on Add CiviCRM Profile.
  2. Give the profile a meaningful name, and mark it to be used for a Profile:

    Profile_checkProfile_2
  3. The next two text fields allow you to include help text to assist the person filling out the form.
  4. The remaining options are listed under Advanced Settings (click on the gray bar to expand this section):
    1. Limit listing to a group: this is very important. If the profile is used for a searchable directory, by default CiviCRM will expose every record in your database; this is not ideal in many cases. Use this setting to limit the available records to contacts who are part of a regular or smart group. For example, if an organisation needs to limit a profile listing to show only active members, they can create a smart group of all members that have a status of New and Current. They then limit the directory to only show contacts in that smart group. Remember, smart groups are dynamic lists of records; when new memberships are added, the corresponding contact will automatically be included in the directory. 
    2. Add new contacts to a group: this is applicable when using a profile as a sign-up form.  You are able to directly add all the contacts who fill out the profile form to a particular group. For example, if your profile form asks contacts to offer their services as a volunteer, then all those who fill out the form can be automatically be added to a volunteer group.
    3. Notify when profile form is submitted?: who in your organisation should receive an email when someone fills out the form? Enter their email address here. If you want to send email to multiple addresses, separate them with a comma.
    4. Redirect URL: when someone clicks Save to submit the form, do you want to take them to a specific URL? Normally you would create a special thank-you page on your website to redirect people to. If this field is left blank, the user will be directed to a page which displays the information they've just entered (a profile view page). This setting does not apply if you embed your form in an event sign-up or contribution form.
    5. Cancel Redirect URL: similar to the previous item, what is the URL you want to redirect people to if they click Cancel on the form? Again, this setting does not apply if you embed your form in an event sign-up or contribution form.
    6. Include reCAPTCHA: CAPTCHA is a type of spam blocking software that requires the visitor to fill in text generated from a graphic. This prevents automated spiders (robots) from completing the form. It is highly recommended that you include it. You must have configured a free reCAPTCHA account before enabling this. Go to Administer > Configure > Global Settings > Miscellaneous Settings to configure your account (click the help icon for on that form for detailed instructions).
    7. What to do on duplicate match: use this option to control what happens when the contact data submitted from this profile matches an existing contact record. Options are to  update the matching record, create a duplicate record, or give the user a "duplicate record" warning (in which case their input will not be saved). This setting is ignored if the profile is embedded in an online contribution, membership sign-up or event registration form. In these cases, a contact match always results in the transaction being linked to the matching contact. Note that if there are multiple matching contacts, the first matching record is used.
    8. Proximity search: if you are using this profile as a search form, you can choose to include proximity searching. When enabled, a proximity search block will be added to the search criteria. This block contains fields to set the proximity start address, and a field to set a "radius" (distance from that address). Set the proximity search as required if you want all searches using this profile to force the user to enter a start address and a radius.

Once you have saved the profile settings, it's time to add fields to the profile. If you plan to reference custom fields in a profile form, make sure that those fields have already been created.

Some important notes on adding fields:

Profile_FieldSettings

Linking to your Form

Once your profile sign-up form is built, it is ready to be used! There are several ways to do this.

Data entry tool

If you have volunteers or interns who perform manual data entry for your organisation, you can make their task easier by creating a profile form which shows only the fields they need to input. This greatly simplifies data entry and reduces the chance of data being incorrectly entered.

Including profiles on event registration and contribution pages

Often you will want to define certain fields for inclusion in event registration and contribution pages. This process is similar to the volunteer sign-up example above. The only significant difference is that you can include fields in your profile that are specific to participant records (for event registration forms) and contributions (for contribution pages). Read the sections covering creating contribution pages and event registration pages for more information.

Including profiles in Drupal's User Registration screen

For websites that have logged-in users, you may want to allow people to provide additional information as they register for an account on your website. Similarly, when people fill out a profile form you may want to encourage (or force) them to sign up for a user account. 

To include a profile form during the user registration process:

  1. Create a profile that is used for User Registration:

    addprofile_usedfor_reg 
  2. Add the fields you want people to fill out as they register, using the same process described above. Make sure the field visibility is set to Public User Pages.

Including profiles in Drupal's My Account screen

You can embed one or more CiviCRM profiles directly into Drupal's My Account screen. This makes it easy for logged-in users to review and update their information whenever they visit their My Account page.

To create a profile for this purpose:

  1. Create a new profile, or navigate to an existing profile and click Settings.
  2. Select in Used For.
  3. Click Save.
  4. Add the fields you want people to be able to edit from their Drupal My Account page.

New account creation during profile sign-up

If you want your constituents to create a Drupal or Joomla! account when filling out a profile, you can enable this with the "User account registration option" under Profile Settings > Advanced Settings. Anonymous (not-logged-in) users will then be invited (or required) to create an account when they visit the profile. Logged-in users will just see the profile fields.  

Profile user registration options 

You must include a Primary Email Address field in the profile for this feature to function properly. This feature also works when the profile is embedded in an online contribution page or event registration page. Hence you can invite or force anonymous visitors to sign-up for an account when they register for an event.

Sharing information

Profiles and directories

Many organisations have data they would like to display on their website. Historically this has been difficult because it required updating the same data in two places - a website and a database. Using CiviCRM profiles solves this problem because it allows you to expose data from your database on your website while only needing to manage and update the data in CiviCRM.

For example, an organisation called Native Americans in Philanthropy (NAP) wanted to create a membership directory that their members could use to search and connect with other fellow members. Before CiviCRM, they would create a very expensive annual print directory and mail it to every member. This process was time-consuming and expensive, and some data would be out-of-date before the members received their directory. Switching to CiviCRM meant significant resource savings and, because their website became a portal for their members to connect, it helped to advance their mission.

To build your directory:

  1. Go to: Administer > Customize > CiviCRM Profile.
  2. Click Add CiviCRM Profile.
  3. Set Used For to Profile:

    NewProfileMemberDir

  4. Advanced Settings: there are a few options under advanced settings that are helpful when using profiles for directories.
    1. Enable mapping: a really cool feature available in CiviCRM is to allow visitors to map contacts in your directory using Google or Yahoo! maps. They can then obtain directions to a record's address dynamically. To use this feature, you must have already enabled mapping under Administer > Configure > Global Settings > Mapping and Geocoding.
    2. Include profile edit links: check this box if you want to include a link in the directory listings to allow people to edit the profile's fields. Only users with permission to edit the contact will see this link. More often than not you will not need to enable this setting as it is not commonly used in the membership directory scenario.
    3. Include Drupal user information (Drupal only): check this box if you want to include a link in the directory listings to view a contacts' Drupal user account information (e.g. their My Account page). This link will only be included for contacts who have a user account on your website.

      profile_adv_settings

Now it's time to include the fields that will make up the directory. For profiles used as directories you have total control over which fields:

The important options you must configure in the fields for directory purposes are shown below:

directory_fields

The image below shows the search mode for our membership directory.

Member Directory Search Form
 

Once you hit search you get this result set. Profile fields that have Results Column checked are shown in the listing.

MemberDirResults

Clicking the view link gives you more details about the constituent, showing all profile fields.

Profile Member View
As we've seen, building a directory for your website can provide a valuable tool for your constituents.

Linking to Your Directory

You have several options to link to your directory:

Other profile uses

Search results

Searching is outside the scope of this section but, assuming you are familiar with searches, you may wish to change the columns used to display the results of an advanced search. To do this:

  1. Create or open a profile and mark it as used for Search Results:

    profile_searchresults
  2. When adding fields to this profile, you will need to set Visibility for the fields to Public Pages and check the Results Column box.

When conducting your advanced search, use the Search Views dropdown menu in the top right of the page to select your profile.

Batch updates

The final way that profiles can be used is to perform batch updates of data. For example, you have a custom field called "volunteer interests" and you want to update the volunteers group with a certain interest. You can easily update the entire group using a profile.

  1. Create or open a profile and mark it as used for Profile:

    profile_batch

    No other profile settings are relevant for this type of usage.

  2. Add your fields to the profile. Only add the fields you want to batch update. In the above example, the only field you would need is your custom "volunteer interests" field (contact name is always displayed when doing batch update). Remember, fields added to the profile must all be of the same contact type. You cannot add fields that are specific to both organisations AND individuals.

Once your profile is created, and you have conducted your search, select Batch Update via Profile from the actions dropdown menu and click Go. Then select the profile you want to use.

batchscreen


You will see a grid with the fields in your profile. You can update each field and row individually. If there is a field where you want to enter the same value for ALL records, you can enter that value in the first row and then click on the "copy values" icon to the left of the column header. This will copy the field value to all the rows in your grid.

Batch Update via Profile

Don't forget to click the Update Contacts button at the bottom of the page to save your changes.

Batch update limitations

Combining record types in a profile

A profile usually contains fields of one record type. For example: First Name and Last Name (Individual fields). But in some cases, such as online event registration and online contribution pages, you can combine fields from two different record types (e.g. Individual + Participant fields or Individual + Contribution fields). You can also combine Individual fields with general Contact fields (e.g. Last Name + Email Address).

If you try to combine fields with an unsupported combination of record types, you'll get an error when you try to save the field.

Installation

Before reading further, please be aware that much of the information contained here is intended for technicians and may be difficult to understand if you have little or no experience in setting up web applications. If you don't understand this topic, you may wish to either seek help, or point your organisation's technical staff to this material.

Prerequisites

CiviCRM must be installed on a computer that has been configured with a web-server, PHP, and MySQL. Some people prefer to try out CiviCRM on their own local computer before installing it on a dedicated web-server. If you are doing this and don't have the pre-requisites just mentioned, you can download packages from the Internet such as WAMP, XAMPP, MAMPP and LAMP, which will quickly install an Apache web server, PHP, and MySQL. (The first two packages are for Windows and the second two are for the Macintosh and Linux respectively).

Before you can begin installation, you need to decide whether you are going to use CiviCRM integrated with Drupal or Joomla!. Refer to the appropriate section in the online CiviCRM Installation Guide for the latest system requirements and specific installation steps:
http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

Network Access

Once you are ready to start using CiviCRM in your organization, you'll probably want CiviCRM to be available on the Internet. However, some organizations only want internal staff to have access. In this case they may choose to install CiviCRM on an intranet or local area network.

Upgrades

New versions of CiviCRM are released two or three times a year, and you will need to apply upgrades to your CiviCRM site periodically in order to take advantage of new features and improvements. It's important that you plan for the resources (people and time) required to apply upgrades to your site. You need to plan on testing upgrades on a copy of your live site to make sure the process runs smoothly. It's also critical to make backups of your site and database prior to running an upgrade.

Refer to the appropriate section of the online CiviCRM Installation Guide for specific upgrade procedures. Be sure to select the procedure that is targeted for the environment you are running (Drupal or Joomla!), and the version you are upgrading to.

Configuration

Now that you have CiviCRM installed and running on your web-server, it's time to review the initial configuration tasks which allow you to customize CiviCRM for your organization.

You can easily access each of the configuration screens described in the following screen from the Configuration Checklist. Log in to your CiviCRM site and navigate to Administer CiviCRM -> Configure -> Configuration Checklist. This section will cover the general tasks, while component-specific configuration will be covered in each component section.

Picture_10

Tokens

Tokens are special blocks of text that refer to specific fields in your database. They are used to control what fields are included in address display and mailing labels, and can also be used to personalize emails. This is described in more detail later in this chapter. If you've used "mail merge" in your word processor, you've already used tokens.

Tokens are always surrounded by curly brackets, and include the record type followed by the field name. An example is {contact.street_address}. Address values are taken from the contact's primary location.

Tokens are skipped when they refer to a field that is empty for a particular contact.

EXAMPLE: The default Individual Name Format includes {contact.middle_name}. If a contact doesn't have a middle name, that token is skipped.

EXAMPLE: The default Mailing Label format includes {contact.supplemental_address_1} on a separate line. If there is no supplemental address for a particular contact, that entire line is omitted - there will not be a blank line in the label.

Localization

Localization involves adapting CiviCRM for use in a specific country or language by translating the text displayed on the screen and setting region specific formats for dates and money (including currency). By default, CiviCRM is localized for the United States. If you are using CiviCRM in a different country, need to store contact addresses that appear in countries other than the United States, or want to use CiviCRM in another language, you will need to review and update the values on this screen.

CiviCRM has been translated into a number of different languages. These translations are contributed by community members. So your first step is to determine if a complete translation exists for the current version by visiting the Translation Server home page at http://translations.civicrm.org/. If you find a completed translation, you can download it and select it on this screen. Otherwise you will need to consider whether you have resources for contributing a translation.

It is also possible to configure your site to support multiple languages. In this mode, your users will be able to choose from a list of available languages after logging in. You can also create and store multi-language versions of text. Examples include custom field labels, an online contribution page, campaign information, and event descriptions.

Further reading:
Localization overview - http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Localisation

Domain Information

Use this screen to enter identifying information for the organization or entity which "owns" this CiviCRM installation. The organization name and address are used to identify your organization in CiviMail mailings when you include the domain.name and domain.address tokens.

You should also enter a valid email address belonging to your organization, which will be used as the From fieldin system-generated (automated) emails.

Site Preferences

This screen allows you to modify the screen and form elements for the following tasks:

Address Settings

CiviCRM allows you to modify the default fields for adding and editing contact and event address data. You can also change the address field layout used for screen display and mailing labels. Review the out-of-the-box defaults by adding a new contact record and noting the address fields provided on the form. Save the record and note the order in which the fields are displayed on the Contact Summary screen. If you plan on generating mailing labels for contacts, review the label layout (select Mailing Labels from the -actions- drop-down after doing a search using the Find Contacts menu option).

After reviewing the default fields and layouts, review the Address Settings screen and make changes as needed.

Mapping and Geocoding

CiviCRM includes support for both the Google and Yahoo mapping services. These services allow your users to display contact addresses and event locations on a map. To enable this feature, select your mapping provider and obtain a key for your site from that provider.

Once a mapping provider is enabled, your contact and event records will be automatically geocoded (the latitude and longitude for that address is inserted) as you add or edit address data.

Search Settings

These let you adjust search behaviors such as the use of wildcards and which data to include in quick search results. Adjusting search settings can improve performance for large datasets.

A wildcard character is a special character that can be used to substitute for any other character or characters in searches. CiviCRM allows you to use the percent (%) character to substitute for zero or more characters, and the underscore (_) character to substitute for any single character. Wildcards are useful for broadening your search results.

EXAMPLE: Typing 'Volunteer%' as your Activity Subject will match any record whose subject starts with "Volunteer" (e.g. "Volunteer for Open House" or "Volunteering Opportunities").

Miscellaneous: Version Checking, reCAPTCHA, Use Trash, Logging

Use the Miscellaneous Settings screen to configure and control the following behaviours:

If you want to use reCAPTCHA protection for online contribution, membership signup or event registration forms, you'll need to configure a Profile with reCAPTCHA enabled, and then include it in those forms.

Contact Types

Here you can modify the names of the built-in contact types (Individual, Household, Organizations), and create or modify "contact subtypes" for more specific uses (e.g. Student, Parent, Team, etc.).

Sending Emails

CiviCRM will use the default From address defined here when sending automated emails. If you've already entered an email address in the Domain Information screen, that address will be listed here (as illustrated on the leftmost field of the following screenshot).

Picture_12

When users send an email using CiviCRM, their primary email address is used as the From address by default. However, they can also select one of the general email addresses defined here as an alternative.

Outbound email

If you are sending emails to contacts using CiviCRM, you need to enter settings which allow CiviCRM to connect to your mail server. Such emails include sending receipts to contributors, sending confirmations to people registering for events, and using CiviMail to send bulk mailings.

CiviCRM supports three different methods of connecting to a mail server: mail (the built-in PHP mail function); SMTP (Simple Mail Transport Protocol); and Sendmail. Each method requires that you enter specific settings. If you're unfamiliar with these terms, or unsure of the correct values for these settings, check with your system administrator, ISP or hosting provider.

You should always send a test email after you enter or modify the settings. Simply click "Save and Send Test Email"(shown in the following screenshot). An email will be sent to the email address associated with your user login account. The From email address will be the default From address you've configured in the previous section.

Picture_11

If CiviCRM is unable to send the test email, you will see a message on your screen with the specific error and some suggestions for trouble-shooting the problem.

Disabling outbound email

If you do not want users to send outbound emails from CiviCRM at all, select "Disable Outbound Email". However, if you disable outbound email, and you are using Online Contribution pages or online Event Registration, you will need to turn off the automated receipting and registration confirmation features (these are enabled by default). Otherwise your constituents will see error messages after they've completed a contribution or registration.

Payment Processors

Payment processors are companies that handle credit card transactions for merchants and non-profit organizations and that transfer funds to the organization's bank account. If you plan on using CiviCRM to accept online contributions, online membership signup and renewal or online event registration, you will need to select and configure a payment processor for your site.

CiviCRM includes support for several different processors, and provides a way for third-party developers to add support for additional processors based on their clients' needs. Each processor has their own pricing structure and features, and you will want to investigate each available option to determine the best fit for your organization. Refer to the "Contributions" section for a list of factors to consider in selecting a processor.

The actual steps involved in configuring and testing your payment processor connection are different for each processor. For more information, visit:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviContribute+Payment+Processor+Configuration 

Permissions for anonymous users

Note: This section applies to Drupal sites only.

If you are using CiviCRM with Drupal, you will need to review Drupal's user permissions to ensure that people can get to your signup forms, contribution pages, membership pages and event registration pages.

You must be an administrator for your Drupal site to review and modify user permissions. Log in to your Drupal site, and navigate to Administer > User Management > Permissions.The following screen is displayed.

Picture_13

Picture_14

Review each of the permissions listed. You should enable them for the anonymous user role if you want these features to be accessible to people who visit your site without logging in--outsiders registering for membership or events, for instance:

Now that you have reviewed all the basic configuration tasks, you're ready to begin exploring the ways in which you can record and use contact data.

System Workflow Templates

Review and modify the templates used for system-generated emails, including contribution receipts and event registration confirmations.

Menu and dashboard

This chapter gives an overview of CiviCRM's dashboard (it's 'home page') and the navigation menu available for people working in CiviCRM.

The navigation menu

The navigation menu is a small bar at the top of every "back office" page of CiviCRM.

NavMenu_menu ...

It provides access to nearly every function of CiviCRM and is broadly organised into headings by individual CiviComponents (such as Contributions, Events and Mailings), with a few exceptions for Search and Administer, both of which cover all of the enabled CiviComponents.

NavMenu_SearchPulldown 

The menu also features a Quick search field for finding contacts. Typing any part of a contact's name or email address into the Quick search field will pull down a list of possible matches that you can click on to go directly to the contact's summary page:

NavMenu_quicksearch

You can modify the navigation menu by going to: Administer > Customize > Navigation Menu and then adding or rearranging menu items on the screen. Remember that changes you make to the navigation menu will be seen by everyone who has the appropriate permissions to see the menu, for better or for worse, so be careful when modifying the navigation menu.

The dashboard

When you first log into CiviCRM, the first page that you will see is the dashboard (CiviCRM Home). The dashboard allows you to see important information about your site and CiviCRM by displaying a series of "dashlets". A dashlet is a snippet of information about a part of CiviCRM: many dashlets come with CiviCRM by default, and you or your administrator can create additional dashlets that are specific to your organisation's needs. Some examples of dashlets that come with CiviCRM are:

Dashboard_homescreen

You can add these dashlets to your CiviCRM dashboard by clicking the Configure Your Dashboard button. You will see a list of dashlets that can be dragged into the right or left column of your dashboard.

Dasboard_editscreen 

Clicking the Done button will allow you to save the dashlets to your dashboard. From now on, you will see updates to the status of your dashlets every time you log in (if you'd like to check and see any changes that have occurred more recently, you can always click Refresh Dashboard Data - this will reload each dashlet and pull in any new information).

Almost any CiviCRM report can be made available as a dashlet. Select a report from Reports > Create Reports from Templates. Update the report criteria as needed. For example, you may want the dashboard version of the report to always show data for "This Quarter" or "This Year". You can also choose to display the report as a table or as a bar or pie chart. Preview the report display. Then check the "Available for Dashboard" checkbox under Report Settings. (Refer to the Reporting section for more details on working with reports.)

Contacts

CiviCRM uses contact records as central hubs for data about your organisation's contacts. There are three distinct contact types defined in CiviCRM, each suited to a common type of contact your organisation may want to track:

CiviCRM provides different fields for each contact type, according to the different kinds of data you will probably want to track. For example, gender only applies to individuals, not organisations or households, so the gender field is only available for Individual contact types and subtypes. You can also define additional data that you want to collect and apply it to only one type. You could choose to create a custom data field to record the Chairperson or CEO's name and only apply this field to organisations.

Adding a contact

The simplest way to add a single contact to CiviCRM is to use the navigation menu at the top of any non-public page. To create a new Individual, go to: Contacts > New Individual:

Contact_createIndividual

Note that the Contacts menu item allows you to create every kind of contact and contact sub-type.

Clicking on New Individual will bring you to the New Individual form. All of the contact creation forms are similarly arranged, with basic information (name, email etc.) at the top of the form and more specific fields below grouped by type or subject in accordions (such as address fields, communications preferences and any custom fields that you have added for the contact type).

You can fill out as many of these fields as you like, however it's recommended that you have at least a name and email address (it is only required that you have first and last name OR email address). Remember that there is no difference between the contact add and edit screens, so you can always go back and make changes as needed.

Once you have filled out the form, you have the choice of three buttons to click:

The contact screen

The best way to understand contact management is to have a look at the different screens that are used to store and display information about contacts.

You can find a contact from your CiviCRM dashboard (or any other CiviCRM page) by entering part of their name or e-mail address into the Quick search box in the navigation menu. If you leave the search box blank and click the Search button, it will find all the contacts in your database.

Below is a search for "sa" that has returned Sam Jones, as well as other contacts with the letter combination "sa":

NavMenu_quicksearch 

Contact Actions Ribbon

Across the top of all contact records is an Actions Ribbon with a variety of buttons that allow you to perform actions related to the current contact. Clicking the Actions button will produce a dropdown menu with a number of actions that can be performed on this contact. For example, you could add a note to this contact, or record a new contribution, meeting or other activity.


Some of the activities you can perform here are:

If you're using CiviCRM in conjunction with Drupal or Joomla, you may also see a link to View User Record. This link is shown when the contact is a registered user of your site. It links to a CMS-specific User Account screen. 

Contact tabs

A list of tabs underneath the Actions Ribbon break up the contact's information into related chunks. We will cover the contact summary tab here in some depth, and then look at other tabs that may be available to you depending on your configuration.

If you think that some of the tabs are not useful and will not be used in your deployment, you can disable or enable specific tabs from Administer > Global Settings > Site Preferences. If you don't see some of the tabs described below, you may need to enable them. The visibility of some tabs is dependent on which components are enabled in your installation. For example, the Contributions tab will be hidden if the CiviContribute component is disabled.

Summary tab

The summary tab gives you an overview of information about your contact. Here you will find names, addresses and contact details. The information on this page appears fairly straightforward, but take a closer look and you will find some pretty clever stuff is going on. 


 

CiviCRM includes a complete set of fields "out-of-the-box" to store basic contact information. These are usually referred to as built-in fields and include:

Note one small but important feature of the summary screen: if you have a number of long sets of fields, it may become useful to collapse some of them. In the example below, Communication Details has been collapsed, while Constituent Info - Individuals is expanded. Some field sets can be set to be expanded or collapsed by default. This happens for example when a contact has more than one location entered. The first one is shown by default, the rest of them will be collapsed. Clicking on the header will toggle the status of the field set.

Contact_expandCollapse  

Name Fields

Each contact's name can include the following fields: Prefix, First, Middle and Last Names, Suffix and Nickname. You don't have to use all of them, but they are available in case you want to store all of this information.

If you wish to record a prefix such as Mr., Ms. or Dr. for your contact you can do so using the dropdown menu on the edit screen. If you require other prefixes such as Sir or Father, you can add these to the dropdown menu from Administer CiviCRM > Option Lists > Individual Prefixes (Ms., Mr...). The same applies to name suffixes.

Locations

A location is a group of address-related fields consisting of phone, email and postal address field groups. 

CiviCRM can hold more than one location for a contact. For example, if a person has a home address, a billing address and a work address, these can be recorded as separate locations. One of these locations will be marked as Primary. It will be used for any postal mailings that you do. You can explicitly choose which location will be primary for a particular person, or let it default to the first one entered. If a person pays you by credit card, the details used for Billing Address in credit card payments will be stored in the Billing location for the contact.

You can share addresses between contacts. For example, you may need to keep information about individual contacts and the organizations where they work. When creating or editing the "work" address for an individual, check the "Share Address With" box. If their employer already exists in your database, you can select them from the quick search box that appears. Otherwise, you can create the employer's organization record on the fly by selecting "New Organization" from the "create new contact" dropdown..

You can also store multiple phone numbers and email addresses for each location. One of these email addresses can be explicitly marked as the address which receives all bulk mailings (e.g. emails your organisation sends using the CiviMail component).

Relationships tab

Relationships are connections between contact records in your database. Each connection can be named to describe the nature of the connection, and a contact may have many relationships to other contacts in the database. In the example below you can see a list of Current Relationships as well as a list of Inactive relationships. Contacts can have relationships with set start and end dates. For example, a contact could have a relationship "Committee Chair" to an organisation for a one year period. In order to track past Committee Chairs, you can keep a record of the contact having an inactive Committee Chair relationship.

Contact-RelatoinshipTab_1 

Another example of a relationship that might be tracked in CiviCRM is the Employee-Employer relationship. Richard is an employee of the organisation Acme Org, and to store this information in the database you can set Richard to be an "Employee of" Acme Org. You do this by creating a relationship between Richard and his employer. Once you do this, you will be able to see this connection from both Richard's and Acme Org's records.

The Employee/Employer relationship is a special one. If you look at the Summary tab again you can see that the Current Employer field shows the name of the employer. This name is a link to the ABC Org contact record. Entering in an Employer in this field is a shortcut way to define an employment relationship. Whenever you fill in the Current Employer field, a record with a matching name will be looked up and the appropriate relationship will be created. If no record for this organisation exists, one will be automatically created before creating the relationship.

The Household Member relationship is used for connecting individuals with households. When editing a contact, you can opt to "Share Address With" a household. You can either select an existing household, or create a new one by selecting "New Household" from the "create new contact" dropdown. When you have opted to use a household address for a contact, a link to the Household's contact record will be displayed along with the usual address information in the contact Summary tab. Using a household address for a contact also automatically creates the Household Member relationship between the contact and household.

Apart from the two special relationship types, you can create and register any other type of relationship. The Relationships tab shows all of a contact's existing relationships with other contacts (individuals, households or organisations in the database).

To create a new type of relationship, go to Administer CiviCRM > Option Lists > Relationship Types. Relationships can be also extended with custom fields if you need to store additional information for them.

Additional powerful characteristics of relationships include the ability to set a start and end date, or disable them manually if they are not valid anymore. This means that you can store the history of relationships in your contact records.

Activities tab

The Activities tab does two things. First, it displays all your interactions with the contact over time; this includes all CiviCRM's built-in activities like event attendance, contributions, membership sign-up and renewal, phone calls, emails and user-defined activities. Second, it allows you to record activities with contacts. Clicking on the icons at the top of the screen (Send an Email, Meeting, Phone call) will bring up a screen where you can enter those details.

This tab can also be used to record any custom activities that you've defined for your CiviCRM installation (from Administer CiviCRM > Option Lists > Activity Types). The ability to define custom activity types, and extend them with custom fields provides a powerful tool for tracking a wide variety of organisation activities. For example, you could choose to track activities such as press releases, press conferences, site visits or voluntary work.

Activities are a great way to store interactions that happen at a specific time, or that link specific people.  If it is important for you to know who at your organisation carried out a task, then record it as an activity. Another advantage of activities is that they record when something has happened, which is useful if you need to report on the volume of activities performed during a specific time period. You can record an activity between a given contact and multiple other contacts by adding as many contacts as you like in the With Contact field on the Add Activity form.

Activities usually have their status set to Completed or Scheduled, however you may add other types of activity status as appropriate for your organisation.

 Contact_ActivityTab

Contributions tab

The Contributions tab shows any financial contributions made by the contact whose details you are viewing, as well as a summary of the contribution activity of the contact (total amount of contributions over time, total number of contributions, and average amount of contributions).

The Contributions tab also allows you to record off-line contributions using the Record Contribution button, or record a credit card transaction on behalf of the contact (useful if the contribution has been made by phone) using the Submit Credit Card Contribution button. Both of these buttons lead to forms that allow you to select the contribution type in addition to the normal contribution information collected from public contribution pages.

Contact_COntribTab 
 

Memberships tab

This tab displays the memberships a contact has signed up for. From this tab you are able to add memberships and submit credit card payments for memberships that require a fee. You can also renew or delete memberships from the "more" link on each membership in the contact's existing memberships.

Contact_MembershipTabs

Events tab

The Events tab displays events related to this contact, whether they are events the contact has registered for, attended, volunteered at or is any other of the user-configurable event statuses.

From this page you can register the contact for an event, and use the Submit Credit Card Event Registration button if the event requires payment. The related payment will then appear up on the contact's Contributions tab in the first row.

You can also modify the event information as it relates to the contact by clicking the Edit link. For example, you can change the contact's event status from "registered" to "attended".

Contact_Eventstab 

Groups tab

The Groups tab shows the groups that the contact is a member of. Groups can be used in a variety of ways including mailing lists and permissioning (ACLs).

You can add and remove the contact from groups, and see a history of groups the contact has unsubscribed or been removed from.

The Status column displays who has added the contact to the group. Whether users can add themselves to a group is one of the settings you can configure when creating a group. When you set a group's visibility to "Public Listings" users can join via Profile forms. You may want to familiarise yourself with the discussion on using Profiles for mailing list sign-ups covered in a later section. 

Contact_GroupsTab

Notes tab

The Notes tab is a place where you can record random bits of information about a contact. Generally you would use custom fields for information you plan to collect about your contacts, but in some cases it may be useful to record additional, ad-hoc notes about a contact. Since this information is unstructured, you should be careful about using the Notes tab, unless you know that you or other people using your CiviCRM implementation will remember to look at that tab. When creating a Note both the subject and the content are free-text fields (i.e. the subject field does not have to be chosen from predefined options).

You can specify "Author Only" privacy for a note. This means that only the person who wrote the note, or someone with "view all notes" permission (Drupal only) can view or edit it.

Contact_NotesTab 

Tags tab

Tags are one way of categorising contacts in your database (other methods are Custom Data and Groups). You can configure which tags you wish to use for your organisation. You can search on tags and create Smart Groups based on them.

The tags next to Keywords are part of the Keywords Tagset. A Tagset is a specific grouping of tags that you can create. Tagsets are non-hierarchical, and you can create a new tag in a tagset simply by typing a new tag into the field. Existing tags that match what you type will also show up as a list from which you can select.

Contact_TagTab 

Change Log tab

This tab gives limited information about changes made to a contact record. It shows the change date and who made the change, but not what was changed.

Contact_ChangeLog 

NOTE: Administrators can use the Contact Logging Report to get detailed information on changes to contact records (who, what and when).

Modifying the contact screens

After working with the contact editing and summary screens for a while, you may realise that there are sections and/or fields that aren't useful for your organisation. The good news is that you can easily hide some fields and sections. For example, if your organisation doesn't need to store demographics information, you can remove it by configuring the Site Preferences:

Similarly, if you want to remove (or add) fields in the postal address section:

Groups and tags

Groups and tags are two key methods of organising data in CiviCRM. When used properly, both allow for powerful segmentation and searching of your database.

Since both groups and tags are methods of categorisation, it can be difficult to determine whether a tag or a group is more appropriate in a given situation. Identifying the differences in their workflow and functionality will help you to decide which to use.

It can also be good to have a conceptual understanding of the differences between the two. Though there are different takes on how tags and groups should be used, a common philosophy is that tags should be used for descriptive categories and groups should be used for grouping people within a cohesive entity that functions or will be treated as such. From this perspective, things like volunteer, ally organisation, vegetarian, and musician would be tags with which you could categorise contacts while Volunteer Committee, Allied Organisations Coalition, Vegetarian Newsletter, and This Awesome Band With A Bad Name would be groups to which you could add contacts.

Groups

Groups are an incredibly important feature within CiviCRM. In addition to their fundamental use as collections of contacts that have something in common, they play a critical role in CiviMail and Profiles, and can be used to set up advanced access rights (on Drupal). Well-defined groups are one of the most important tools available when segmenting your CiviCRM contact database.

There are two kinds of Groups - Regular Groups and Smart Groups.

Group settings and functionality

Each group should have a clear, easily understandable group name and a description of the group and its purpose, both of which will allow users to quickly figure out what particular groups are for when working in different contexts (e.g. CiviMail). This clarity and specificity is especially important once your organisation has amassed many different groups. If a group is created for a specific person within your organisation, it is a good idea to mention in the description who the owner of the group is, so that in the future someone can check if this group is still used or if it can be deleted.

Groups can be assigned the following types:

Visibility determines permissions for joining and removing contacts from groups. Select "User and User Admin Only" if membership in this group is controlled only by authorised CiviCRM users. Select "Public Pages" if you want to allow contacts to join and remove themselves from this group via Registration and Account Profile forms.

Some organisations find it useful to create a hierarchy of groups. In CiviCRM, this is done by creating one or more parent groups and then assigning other groups to them. When a user sends a mailing to a parent group or searches for contacts in a parent group, all contacts in the associated child groups are automatically included.

For example, an organisation that has a national office and 5 regional offices puts constituents in each region into their own group. Then they create a National group which is assigned as the parent group for all regional groups. The national office can now send mailings to the National group, knowing that all contacts in the regional groups that are children of the National group will be included.

Adding and removing contacts

You can add contacts to groups in multiple ways:

The first two methods also allow you to remove individual contacts from a group; the last two methods allow you to add multiple contacts to groups at once.

Individual contacts can be added to a Group either in the contact edit screen or via the Groups tab. Multiple contacts can be added to a group at once by conducting a search, and then selecting Add Contacts to a Group using the More Actions menu. The second way allows you to add multiple contacts to a group by going to Manage Groups, selecting Members for the relevant Group and then using the Add Members to this Group option at the top of the screen.

Contacts can also be added to a group as a result of filling out a Profile (see below).

Managing Groups

To view and manage all groups, go to: Navigation Menu > Contacts > Manage Groups.

Groups_manage

You can use the Find Groups form at the top of the Manage Groups screen to search for groups by name, type, visibility and whether the group is enabled or disabled. You can also scroll or browse through the list of groups further down the Manage Groups screen. This list includes both regular and smart groups.

You can:

Group IDs

CiviCRM assigns a unique numeric ID to each group. These group IDs can be used for a variety of operations. For example, the group ID can be used to define a URL for group sign-ups. You can find a group's ID by checking the ID column in the tabled list of groups at Navigation Menu > Contacts > Manage Groups.

Finding contacts in a group

The Contacts page for each group includes a form for finding contacts within the group. You can search contacts within a group by name, email address, contact type, group status (added, removed, or pending) and tags.

Groups_searchwithin

Creating and managing smart groups

Smart groups are created by conducting a search (either quick or advanced) based on the criteria you'd like to use to determine who is automatically added to or removed from the smart group, then using the New Smart Group batch action in the Actions menu on the search results page. The smart group creation page is similar to the regular group addition page, except that it displays the smart group criteria at the top.

Though smart groups are automatically maintained by CiviCRM based on the criteria you've set, contacts can be manually added to or removed from a smart group whether or not they match that criteria. For example, if someone unsubscribes from a mailing that is based on a smart group, they will be recorded as removed from the group even if they still meet that smart group's search criteria. Similarly, you can manually add a specific individual to a smart group. For example, you can add someone who is moving away from a city to that city's newsletter smart group so that they continue to receive the newsletter despite their address not matching the criteria for the smart group.

To manage smart groups, go to: Navigation Menu > Contacts > Manage Groups and click the Settings link for your chosen group. Smart group management pages include links for manually adding contacts and editing the smart group's criteria. When you edit a smart group's criteria, CiviCRM will update the members in the group and future members will be automatically added according to the new criteria.

Using groups in a search

When using Advanced Search, if you select several groups in the Group list near the top, it will treat the search as an OR search, and return results for contacts who are in any of the groups you select. If you want to find contacts who belong to all of the selected groups, you will need to use Search Builder. 

There is also a very useful built-in custom search, "Include/Exclude Contacts in a Group/Tag", that enables you to find contacts who are in one group but not in another, which you can find by going to Search > Custom Searches in the navigation menu.

Groups_searchIncExc

Groups and ACL (Drupal only)

Access Control Lists (ACL) provide finer grained permissioning than what is available through Drupal's Permissions and Roles. Setting up ACLs requires a good understanding of the concept, which is thoroughly explained in the online CiviCRM documentation here: http://wiki.civicrm.org/confluence/display/CRMDOC/Access+Control

As with many processes, the key is to make sure you have assembled all the parts before you try to join them together. In this case, you must set up the required Groups, Custom Data Groups, Profiles and Roles before you can use them in ACL.

Groups and Organic Groups (Drupal only)

The Organic Groups CiviCRM module (http://drupal.org/project/og_civicrm) integrates Organic Groups from a Drupal site with CiviCRM groups. This is useful for groups that require Organic Group functionality on their website but also need to be tracked within CiviCRM. Once an Organic Group of Drupal users are integrated into CiviCRM, the Drupal group can be used for mailings, tracking address information, tracking activities or anything else normally done with CiviCRM contacts.

Once the Organic Groups CiviCRM module is installed and enabled in Drupal it automatically creates two CiviCRM groups for each existing Drupal Organic Group:

The groups are synchronised one way only, from the Drupal Organic Groups to CiviCRM groups. When a new user is added to or signs up for an Organic Group, they are automatically added to the corresponding CiviCRM group. If they leave the Organic Group then they are removed from the CiviCRM group. If an Organic Group is deleted, the CiviCRM group is also deleted. However, the reverse of each of this situations is not true; a contact added to the CiviCRM group will not appear in the Drupal Organic Group, a contact removed from the CiviCRM group will still remain in the Drupal Organic Group, and if you delete the CiviCRM group, the Drupal Organic Group will still remain. Therefore, this integration is meant to be used when you administer the group from the Drupal side.

Tags

Tags are used to categorise contacts, activities and cases in CiviCRM. You can create as many tags as needed to classify the contacts in your database, though it is advisable to avoid duplicating existing tags or adding too many tags that aren't really necessary. It can be useful to create a standard process for creating and using tags within your organisation to avoid these problems.

Viewing, creating, and editing tags

To view tags, go to: Contacts > Manage Tags (Categories) in the navigation menu. 

A tag can be edited or deleted using the respective links in its row. New tags can be created by clicking the Add Tag button on the Manage Tags (Categories) screen or by going to Contacts > New Tag in the navigation menu.

admin_tags

Each tag should have a clear and unique name and an explanatory description to help users understand the tag's purpose. Tags can be structured hierarchically and designated as subtags of an existing tag by selecting a Parent tag from the dropdown list.

Tags can be designated for use for contacts, activities and/or cases. If a tag is designated for use for contacts, it will be available for all contact types and subtypes; tags cannot be specifically designated for use for only one type of contact.

Tags are a flexible tool and every user can create more if needed. However, very important tags can be locked to prevent them from being modified or deleted by users who do not have the "administer reserved tags" permission (this permission is available in Drupal only).

Tags can be assigned to contacts, activities and cases in the following ways:

You can also use the first two methods to remove tags.

Tag sets

Tag sets allow you to create free tagging taxonomies which users can add their own tags on the fly, without having to access the Manage Tags page described above.

Tag sets are created by going to: Contacts > Manage Tags (Categories) in the navigation menu and clicking the Add Tag Set button. Tag sets are configured identically to regular tags. However, they function quite differently. When you create a new tag set, it creates a new field on the edit pages of the entity's activities or cases as well as in the Tags tab for contacts.

This is a tokenising autocomplete field: as you begin to type, CiviCRM looks for matching tags in this tag set and displays any matches below the field. You can select an existing tag or create a new one by typing the entire tag and pressing the Enter key. The tag will then appear within the field in a box. Clicking on the X will untag the entity (contact, case or activity) that you are editing.

Tags created within a tag set can be viewed and edited from the normal Contacts > Manage Tags (Categories) list. However, tags created within a tag set will only be available within that particular tag set.

Tags or Groups?

This is a common question on any project, and the philosophy described in the introduction of this chapter is a guideline, but rules might need to be bent based on how you intend to use your contact segmentation.

One interesting benefit of having both groups and tags is that you can perform more refined searches using AND and OR. For instance, if you have journalists, volunteers and members as groups and use tags to identify topics of interests such as development, art and history, you can find all the journalists who are interested in art or development, all the volunteers or members that are interested in history, or any other combination.

Beside that, groups have some features that tags don't:

Think of it this way: tags can be applied to contacts, activities, and cases, whereas groups can only consist of contacts.

Searches and actions

This chapter covers different ways to find information you've stored in CiviCRM. Two of the techniques in this chapter - finding contacts and the "search-action" work flow - are core functions in CiviCRM, so most if not all users will find this chapter helpful.

We will start off with some simple searches and then move on to more advanced techniques. CiviCRM beginners should be familiar with Quick search, Advanced search and the component searches. More advanced users should also look at reports, custom searches and search builder. 

There are three main reasons to search:

For reports, searching is often useful but has limitations. For example, you can't group results by particular criteria, or summarise or easily produce graphs of the results. For more advanced reporting, read about CiviReport in the section Reporting.

Note that when you search for character strings, the search is not case-sensitive. For example, if you search for 'brooklyn', the search will return strings with capitalised letters if the string exists, e.g. 'Brooklyn' or 'BROOKLYN'.

Quick search for contacts

The easiest way to find a specific contact, if you know part of their name or email address, is to use the Quick search box that appears in the navigation menu at the top left of the screen. Contacts that match the phrase you enter will appear in a dropdown list below the box. For example, entering "peter" will find

You don't need to type the full name of the person - just the first few letters. The following screenshot shows that two contacts turn up in our database when we search just for "pe".

quicksearch 

Advanced search

Advanced search allows you to search across all the information you have about your contacts. For example, you could find "all contacts in Venezuela" or "all advisory group members". If you specify two or more categories of information, the search displays every contact that matches all the categories. For instance, you can combine the two criteria just mentioned to find "all advisory group members in Venezuela".

The Advanced search screen is accessible from the navigation menu Search > Find Contacts > Advanced Search. On this screen, search criteria are grouped into sections which refer to different types of data that you can search on, such as address data, notes and information from components such as Contributions or Events. Each group of criteria is shown as a gray bar. If you click on a gray bar, it expands to reveal the options within that group. For example, if you want to search for all people in your database from 16 to 18 years old, click on the Demographics bar. It expands, as shown in the following figure, and you can specify the birth date range you are interested in.

AdvSearch

Combining search criteria

Different criteria are combined by "ANDing" them. For example, if you select the tag "major donor" and the country "Mexico", the search will return major donors from Mexico.

Within criteria groups that allow you to check boxes for more than one value, these options are also combined by "ANDing". For example, if you can search for contacts whose Preferred Communication Method is both Email AND SMS.

With fields that allow you to select values from a drop down list, options are combined by "ORing". For example, you could find contacts that live in Mexico OR the United States by selecting both countries in the country field. 

Display Advanced Search results as ... 

Advanced Search returns your results as Contact records by default. However, you may want to get another record type instead. For example, you may want to see all the Contribution records which match your search criteria (while taking advantage of the rich set of search filters available in Advanced Search). Simply select the record type you want from the dropdown in the upper right corner of the Advanced Search form.

Modifying search columns

Advanced searches allow you to use to change the columns displayed in your search results. The default columns are Name, Street Address, City, State, Postal Code, Country, Email and Phone. If you want to display a different set of columns (perhaps to include a custom field or remove a column you don't need), create a Profile with the Search Results option selected. Make sure that the fields in this Profile are set to "Public User Pages and Listings" visibility, and are marked as Results Columns. (For more information about creating Profiles, which are described in detail in the Profiles chapter in the Configuration section.)

The Profile will appear in the Search Views dropdown menu in the upper right corner of the form, as shown below. The following screenshot shows what the menu displays after someone has created a Profile called "Birthday".

Search_prifleFields

Combining this feature with the "Batch Update via Profile" action provides a powerful method of viewing and updating a specific set of fields across a batch of contact records.

Instant view pop-up

You can see a pop-up box with detailed information for any contact listed in your search results by hovering over the contact icon in the left column, as shown below. You can adjust the fields shown in this "pop-up view" by modifying the fields included in the "Summary Overlay" profile (Administer > Customize > CiviCRM Profile).

Search_summaryOverlay

The "search-action" workflow

After you retrieve your search results, you can perform a number of actions. An Actions box appears above the results. You can select either all records or specific records, then carry out an action with the selected records. Different actions are covered in more detail in the chapter on Everyday Tasks.

Search_resultsactions

Some of the most commonly used actions are Add Contacts to Group, Export Contacts, Map Contacts, and creating and printing Mailing Labels. (To use Map Contacts, you will need to configure Mapping and Geocoding. You can read more about this in the Installation chapter of the Configuration section of this manual).

For example, to send email to a selected  number of contacts, mark the contacts you are interested in and then select Send Email to Contacts in the dropdown list of actions. 

The wildcard (%)

Understanding wildcards greatly expands your search options. A wildcard represents "any character" (letter, numeral or punctuation mark). In CiviCRM, the wildcard is represented by the % symbol (you may be familiar with other symbols such as * from other applications). It is most easily understood through examples.

Suppose that somebody asked you to find a contact with a first name similar to "Michael", but possible something different such as "Michelle" or "Michał". If you search for "Mich%" you will find all these variations, including a contact who is supposed to be named "Michael" but whose name was misspelled as "Micheal". Wildcards can be used before, after, or even within words. For example, searching on 'Mich%el' will exclude "Michał" and "Micheal" but still find "Michelle" and "Michael".  

This search is not case sensitive. Entering "mi%el" in lowercase will also find contacts with an upper case 'M' in their name.

Component searching

Most CiviCRM components offer a search on the data they maintain, such as Find contributions, Find members, etc. These forms work in a similar way to Advanced search but return rows of the main objects associated with the components, instead of contacts. Find Members returns memberships, Find Participants shows event registrations, Find Contributions returns contributions and so on.

Each component search has its own Action list. See the Component sections for more details.

Search Builder

Advanced search lets you choose from a wide range of criteria, but it has limitations. The main limitation is that the search criteria you enter into different fields are "ANDed" together.

The Search Builder tool provides an alternative for situations when you need to search using OR for some criteria. For example, you can build a search for contacts who are born within a range of dates OR who are female. To do this, access the Search Builder tool and Edit Search Criteria from the navigation menu: Search > Search Builder.

SearchBuilder 

Search Builder is intended for advanced users and requires you to use specific formats for your search values. Refer to the online documentation at http://wiki.civicrm.org/confluence/display/CRMDOC/Search+Builder before you try to create your own searches.

Custom search

Custom searches are designed to answer specific questions that can't be easily answered using Advanced search or Search Builder. A good example are the "Exclude Contacts" and "Exclude Groups" options, which, in combination with a previously run advanced search, allow you to find contacts that do not meet certain criteria.

Go to: Search > Custom Search in the navigation menu and look at the list of available custom searches. These customised searches have been written by members of the CiviCRM community to meet their own needs, and then contributed back to the community to share with others who need the same or similar custom searches. It's worth spending some time exploring these searches as some may be useful to you, and they will give you an idea of the sorts of things that are possible.

It is possible to write your own custom searches, but you'll need to be comfortable with MySQL and PHP. See the section of this manual called Extending CiviCRM for more information about how to do this. If you create a custom search that you think could be useful for others, consider contributing it back to the community.

By combining Include and Exclude options, you can find contacts who are in one group but not in another.  You can find these options, which are shown in the following screenshot, in the navigation menu Search > Custom Searches.

Groups_searchIncExc

Importing Data into CiviCRM

Most organisations have data in sources outside CiviCRM, such as previously used database platforms, spreadsheets created on the fly for specific events or other purposes, and email address books. Because manually entering large amounts of data can be tedious, CiviCRM provides a way do import data en masse if the source can export it into some common format such as a Comma Separated Version (CSV) file.

Considerations before importing

It might be useful to think about your pre-existing data in the same way as the contents of a house or apartment when you need to move. People often use moving as a chance to say, "Do we really need this? This stuff is too old; let's trash it and get some new stuff once we have moved in."

To apply this metaphor to your data, look for fields that have no purpose, such as old organisational divisions that you've abandoned or office locations in a facility you no longer occupy.

Some old data will have continuing value. For instance, one organisation in a financial pinch decided to use an old list of founding donors who had not given money for many years. It turned out that these lapsed donors still had strong emotional ties to the organisation that they had founded and they came to its financial rescue. In that case, saving old data was crucial.

Moving to a new living space doesn't just provide an opportunity to evaluate what's really important to keep and what can be left behind; it also gives you a chance to clean up everything that you do decide to take with you. Just as you wouldn't pack up dusty picture frames and dirty dishes because that would make your nice new clean place as dirty as your old place, you'll want to clean up your data before moving it into CiviCRM so that you're starting off with as clean and useful a database as possible.

In planning for a move to CiviCRM, prepare to spend a good amount of time looking at your old data; standardising how different elements of contacts' records are stored (e.g. are states entered as NY or New York?) and deleting obvious duplicates, accidental entries, outdated information, and corrupted records.

For many US-based organisations, an important element of cleaning your data is standardising addresses to conform to the conventions defined by the United States Postal Service's Standards for Addresses. Standardising how addresses are entered into CiviCRM will allow for more accurate search results when searching by address, as CiviCRM can parse addresses based on the USPS standards if you choose to do so. (To find out more about how Address Parsing is handled and used in CiviCRM, refer to the Installation chapter of the Configuration section of this manual.) When adding or editing contacts, you will enter and edit such address elements as street number, street name, and Apt/Unit/Suite number according to these standards.

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 at http://pe.usps.com/text/pub28/welcome.htm  or http://pe.usps.com/cpim/ftp/pubs/Pub28/pub28.pdf for the pdf version.

Preparing to import data

Importing data requires considerable attention and care, so we'll present some concepts here that you should know before you start your first import. You can import both core and custom data for contacts, as well as data for event attendance, activities, memberships and contributions. This chapter focuses solely on the import process for contacts, though the processes for other data are similar.

There are two ways to import data:

If you do not have a clear understanding of your existing data and how it will map to CiviCRM fields, you will experience frustrations and problems when you try to import the data. Please read about each type of data in other sections of this CiviCRM Manual and visit the CiviCRM online documentation for more information: http://wiki.civicrm.org/confluence/display/CRMDOC/Importing+Data

The following rules and recommendations will help you to import data with minimal problems:

Setting up a CSV file for importing

Example of spreadsheet .csv format

student_sample

When thinking about setting up your spreadsheet, think about the data that you are collecting and plan out your column headings. Keep in mind that you may need to create more than one .csv file and perform multiple imports before you are finished.

If you plan to import related data that pertains to a specific contact, e.g. event participant information, contribution data, etc., you will need to make sure that each contact record has a unique identifier or the contact record should have First Name, Last Name and Email, so that you can link their related data during later imports.  If you have unique ID, you would map the ID to CiviCRM's External Identifier on import.

Running an import

The import process has four steps.

Step 1: Setup

Setup lets you specify the basic details of your import, including the source of the data. Data can come from either a CSV file, or an SQL query of a database on your server. A check-box lets you indicate whether the first row of your file contains column headers.

Step1a

Imports use the default strict rule to decide whether a contact record is a duplicate (refer to the Deduping and Merging chapter in this section for information on duplicate matching rules in CiviCRM).  You can specify what action to take when an import encounters a duplicate:

Step1b

Import mappings tell CiviCRM how the fields of data in your import file correspond to the fields in CiviCRM. The first time you import from a particular data source, it's a good idea to check the box to "Save this field mapping" at the bottom of the page before continuing. The saved mapping can then be easily reused the next time similar data is imported, by requesting that it be loaded at this step.

Step 2: Match the fields

If you had column headings in your file, these headings will appear in the first column on the left-hand side of the Field Map, while the next two columns show two rows of data in your file to be imported, and the fourth column is the Matching CiviCRM Field. If you loaded an import mapping in Step 1, your choices will be reflected here. You can change them if they are inappropriate for this import.

ImportMatchFields 

The matching CiviCRM fields include standard CiviCRM data such as First Name and Last Name as well as any custom data fields that have been configured for use with contact records on your site. Match the fields by clicking the dropdown list and selecting the appropriate data. For example, if the heading of the second column in your input is Surname, you should choose Last Name as your Matching CiviCRM Field.

Select "- do not import -" for any columns in the import file that you don't want to import into CiviCRM.

If you have a saved mapping for a specific set of spreadsheet columns, and your spreadsheet layout has changed (for instance, you need to import additional fields, so you add the appropriate columns of data in the spreadsheet), you can modify and save the field mapping. One tip to ease the mapping process when you need to import additional fields is to place the additional columns of data in your import spreadsheet to the right of the columns you've previously mapped in CiviCRM. This allows you to use the existing saved field mapping to map the initial import fields, and then continue mapping the new data fields.

Step2d

Note that if you add new data columns in your spreadsheet and do not position the columns AFTER the columns you previously mapped, you then can't use the saved mapping and will have to map all your import fields again.

Once you've mapped your fields, you can decide if you want to keep the original saved mapping unchanged, or check the box to "Update this field mapping" to include the new field mappings.

Step 3: Preview

This screen previews the results of importing your data, reports the number of rows to be imported, and allows you to double check your field matches.

If some of the rows in your spreadsheet contain data that doesn't match CiviCRM's requirements for one or more fields, you'll see an error message with a count of the invalid rows (see the screenshot below). Click the Download Errors link and review the errors reported in the downloaded file, so you can fix them before doing the import. 

ImportPreviewErrs

At the bottom of the form, you can choose to add the contacts to an existing group, import to a new group, create a new tag, or tag imported records. Adding imported records to a separate group is strongly recommended in order to be able to quickly find the imports and, if necessary, delete and reimport them.

Step3b_1

Step 4: Summary

The final screen reports the successful imports along with Duplicate Contacts and Errors. If you have set the import to add all contacts to a Group or Tag, you can click through to see your imported contact records.

Step4a_2

At this point it makes sense to check to make sure that your import has worked as expected.  Search for the contacts that you just imported and examine their fields and custom data to make sure all is as expected.

Importing relational data

We have just described the process of importing one data file.  But what about if you want to import related data, like parent child relationships, activities, contributions, etc.?  For each type of data you want to import, you will need to import a seperate CSV file.

CiviCRM has specific tools for importing related contact data and a set of specific import tools for contributions, memberships, event participation etc. (and you should see specific chapters for details of how to use these tools).  To import relationships, you should run multiple contact imports.

For example if we want to import data for children and then for both parents, we run three imports, one for the child, one for the father and one for the mother.

We first import the child remembering to include an external identifier that we can use to match the child to their parents.  We then import the father, and then the mother, as related contacts, linking them to the child using the child's external identifier.

In the example below we have one CSV file which contains father and mother information.  We use this CSV file twice as part of the import.  Have a look at the fields below to understand what is happening.

Parent1a

We are linking the father to the original child using the external identifier and are then importing the related father name using the 'Child of' relationship type.

Parent1b

When the import is done, go back and verify the data by searching for the parent and examining the relationship tab.  They should have a relationship linking them to the child.

You can then repeat this process for the mother, and also for other relationships as necessary.

Full example of a multiple import

A full example of a relational import based on an example of a school, which includes mothers, fathers, teachers, advisors etc, can be found on the wiki at:
http://wiki.civicrm.org/confluence/display/CRMDOC/Importing+Student%2C+Staff+and+Parents

The example has step by step instructions and can be useful in better understanding the import process.

Deduping and Merging

Duplicate contacts can turn up in your data for many reasons, such as mistakes by users who don't realise they're creating a contact for someone who is already in CiviCRM, duplicates that aren't caught in the import process, and duplicate records created when people fill in forms about themselves (maybe with their names spelled differently or use a different email address) on your site without realising they're already in your list of contacts.

CiviCRM is equipped with duplicate matching rules that are applied automatically when new contacts are created, and can be run manually at any time to search for duplicates. You can configure these rules to suit your needs.

To view the DeDupe rules:

  1. Go to: Administer > Manage in the navigation menu
  2. Select Find and Merge Duplicate Contacts.

This displays the following screen:

rules

From the screen, here's an example of a process to dedupe all individuals in your data:

  1. Start by looking for dupes using a strict rule: click the Use Rule link for the third row (Contact Type: Individual, Level: Strict).
  2. Select All Contacts or a particular group.
  3. Click Continue.
  4. If duplicates are found, merge or delete the duplicate contacts.
  5. Now look for dupes using a fuzzy rule to find those dupes that were missed with the stricter rule: Click the Use Rule link for the fourth row (Contact Type: Individual, Level: Fuzzy).
  6. Select All Contacts or a particular group.
  7. Click Continue.
  8. If duplicates are found, merge or delete the duplicate contacts.

Different rules are configured for each contact type (individuals, organizations, and households.)  A default fuzzy rule and a default strict rule is set for each contact type. The default rules are used when CiviCRM invokes automatic checking, in ways we'll explain in detail shortly.

Strict and fuzzy rules

CiviCRM includes two categories of dedupe rules:

Configuring rules

To determine whether two contacts are duplicates, CiviCRM checks up to five fields that you can specify. You can also set a length value which determines how many characters in the field should be compared. For example, if you set a length of 2 on the "First name" field, a first name of "Mike" would match "Michael" and they would be recognized as duplicates, because the first 2 characters are the same. However, if you set the length to 3 instead, "Mike" would no longer match "Michael" and they would be accepted as different contacts. If the length value is left blank, the comparison is done on the entire field value.

Each field is also configured with a numeric weight that determines the relative importance of a match on that field. When a match is discovered on a field, that field's weight is added to the total weight for the rule. After each field is checked, if the total weight is equal to or greater than the numerical threshold set for the rule, the contacts being compared are flagged as suspected duplicates.

Using rules and merging duplicate contacts

Go to: Administer > Manage > Find and Merge Duplicate Contacts, and click the Use Rule link to scan for duplicate contacts using the selected rule. You can then select to search all contacts for duplicates or to search only a particular group. Contacts of the type to which the rule is assigned will be scanned and compared. If the match between two contacts exceeds the rule's threshold, the contacts will be displayed on the following screen of possible duplicates.

Clicking Merge for any pair of contacts brings up a table showing details for each contact. CiviCRM designates one record as the duplicate record and displays its information in the left column. The record in the right column is considered the original record into which selected data from the duplicate record will be merged. If you want to move the information in the opposite direction, you can swap the duplicate and original contacts by choosing "Flip between original and duplicate contacts".

For each field, you can choose whether to keep the original data shown on the right (don't check the check-box in the middle column), or use the value from the duplicate contact instead (check the box). For the email addresses or phone numbers, you can decide to keep both the value of the duplicate and of the original (check both the checkbox in the middle column and the "add new" on the right column) to copy the duplicate data. Note that associated tags, groups and activity data (including event attendance, contributions, etc.) will appear in addition to data already recorded in the original record, not in place of it. It is safer in general to keep the tags, groups and activities of both contacts after the merge.

Exporting Your Contacts

Exporting lets you share data with external applications by providing a copy of data from CiviCRM in a standard comma separated value (CSV) format. This format can be viewed and edited in spreadsheet applications, imported into other database applications, or merged with word processing documents.

You can either export a predefined set of fields or create your own custom export mapping which can be saved for reuse.

CiviCRM's export functionality is available:

Here's how you can export contact information:

Search for contacts. Carry out a search based on your desired criteria using one of the available search tools, e.g. Quick search, Find Contacts, Advanced search, Search Builder, or a custom search (you can find out more about performing searches in the Searching chapter earlier in this section)

Select contacts you wish to export. Select all records, or choose individual records for export using the check-boxes to the left of each record. From the "- actions -" dropdown menu, choose Export Contacts as shown in the following figure, and click Go. This takes you to the export wizard.

ExportFromSearch  Export primary (default) or selected fields. Choose between exporting the primary fields or selecting your own set of fields for export. The primary fields include all core contact fields with email, phone, and address data. If this is satisfactory, click Continue >> and skip step 4 of this list.

If you want to add or remove fields to be exported, choose "Select fields for export" and continue with step 4. The default export uses primary location data, so if you wish to export non-primary addresses you need to select fields for export and explicitly specify the address type

Select Fields to Export Choose the fields you want to export. CiviCRM allows you to save this export mapping, which enables you to reuse the export field mapping at a later time. To save your selection of fields, click "Save this field mapping" at the bottom of the form and enter a descriptive name for this type of export.
ExportSelectFlds

Click Export to create your CSV file. By default, a comma is used as the field separator for import and export functions. In some locales, other characters are used (e.g. a semi-colon). You can change the separator value by going to Administer > Configure > Global Settings > Localization and modifying the Import/Export Field Separator.

s2

Postal Mail Communications

This chapter discusses the different ways that CiviCRM helps with postal mail and post mail campaigns. It will help if you already have a strong understanding of CiviCRM's search features as well as custom fields, activities, profiles, and how to perform mail merges using word processing software.

Planning Your Mailing

Before beginning any communication activity, take the time to identify your goals and plan the steps. For our purposes, there are a few key questions to ask before sending out postal mailings.

There are three ways that you can use CiviCRM in postal mailings:

  1. Generate labels: print out standard address labels when you don't need to personalise the content, for instance to send a printed brochure.
  2. Export contacts and do a mail merge to an external tool (such as OpenOffice or Microsoft Word). Refer to the chapter on Exporting in the Getting Around section.
  3. Generate PDF letters and do the merge directly in CiviCRM.

TIP: Many nonprofit organisations in the USA need to sort recipients of a mailing based on zip code for bulk mailing purposes. If this is true for your organisation, it is recommended that you create your mailing labels using a word processor where you can control the sort order, rather than in CiviCRM. You can reuse the same spreadsheet for your mail merge.

Fundraising Mailings

Many non-profits have specific types of mailings such as thank you letters, renewal letters, and general fundraising appeals which need to be personalised. Here are some suggestions for how to handle those types of mailings.

Greetings and salutations

An important part of a postal mailing is including a salutation that is personable and friendly. Some people prefer to be greeted in a special way if they are a doctor or esteemed person such as a politician.

You can set a specific postal greeting format for each contact. There are several options from the friendly "Dear John", to more formal "Dear Mr. John Doe". You can also enter a customized greeting ("Your royal highness"). Postal greetings can be edited in the Communications Preferences section of the contact edit form. If you need to set or reset postal greetings en mass, refer to the Command Line Script Configuration documentation:

http://wiki.civicrm.org/confluence/x/LIK9AQ

Print PDF letter

The workflow is to first select the group you want to target, then choose the action "Print PDF letter" from the dropdown menu. The letters will then be outputted as a PDF, allowing you to easily print them.

To create the letter:

  1. Go to Search > Find Contacts or Find Contacts > Advanced Search.
  2. Enter your search criteria and click Search.
  3. Select the contacts who will receive the letter.
  4. From the Actions dropdown menu, choose "Print PDF Letter for Contacts" and click Go.
  5. Create your letter, using the formatting options provided. You can personalise the letter by using tokens, for example Postal Greeting is a commonly used token in this situation. Click in the body of the letter where you want to enter the token. Then click on "Insert Tokens" located above the letter at the top right and select the desired token.
  6. Before you move to the next screen, decide whether the format of this letter could be used again. If so, check the Save New Template box and enter the Template Title.
  7. When your letter is finished scroll to the bottom and click Make PDF Letters.
  8. A pop-up window will offer the option of opening or saving the PDF. Open and review your letter and then print it, or save the PDF and review at your leisure.

 PostalGreetingToken

TIP: You can use this feature for any kind of document, not only letters. For example, you could use it to print attendance certificates for a workshop.

Generate mailing labels

Generating mailing labels is a very easy and useful function.

  1. Perform the search to select the contacts you want to target.
  2. Choose Mailing Labels from the Actions dropdown menu and click Go.
  3. Select the mailing label style
  4. Determine if you want to exclude people with "do not mail" checked in their privacy options (checked by default and recommended), and whether you want to merge any records with the same mailing address into one label.

This last option is very useful when sending a mailing to a households or organisations where you don't want them to receive duplicate mailings. When the records are merged, each name at that address is listed on a separate line on the label.

Your system administrator can configure the fields included in mailing labels. Read the information on configuring address settings in the Contacts chapter to learn more about the options.

Everyday Tasks

The following are step-by-step guides to performing common and useful tasks in CiviCRM.

Adding contacts to groups

  1. Perform a search and select the contacts that you wish to add to your group from your search results (you can choose either specific contacts or all contacts).
  2. Select Add Contacts to Group from the dropdown " - more actions - " menu, then click Go.
  3. On the Add Contacts to A Group screen, select the appropriate radio button to either add the selected contacts to an existing group or create a new group for the selected contacts.
  4. If you are adding contacts to an existing group, select the desired group from the Select Group dropdown menu, then click Add to Group.
  5. If you are creating a new group, enter a Group Name. You can also optionally enter a Description and/or select a Group Type (refer to the Tags and Groups chapter of this manual for more information on Groups and Group Types.) When finished, click Add to Group.
  6. You should see a message stating that the number of participants that you selected have been added to the group. 
  7. Click Done to return to your search results.

Creating smart groups

Smart group are useful in many different situations. They are often used to assist organisational workflows. For instance, when you find yourself doing the same search over and over on your contacts, you can save the search as a smart group. Whenever you select that group, CiviCRM will run the search and display the results. Any new contacts that meet the search criteria will be added to the group, and contacts that no longer meet the criteria will be removed from the group.

Smart groups can be created from the search results generated by any of the search forms. For example, you can create a smart group of all donors who have not yet been sent a thank-you letter. As you send your letters, the donors receiving them will automatically leave the smart group, allowing you to always have an accurate list to work from. To create this smart group:

  1. Go to: Search > Find Contacts > Advanced Search.
  2. Scroll down to the Contributions section and click on Contributions.
  3. Check "Thank-you date not set?" and choose Donation from the Contribution Type dropdown menu.
  4. Click Search at the bottom of the page.
  5. Click the button that selects all the records
  6. From the " - more actions - " dropdown menu select New Smart Group, then click Go.
  7. The next screen provides a review of the criteria chosen for the smart group. Give the smart group a name, a description (optional) and decide if you want to make this smart group a Mailing List (allowing you to include the smart group in CiviMail). Then click Save Smart Group.
  8. You can view your smart group by going to: Contacts > Manage Groups where you will see your smart group in the list.

Creating relationships between contacts

CiviCRM allows you to represent connections between contacts by creating relationships. For example, if a mother and son are both in your database, it can be useful to be able to look at either record and see that they are related to each other. To do this:

  1. Navigate to one of the records that you want to relate.
  2. Click on the Relationships tab in the Contact's record.
  3. Click New Relationship.
  4. Select the Relationship Type. In this case it would be either "Child of" or "Parent of".
  5. Click inside the Find Target Contact box and begin to type the first name of the person you are relating to this contact. One or more options will be displayed. Click on the appropriate entry.
  6. Click Search.
  7. Click the check-box next to the name of the person you are relating to this contact.
  8. You can scroll down and enter further information, which includes Start Date and End Date (in case the relationship is time limited), Description and Notes. There are also two permission-related options, which allow users of the database to edit this record. Finally there is an Enabled? box, which is checked by default.
  9. When you have made the changes you want, click Save Relationship.

Connecting employees and employers

A quick way to connect employees (which are stored in CiviCRM as individuals) to employers (stored as organisations) is to use the Current Employer field within an individual's record.  This will set the current employer field in the contact record and create a relationship between the contacts.

  1. Navigate to the record of the individual who you want to connect to an organisation.
  2. Click the Edit button to edit the individual's record.
  3. Begin typing the organisation name into the Current Employer field. As you type, matching names of organisations that already exist as contacts in CiviCRM will appear in a dropdown autocomplete list below the Current Employer field. If the organisation is already a contact in CiviCRM you can select it from the dropdown list by pressing the down arrow key or by clicking on it. If the organisation does not already exist as a CiviCRM contact, simply enter the full organisation name.

    Employee_Org_Rel
  4. After the organisation's full name is entered in the Current Employer field either press the Enter key or click the Save button. If the organisation is a pre-existing contact, an Employee/Employer relationship will be created between the individual and the organisation. If the organisation does not already exist, a new organisation contact will be created and the relationship will be created between the individual and the organisation. You can click on the Relationships tab to view your newly created relationship Employee of and see any existing relationships.
Relationships

Adding contacts to organisations

  1. Select the desired contacts from your search results as described above.
  2. Select Add Contacts to Organization from the dropdown " - more actions - " menu, then click Go.
  3. On the Add Contacts to Organization screen, select the Relationship Type from the dropdown menu.
  4. Enter part of the desired organisation name in the Find Target Organization field, then click  Search.
  5. Organisations that match your search will appear in the "Mark Target Contact(s) for this Relationship" section below the Search and Cancel buttons. If the organisation you're looking for appears in this list, click the radio button next to that organisation and then click the Add to Organization button below. If the organisation you're looking for does not appear in this list, try entering something different into the Find Target Organization field and clicking Search again. If you are still unable to find your desired organisation it may not exist; click Cancel, add a new organisation, and try again.
  6. After you've successfully chosen an organisation and clicked the Add to Organization button, you should see a message stating that the number of participants that you selected have been added to the organisation.
  7. Click Done to return to your search results. 

Adding contacts to households

  1. Select the desired contacts from your search results as described above.
  2. Select Add Contacts to Household from the dropdown " - more actions - " menu, then click Go.
  3. Select the Relationship Type from the dropdown menu. Note that while CiviCRM will not stop you from adding multiple contacts as Head of Household for a single household, this may cause problems later on in any situation where you are expecting Head of Household to refer to only one individual per household. Therefore, the "Household Member of" option may be the better choice in most situations.
  4. Enter part of the name of the household to which you are adding contacts (such as a last name shared by household members) in the Find Target Household field, then click Search.
  5. Households that match your search will appear in the "Mark Target Contact(s) for this Relationship" section below the Search and Cancel buttons. If the household you're looking for appears in this list, click the radio button next to that household and then click the Add to Household button below. If the household you're looking for does not appear in this list, try entering something different into the Find Target Household field and clicking Search again. If you are still unable to find your desired household it may not exist; click the Cancel button, add a new household, and try again.

    AddMemberHousehold


  6. After you've successfully chosen a household and clicked the Add to Household button, you should see a message stating that the number of participants that you selected have been added to the household.
  7. Click Done to return to your search results. 

Creating new relationship types

CiviCRM comes with a set of common relationship types that can be used to indicate relationships between contacts. If you need to track different types of relationships between your contacts, you can create your own custom relationship types.

  1. In the navigation menu, go to: Administer > Option Lists > Relationship Types.
  2. Review the list of existing relationship types to ensure that you are not creating a duplicate.
  3. If the relationship type you need does not already exist, click the New Relationship Type button.
  4. Enter descriptive labels for the relationship type you are creating in the "Relationship Label-A to B" and "Relationship Label-B to A" fields. The "Relationship Label-A to B" field describes the relationship between Contact A and Contact B; the "Relationship Label-B to A" field describes the relationship between Contact B and Contact A. You will designate which contact types are used for Contact A and Contact B respectively in step 5.

    Some relationships can be described by the same label in both directions; in these cases you can enter the Relationship Label once in the "Relationship Label-A to B" field. For example, when describing the relationship between two domestic partners named Sylvia and Audre, you can say that Sylvia is the "Partner of" Audre and Audre is the "Partner of" Sylvia. Therefore you would enter the "Partner of" label only in "Relationship Label-A to B" field, leaving the "Relationship Label-B to A" field blank.

    In other situations one Relationship Label cannot be applied in both directions; in these cases you need to enter different Relationship Labels in each of the Relationship Label fields. For example, you can say that Kiyoshi is the "Grandparent of" Yuki but you cannot say that Yuki is the "Grandparent of" Kiyoshi. Therefore you would enter the "Grandparent of" label in the "Relationship Label-A to B" field and either "Grandchild of" or "Grandparent is" in the "Relationship Label-B to A" field.
  5. Use the Contact Type A and Contact Type B fields to designate which kind of contacts are being linked by your relationship. Remember to check that the contact types you select for Contact A and Contact B make sense when corresponded to your Relationship Labels.
  6. Optionally enter a description for this relationship type. This is especially useful if the intended purpose of this relationship type may not be obvious to other users.
  7. Leave the Enabled box checked unless you intend to create this relationship type but not allow users to utilise it until a future date.
  8. Click Save. You will see a message telling you that the relationship type has been saved and you will see your new Relationship Type in the list below.

Disabling or deleting unneeded relationship types

If an existing relationship type is no longer useful or relevant for your organisation you can either disable or delete it so it is no longer presented as an option for new relationships. Disabling rather than deleting the relationship type has two significant advantages: you will still be able to see existing data on relationships of this type, and you can easily enable the relationship type again should you find you need it later.

  1. In the navigation menu, go to: Administer > Option Lists > Relationship Types.
  2. Click the "more" link in the row of the relationship type that you'd like to disable or delete. 
  3. Select either Disable or Delete from the pop-up menu.
  4. If you select Disable, a pop-up confirmation bubble will appear. If you select Delete, you will be directed to an additional screen that provides a more serious warning and requests confirmation. Review the information provided in either confirmation message and if you are sure you'd like to complete this action, click the OK or Delete button.
  5. If you have chosen to disable the relationship type it will appear in red in the Relationship Types list and relationships of this type will still be visible when viewing contacts. If you have chosen to delete the relationship type it will no longer appear in the Relationship Types list or in contact relationships data. In either case users will no longer be able to create new relationships of this type.

To enable a previously disabled relationship type, follow steps 1 and 2 above and select Enable from the "more" pop-up menu.

Merging contacts from search results

If you notice duplicate contacts within a set of search results you can quickly merge them directly from the search results instead of using the separate "Find and Merge Duplicate Contacts" process. This is a great way to clean up your database during your everyday workflow with minimal disruption.

  1. Select the duplicate contacts from your search results by clicking the check box at the left side of each record.
  2. Select "Merge Contacts" from the " - more actions - " menu, then click Go.
  3. Follow the normal steps for merging duplicate contacts; see the Deduping and Merging chapter for more information.

What is CiviContribute?

CiviContribute is a CiviCRM module that supports fund-raising and related money management. It has two main uses:

CiviContribute has a number of tools for raising money through your website. You can create contribution pages with fundraising targets. Campaigns support a thermometer style widget that you can embed on other websites and blogs. Personal campaign pages (PCPs) and tell-a-friend functionality engage your supporters in raising money for your organisation and give them credit for any money that raise from other people on your behalf. 

Planning

This chapter is aimed at fundraisers, administrators and others who want to use CiviContribute. You should find the information here useful before configuring and using CiviContribute.  Start by listing the types of contributions you receive as an organization and which of those you want to track using CiviCRM. Then evaluate the following issues.

Data needs and fields

CiviContribute has a set of predefined fields to track contribution information. If you need to track more information about contributions, you can define and use custom data fields.  Custom data might be useful to further categorize your contributions or track additional information.

Consider all the information you want to track about your contributions, including the reports described later in this chapter. Then carefully compare your data needs to CiviCRM's predefined fields. A lot of useful functionality is built in to the core contribution fields and there's no point in duplicating them with custom fields.

Types and accounting codes

CiviContribute categorises contribution by type. Examples of contribution types include event fees, member dues, donations, and grants.

To aid integration with your accounting software, you can assign an accounting code to each contribution type.  This accounting code is included when you export contributions for import into your accounting package.

Reporting and evaluation

Reports can support targeted fundraising, reveal how you can improve fundraising processes, and help you gauge the financial health of your organization. Examples of what you can learn include:

As part of the planning process, consider the reports that you would like to run with CiviCRM. The data they require helps determine the data you need to collect in CiviContribute, and whether you need to create new custom fields to hold the data. This planning also helps you configure CiviContribute to allow you to run these reports.

CiviReport comes out of the box with a number of reports designed to give you information about your donors and fundraising campaigns.  Spend some time familiarising yourself with these reports.

Configuring

This chapter shows how to set up CiviCRM, and particularly its contribution management component, CiviContribute, to support fundraising. Throughout CiviCRM, the term "contribution" refers to any financial transaction or payment taking place in the system: a donation, event fee payment, membership dues payment, or other similar transaction.

This chapter assumes you have a working understanding of custom fields, contact matching rules, CiviCRM Profiles, and the CiviMember and CiviMail components. The chapter also assumes you have already set up your payment processor, configured contribution types, and created any custom fields you want to use when tracking contributions.

General Configurations

You may need to configure the following fields before you begin setting up various methods for managing contributions.

Online Fundraising

One of the most useful aspects of CiviCRM is its integration with your site's content management system.  Once integrated with either Drupal or Joomla!, CiviCRM allows you to build an unlimited number of contribution pages that can be seamlessly accessed from your website. Contribution pages can be used to:

This section will walk through each of those three scenarios and point out some options and features that may be useful. Once you answer all the necessary questions and consider all the points mentioned in the chapter, you can build your contribution pages. Step-by-step documentation for doing that is available at http://wiki.civicrm.org/confluence/display/CRMDOC/Manage+Contribution+Pages.

General Online Contribution Page

Before you configure a general contribution page, ask:

Once you have answered and resolved all of these questions, you can build your contribution page. Go to CiviContribute and click on Manage Contribution Pages > New Contribution Page. The options and settings should map pretty clearly to the choices you made for the questions listed in this section.

Membership Sign-up Donation Page

CiviContribute is closely integrated with CiviMember, the membership management component of CiviCRM.  This means that your online contribution pages can allow people to join your organization at predefined membership levels.  When people do, they create not only a membership record for themselves but a corresponding contribution record.

You must create all of your membership types and status settings within CiviMember before you build your online membership sign-up page.

Before building your membership sign-up page, you need to ask most of the questions listed in the previous section for the contribution page. A couple of additional questions include:

If your organization allows organizations as well as individuals to become members, you will need to allow individuals to join on behalf of an organization. Depending on your membership structure, you may want to require this behavior.

Campaign Fundraising Page

In addition to the questions in the previous sections about how the contribution page will be used and what information it will capture, CiviCRM includes some exciting features for campaign fundraising purposes:

Publicizing your campaign

Now that you've created your contribution page, it's time to bring people to the page so they can contribute. Naturally, you will display a link to the page prominently on your website through a donate button or menu item. Here are some additional tips for promoting a contribution page in different CiviCRM configurations:

CiviContribute contribution pages have "ugly" URLs.  In other words, they are difficult to remember. An example is :

www.myorganization.org/civicrm/contribute/transact?reset=1&id=1

You may find it useful to create a URL redirect (take people from one URL of your website to another automatically) on your server to take people to a "pretty" URL like:

www.myorganization.org/donate

Pretty URLs are much easier to remember and use in your organization's outreach. Creating a redirect requires some technical skill and access to your web server.

Drupal provides a helpful module called Path Redirect (http://drupal.org/project/path_redirect) that lets you can create URL redirects from the user interface without complicated web server configuration. Joomla! users also have a work-around if Search Engine Friendly URLs are enabled in Global Settings. You can then create a menu link to the contribution page and define the "pretty" URL using the alias field.

Emailing your current membership is the other critical way to publicize the campaign. The CiviMail component of CiviCRM allows you to send targeted emails to any group of contacts in your database. Within a CiviMail message you can include links to the contribution form and use CiviMail's tracking capability to see how many people click on that link.

One time-tested way to increase contributions is to send each targeted constituent a personalized email with a link to the contribution form that has all of their contact information already filled in. This saves them the hassle of filling it out and raises the chances that they donate. Using CiviMail, you can use this feature by creating a special link in the body of your CiviMail message that includes a checksum token. A checksum is a unique and pseudo-random number assigned to each recipient of the mailing that points back to their contact information, securely stored in your database.

When people click on the special link, CiviCRM looks them up in the database and pre-fills fields on the contribution form (core fields or fields exposed via a profile) with any information in their contact record.  To read more on how to do this and what the link path must be, visit: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data

Automatic Contribution Recording

Regardless of how donors get to your contribution page, CiviCRM automatically records their donations, freeing your staff from doing manual data entry. If the donors already exist in the database, CiviCRM adds the contribution to their existing record. If they don't exist, CiviCRM creates a new record for them.

To record contributions in the appropriate records, CiviCRM must identify the donor correctly by comparing the information they enter into the contribution page to their contact in the database. By default, CiviCRM checks just the contributor's email address. In other words, if Judith Monroe has a contact record in CiviCRM with an email address of judith@example.com and she puts in that email address when she contributes, but with the first name of Judy, the contribution will correctly go into her record. If she puts in another address, such as a Hotmail or Gmail account, a new record will be created and you may have to manually clean it up later. Note that this problem appears only for anonymous visitors (those not currently logged into your website). Once users log into the website, CiviCRM recognizes them in the system and will attribute any activity to their records.

We recommend that you configure CiviCRM to match contact information very strictly by changing the default duplicate matching rules.  In our opinion, it is better to risk creating a new (duplicate) record for someone who is already in the database than to incorrectly credit their donation to someone else. It is not uncommon for multiple people to share an address such as info@example.org  or judyandjim@example.com, the default rules may find the wrong contact if such a shared email address is entered. We recommend you change the duplicate matching strict rule so that the first name, last name, and email must all match. This raises the bar on whether data is merged with an existing record, increasing the change that a new record will be created. Using CiviMail's automatic fill-in feature (the checksum token) will help avoid some of these issues. To configure your duplicate matching rules, navigate to Administer CiviCRM > Find and Merge Duplicate Contacts.

Offline fundraising

Organizations have plenty of offline opportunities to raise money. You may pick up donations at events or solicit donations via postal mailings. For money raised through any of these offline activities, your staff needs to enter the results manually.

There are three steps in offline fundraising: creating your lists, creating your mailings, and manually entering contributions.

Creating your lists

This process is fairly straightforward if you are familiar with CiviCRM's search capabilities.

  1. Create a list of records to receive your offline postal mail appeal (this can be your entire database if you like). If you want to later track the success of a mailing or if you are tracking who receives certain appeals, it is recommended you save the search results as a group.  Later on, you can mark everyone in that group as recipients of that appeal using the Record Activity for Contacts option under the "- actions-" menu.
  2. From a search (whether a search of the groups' members or of other criteria) you will see an "- actions -" dropdown menu that allows you to, among other things, export the list as a CSV file. Select all records or a subset using the checkboxes, choose "export", and click Go.
  3. As you export to a CSV spreadsheet, you can determine which fields you want to export to your spreadsheet and save the list of exported fields as an export mapping for future use. By default, CiviCRM will export a great deal of data, including contacts' names, contact information, email addresses, phone numbers, and a list of their groups and tags.

Creating your mailings

Once your spreadsheet is created, you can do a mail merge using any popular word processing software (such as OpenOffice.org Writer, the Free Software Word Processor) that will insert any fields you want in the letter.

CiviCRM can also create mailing labels for you. Perform the same search you used in the previous section to create your list of recipients, but under the More Actions menu, choose Mailing Labels. Then select the mailing label number, determine whether you want to exclude people with "do not mail" checked in their privacy options (checked by default and recommended), and whether you want to merge two records that have the same mailing address into one label. This last option is very useful when you are mailing a household or organization and you don't want them to receive duplicate mailings. When the records are merged, each name at that address appears on its own line on the label. Once you click 'Make Mailing Labels," a PDF document will be created that you can print.

Its important to note that many nonprofit organizations in the United States have to sort recipients of a mailing based on zip code for bulk mailing purposes. If this is true for your organization, it is recommended you do not create your mailing labels within CiviCRM, but instead create them using word processor merge functions where you have control over the sort order. You can reuse the same spreadsheet for the mail merge you exported in the previous section.

Payment processors

A payment processor is a tool that integrates with CiviCRM to process live credit card transactions. In other words, it accepts the credit card information submitted by your site visitor, processes it, and transfers money to your organization's bank account.  As of this writing, the payment processors compatible with CiviCRM include:

Each has their own pricing structure and features, benefits and drawbacks.  You should carefully investigate each available option to determine what's best for you.  Important things to consider include:

Secure Sockets Layer (SSL/HTTPS)

If you wish to collect credit card information through a CiviCRM form (as opposed a payment processors own website) you must configure your site for Secure Sockets Layer encryption. Alternatively, choose a processor such as Paypal Standard, Elavon or PaymentExpress where the customer is redirected to the payment processor's website to enter their credit card details and back to your site afterwards.

Visitors to your website can determine that their data is encrypted when they see a symbol (often a padlock) somewhere in the browser or by noting that the "http:" part of your url has been replaced by "https:".

To enable SSL, you will need an SSL certificate. An SSL certificate should be purchased through a reputable third party provider, and may range in price from USD$30 to USD$100 a year depending on the company and the level of service and protection they provide.

If you are using shared hosting or a virtual private server (VPS), it is likely that your hosting provider has a list of preferred vendors they work with to provide SSL security. Contact your hosting provider for more information and to get help installing the SSL certificate.

SSL certificates are domain-form specific. If purchased and installed to your root domain (something that looks like example.org), it does not automatically work for subdomains, such as http://www.example.org or http://contribute.example.org. Discuss the options available with your hosting provider and ensure that the certificate and its installation will meet your needs. Wherever possible, purchase a certificate that will cover both the root domain and www form of your domain.

Once the certificate is installed and you have tested its functionality by browsing to a page on your site using https (rather than http), you should enable SSL redirection in CiviCRM. To do this, navigate to Administer CiviCRM > Global Settings > Resource URLs > Force Secure URLs (SSL) > Yes. This will force any pages that include contribution-related information (i.e., credit card fields) to redirect to the secure form of the URL (https).

After you enable the Force Secure URLs setting and save the page, CiviCRM will automatically check to ensure the SSL certificate is activated and working properly.  You should also navigate to a contribution page on your website to confirm that https redirection works correctly. 

PCI DSS Compliance

The prevalence and impact of online fraud has led to increased security measures to counteract the schemes of fraudsters. The Payment Card Industry Data Security Standard sets out security standards that all major credit cards require sites to comply with. If your CiviCRM page accepts card numbers directly rather than sending visitors to your payment processor web page, your site and its hosting environment may need to comply with those standards. Some payment processors, notably Moneris, put some of the compliance burden on you by making you complete a long and technical Self-Assessment Questionnaire.

For more information, visit: https://www.pcisecuritystandards.org/

Everyday Tasks

This chapter describes some common CiviContribute tasks.

Adding contributions

When your organisation receives a contribution from a contact, you can add it to their record.

If the donor does not already exist in the database, you need to first create a new contact record for them. Use the links on the CiviCRM home page to create a New Individual, New Organization, or New Household, and fill out any information you have for this contact. Once the record is created, you can then enter the contribution.

To manually enter a contribution for a contact in your database:

  1. Find the contact's record using one of the contact search tools.
  2. Select the contact's Contributions tab.
  3. Click Record Contribution (Check, Cash, EFT...). Alternatively, if you have set up a payment processor that allows credit card transactions directly on your site, you may select the Submit Credit Card Contribution option and process the payment immediately.
  4. Complete the new contribution form. The following screenshot shows the offline contribution (i.e. contributions via check, cash, EFT, etc.) form. If you selected to record a credit card contribution, the credit card form is almost identical except for the payment-related fields.

Record


Record the contribution type, amount, received date (the default is the current day), receipt date (shown on the receipt generated by the system), and status (the default is Completed). Any custom fields for contributions will also appear on this form.

The Soft Credit To field works with personal campaign pages (PCPs) that harness your contacts' help for campaigns. As described in the previous chapter, when a donor sets up a PCP for their friends and family to make donations to your organisation, some of the credit goes to the donor who set up the PCP. The person giving the money receives a "hard" credit while the owner of the PCP receives a "soft" credit. When you enter a donation manually on the contribution form for the contributor, you can assign a soft credit to the owner of the PCP. Soft credits can also be applied to spouses, partners, or employers, to give an indication of how much money is coming from a relationship or providing a credit to employees if they urged their employers to donate. (There is more information about PCPs and campaign fundraising pages in the Configuring chapter of this section on CiviContribute.)

The Additional Details section near the bottom of the screen offers other options including adding a note about the contribution and entering the date when a thank-you letter was sent.

The last two sections allow you to enter whether the contribution was in honor of someone else (Honoree Information) and whether there is a premium associated with the contribution (Premium Information).

Viewing the CiviContribute dashboard

The CiviContribute main page or dashmboard summarises the contributions made, including lists of contributions received in the current month to date, year to date, and cumulatively since the campaign's inception. For example, the following screenshot lists the most recent contribution to a campaign using the Table Layout tab:

ContactSummary1a

 

You can also view bar or pie charts to compare contribution totals across months of a given year and across years by clicking on the Chart Layout tab.

ContactSummary1b

Finding contributions

Use this screen to find contributions made to your organisation.

To View the Find Contributions screen:

  1. Click the Contributions Tab.
  2. Select Find Contributions.

FindContributions


You can search based on a number of criteria, specifying date range, amount, contribution status etc.

Contributions must match all specified criteria in order to be returned, so the more criteria you enter, the narrower the search will be. For example, searching for the contribution type "donation" and the date range "January 1st to May 31st" will return contributions that meet both criteria.

The results screen from a search displays the the total amount for the results returned for that search, the number of contributions, and the average amount per contribution in addition to the subset of records resulting from the search:

FindContributions1b 

You also have options under the "actions" menu once you select all or a subset of records. The "actions" menu allows you to:

What is CiviEvent?

CiviCRM's CiviEvent module centralizes your registration data process, lets your constituents register themselves (including such conveniences as paying online with credit cards), and even gives people live access to your data while onsite at the event.

CiviEvent is integrated with CiviCRM's other modules, so you can send a targeted email to the list of participants, or to specific subsets such as the ones who have a volunteer role but cancelled attendance. Moreover, each registration is added to the list of activities for the contact, letting you see for instance that Mr Doe registered 15 hours after having received your monthly newsletter.

Scenario: recruiting for an annual youth leadership workshop

Organizations have many ways to take advantage of CiviEvent to lighten the task load when planning and managing events. Here is a scenario of how an organization is using CiviEvent.

A community organizing group holds leadership workshops for youths 25 and younger as their major yearly event.  They invite youth speakers and volunteers, as well as several other speakers for the training workshops. The organization also charges nominal fees for meals and lodging, a flat fee for the registration fee, and additional costs for optional workshops. Information is collected beforehand about the participants' food and lodging preferences. The event invitation is usually sent to a targeted audience contact list to ensure that the organisation's core constituency attends, and the event is also announced more broadly by posting it on the website to allow for online registrations. At the end of the event, staff want to evaluate the success of the event and report results such as number of attendees, total event fees paid, and total amount still due.

To prepare for the event, the organization plans their data needs and the tasks needed to configure the event as well as to keep tabs on the registration and event management process. Here are some items that the organization plans to do in preparation for the day of the event:

Planning the Event

Before you dive in to create an event, we recommend you review the work flow in this chapter to help you plan for setting up and managing the event. The work flow also includes concepts you should know about the structure and functions of the event management process.

Global Event Configuration

There are several global event configurations as well as general CiviCRM configurations you will need to consider before you create your event. These configurations define the details and structure of the event, such as the type of event, the cost if it's a paid event, and the payment processor to handle credit cards. You can also configure information about the type of participant, e.g. attendee or speaker, and define different status options to help track participants' progress through the event process, from being Registered to indicating whether they Attended or were a No-Show. You may also want to capture additional information about the participant, such as food preference if the event is a Dinner. Additional data often requires you to create custom data and profiles in the general CiviCRM configuration.

Some of these configurations are a required prior to creating the event, so familiarizing yourself with these concepts and planning your data needs before you create the event will help streamline the event configuration process. Although, if you've already begun creating an event when you decide to expand your configuration needs, you can always complete the event configuration process, address your additional data needs, and return to reopen and complete the event configuration.

You may want to review the following concepts before you begin to configure your event.  These concepts will be discussed in more detail later in the following chapters of this Events section.

Creating the Event

In addition to planning the configuration you will need, you may want to ask some questions to help you make some decisions about the details of your event:

Thinking about the structure of your event and how you want a person to experience the event registration will help inform whether you need to do additional configuration and how to set up the event.

Test Driving the Event

Once you finish configuring and setting up the details of your event, you are well advised to test drive the event to make sure all the pieces of the event process are working according to your expectations. You may want to test the following:


Test the event through the eyes of a person who is registering for the event, to make sure the flow of the registration process guides the person effortlessly each step of the way. After initial testing, if you send your invitation email to a person in the organisation that hasn't been directly involved in the the configuration of the event, you can get a fresh point of view that represents what your contacts will feel during the process.

When using the "Test-drive Registration" option, you see the same registration pages as a regular user, but the online payment isn't really debited from your card (and you can enter a fake one).

Promoting the Event

Think about all the ways you would like people to learn about your event:

In addition to configuring and creating your event, you may need to plan how you could use other CiviCRM functions to promote the event, as well as determine what other tools, such as as your website, may need to be utilized to promote your event.

Managing the Event Process

From the time you announce your event to the time the event is over, there will be ongoing event management tasks that you may need to carry out to ensure good participation:

The event management tasks vary depending on the type of event and venue you're planning, and CiviCRM supports these tasks through many event and communication tools, along with its searching and reporting features.

Consider asking the staff people directly involved in these tasks to add a report for that event in their dashboards, in order to have a direct overview directly on their homepages.

Following up after the Event

Once your event is over, you may want to evaluate the event by looking at the total number of attendees, the total event fees received, who hasn't completed payment for their registration, and who canceled. Several event reporting tools can help, including the Event Participant Report, the Event Income Summary Report (summary and detail), the Event Dashboard, and search tools such as Find Participant.

It is worthwhile updating the status of each participant during the event or just afterward, while it's fresh in your memory, so you properly flag the no-shows.

It is good practice to send an email after the event to all the participants to thank them and provide links to pictures or slides of speakers if you have published them online. You might want to use this opportunity to promote a new event, suggest that attendees join your organisation as a member, or solicit donations for a specific campaign.

Configuration

This chapter assumes that you've gone through the event planning chapter and sketched out the type of events you need to configure, along with the event-related data you want to collect and track. Now it's time to actually start configuring CiviEvent and creating events.

If you do not see the Events menu item in your navigation menu bar and you don't see CiviEvent under the Administer menu, you may not have the component enabled. Navigate to Administer > Configure > Global Settings > Enable Components to manage which components are enabled.

General CiviEvent configuration

There are a number of "general" configuration tasks for the CiviEvent component that are best to work on first. These settings lay the foundation for creating your events. Review each of the following event-related settings and modify them as needed before you begin creating events.

Event Types

CiviCRM allows you to define different types of events as a categorization mechanism. This is particularly useful when searching through event participants or generating an event listing feed. You can also configure custom fields to store and display additional data about an event by its event type. Take the time to consider what types of events your organization holds and define them in this interface. You can return at any time to add to the list of types or modify an event type label. However, you can not delete event types which have been assigned to one or more events.

Navigate to Administer > CiviEvent > Event Types to review the default list of event types, shown in the following screenshot. You can modify event type labels by clicking Edit on any row. Click "Add Event Type"  to create a new category for your events.

EventTypes 

Participant Roles

When an individual registers for an event, he or she will be assigned a participant role. This field helps you segment your participants into meaningful categories based on their involvement in the event, such as attendee, volunteer, speaker, or staff (attendee is the default role). You can also define custom fields and assign them to a specific role, which can be helpful when you need to collect certain information relevant only to speakers or another role. When creating a registration page for inclusion on your website, you will select a default participant role which will be assigned to all online registrants.

You can search for participants matching particular roles using the Find Participants and Advanced Search screens. 

Navigate to Administer > CiviEvent > Participant Roles to review the default list, shown in the following screenshot. You can modify participant role labels by clicking Edit on any row. Click "Add Participant Role" if you need participant roles that are not in the default list (e.g., audio-visual coordinator, food and beverage manager, etc.).

ParticipantRole

Participant Statuses

The participant status field allows you to track the individual's registration through your system. This can help you identify pending or canceled registrations, people on a waiting list, no-shows, confirmed attendance, or any other status you define. Participant status is also searchable in the Find Participants and Advanced Search screens. 

For organizations that need more of an RSVP workflow, you can rename your statuses to friendly names such as "Yes, I'm Coming", "No, I can't make it", and "Maybe". Then configure, for each of those statuses, which ones are for administrative use only or for public use. This allows you to expose the participant status field via a profile on your registration form, displaying only those with public visibility. For more information on this scenario, visit: http://wiki.civicrm.org/confluence/display/CRM/RSVP-style+Event+Registration

Navigate to Administer > CiviEvent > Participant Statuses to review the default list, shown in the following screenshot. Some statuses in the list are marked Reserved (with a green checkmark). This means that they are required for event workflows and can not be deleted or disabled. However you can change the Label, which is what users see when they select from a list of statuses. ParticipantStatus

There are also five statuses that are disabled by default (displayed in red). These statuses are used for optional event registration features and must be enabled if you want to use those features.

Waitlists

You can offer a waitlist to users during online registration when an event is full. If a space becomes available, the first participant from the waitlist will be invited to complete their registration. The workflow for this feature is described later in this chapter. Enable the "On waitlist" and "Pending from waitlist" statuses here if you want to use this feature for any of your events.

Approval required to attend event

For certain types of events, you may need to require administrative approval for all the participants who self-register, prior to being able to complete the registration process. The workflow for this feature is described later in this chapter. Enable the "Awaiting approval", "Pending from approval" and "Rejected" statuses here if you want to use this feature for any of your events. 

Custom data

CiviCRM provides ample flexibility for you to define and integrate custom fields into your event management process. Custom data are fields that you define and associate with a specific data type. You can then use them to collect information from your contacts as they register for an event, as well as in other ways.

Custom data is managed through Administer > Customize > Custom Data. Begin by creating a new set of custom fields, then designate the objects in which those fields appear. You might assign some fields to events, some fields to participants, and some fields to participants at certain events or participants who take on certain roles (such as speakers). The scope of the custom field set is called its use. Several types of uses are available to CiviEvent tools:

After creating your set of custom fields, define the actual fields within each set. If you are not familiar with creating custom data, refer to chapter in this book on extending core data before creating your actual fields.

Using Profiles for online event registration

Participant custom data groups and fields will be automatically included in their assigned location when you access the information through the CiviCRM administrative tools. However, they will not be displayed in your online event registration page unless they are first included in a Profile, which is then included when you configure online registration for an event.

Participants always provide an email address when they register for an event in CiviEvent, but most organizations find it useful to collect more personal information during online event registration. This might include basic information such as first and last name, as well as event-specific information such as meal preference. You will need to create a profile containing these additional fields prior to creating your event.

Navigate to Administer > Customize > Profile to set up and edit profiles. The following screenshot offers a typical example of a Profile used for a conference where there is an option to provide childcare. Notice that this profile contains fields belonging to Individuals and Participants.

EventProfile 

If you are not already familiar with setting up Profiles, refer to the section on using them.

Registration confirmation and receipting

CiviCRM can send automated confirmation and receipt emails to participants who register online, as well as participants who are registered by your staff or volunteers using back-office screens. The content and layout of these emails are controlled by message templates. Both HTML and Text formats are provided. Your organization may want to modify or add text to these emails, or add branding such as a logo to the HTML versions.

Once you create an event, you can test-drive the online registration process and review the confirmation email. Navigate to Administer > Configure > Message Templates (shown in the following screenshot) and click the System Workflow Message tab to see the list of messages you can modify. Click Edit next to "Events - Registration Confirmation and Receipt" rows to edit the content and layout.

WorkflowMsgTpls 

The templates for these messages include both the text shown and necessary program logic. Use caution when editing so as not to modify the program logic. Be sure to test the workflow and review the emails sent after making any changes. If you find that your changes have caused problems, errors or missing information, you can always "Revert" to the system default for that workflow.

Core settings used by events

Several core CiviCRM settings may play an important role in how you use the event tools:

Creating an event

You're ready now to create an event.  The following sections guide you through a sequence of screens which allow you to control each aspect of the event. As we walk through each step, we will demonstrate the options and their effects on the resulting registration form through screenshots and examples.

It's a good idea to go through each screen in detail as you learn about available options. Later in this chapter we'll discuss how you can streamline the event creation process by creating event templates. These allow you to prefill most options with a single keystroke.

Begin by navigating to Events > New Event. 

1. Event Information and Settings

The first page in the event wizard requests basic information about the event:


 NewEvent

After reviewing the details on this page, click Save to advance to the next step. When you press Save, your event is created. You can interrupt configuration on any subsequent page by clicking Cancel and return later to review and modify any of the event settings. Any information you entered on any page will be preserved so long as you pressed Save on that page. To return to a saved event, navigate to Events > Manage Events and click Configure to continue working on the event.

2. Event Location

The next step in event configuration is to complete the location and contact details for the event. Though optional, it is highly recommended that you take the time to provide these details to your potential participants. If you have enabled a map link in the previous step, make sure that you fully complete the address details on this page (see screenshot).

Once you have entered an event location, you can reuse it for subsequent events by clicking "Use existing location" and selecting from the dropdown list. 

EventLocation

You can also list phone numbers and email addresses on the event information page if you want to give registrants a way to contact event organizers directly. If the event is being held off-site from your organization's primary location, you may also want to provide contact information for the meeting location.

Click Save to save your entries and advance to the next step.

3. Event Fees

CiviCRM supports both free and paid events. If this event is free, set the Paid Event radio button to No, then click Save and skip to step 4, Online Registration. If this is a paid event, click Yes. The screen will show the options available (see the following set of screenshots).

Note that if you plan to accept credit card payments through the online registration form, you need to configure a payment processor prior to completing the details in this section (you will see a notice on top of this screen if no payment processors have been configured). Questions you are asked on this screen are:

EventFeesPayLater

EventRegFees 


CDiscount

Click Save to save your entries and advance to the next step.

4. Online Registration

Your organisation may want its staff to register participants manually. However, allowing people to register online (self-service) through your website offers many benefits. Online registration is convenient for your constituents and can save staff time and resources.

If you want to offer online registration for this event, check Allow Online Registration and use the options on this form to configure this feature.

OnlineReg1
OnlineRegProfiles
OnlineRegEmail
Click Save to save your entries and continue with the next step.

5. Tell-A-Friend

CiviEvent makes it easy to leverage the social networking power of your committed constituents by empowering them to quickly and easily share details about your organization and event with their friends and colleagues. The final step in the event creation is a page where you can enable "Tell-A-Friend" capabilities. You can define the text and links to be included on that page and in the email sent from the tool (see the following screenshot).

EventTellFriend 

A "Tell a friend" activity record will be added to a participant's Activities tab each time he sends mail to his friends. This allows you to track your most active supporters and engage them further. The people who are emailed using this feature are also automatically added to CiviCRM as contacts.

This is the last step in creating an event. Click Save and Done.

Now that you have completed the creation of your event, you should test it. Returning to the Manage Events page, you will see your recently created event listed with any others you have created. From the action list, select Test-drive to test the registration page. Test-drive mode will use the sandbox options for your payment processor, if available, and will create a registrant record with a "test" indication so that it can be reviewed and easily removed.  If you have events where anonymous users register for events, you should also test the registration when not logged in. Refer to the Event Permissions information later in this chapter for details.

If you discover elements that you need to edit and adjust, select Configure to return to the list of event setting pages. Once you are satisfied with the event information and registration form, it's time to display it on your website. The everyday event tasks chapter includes detailed information on adding the event to your website and promoting it.

Using event templates to streamline event creation

If you find that you are setting up a number of events with similar configurations, you can streamline the process using Event templates. Enter all the characteristics your events have in common in the event template. Common characteristics might include location, event fees, online registration settings, tell a friend settings, etc.

Once you've created an event template, you can select that template (as shown in the following screenshot) when you start to create a new event. Your event will be automatically prefilled with all the saved configuration properties.

 NewEventSelTemplate

To create a template, start by navigating to Events > Event Templates and clicking Add Event Template.

EventTemplatesListing

The steps for creating event templates are similar to those described earlier for creating an event.  The main differences are:

Setting permissions for event registration

This section applies to Drupal installations only.

If you've enabled online registration for events on your site you need to review the Drupal user permissions to ensure that visitors are able to view event information and complete the registration forms. Navigate to the Drupal Administer menu and select Users > Permissions.

Most organizations allow anonymous users (users who have not logged in) to view and register for events. If you want to allow this convenience, assign the following CiviCRM module permissions for the anonymous user role:

Alternatively, you can assign these permissions to an authenticated user role if you want to exclude anonymous visitors from viewing or registering online for events. Finally, if you need special access control rules for specific events, you can use the Manage Access Control feature to assign access to specific groups of contacts. If you're not familiar with CiviCRM's built-in ACL (access control list) features, refer to this online documentation:

http://wiki.civicrm.org/confluence/x/Y4C9AQ

Including profiles for an event registration

To collect information about registrants, such as additional contact information or food and lodging preferences, when the registrants register online, the best way is to include profiles in your event configuration. Do this as follows: 

  1. Choose Events > Manage Events.
  2. Click Configure for this event.
  3. Click the Online Registration tab or link. 
  4. Choose one profile for "top of page" and another profile for "bottom of page"

Complex event fees with price sets

Price sets play a role similar to custom data fields and profiles, but support options for event fees instead of basic data collection. Here's an example of how a price set looks to a person who is registering for a Conference that includes optional pre-conference training sessions, meals and lodging: PriceSetRegistration

We saw earlier that step 3 in event creation involves configuring event fees. The standard fees layout form is a very simple structure, allowing you to create a list of fees and their labels. The resulting layout allows the registrant to select one option from the list. Often, this single-option format does not meet the complex demands of your event registration structure. Price sets allow you to create multiple registration fee fields and assign the entire set to an event.

Price sets are created and managed by navigating to Manage Price Sets and choosing the Events link or by navigating to the CiviEvent > Manage Price Sets menu and choosing the Administer link.

Similar to custom data sets, you begin by creating a new price set and then adding specific fields.

Creating a New Price Set

To create a new price set, click "Add Set of Price Fields".  In the Price Set form, enter the name of your price set, whether it's used for events or contributions, and a description. Press Save. A form appears for you to create the first field in your price set.

Creating a New Price Field

Begin by entering a name for the event item in the Field Label.

Picture_20 

The Input Field Type has a structure similar to custom data fields, with some unique qualities and usage relevant to fee structures.

You can combine these field types to create virtually any fee structure.

Enter a number in the Participant Count field if you want to increment the number of registered participants per unit against the maximum number of participants allowed for this event. For example, if this price field is for a table at a fundraiser which seats eight people, you would set Participant Count to 8.

For Text/Numeric Quantity fields, enter an amount in the Price field. For Select, Radio and Checkbox types you will enter a price for each option in the table of options (shown in the screenshot above).

If you want to display the price next to the event item, check the "Display Amount?" box.

As when creating other custom data, you can enter a description for the Field Help, decide whether the event item is Required, select whether the event item is visible to the public or only to the administrator in the Visibility field, and indicate wheter the event item is Active. These fields are described in the chapter on extending core data.

Next, you can either press Save to finish configuring this event item, or Save and New to create another price field for this price set.

Once you finish configuring your price set, you can add it to your event in step 3 where you configure the event fees.  Select the name of your price set in the Price Set field as shown in the following screenshot.

PriceSetEvent

As with custom data fields, it is to your advantage to give thought to the structure of your registration fees and build the price set before creating the event. However, if you begin the event creation process and determine that you needed to construct a price set, you can complete the process, create the price set, and then return to the event configuration page to assign the price set.

Price sets can be reused in multiple events. This is particularly helpful for organizations that run multiple events in a series, such as a regional training seminar program.

CiviEvent Everyday Tasks

This chapter describes a variety of procedures related to managing an event after you set it up in CiviEvent.

Mass Registrations

CiviEvent offers the time-saving feature of registering multiple contacts for an event at one time (or as a "batch"). 

Scenario for doing mass registration

An organization is planning a large event and has invited many people, based on who they think will be interested. The staff then does a mass registration of those people, setting the participate status to "pending". They then use the event list of pending contacts as a means of calling people to see if they are coming.  If the person says they will attend, the event organizer can change the person's status from "pending" to  "registered".

Mass registration is accomplished by the steps:

  1. Search for the set of contacts you are interested in.
  2. On the search results page, either choose "select all" or put a check mark next to each contact you are interested in. A sample search results page appears in the following screen-shot.  MassRegistration
  3. Choose  "Add Contacts to Event" from the "actions" list just above the search results, then click  "Go".
  4. Complete the registration form, choosing the appropriate action choices for this set of people, such as setting the Participant Status to "pending". Choices made here will be applied to all contacts in this set.

Limitations of mass registrations

You can not make different action choices for a single set of contacts. The action choices are applied uniformly to the entire set of contacts. To work around this limitation, do a mass registration several times, each time choosing the desired action choices for that set of contacts. For example, you might mark one set of contacts you plan to call and invite with a Participant Status of "pending", then add another set of contacts to the event, such as event leaders you know will attend, with a Participant Status of "registered".

You cannot apply contribution information, such as a pay later contribution or a credit card transaction, in a batch action. Therefore, mass registration is best for free events  or for contacts who are not required to pay a fee at this point. You could always add payment details for an individual later on.  

Importing Registrations

Importing registration information is a quick way to add a bunch of registrations to the event.  The information to be imported must be available in a comma-separated values (CSV)  file. If the majority of the contacts are already in CiviCRM, it may be faster to do a mass registration action as mentioned earlier in this chapter.

Scenarios for importing registrations

Your organization may be collaborating with another organization for a specific event. The other organization may be handling event registration and sending you a spreadsheet after the event.

Another scenario is that a volunteer event coordinator, who did not know that you had CiviCRM, recorded event registrations using Excel or another spreadsheet program.

In these cases, it is still important to record the event registration inside CiviCRM to help you consolidate your information and allow better interactions and reporting for the event participants in the future.

Steps for importing registrations

  1.  Prepare the data in the CSV file. Make sure date fields (if used)  are valid dates. If some of the contacts are already present as contacts in CiviCRM, make sure the first name, last name and email address match what is already in CiviCRM.
  2. Differences between an imported contact's and an existing contact's information can cause a duplicate record to be created.  While duplicate contacts can be merged later, its preferable to avoid the situation. The rules for determining duplicate contacts can be defined by navigating to Administer > Manage > Find and Merge.
  3. On the navigation menu, choose Events > Import Participants.

Finding and Reporting on Participants

This section helps you do some common information searches.

To see an overview of participants for all upcoming events

  1. NAvigate to Events > Dashboard
  2. Click the "Counted:" link to see all the contacts for that event.
If any count is zero, the associated text will not be a hyperlink.  Some participant roles may not count for the event total, such as someone who is on the cleanup duty.

To see the participants for any event with a variety of criteria

  1. Navigate to Events > Find Participants.
  2. In the event name field, start typing to see a list of events. Click on the event you want.  Set additional search choices for the fields you want to see.
  3. Click Search.

When the search returns results, you have the opportunity to select all of the resulting participants or a subset, and perform an "action" on them. Available actions include:

To see a participant list listing individual fees

  1. Navigate to Search > Custom Searches.
  2. Click the Event Aggregate link.
  3. Choose your search criteria, and click Search.

To use a report template to create an event report

  1.  Click Reports > "Create reports from templates".
  2. Scroll to see the templates in the Event Report Templates section.
  3. Click the name of the report template to create a new report.
  4. Choose the desired report criteria, then click Preview Report.
  5. Expand the area labeled Create Report.
  6. Choose a report title, and other choices as desired.
  7. Click Create Report. Typical results appear in the following screenshot.
    Template

Testing your event

Before unleashing your event on the public, you should always test the event registration process. This can be done as follows:

  1. Navigate to Events > Manage Events.
  2. Locate your event in the list of all upcoming events and click the Test-drive link.
  3. Fill out the registration form and complete the registration process. If this is a paid event, the test settings for the payment processor will be used, you can enter dummy information.
  4. In order to find the new test participant record, navigate to Events > Find Participants.
  5. In the search criteria, check the box Find Test Participants.
  6. If you need to adjust the event settings, navigate to Events > Manage Events and click the Configure link for this event.

Promoting your events

Getting the word out and building excitement about your event can take many forms. The most important is making sure the event is prominently listed on your organization's website and your public calendar, and letting many people and organizations know about it.

Some organizations may want to publicise their guest list as part of the event description as a means of encouraging others to register.  Participants should also be encouraged to help promote the event.

If you are publicising your events on another website or organization's calendar, make it clear how people are expected to register. For example, some social networks have a built-in event registration system, such as Facebook events. Other organizations that are helping to publicise your event may have their own event registration systems.  Make sure that no matter where you publicise the event, it is obvious how the person is expected to register.

There is also additional information about how to list your event on a Drupal-based website and a Google calendar on CiviCRM's Wiki:

http://wiki.civicrm.org/confluence/display/CRMDOC/Event+Listings

To add the participant list to the event information page

  1. Navigate to Events > Manage Events, then click the Configure link for this event.
  2. Expand the section labeled Public Participant Listing and copy the URL in the description area. 
  3. Click the link Event Information and Settings.
  4. Paste the URL from step 2 into the event summary or event description, then click Save and Done.
  5. Optionally, you can share the URL via other communication vehicles such as within an email message and other places you are promoting the event.

You may also choose to share the URL through email and other places where you are promoting the event.

To display an event description or registration on the website (Drupal steps)

  1. Navigate to Events > Manage Events and then click  "more" > Live Page for this event.
  2. Copy the URL for this event page.
  3. Create a Drupal menu item for this URL or paste the URL into any Drupal page.
Additionally, you may enable a Drupal block that lists all upcoming public events. To learn more, go to the CiviCRM wiki: http://wiki.civicrm.org/confluence/display/CRMDOC/Event+Listings

To display an event description or registration on the website (Joomla! steps)

  1. Go into the Joomla! control panel.
  2. Choose Menu Manager > Your menu name.
  3. Click New.
  4. Expand CiviCRM > CiviCRM Events and click the Event Info item.
  5. Choose the event from the "Select an Event" list on the right side of the page.
  6. Click Save.

Getting the URL of a listing of upcoming events

This lets you give an external organization or external website a URL that they can place anywhere on their website. The only drawback is that the page will appear like the rest of your own website.  

  1. Navigate to Events > Manage Events.
  2. Click on the "globe" icon on the top right of the page.
  3. Copy the URL.

Getting an RSS feed for all upcoming events

This lets visitors subscribe to all your events in the RSS feed reader of their choice.  Also, many website management systems allow a website to subscribe to any RSS feed and present the information within their layout.

  1. Navigate to Events > Manage Events. 
  2. Click on the orange and white square icon on the top right of the page.
  3. Copy the URL to share or embed into your website.

Allowing people to tell a friend about an event

This offers people the chance, when they register for the event, to email their friends and colleagues about it. CiviCRM will also capture the "friend's" email and create a "Tell A Friend" activity for the email. At the same time, CiviCRM will create a similar activity in the participant's record.

  1. Navigate to Events > Manage Events and click the Configure link for this event.
  2. Click on the "Tell a Friend" link.
  3. Click the checkbox to enable "Tell a Friend" for this event.
  4. Provide the appropriate message to include for this event.

Getting your events on a calendar

Most websites include a graphically laid out calendar that can be shown by he month, week, or day.  It is very useful to get your events on relevant calendar pages.  Many individuals also maintain personal calendars to track events along with their personal meetings and appointments; you can make it easy for them to copy your event to their calendars. 

The standard format for sharing information between calendar systems is called iCal. CiviCRM can export a static iCal file as well as a dynamic iCal feed.    

 Getting a static list of events into another calendar system

  1. Navigate to Events > Manage Events.
  2. Click on the square icon displaying  "31" on the top right of the page.
  3. Save the iCal file on your local computer.
  4. Go into the other calendar system and find the import iCal file tool.
  5. Within the import wizard of the other calendar system, browse to and upload the iCal file from your local computer.

New CiviEvents created later on will not appear in the other calendar system. These steps will need to be repeated to show new events. Dynamic updates are described in the following procedure.

Getting a dynamic list of events into another calendar system

  1. Navigate to Events > Manage Events.
  2. Click on the square green icon displaying the letters "ICAL" on the top right of the page.
  3. Copy the URL of the page that opens.
  4. Go into the other calendar system and find the import iCal feed tool.
  5. Within the import wizard of the other calendar system, paste the URL from step 3. 

From this point forward any new public events created in CiviEvent will automatically appear within the external calendar system.

Displaying an event report on CiviCRM 's home dashboard

  1. From the navigation menu, click on Reports > "Create reports from templates".
  2. In the Event Report Templates area, select one of the reports you would like to display on the home dashboard.
  3. Enter the criteria you want to build the report, then click Preview Report.
  4. Click Create Report and enter the additional information you want in the report.
  5. In the Other Settiongs area, check the "Available for Dashboard?" box.
  6. Click Create Report.
  7. From the navigation menu, click Home to view the dashboard.
  8. To add the report to the dashboard, click Configure Your Dashboard.
  9. Drag your report from the Available Dashlets area into either the Left Column or Right Column of the dashboard area, and click Done.
  10. On the home dashboard, you should now see your report.  To view the latest updated information for your report as well as any other items you've included on your dashboard, click Refresh Dashboard Data.

Waitlists

Your organization may have limits on attendance, such as a 25-person limit for a training workshop or a 200-person limit for a fund-raising dinner. CiviEvent lets you set the maximum number of people allowed to register for your event. When registrations reach that number, CiviEvent will not allow other people to register, but will instead send an automatic message saying, "The event is currently full." This message can be customized by the organization when creating a new event, and you can let people add themselves on a first-come-first-served basis to a waitlist.

To create an event with a waitlist:

  1. Navigate to Events > Manage Events.
  2. Click the Configure link next to your event.
  3. Click the "Event Information and Settings" link, and on the Info and Settings form, check the "Offer a Waitlist?" box.

Approving Registrants

Many events are open to everyone, but there may be times when your organization invites only specific people to the event. For example, you could have an event where only volunteers that have donated 100 or more volunteer hours are invited to an appreciation dinner. But it is possible that the people invited will talk about the event to their friends, and possibly forward the information.  Hence, other people not invited may try to register for the event. CiviEvent allows you to create an event that allows you to check the people who have registered and approve only the people invited.

When a person registers for the event, they will get a reply that says, "Your registration has been submitted. Once your registration has been reviewed, you will receive an email with a link to a web page where you can complete the registration process."  This reply can be customized to your organisation's needs.

To create an event that requires approval:

  1. Navigate to Events > Manage Events.
  2. Click the Configure link for your event.
  3. Click the Online Registration link. On the Online Registration form, check the Requires Participant Approval box.
  4. You can then customize the text for the Approval Message. You can also limit the amount of time participants have to complete their registration after approval by entering the time in hours in the "Pending participant expiration" field. For example, if you want to give participants 3 days to complete their registration, enter "72" in that field.
  5. Click Save or Save and Done.

Managing Participants

After you create your event and provide the registration form to website visitors, you need to begin managing your participants through the CiviEvent administrative tools. CiviEvent lets you register participants manually, search through participants based on a variety of criteria, export participant lists, and perform a number of other functions on your event records. CiviEvent not only gives participants a smooth journey from registration to payment to attendance at the event, but also lightens the burden of administrative duties on your organisation's staff. An Events dashboard brings all your events and participant information together in one place (see screenshot). In this section we will discuss how these administrative tools are used.

  EventSummary

Registering a Participant Manually

Although CiviCRM helps alleviate data entry for event registration by allowing your constituents to register directly through your website, a segment of your contacts will probably continue to register by mail, phone, or in person on-site. Your staff will then enter the registration information manually.

For example, when a person calls the office to register for an event, the staff person who takes the call can enter the person's name in the "Quick search" box, select the contact from the results, click the Events tab on the caller's contact record, and add the person to the event.

The Events tab, shown in the following screenshot, displays a summary list of the contact's past event attendance and provides a link for registering the contact for a new event.

 

There are two options for registering the contact:

The interface for both options is very similar, with the exception of those fields that record payment details.


 

 

As you work through this form, certain sections of the page change to reflect selections you have made. For example, when you choose the event you want to register the contact for and select the participant role, the form will automatically load predefined custom data fields that pertain to those selections.

If the event selected is a paid event, you will see an event fees section which has been defined in the event configuration details, and an option to record the financial transaction details (Record Payment) will be visible. This leads us to an important concept central to CiviEvent (as well as other modules). Event registration records in CiviCRM are independent of, but can be related to, a financial transaction. While this may seem confusing to organizations accustomed to viewing event registrations as essentially a financial transaction, it offers an important and valuable distinction.

An event registration communicates the contact's participation in the organization's event. A corresponding financial transaction indicates the monetary value associated with that participation. While related, the two are distinct.

The distinction is best understood by considering the all common scenario of an organization waiving fees for a V.I.P., a speaker, or someone who participating in the event in a limited way. In such cases, you want to register the individuals but may not want to create an associated financial transaction.

CiviCRM respects this distinction by recording the event registration record under the Events tab, recording the financial record under the Contributions tab, and then creating a link between the two records.

If the event is a paid event, click the Record Payment checkbox and enter information in the transaction fields that are displayed. This process essentially "links" together the event registration and the contribution record for this contact. After recording the registration, you will be able to view the event registration record and see the related contribution record at the bottom (see screenshot). If you do not select the Record Payment check box, only a registration record will be created.  


What is CiviMember?

CiviMember allows you to track and manage membership for one or more organisations. You can define different membership types for each organisation.  CiviCRM provides tools to track contacts through the membership cycle, and handles membership renewals. A central aim of CiviMember (much like other CiviCRM components) is to automate membership administration as much as possible.

Real world scenarios

The Atlantis State Public Transit Association (ASPTA) is a useful case study to learn from when deciding how to manage membership. They have four membership categories:

As the ASPTA CiviCRM administrator configures the membership types, she creates three separate types for the Regular Member category to account for the three dues levels. The duration is one year, beginning on January 1, with a rollover date of October 1. In this way she accounts for new members who join very late in the year and are not able to fully benefit from their membership during that calendar year: their memberships extend through December 31 the following year.

It is now time to see how CiviMember responds to the particular needs of a membership drive. ASPTA's membership committee begins a focused outreach to non-member public transit systems (Regular Member category) and non-member businesses working in the public transit industry (Affiliate Member category). They want their members to renew online and pay through a credit card.

To accomplish this, they create a membership signup/renewal page. CiviMember can maintain the information about how to join in one place and generate a signup page or renewal page from it as appropriate. The signup page will be available to all website visitors, whereas the renewal page will be visible only to contacts who are already members, after they login to the members-only section.

After completing configuration of the signup/renewal page, ASPTA creates a menu link to expose the form (shown in the following screenshot) and begin their online membership recruitment effort.


 

Planning

This chapter covers the major areas you should think about before configuring CiviMember. It should be useful for system administrators setting up CiviMember.

Before you begin using CiviCRM's membership tools with your contacts, spend some time thinking about your organisation's membership structure. Work out the membership types you'll offer and how you'll model them in CiviCRM.

Key questions include:

It's tempting to over-engineer your membership structure and create more membership categories than you actually need. Try and keep things as simple as possible.

Map your membership structure to the way CiviMember handles membership. If you are having trouble modelling your membership structure in CiviCRM, ask in the forums about the problems you are having. There might be other ways to model your data, or simple changes you can make to CiviCRM's behavior to better fit your needs. 

Also ask why your membership structure is the way it is. Perhaps the workflow was set up based on a previous technological or organisational limitation that doesn't apply now that you are using CiviCRM.

The renewal process is as important as the initial sign-up. You'll need to plan time to get renewal reminder templates working and tested.

Do you want to provide a special members area of your website, or offer them extra online content as a result of their membership?  If so, you should explore CMS integration modules such as Drupal's CiviMember roles integration module.

Configuration

This chapter takes you through the necessary configuration steps for CiviMember. As with other modules, CiviMember takes advantage of CiviCRM's integration with the Drupal and Joomla! CRMs, allowing your members to manage their own memberships through your web site. So the second half of this chapter takes you through setup of online renewal pages.

Configuring membership types

The first configuration step is to configure the membership types and status rules. These are handled in: Administer > CiviMember > Membership Types.

Membership types are the various membership categories that your organization offers. You can configure an unlimited number of membership types and set various options for each of them. Options include how they are used, the membership term period, and the dues amount.

Begin by defining the name of the membership type and a brief description. The name will be used throughout the system, so choose it carefully.

CiviCRM requires the membership type to be associated with an organization record.This gives CiviCRM the flexibility to handle multiple membership types with multiple organizations (or sub-organizations) within a single interface. For example, if your national organization consists of six regional chapters, each of which maintains membership records separate from the national membership, you can create membership types for each chapter membership and associate them directly with the chapter organization.

Continue with the membership type configuration by entering the minimum membership fee (zero if the membership is free), and select the contribution type. In most cases you will select Membership Fee from the dropdown menu. You can create and modify Contribution types through the Administer CiviCRM tools. When a user or administrator enters a membership record that includes payment of dues or a fee, CiviCRM will log a corresponding contribution record and assign the selected contribution type.

Each membership type must have a duration value and period type. The duration value is the length of time for which the membership is valid (e.g., an annual membership has a duration of 1 year). The period type determines when that duration is measured from. A rolling membership is measured from the date it is entered in the system, whereas a fixed membership begins on a defined date. For fixed period memberships you must also identify the rollover date: the point after which new memberships are entered as belonging to the next dues period.

Membership can be inherited from one contact to another, which is useful in situations such as one finds in professional trade organisations, where they sign up another organisation as the member, but employees of the organisation receive the benefits of membership. Use the relationships dropdown menu to specify which related records should receive membership through the parent record.

You can use the visibility option to make sure certain membership types are handled by an administrator manually  (e.g., honorary and lifetime memberships). When you restrict their visibility, they do not appear on membership signup or renewal pages on your website.

At the bottom of the membership types page lies a block of information for managing renewal reminders. CiviCRM can be configured to send out a reminder email to members as the expiration date for their membership nears. This is particularly helpful for rolling membership types, where contacts may join at any time during the year. To configure the renewal reminder you must first have set up a renewal email template through Administer > CiviMail > Message Templates.

Membership status rules

Membership status rules control the journey that contacts take through the membership process.  Each step is marked with a different membership status.

The path taken by a member, along the lines of the default membership status rules, is as follows:

All membership status rules can be configured in Administer > CiviMember > Membership Status Rules.

Status types are measured from the start or end date of the membership record.  The "current membership" checkbox determines whether a certain status is considered "current" when viewing the CiviMember summary statistics for memberships.

When configuring the membership status rules, be sure to take note of the order in which they are listed. CiviCRM will process the rules beginning with the first and assign a status as soon as one matches.

Setting up cron to automatically update membership statuses

CiviCRM checks the status rules for a membership record and updates it accordingly when you create or edit the record. In order to take full advantage of the membership status rules, and to automatically send membership renewal emails, you must configure your server to regularly update the status of your members.  This is done using the Unix cron utility.  For more details, visit the online wiki documentation: http://wiki.civicrm.org/confluence/display/CRMDOC/Membership+Types.


Signup/Renewal Pages

Membership signup and renewal pages allow website visitors and existing contacts to manage their own memberships.  Membership signup and renewal pages can be connected with a financial contribution, which means you can use CiviCRM to process membership dues, fees, and special contributions.

CiviCRM thinks of membership sign up pages as a type of Contribution page (even if there is no associated contribution). So to create a sign up page, you need to create a Contribution page:

  1. Select Manage Contribution Pages from the navigation menu's Contribution link.
  2. To create a new page, click the Add Contribution Page button.
  3. Follow the screens displayed by the setup wizard that starts up. The following discussion focuses on options in the contribution page setup wizard which are most likely to be used for a typical membership signup/renewal page.

1. Title and Settings

This page appears as shown in  the following screenshot. The option must relevant to memberships is the "Allow individuals to contribute and / or signup for membership on behalf of an organization" checkbox.

People (not organizations) visit websites, so CiviCRM assumes by default that any interaction is done through an individual's contact record.  This becomes a problem if your membership categories are organization-based. To address this, CiviCRM allows you to select this option and permit an individual to act on behalf of the organization she represents. The membership record will then be attached to the organization's record, not the individual's. After checking this box, you can add descriptive text and select whether signing up on behalf of an organization is optional or required.

Contribute_TitleSettings 

2. Contribution Amounts

The second step of the wizard allows you to configure details related to the financial transactions performed through the Contribution page. If you have configured a credit card transaction payment processor in CiviCRM, you will be able to set up real-time transactions here.

If you are building a contribution page for membership signup and renewal only, uncheck the "Contribution Amounts section enabled" checkbox. This hides the section which allows you to solicit extra financial contributions over and above the membership fee.

In addition to executing real-time transactions, you can allow constituents to make make offline payments through the "Pay later" option. The "Pay later" feature leaves the responsibility on the member to pay by check or cash at a later date.

3. Memberships

The next step in the contribution page setup wizard is specifically related to memberships. Check the Membership Section Enabled checkbox to show two sets of title and introductory message fields, one for new memberships (signups) and the other for membership renewals.

CiviCRM will display the title and introductory message for new memberships if the website visitor is not logged in. If the user is logged in and has an existing membership record, CiviCRM will display the title and introductory message for renewals. Joining the organization creates a new membership record, while renewing membership updates the member's existing record and extends the membership end date.

Administrators should be aware of potential confusion and duplicate records if an existing member uses a membership join page without having first logged in. CiviCRM will make an attempt to match the user with an existing contact record, but any variations in the name or email address could cause a new contact record with corresponding membership record to be created.

You may want to provide guidance in the introductory text on your membership join page to encourage members to log in before completing the form. By logging in first, existing members can ensure that the transaction properly interacts with their contact and membership records.

Some addition options appear at the bottom of this page:

4. Thank-you and Receipting

After the site visitor completes the membership signup or renewal form, he will be redirected to a thank-you page and can have an email receipt generated and sent to him. This fourth step in the wizard allows you to configure those options.

5. Tell-A-Friend

Organizational growth and development is increasingly built through viral social networking mechanisms. CiviCRM allows you to add a tell-a-friend feature to the thank-you page. The page lets your members share details about your organization with their friends by emailing them a link and information.

6. Include Profiles

Profiles are central to CiviCRM's interfaces with website visitors. A profile is a collection of data fields that CiviCRM displays to obtain information from visitors or display data to them. If you are not familiar with the creation and function of profile sets you should read more about it in the Profiles chapter of the Configuration section in this book.

Profiles are critical to the functioning of membership signup and renewal pages. By default, contribution pages will include only an email field (which the member is required to fill in), in addition to the membership and contribution amount fields. Organizations almost always want to collect additional contact information as part of the membership signup process. Profiles provide these extra fields. On this step of the contribution page wizard, you may select one ore more existing profiles for inclusion on the form.

 

 

if you haven't yet defined a profile with the fields whose information you want to collect, simply procede to the next step of the wizard. Save your work on the Contribution page, define the Profile you want, and come back to the Contribution page to assign the profile.

7. Premiums

Premiums are thank you gifts and incentives offered to organization contributors. They are most commonly associated with tiered donation levels, though they could be created for use with memberships. Before including premiums on a contribution page, you must configure them through Administer > Contributions > Premiums (Thank-you Gifts). Step 7 (Premiums) of the contribution page wizard controls the introductory text, contact information, and other premium-related details.

8-9. Campaign Widgets and Personal Campaign Pages

Contribution Widget (Step 8) is used for displaying fundraising goals, while Personal Campaign Pages (Step 9)  is geared toward obtaining help from visitors toward fundraising efforts. These steps are usually not used for membership pages.

Publishing your membership signup/renewal page

After completing the contribution page wizard, return to the listing of Contribution pages, where you will find the page you've just created. You can now view the page, test the functionality, or return to the configuration options and make adjustments.

At this point you've completed the Contribution page but have not made it visible or available to website visitors. Depending on the environment in which CiviCRM is operating, this will be accomplished in different ways.

Everyday tasks

This chapter describes some of the CiviMember tools of use to administrators. It will show how to expose membership signup/renewal pages and membership directories to your members and other website visitors.

Administering Memberships

Organization administrators will primarily work with membership records by viewing contacts. After finding the contact you wish to manage, click the Membership tab to view a summary of the contact's membership records (illustrated in the following screenshot).

Contact_MembershipTabs 

Membership records appear in a list with active memberships (those with a current status) first and expired or cancelled memberships below.

From this interface, you can edit existing membership records, renew a membership, or create a new membership record. If you have configured an online credit card payment processor for use in CiviCRM, you will see two options for creating or renewing a membership: one for handling an offline record (no real-time transaction taking place), and one for handling an online record (using a real-time credit card transaction). The interface for each process is very similar, except that the credit card option includes payment processing and recording options .

After creating a new membership, you are taken to a form where you complete details regarding the record.

new_member 

Many of the fields on this page will be auto-completed if left blank. Fields include:

You can use the Status Override field to manually define a status for the record. As indicated by the title, it overrides the status automatically provided. You should use caution with this field as setting it will disable the automated status function for the record.

Recording membership payments

The Record Membership Payment checkbox expands the membership payment and receipt block and lets you record payments associated with the membership record. This feature touches an important concept central to CiviCRM's membership function: membership records in CiviCRM are independent of, but can be related to, a financial transaction. While this may seem confusing to organizations accustomed to viewing membership records as essentially a financial transaction, it offers an important and valuable distinction.

A membership record communicates the contact's relationship with the organisation. A corresponding financial transaction indicates the monetary value associated with that relationship. While related, the two are distinct. The distinction is best understood by considering two scenarios:

CiviCRM respects this distinction by recording the Membership record under the Membership tab, recording the financial record under the Contributions tab, and then creating a link between the two records.

Membership + Contribution 

By clicking the Record Membership Payment checkbox and completing the transaction fields displayed, you are building these two associated records. After recording the membership, you will be able to view the membership record and see the related contribution record at the bottom.

Renewing memberships

Naturally, you expect your constituents not only to join your organization, but to maintain their membership on an ongoing basis through renewals. CiviCRM facilitates the renewal process.

Returning to the contact's membership tab, you will see the option to renew an existing membership record. The renewal process does two things:

Members' "join date" is not modified when a membership is renewed, so you always know when the contact first became a member. You cannot change a member's membership type when renewing their membership. If your constituent is moving from one membership type to another, you need to create a new membership record, distinct from the existing one. In this way you develop a membership history for the member. 

The membership dashboard

CiviCRM provides several tools to help you obtain a quick snapshot of your members and search through them based on various criteria.  From the main sidebar menu, select CiviMember to view the membership dashboard page. This page contains two blocks of information that display a summary or your members, categorised by type and date range, and a list of recent member activity.

Membership_dashboard
 

All of the summary numbers are hot-linked. Simply click on one to drill down and view a list of members who have joined or renewed over the last two months or the year-to-date, or who are considered current according to the membership status definitions.

Searching for members

The Find Members page displays a series of searchable fields to help you segment and locate membership records. It is important to note that searching with this tool will display a list of membership records. So if a certain contact has multiple membership records meeting your search criteria, multiple records will be displayed for that contact. This contrasts with the advanced contact search tool, which displays one row per contact (i.e., there would be no duplicate listed, even if a contact had two membership records meeting the search criteria).

Toward the bottom half of the form are a series of date range fields. The left column indicates the From value and the right column the To value so you can narrow down searches to activities that take place between two particular dates.  If you are interested in membership records before a certain date, use only the To field.  Conversely, if you are interested in membership records after a certain date, select only the From field.

The top of the search result set includes a shaded block with tools letting you take action on all records in the result set, or on those selected using the checkboxes in the leftmost column.

Members_FindMembers  

Batch updates to members

Use this option to edit multiple records in a table grid using a pre-defined profile. If you are not familiar with how Profiles work, you will want to investigate how they are created before using this function. As you use this tool, note the following:

Deleting members

This action deletes all the selected membership records from the database. The contacts are not deleted, only their membership records. This action cannot be undone.

Exporting members

After selecting this action, you have the option of exporting a default set of primary fields or choosing which fields to export. When selecting which fields to export, you may save the mapping for future use. The data is exported in CSV format, which can be easily modified further in spreadsheet software or used for document mail merges.

Sending email to members

After searching your records, you may send an email to selected contacts and include data field tokens. Tokens are placeholders that are filled with the contact's data when the email is sent. This can save a lot of effort and possible errors, because you are able to send a bulk email to contacts while customizing it to each contact (e.g., beginning the email with a personalized salutation containing the contact's name).

What is CiviMail

This chapter introduces the ways CiviCRM can help you maintain relationships with contacts through email, using either CiviMail or other features. There are two main ways to send email in CiviCRM:

There are advantages and disadvantages to either method. The first is quicker and easier. The second is more sophisticated and offers better options for reporting.

Whichever option you use, integrating email to contacts with CiviCRM offers several benefits: 

Advantages specific to CiviMail include:

CiviMail can be configured to automatically track replies by creating an autofile mailbox.  Email sent to this mailbox is automatically converted into an activity and added to the right contact.

CiviCRM's mail features, including CiviMail, interact with your mail server software. Configuring the mail server and CiviMail are system administrator tasks, which may also require professional assistance. You will also need to verify with your web hosting provider whether they meet the configuration requirements, and verify that they don't put limits you might exceed on the number of emails you can send per day.

Planning

This chapter explains some key ideas that are useful for planning the use of CiviCRM's email capabilities. The chapter should be read by system administrators before they start configuring CiviCRM for sending email, and by regular users before they start sending emails to contacts.

You have three options for sending email:

Simple or insignificant emails that don't need to be viewed by others in your organisation shouldn't be sent through CiviCRM. Emails that you want to share with other members of your team should be sent through CiviCRM.  If you are also interested in capturing statistics about the success of your email, including bounce statistics and click-throughs, use CiviMail.

CiviMail requires more work initially to configure and there are more steps involved in sending each email.

Working out which method to use for each email might not be immediately apparent. Over time, the best practices for using the right tool for each situation will become more obvious and can be shared among your users.

Personalisation of emails

You can email from a personal address, from a more general email address associated with your organisation, or from another person's address. For instance, an assistant can send official email messages under the name of his manager.

You can use tokens to insert personalised text, such as a persons name, into a mailing sent with CiviCRM.  Tokens are placeholders that CiviCRM recognizes and replaces with an appropriate value when sending each message.

Display name and email greeting tokens are very useful.  With a bit of customisation, you can also add  more sophisticated information, such as details about the recipient's most recent donation or when her membership expires.

You can also provide a link to the person's contact dashboard so that they can review their registration details for themselves after logging in. Or you can use the checksum token to direct them to this page without logging in.

Templates

An email template allows you to create a generic structure that can be reused when sending emails.

You might want to have specific headers and footers for mass mailings (newsletter, internal bulletin, Press Release), and a few templates for regular emails.

Part of the planning involves to talk to those using CiviCRM for email to see what they need to send on a regular basis. Use this information to create a template for them.

Lies, Damn Lies, and Reporting

CiviMail can track links that have been clicked, providing useful information to help you understand the areas your recipients are interested in.

You can also track how many of your recipients opened the email and which links in the email were popular.

A word of warning about email opening statistics.  The vast majority of the mail clients protect (by default) the privacy of the recipient. That's why, when you receive an email containing external data (such as images that are online), you get a warning message saying something such as "Images are not displayed". If a recipient doesn't override the privacy features, she won't be counted among the contacts that read the email.

Therefore, it's likely you will have more readers than the number reported by CiviCRM.

In our experience, having around a 30% reported opening rate can be considered good. This is obviously different for each organisation and each group you send emails to.

Don't focus too much on the absolute numbers, but rather use them as a way of comparing different mailings you send. You might want to use them to experiment with different layouts, writing styles, and lengths and see what works best for your constituents.

You might also want to consider the privacy issues (and we encourage you to do so). There are good reasons to turn off CiviCRM's tracking of recipients in order to honor your constituents' privacy. For instance, you may wish to avoid tracking who has clicked on the "how to deal with drug issues" link on a specific mailing.

Autofiling outbound email

CiviCRM lets you keep a history of email sent via your email client as follows. Use the BCC field (which no one who receives the email will see) to enter an email address that will be read by the database and converted into an activity. This activity gets filed in the record of the contact that matches the email address. If that email address does not exist in your database a new contact record will be created.

System Configuration

This chapter covers CiviMail system configuration.  This is a complex task which requires system administrator level skills.  Correct configuration is crucial to keep your server off spam lists and black lists.

You will need to be able to change the configuration of your DNS, create email accounts, configure a cron job, read the headers of email messages, and possibly change the configuration of your SMTP server.

In this chapter, we assume you are running CiviCRM on a Linux server and that you are comfortable working with the shell and running some simple commands.  Most of these steps will be similar on other operating systems, but you will need to adapt them to your system and tools. 

The configuration described works fine for mailings to up to about 10,000 people. If you plan on sending email to hundreds of thousands of contacts, you should benchmark several options and consider a dedicated SMTP server. This more complex configuration is outside the scope of this book.

In this chapter we'll use an external Gmail mailbox address to test configuration. So the first step is to create a Gmail account if you don't have one already; alternatively, you can use another address for testing the procedures in this chapter, but you will need to be able to view the source of the mails you receive.

Once your system is properly configured, you are going to run periodically (for instance every 10 minutes) two different programs:

Configuring outbound email

Outbound email setting are configured at: Administer > Configure > Global settings > Outbound Email. The choices here are:

After making a choice, send a test email to your account on Gmail and verify that you receive it.

If you receive the following error message, you'll need to configure a default FROM email address (covered in the chapter on CiviMail configuration).

Sorry. A non-recoverable error has occurred.
The site administrator needs to enter a valid 'FROM Email Address' in Administer ->
 Configure -> Domain Information. The email address used may need to be a valid
 mail account with your email service provider.

Once you have received the email, you will need to view the source.  This is done in Gmail by clicking on "Show original" in the email you receive.

The email should contain headers that resemble the following.

Received: from yourmailserver.example.org (xxx.example.org [12.45.120.30])
        by mx.google.com with ESMTP id e31si4519230wej.3.2010.04.26.00.38.16;
        Mon, 26 Apr 2010 00:38:17 -0700 (PDT)
Received-SPF: pass (google.com: best guess record for domain of
    youremail@example.org designates 12.45.120.30
    as permitted sender) client-ip=12.45.120.30

In particular:

Configuring Email in CiviCRM

The preceding chapter set up your mail server to support CiviCRM's mail functions. This chapter covers configuration of CiviCRM itself. The configuration steps in this chapter are essential if you want to delegate the creation and sending of mailings to someone in your organization using CiviCRM.

Configuring the domain information

Your domain information is basic information about your organization: its name, a short description, your email address and your physical postal address.  CiviMail requires that you include the sender's physical address along with unsubscribe/optout links in any email you send, in order to comply with privacy laws in many countries. This information is made available via tokens and must be included in any mail sent with CiviMail.

To configure the domain information, go to: Administer > Configure > Domain Information.

Configure groups

CiviMail uses Groups to manage subscriptions to mailing lists. To create a group, go to: Contacts > New Group. When you create and configure a Group for this purpose, make sure to check Mailing List so that it is available as a Mailing List in CiviMail.

You can also create Smart Groups using the search forms. For example, using the Advanced Search you can create a Smart Group of contacts who have active memberships, or a Smart Group of contacts in a given city. You can then use the Smart Group to send mailings without having to first update the contacts in that group.

To create a Smart Group:

  1. Go to any of the search forms and run a search query based on the criteria for your group.
  2. On the search results page, click the radio button that selects all the records.
  3.  Click on " - more actions - ", select New Smart Group and then click Go.
  4. The next screen provides a review of the criteria chosen for the Smart Group. Give the Smart Group a name and (optionally) a description, and make the Smart Group a Mailing List.
  5. Click Save Smart Group.

Configure mailing list subscription pages

CiviCRM provides a page that allows users to sign up for email directly from your website.  This page is available at www.yourdomain.org/civicrm/mailing/subscribe.

This page contains all the groups that have publicly viewable mailing lists and allows visitors to subscribe directly to these groups. After people fill in this form, they will be sent an email asking them to confirm their subscription and their details will appear in CiviCRM with their group subscription set to Pending.  When they click the confirmation link in the email, their group subscription will be set to Added.

Another way to add contacts to a group is to create a profile, make this profile public and set the profile so that when it is completed, the contact is added to a group.  The advantage of using a profile is that you can collect extra fields.  The disadvantage is that there is no email verification.

When you use a profile to enable emall subscriptions, decide what information you want to ask contacts on the registration form. Avoid asking for information just because you might need it laterr. Focus on what is immediately useful and strive to keep the form as short as possible. It is probably wise to add a Recaptcha to avoid getting a lot of spam contact.

Creating templates

Message templates can be used for an email message's subject and body.  Messages templates can be used for routine mailings such as canned responses, daily tasks, and reminder messages, or just to create a standard format for the body of messages.

Manage message templates from Administer > CiviMail > Message Templates.

  1. Click on New Message Template.
  2. Enter a Message Title and a Message Subject. You can choose to use tokens to personalize your subject line.
  3. Scroll down to the HTML Message section and create your template. There are online resources that offer instructions on creating an HTML Email Template. One suggestion is to find and copy an Email Template from a website that offers samples.
  4. One of the toolbar buttons at the top of this section lets you view the source code of your template. When you click on it, the template changes the view to show the HTML code that is being used. If you want to use HTML from a template you found externally, you need to switch to this view in order to paste in HTML code from the template. Make structural changes in your template in this mode as well. 

Tips for creating templates

HTML email is not regular HTML. It has significant restrictions, including the need to use tables and inline CSS and not to include a background image. Here are some tips for creating a template that will look good in all mail clients:

Creating headers and footers

The mail header is the area at the top of the email, which should include elements that you want to be always displayed before the main content body, such as the logo of your organization and the title of the newsletter.

The default footer, which is always the last thing in the email, often includes the tokens required by law in some countries (unsubscription links and domain information).

You can manage headers and footers in Administer > CiviMail > "Headers, Footers, and Automated Messages". Style them to present a coherent visual identity across all your messages. Both should be configured for maximum flexibility. For example, one or more headers can be created with different images and titles that can be used for different campaigns or programs.

After headers and footers are configured, staff who prepare a new mailing will be able to select them from available headers and footers. This helps staff create more standardized mailings with elements that help your readers identify the contents of the mailing or find information.

Testing templates

Once your templates are ready, we strongly recommend that you test them in various email clients, such as Mozilla Thunderbird, MS Outlook, Mac Mail and web-based e-mail such as Gmail, Yahoo and Hotmail. You can create a group that includes a test contact for each of those destinations and use it each time you create a new mailing.

Because email clients can display the HTML in emall very differently, we recommended that you keep the HTML as simple as possible and use only inline CSS or tables for formatting. Include as much of the layout as possible in the templates so that each new mailing will not require too much reviewing, the template having already been tested.

Using tokens

In many mailings is useful to insert dynamically chosen information that is different for every recipient. This is accomplished by using mail merge tokens in your message. A list of available tokens appears in the top right corner of the message editing area.

You might need to insert information that isn't available as a token, for instance to create a joint family greeting. Creating custom tokens is a task for a developer. To find out more about working with custom tokens, refer to the discussion about custom mail merge tokens in the Hooks chapter of the Extending CiviCRM section of this book and look at the wiki: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data.

Everyday Tasks

This chapter contains some step-by-step instructions for performing important everyday tasks with email.

Send an email to one person

You can use CiviCRM to send an email to individuals. Using CiviCRM for this purpose is useful if you want other people at your organisation to see the email or if you want to send an email based on a pre-defined template.

  1. Find the person you wish to email. There are two common ways to do this:
    • Use the Quick Search box on the top left. Click inside the box and begin typing a part of the person's name or email address. Choose the person from the choices that are presented.
    • Navigate to Search > Find Contact.  Enter part of the person's name or email address. Click Search and click on the person's name when it shows up on the search results screen.
  2. From the contact summary page, click Actions > New Activity > "Send an email".
  3. If you have templates defined, you can choose one to use for this email. Selecting a template populates the text content and HTML content fields with the message content from the particular template you have chosen. You can then edit that content. You can also update the template, either changing the original template or saving it as a new template.
  4. Enter a subject line for your email, or modify the subject from the selected template as necessary.
  5. If you just wish to send a text version of your email, ignore the HTML section and click on the Text section. Enter your message in the box.
  6. Click Send to send your message.

To see the activity that was just recorded of the email sent, click the Activities tab of the contact. 

Sending a quick email to less than 50 contacts

In the results from a search, CiviCRM makes "Send an email" available from the actions dropdown menu. This allows you to send an email to more than one contact at a time. Sending an email this way is relatively quick but provides no options for tracking email and doesn't give contacts the option to opt out.  It is bad practice to use this method for mass mailings, which is why it is limited to 50 contacts.  For mass mailings, use CiviMail.

  1. Click Search > Find Contacts > Advanced Search > "Choose your search criteria" and click Search (or use any other search to find the contacts that you wish to email).
  2. From the search results screen, choose some or all of the contacts and click Actions > "Send an email".
  3. Enter a subject line for your email.
  4. If you have templates defined, you can choose one to use for this email. Selecting a template populates the text content and HTML content fields with the message content from the particular template you have chosen. You can then edit that content. You can also update the template, either changing the original template or saving it as a new template.
  5. As you write your content, remember that every email will be sent individually. CiviCRM offers the ability to personalize each email using tokens. See "Using tokens in emails" later in this chapter.
  6. If you just wish to send a text version of your email, ignore the HTML section and click on the Text section. Enter your message in the box. You can also use tokens in the text version of the message. There is also a token link at the top right of the Text box.
  7. Click Send to send your message.
  8. You can, if you wish, look at the different contacts' activities to see that each one has an activity recorded for the sending of this email.

To see the activity that was just recorded of the email sent, click the Activities tab of the different contacts. 

Because the recipients don't see who else received the email, you might want to mention whom you are sending it to in the text of your mail (for instance: "TO: Members of the board, staff")

Sending a mass email through CiviMail

Using CiviMail offers many benefits over  the "Send an email" action, allowing you to track respondents to your mailing, process bounces and allow people to unsubscribe to your mailings.

There are two ways to select the recipients for your mailing.

The  process for sending the email then proceeds as follows:
  1. Enter a title for this mailing. Select a title that will allow you and others in your organization to clearly identify the purpose of this mailing (e.g. "August 2010 monthly newsletter"). This title is for internal use only and will not be shown to recipients. Then click next.
  2. This step of the process offers options for Tracking and Responding.  Tracking collects information about what your contacts do with this email. CiviCRM can store whether a contact opens this email (open rates) and/or what links in the email are clicked.  Responding offers options concerning what to do when a contact replies to the message you are sending. By default, the reply is sent to the sender, but you might want to redirect the replies to a special address (the same one used to collect the bounce). This is a very specific and advanced usage and you probably don't want to use it unless you have specific tracking requirement in your organisations. Make your selections and click next.
  3. Enter the content for your mailing.  If you have templates defined, you can choose one to use for this email. Selecting a template populates the text content and HTML content fields with the message content from the particular template you have chosen. You can then edit that content. You can also update the template, either changing the original template or saving it as a new template.
  4. As you write your content, remember that every email will be sent individually. CiviCRM offers the ability to personalize each email using tokens. See "Using tokens in emails" later in this chapter.
  5. If you just wish to send a text version of your email, ignore the HTML section and click on the Text section. Enter your message in the box. You can also use tokens in the text version of the message. There is also a token link at the top right of the Text box.
  6. Choose a Mailing Header and Mailing Footer. Click Next to continue.
  7. Test your email by sending it your yourself and viewing it in your email client to make sure it looks as you expect. If you are sending a mail with a complex layout, send it to your test group and verify it from various mail clients. It is preferable to have more than one person receive your test email and give you feedback. Once you are satisfied with your email, click the Preview button for one last look. If you are ready to send the message, click Next.
  8. Either send the email immediately or schedule a day and time for it to be sent. By default, CiviMail checks every 15 minutes whether an email is ready to be sent, so there can be a delay of up to 15 minutes after you request the email to be sent.

To see the activity that was just recorded of the email sent, click the Activities tab of the different contacts.  As people receive your email, information about open rates and clickthroughs becomes available on the report page. To see these statistics, click on Mailings > Scheduled and Sent Mailings, find your mailing, and click on Report.

Using tokens in emails

You can use tokens to insert personalised text, such as a person's name, into a mailing sent with CiviCRM.  Tokens are replaced by the appropriate value at the time the email is sent out.

For instance, if you want each email to address the person after "Dear " you would type the space and then click on the Token link at the top left of the HTML box. The popup that appears enables you to find the appropriate token. Start typing "First name" in the box and choose the token that corresponds. Click Close and you will see that your message now reads "Dear {firstname}". When the email is sent the appropriate first name will be inserted into each message.

To view the list of available contact tokens, click on the Token link. Tokens for the display name and email greeting are particularly useful.

Only contact fields and actions can be inserted in your email as tokens. Related records, such as the name of the event for which the contacts have pending enrollments, cannot be included. However, you could provide a link to the person's contact dashboard so that they can review their registration details for themselves (once logged in). You can also use a checksum token that generates a unique URL for each contact so they can modify their information without having to login.

View a Mailing Report

As people receive your email, information about the number who opened the email (open rates) can be available, as well as information about the links they are clicking on.

  1. Choose Mailings > Scheduled and Sent Mailings and find the row your mailing is in.
  2. Click on Report and examine the results (illustrated in the following screenshot):
    • Intended Recipients: counts how many email messages were sent by this mailing.
    • Successful Deliveries: shows how many messages reached their intended recipients
    • Tracked Opens: shows how many messagess were verified as opened. Since many email clients do not show images by default, this number is not particularly accurate. The number is more useful to compare mailings.
    • Click throughs: tracks how many times a link on any message was clicked. This is useful to gauge what items your recipients were most interested in.
  3. You can also see statistics for Forwards, Replies, Bounces and Unsubscribed Requests.

report_email

Managing bounces and contacts with invalid emails

If your server is set up to process bounces, contacts will be marked as on hold when their email bounces. Further messages to those addresses will be suppressed.  You can search for emails that are on hold either from the Bounces report or with an advanced search, and then investigate why the emails are bouncing.

What is CiviCase?

CiviCase is a way to track and manage a sequence of interactions between people in your organisation and contacts in CiviCRM. In addition to tracking and managing your organisation's interactions with clients or constituents, CiviCase can also manage internal organisational interactions.

CiviCase tracks interactions in two ways: as cases and as activities.

Activities are single interactions. For example, if a constituent calls to request information and the staff person directs them to a website, it would be recorded as an activity, with a brief description of how the staff person followed-up. CiviCRM will auto-generate some activities in conjunction with other actions, such as logging an email receipt for event registrations.

Cases are used to track more complex interactions or communication processes. Multiple activities can be grouped together into one case, and these activities can be optionally structured in a timeline. A case can be used to track a specific workflow that must be followed, for example: a client fills out an intake form, then has an initial meeting with a staff person, and finally receives a certificate from the organisation for meeting certain goals.

As well as linking activities around a common case, CiviCase identifies the people involved and their role(s) in the case. For example, a website project would be a case, with tasks such as design, develop and write content being activities within that case, and the people involved would have roles as designer, developer, tester, writer, etc.

Actual Scenarios

Organisations have employed CiviCase in a wide variety of situations. Here are a few examples of different types of organisations and how they might employ CiviCase.

Managing Legislator-Constituent Interactions

A Legislator's staff may manage hundreds of interactions with constituents and communities daily.  CiviCase provides a flexible and predictable way of allowing Legislative staff to manage and track these interactions while avoiding duplication (for example, if a constituent calls in about a topic that a staffer is already working on). CiviCase also automates the task of remembering and scheduling follow up activities by presenting staffers with a list of upcoming case activities that require their attention.

Below are some scenarios in which CiviCase can be used to effectively record interactions between Legislative staff and constituents:

Helping clients with emotional health or substance abuse problems

Social services agencies have specific workflows for processing clients through the variety of services that they provide. CiviCase can be used to outline and record the path that clients travel on their way to recovery.

When a client phones a social services agency, they will speak to an intake counsellor. The intake counsellor can set up a case to quickly record and determine what the clients' needs are, who are the people that need to be involved, and then set up a follow up meeting with a social worker.

Planning

The CiviCase component allows for a high degree of customisation to meet the needs of a wide variety of organisations and workflows. It is important to understand CiviCase's underlying principles and assumptions, as well as the elements that can be customised, before you begin to plan and configure the component based on your requirements.

Assumptions

Although CiviCase is quite flexible, there are a number of assumptions about managing cases built-in to the component. These assumptions have been arrived at through an extensive trial and error process and although some of them may seem new or foreign at first, we encourage you to approach them with an open mind.

Case Types

The first step in planning your CiviCase configuration is to think about the types of cases your organisation needs to manage. Complex processes which include several activities, span several days or weeks, and involve multiple people are potentially good candidates for case management. Start by listing these processes and defining a case type for each one.

For example, the Physician Health Program provides support for physicians who are experiencing problems related to emotional health issues, the inappropriate use of alcohol and/or drugs or coping with physical illness. Some of the case types they use are:

For a community services organisation, examples of case types might include:

Think about the complex tasks that staff in your organisation do on a regular basis and make a list of potential case types.

Case Activities

Activities track specific interactions and tasks within a case. Activities may be scheduled or ad hoc, and may involve the case client or constituent, or a third party such as a family member or a professional who is assisting with the case. Each organisation needs to determine the level of detail to be recorded, but many organisations find it helpful to include every phone call, meeting or internal discussion in the case story by recording it as an activity.

Activity Types

CiviCRM is preconfigured with a number of predefined activity types such as Phone Calls, Meetings, Emails Sent, Interviews and Follow ups. These may be sufficient for your needs. However most organisations will want to track other specific tasks, and activity types can be added for these.

During the life of each case, some activities will be automatically created, such as:

For a community services organisation, additional activity types might include:

For each of the case types you identified, create a list of the specific activities involved. Creating new types instead of relying only on "Follow up" will make the list of activities easier to read.

Activity Data

A standard set of information can be entered whenever a case activity is recorded in CiviCase:

This is sufficient for some types of activities, however it is often useful to collect additional structured data. The "Open Case" (intake) activity is a common example where you may want to include a set of specific questions about the client and their situation.

Create a list of additional requirements (custom data) for each activity type, including the type of data being recorded (free text, multiple choice, date, etc.). For more information about custom data please refer to sections on custom data in the the CiviCRM flossmanual, or to the CiviCRM wiki.

Timelines

CiviCase allows you to define a workplan or an expected sequence of tasks and activities for each type of case. These are called standard timelines, and one is created automatically when a new case is opened.

For simple cases, the timeline might include only two items:

Even in this example, the timeline is useful as it allows you to predefine when the persons assigned to the case should follow up with the client or constituent.

For more complex processes, the timeline provides a case plan that can help the people involved to stay on track. The timeline lists all the activities which are expected to occur and should be accomplished within a certain timeframe. You can define the expected number of days between the beginning of the case and each of the subsequent activities in the timeline.

If necessary, an activity can also define an offset from another activity. For example: for a "Referral to Specialist" case, the "facilitate first appointment" activity might be expected to occur within 2 days after the case is opened. "Survey client satisfaction" might be scheduled for 30 days after "facilitate first appointment".

You might also want to define a timeline based on the end date. If a case has to be completed by a specific date, each activity can be defined as needing to happen a number of days before this end date. You then set a negative offset on the timeline.

Case Roles and Relationships

CiviCase provides three mechanisms for relating people to cases and clients:

CiviCRM provides relationship type definitions for most of the standard relationships you might track (e.g. Spouse, Child). However you will probably need to define additional relationship types for your case roles, such as:

Make a list of the expected case roles for each type of case you've listed, then determine which role will normally be considered the "case manager" for that case type.

Controlling Access to Case Data

This section applies to Drupal installations only.

You can assign permissions to users in order to control whether or not they have access to the CiviCase component, as well as what case data they can see (Administer -> Users -> Permissions). Here is a list of the CiviCase-related permissions.

Access my cases and activities

Allows a user to create new cases, add activities to the cases they've created and edit those activities. Users with this permission can NOT see cases or activities created by others.

If you need to restrict certain users to ONLY seeing case data (i.e. hide all other contact information from them), assign access my cases and activities permission WITHOUT edit and view contacts permissions. This permissioning model is useful for users who work in external agencies and who should not be allowed to see contact details. 

Access all cases and activities

Allows a user to create new cases, as well as view and add activities to any case (regardless of who initially created the case).

Delete in CiviCase

Allows a user to mark cases or case activities as deleted. Cases and activities are never physically deleted from your database, but only "hidden" when you mark them as deleted.

FindDeletedCases

Users with this permission can also find and undelete these cases and activities by checking the Deleted Cases option in Find Cases and the Deleted Activities option in the Case Activities Search Filter.

FindDeletedActivities

Administer CiviCase

Gives access to Administer -> CiviCase options including:

Configuration

Now that you've gone through the planning process and determined the types of cases, activities and case roles that you need, you're ready to configure your CiviCase installation. The configuration process requires some technical skills. Review these prerequisites before getting started, and recruit assistance if needed.

Prerequisites

Many of the configuration steps require that you create and edit files outside of the CiviCRM user interface. You will need to:

Configuration Tasks

Follow these steps to configure CiviCase for your organisation.

1. Case Type Configuration Files

You will create a separate XML-formatted text file for each of the case types you identified during the planning process. These files specify the characteristics of the case type using XML elements. Case configuration files should be saved to the following directory in your CiviCRM installation:

<civicrm_root>/CRM/Case/xml/configuration

You will need to create this directory when you save your first configuration. Ensure that the directory is readable by your web server process.

If you are not familiar with XML markup, refer to the Wikipedia page on XML at:

http://en.wikipedia.org/wiki/Xml

A set of sample configuration files are included when you download CiviCRM. If you can access the CiviCRM codebase at http://svn.civicrm.org/civicrm/, load the sample case type configuration file for Housing Support in your text editor before continuing, and refer to it as you review each of the sections below.

<civicrm_root>/CRM/Case/xml/configuration.sample/HousingSupport.xml

Activity Types: this is a list of all activity types that are valid for this type of case. Several activity types will be needed for any type of case. Be sure to include them in this listing: Open Case, Change Case Status, Change Case Type, Follow up. You will use Change Case Status to close a case. Follow up is a useful general activity type for most case settings.

You can optionally specify the maximum occurrences of this activity type in a case using the max_instances element. Generally you'll want to set max_instances to 1 for the Open Case activity type, but you can also use this to limit recurrence of other types of interactions or processes.

Activity Sets: groups of activity types which define a sequence of interactions. You must include at least one activity set in the configuration file which defines the standard timeline (plan). The activities in the standard timeline set are automatically created when you open a case of this type. You can control the scheduling of each activity relative to the date the case is opened OR relative to another activity using the reference activity and reference offset elements. Offsets are expressed in days.

Here's a simple timeline example for a Housing Support case:

CaseTypeConfigExample 

In this example, the Open Case activity is marked as Completed when the case is opened. Three additional activities are automatically scheduled when the case is opened. A Medical evaluation is scheduled for the following day (reference offset is 1); then Secure temporary housing (reference offset 2); and finally a Follow up three days later.

Case Roles: this section lists the types of people who are involved in the case in some way. Roles listed here will be automatically created when the case is opened. One role is marked as creator. This role is automatically assigned to the person who created the case. After the case is opened, users with access to the case can assign the remaining roles to contacts as appropriate. You may also mark one of the roles as the case manager. The case manager's name will be displayed prominently in case listings and reports.

Here's a simple example of case roles for a Housing Support case: 

 CaseRolesConfigExample

In this example there are three case roles. The Homeless Service Coordinator is both the creator and manager of these cases. In addition, a Health Services Coordinator and a Benefits Specialist role are created when the case is opened.

Refer to the detailed configuration documentation on the wiki for more detailed explanations of each element in the XML file:

http://wiki.civicrm.org/confluence/x/UIC9AQ

Create a separate XML file for each of your case types. Your file names should match the case type name with spaces removed and the first letter of each word upper-cased.

For example, if the Case type is "Housing Support", the filename would be "HousingSupport.xml". A good approach is to use a copy of one of the sample configuration files that are included in the distribution as a starting point, and edit it to meet your requirements.

2. Enable the CiviCase component

Once you have created your configuration files and uploaded them to the configuration directory in your CiviCRM installation, you must enable the CiviCase component. The CiviCase component is included in CiviCRM downloads, but it is NOT enabled by default. To enable the component:

You will now see an Other option in the navigation menu. Click that option to see the Cases menu. People in your organisation who work with cases will probably want to modify their navigation menu to move Cases to the top-level. Navigate to Administer -> Customise -> Navigation Menu to make this change.

CaseMenu

3. Review CiviCase permissions

This section applies to Drupal installations only.

In order for users to add and manage cases, you will need to configure CiviCase-related permissions (Administer -> Users -> Permissions). You may want to create case management specific Drupal user roles for staff, based on their responsibilities within your organisation. Permission options are described in the Planning chapter of this section.

4. Populate Case Types, Activity Types, and Case Roles

You will need to add database records for each case type, activity type, and case role that you've included in your case type configuration files. You can use the CiviCRM Administrative screens to do this:

Case types Activity types

Generic activity types (Open Case, Change Case Status, etc.) are included in all CiviCRM installations. Meeting, Phone Call, Email (inbound and sent) activity types are also included "out of the box". However you will need to manually add any other activity types that you've defined in your case configuration files.

Alternatively, if you have a lot of entries, you may prefer to use the API to write a simple programme to automatically create all the activity types:

 <?
require_once 'civicrm.config.php';
require_once 'CRM/Core/Config.php';
require_once('api/v2/ActivityType.php');

//read the API chapter to get more explanation
$componentCase = 7;
$types = array ("Medical evaluation","Secure temporary housing");
foreach ($types as $type) {
  $param = array("label"=>$type,"description"=> "Example of Type","component_id" =>
     $componentCase, is_reserved=>false,is_active=>1,weight=>1);
  $result = civicrm_activity_type_create ($param);
  if (civicrm_error( $result )) {
    echo "\n ERROR creating $type: ". $result['error_message'];
  } else {
    echo "\n Type $type created";
  }
}
?>
Case roles

You will need to define relationship types for any case roles you've defined in your case configuration files. Examples might include Intake Coordinator, Employment Counsellor, Housing Advocate, etc.

For example, to define a Case Coordinator relationship type:

Relationship Label-A to B : "Case Coordinator is"
Relationship Label-B to A : "Case Coordinator"
Contact Type A: "Individual"
Contact Type B: "Individual"

Again, if you have a lot of entries, the process of defining relationship types can be automated using the API:

<?
require_once 'civicrm.config.php';
require_once 'CRM/Core/Config.php';
require_once('api/v2/RelationshipType.php');

//read the API chapter to get more explanation
$types = json_decode ('[
 {"label_a_b": "Case Coordinator is","label_b_a":"Case
    Coordinator","contact_types_a":"Individual","contact_types_b":"Individual"}
,{"label_a_b": "Benefit Specialist of","label_b_a":"Benefits
    specialist","contact_types_a":"Individual","contact_types_b":"Individual"}
]');

foreach ($types as $type) {
  $result = civicrm_relationship_type_add (get_object_vars($type));
  if (civicrm_error( $result )) {
    echo "\n ERROR creating $type: ". $result['error_message'];
  } else {
    echo "\n Type $type created";
  }
}
?>

Custom fields

It is likely that you will want to collect structured data for some of the activity types you've defined. Custom fields are most often connected to a specific activity type. For example, in Employment Counselling cases, you may want to define an activity type used to record client job skills. This activity type will require one or more custom fields - perhaps a set of checkboxes. If you are transitioning from a paper-based system, it is helpful to refer to existing forms and then determine what information from the forms is relevant to include. Remember that CiviCase is designed to store case information within activity records, and does not support custom fields at the case level.

Please review the section on configuring custom data fields prior to beginning these steps.

If you need to define a large number of fields for a given activity type, consider breaking them up into sets of related fields. Group the fields into logically related sets that will make sense to the users, and avoid the form looking like an endless tunnel of fields.

You can assign more than one custom data field group to a single activity type. For example, if you are collecting a lot of data during client intake, you may want to create several sets of custom fields for the Open Case activity type.

If you have sets that are only relevant to some contacts, for example a different set of fields for male or female contacts, you can modify the form's template and add client-side logic using jQuery to hide/show the relevant sets based on the values selected on previous fields.

Filing Inbound Emails to Cases

Some organizations find it useful to record incoming case-related emails in CiviCase. For example, the case coordinator for a work disability case might send an inquiry to a state agency representative - and would like the reply to become part of the case story.

You can enable this functionality by configuring the provided Email Processor script as described here:

http://tiny.booki.cc/?vfW0

5. Add staff members

You will need to create a contact record for each staff member or service provider who will be using CiviCase to enter or view case information. These individuals will also need to have a Drupal or Joomla! user account.

For Joomla! installations, staff members must have back-end (administrator) access. All CiviCase functions are done within the Joomla! Administrator interface.

You should also add contact records for service providers who will be assigned case roles but will not be accessing the CiviCase system. This will allow your staff to easily send emails with pertinent case and client information to these providers via CiviCase, as well as record case-related interactions reported by providers.

Everyday Tasks

This chapter describes a list of everyday tasks that you might perform using CiviCase, and how to go about them.

Viewing the Case Dashboard

The Case Dashboard gives you an easy way to keep track of case-related tasks. It provides:

If you have permission to view cases other than ones that you are working on, you also have the option to see:

You can switch between viewing Your Cases and All Cases by clicking on the link at the top right of the content area.

Click the "edit" icon next to the Next Sched. activity name to work on that task. In the case shown in the following screenshot, the Next Sched. activity is "Medical evalution". You can view this activity in a pop-up window by clicking directly on the title. If you're ready to work on that activity, click the edit "pencil" to the right of the activity title.

CaseDashboard  input field

Click on the triangular expand icon (►) to the left of the client name to see the complete list of activities for that case. From this list you can view or edit any activity in that case. Click Manage Case when you want to work on a number of tasks within a case or to change the status of the case, print a case report, or view case roles.

To add a new case from the Case Dashboard, click the Add Case button at the top left of the content area.

Finding cases

You can search for cases by clicking on Find Cases under Search or under Cases in the menu bar at the top of the CiviCRM screen. The Cases search form gives you a number of options. You can search by each option individually, or combine them for further filtering.

You can search by:

If you make selections in multiple criteria (e.g. adding a client name, checking off a case type, and selecting "all cases") the search criteria will be combined so that the results must fulfill at least one requirement in each set of criteria (in other words, the criteria sets are ANDed). In contrast, making multiple selections within one set of criteria (e.g., checking two case types) will ensure that the returned results fulfill at least one of the selections in the criteria set (in this example, cases must match at least one of the case types).

Opening a new case

You can open a new case with either an existing contact or a new contact not yet in your system.

Creating a case from an existing contact's summary screen or actions menu automatically links the case to that contact. To open a case on an existing contact, follow these steps:

  1. Go to the contact's summary screen.
  2. Select Add Case from the Actions dropdown menu, or alternatively click on the Cases tab.
  3. Fill in the required fields in the Add Case form.
  4. Click Save.

If you open a new case for a new contact, the contact's record in CiviCRM is created at the same time as you create the case. Follow these steps:

  1. Navigate to Cases > New Case or select the Create New > Case dropdown button. This button is provided as a block in Drupal or on the left hand side in Joomla!. 
  2. If you've opted to create a new case without navigating to an existing contact first, you may want to check whether the contact already exists in the database. Type the name or email of the contact you are looking for in the Select Contact field, and you will see a list of potential matches (as illustrated by the following screenshot).

    NewCaseSelectContact 

  3. If you don't find the contact, you can create it immediately by selecting the type of contact from the "create new contact" list. This opens a popup window (shown in the following screenshot) that allows you to fill out the new contact's name and other information while opening the case. The fields in this popup window are controlled by the fields in the "Add Individual" profile. This means you can easily add or modify the fields provided. You can read more about profiles in the Profiles chapter.

    NewCaseCreateContact

    Use the Medium and Location fields to record information about where and how this case came to your attention. For example, you might select "In Person" for Medium and "At the Annual Gala" for Location.

    Use the Details text area to add information pertaining to the overall case, but not to a specific activity of the case. An example might be "Jane is concerned about some illegal land use that she has witnessed in her neighbourhood, and would like us to see what can be done about it. I told her that the best person to look into this was Tom, and she asked whether her husband could be included on any correspondence."

    The Subject field is displayed in search results and in other listings of cases, next to the name of the case client. Keep this in mind when entering the subject text: a brief and unique description of the case will be more helpful than using the client's name as the subject.

    The Case Type selector allows you to choose the type of case that you are creating. Many case types have specific activities and timelines, so it is important to choose the appropriate case type at this point. You can change to a different case type at a later point by clicking Manage Case next to the case when it's displayed in the CiviCase Dashboard, or from the contact's record Case tab. Then select Change Case Type from the New Activity drop down list, Changing an ongoing case may require you to then update or re-enter some data.

    The Case Status selector allows you to indicate the current status of the case. Generally you will use a status such as Ongoing or Urgent, but if you are adding a case that has already been completed (for tracking purposes) select "Resolved".

    The Case Start Date field defaults to the current day. If you are creating a case that has already been completed or entering data for upcoming cases (not yet started), adjust the case start date accordingly.

    The Duration field records the time spent collecting the data needed to fill out the create case form, not the amount of time it took to fill the form out. Fill out the number in minutes. For example, you might use this field to record the number of minutes spent on the phone with a constituent as they described the case.

  4. After you finish the popup window, clicking the Save button saves the case and loads the Manage Case page, where you can then modify activities, add attachments and assign case roles. Alternatively, clicking "Save and New" save the case and resets the form so that you can add further new cases uninterrupted (this is particularly useful if you are doing data entry). Clicking Cancel discards the case data you have entered and sends you back to the CiviCRM dashboard.

Assigning case roles

You can assign case roles to contacts who are working on the case or need to stay informed about case activities. Users who have access to CiviCase and are assigned a role in the case will then see that case in their My Cases view. The phone number and email address of each person with a case role will be displayed on the case, making it easy to communicate with them (see screenshot).

CaseRoles

To assign a case role to a contact:

  1. Click the Case Roles area to open it.
  2. Case roles that have not been assigned display "(not assigned)" in the Name column. Click the edit icon to assign someone to that role.
  3. The Assign Case Role popup window will appear. Begin typing the last name of the contact until you see the name in the dropdown list.
  4. Select the contact you want to assign to the role and click OK.

Generally, anyone who might be assigned to a case should already be in the database, but if you can't find the person you're looking, for you must add her as a contact first (navigate to Contacts > New Individual).

Each assigned case role has mail, edit and delete icons under the Email and Actions columns. You can email contacts with roles in the case, or modify their relationships to the case. Change the case role by clicking the edit icon, or delete a case role by clicking the delete icon. Emails that you send from here are automatically added to the list of case activities in the proper sequence. This provides an audit trail of case-related communications, and ensures that the "case story" is complete.

Finding activities within a case

You may need to find a specific activity within a case, for reference or modification. To view the activities in the case, scroll down to the Case Activities section and click it to open it if it's closed. In the default view, scheduled activities are listed first, sorted by date, followed by completed activities. Click on the column headers to sort by a specific column (for example, by activity type).

You can filter the activities if there is a large number of activities, or if you'd like to restrict the view to activities of a certain type (for example, to see all of the "Follow up" activities that have been performed for this case). Click the Search Filters accordion button, which opens a form (see screenshot) that allows you to filter by:

Once you have selected your search criteria, click the Search button to the right and the table will automatically filter out all of the activities not matching your criteria.

CaseActivitySearch 

Adding and managing activities

Several tasks are commonly performed on activities. After performing the necessary work, click the Save button to save the activity and be sent back to the case page, or Cancel to discard your work.

To add a new activity to a case

  1. Navigate to the case (either using Find Cases or via the Cases Dashboard).
  2. Choose an activity type from the select list labeled New Activity.
  3. Click Go.
  4. Fill out the activity form. The Client" field will be pre-populated with the case's client data.

To send a copy of the activity to anyone with a case role for the case

  1. Open the "Send a Copy" area.
  2. Check the contacts or case roles whom you would like to be alerted about this activity.

To schedule a follow up activity

  1. Open the "Schedule Follow-up" accordion.
  2. Select the follow-up activity type, the number of days until the follow-up should occur, and subject of the follow-up (e.g. "confirm that Jane's problem is fixed").

To add an attachment to the activity

  1. Open the Attachments area.
  2. Click a "Choose file" button.
  3. Up to five files can be attached to an activity. Select an attachment from your file browser.
  4. Click Choose. The name of the attachment will appear to the right of the "Choose file" button.

The attachment will not be saved into CiviCRM until you have saved the activity.

Editing an activity in a case

To edit an activity in a case:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click the "edit" link at the far right side of the activities table at the bottom of the case form.
  3. This brings you to the activity form, which you can edit in the same way as when creating an activity for a case. The only difference is that many of the fields will already be filled in.

To assign a "scheduled task" to a staff member while adding or editing a case:

  1. Start typing the staff member's name into the "Assigned to" field; a list of possible contacts will appear.
  2. Select from the list of suggestions and make sure the staff member's full name shows up in the "Assigned to" field.

You can assign multiple contacts to an activity. If you accidentally select the wrong contact, click the X by the contact's name to remove him from the list.  

Changing the status of a case

 The case status lets you quickly determine how a case is progressing. Sample status values include Ongoing, Resolved, Not Assigned, and Urgent.  To change the status of a case:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click Manage Case.
  3. Click the "edit" icon next to the current status column in the Case Summary table. 
  4. This will open the Change Case Status form (an activity with an additional field called Case Status).
  5. Set the case status to the new status.
  6. Modify the other the fields as you would when editing an activity in a case. Make sure to set the Status field. It is required, but not set by default. 
  7. Click Save to return to the case page, with a message stating that the Change Case Status Activity has been created.

Printing Case Reports

To print a report that lists all case and case activity data:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click Print Case Report in the Case Summary section.

Your installation may define additional reports for audit or quality assurance purposes. If so, you will see them listed in the "Run QA Audit/Redact" dropdown menu.

What is CiviReport?

CiviReport allows you to create, run and schedule reports based on the data CiviCRM has about your contacts and their interactions with your organisation. Many report templates are designed to work with a specific CiviCRM component, such as CiviContribute or CiviCase.

CiviCRM comes with a number of predefined report templates that are used to create reports. For example, the Membership Report template can be used to create a report that shows all student members that have joined your organisation within the past year.

CiviCRM's predefined report templates are built to satisfy the basic needs of non-profits and organisations. Each new version of CiviCRM will include further report templates, but if you can't find the right template for your requirement, you can extend CiviCRM by writing a new template yourself - and contribute it back to the CiviCRM community to share the benefit of your work.

Writing a new report template requires some PHP and SQL skills. A well-written template will be flexible enough to meet your specific needs as well as the needs of others. Techniques for developing report templates are explained in the section of this book which covers methods of extending and customising CiviCRM.

Real world scenarios

Reports help your organisation to evaluating its impact and achieve its mission. Here are some reports examples:

Evaluating turnout for an event

An organisation wants to attract young people to their annual 'Community Organising and Youth Leadership workshop'  They decide to announce the event three months in advance to ensure a good turnout. Lead staff or organisers will use the Event Participant Report throughout the registration process to determine if they need to do more outreach to attract m.

Here is a work flow describing how the organisation's staff will use this report.

  1. A lead staff person uses pecific criteria, such as youths under the age of 25 based in the target area, to identify contacts to invite to the event.
  2. Lead staff then email and phone the identified contacts to invite them to register and attend the event. 
  3. During the three months before the event, a lead organiser views the Event Participant Report at the end of each week to see how many have registered and to determine what other strategies could be used to increase the turnout. The lead organiser may also want to know the roles of the participants, such as who and how many will be speakers or volunteers.
  4. At the end of the event, the lead organiser will view the Event Participant Report again to see how many actually attended the event, as well as how many registered but didn't attend. Organisers may then want to follow up those contacts who registered but didn't attend, to determine whether there were any barriers to attending such as the cost of the event, lack of transportation or lack of interest in the topics scheduled for the workshop.

Determining total contributions for all people in a household

A non profit keeps records of individuals organised by households.  A common situation will be that the husband in the household has attended a numbe of paid events, and their wife has also registered for other events, and made seperate donations.

Staff at the organisation want to see the total contributions received from everyone in the household so that when someone calls the office to inquire about a donation or event payment made by someone else in the family, all the relevant information is at hand.  Staff run the Donation Summary Report (Household) and fill in the name of the household to find all contributions and find all relevant information and answer the caller's questions. 

Targeting a mailing for fundraising

Your organisation has launched a capital campaign to raise money for a new shelter. The development director wants to reach out to donors who made a large donation last year but haven't given money this year.

  1. She creates an instance of the LYBUNT report ("Last year but not this year") which filters data to show people who gave more than 500 EUR last year.
  2. She runs the report and uses the "Add to Group" button to put these donors in a new group.
  3. Then she sends an email to everyone in the group with information about the capital campaign.
  4. She adds the report to her CiviCRM Dashboard so she can review progress getting this group of prior donors to contribute to the campaign.

Planning with CiviReport

This chapter explains some key ideas that are useful when planning your use of CiviReport. It should be read by system administrators before they start to configure CiviReport for daily use. It will also be useful for anyone who wants to better understand the thinking behind CiviReport. Skip this chapter if you just want to look at specific reports that have already been configured by your administrator!

When to use CiviReport

CiviReport grew out of the need for users to be able to easily display complex information about their data, and to display answers to questions about this information in accessible ways. It is useful when you need to repeatedly ask the same question, or a set of similar questions, about your data.

CiviReport can be used as a management tool in organisational planning and as an analysis tool for membership or donor development. Tabular or graphical output can be produced and set up to email reports to specific people according to a schedule.

CiviReport might be overkill if you want to quickly find a set of contacts that match a certain criteria. In this case you might consider using one of CiviCRM's search tools.

What reports are available?

When you think about it, the number of questions a non-profit might want to ask about their data is pretty much infinite. The CiviCRM approach to solving this problem (which is a familiar CiviCRM approach) is to aim to cater for 90% of the scenarios and allow the system to be easily extendable by administrators and developers to cover the last 10%.

Reports often come in pairs: one showing a summary and the other showing the detail. These reports can be linked, allowing users to see information at a glance with the option to drill down in a certain report for more detail.

We haven't included all the reports available in CiviCRM here because the list is constantly growing. For a complete list of reports available in your version, along with an explanation how the reports can be used, look at the page 'Create reports from templates' (in the Reports dropdown menu).

Report templates and report instances

Two key concepts in CiviReport are report templates and report instances. A report template is the base for creating a report instance. In other words, you can generate any number of report instances from one report template. For example, the Top Donors Report template is used to show those people who have given most to your organisation. An instance of this report might show the top 10 donors that have given to your organisation this year-to-date.

Report vs. Search

CiviCRM has inbuilt search functionality that covers most scenarios, so it's important to know when to use a report and when to search. The current report interface does not support most common batch actions such as "Update via Batch Profile," "Smart Group" creation, etc. This means that if you want to perform any action against a result set, it is better to use search rather than report.

Reports are more flexible than searches, and each has its own set of features. Reports allow you to change display columns in selector, support column grouping, email the report and also save it as dashlet. Because you can create multiple report instances from a single report template, you can use the same report to show different iterations of the report, such as monthly donations or quarterly donations.

 

Configuration

This section explains how to configure CiviReports. It assumes a basic knowledge of why you would want to use CiviReport, and describes the workflow from creating a report from a template to making these reports available for users.

Report templates

Report templates are general reports that can be further customised to create specific report instances. These report instances can then be made available to users.

The "Create report from templates" page lists all available report templates and is found in the Reports menu. The templates are grouped by component, and each has a brief description of its intended scenario. If there are already report instances for a given template, you'll see a link to view "Existing Reports".

ReportTemplates

Clicking on the report template name will bring up a screen where the report can be configured.

There are two steps to configuring a report:

Select report criteria

There are three types of report criteria:

The options available for these criteria change from report to report. General principles for the different types of report criteria are outlined  below. 

Display Columns

These check boxes allow you to select the data to be displayed for each record in your report. In most reports, at least one display column is required and cannot be unselected. For example, in the Top Donors report, showing the total amount donated is required. In the Constituent Detail report, showing the contact name is required.

Group by Columns

This is not available in all reports, but it is useful when creating a report which summarises data, rather than displaying each individual row, and for reports that compare different types of data.

The report below compares donations per quarter in 2009.

summary_report

You can specify more than one grouping criteria. When you do this, groupings will be nested based on both groupings. Not all groupings or combinations of groupings will make sense for your data. You may need to spend time experimenting with Group By Columns to become familiar with this functionality.

Note that some Groups By Columns interact with Display Columns and can't be selected at the same time. The system will warn you if you try to make an invalid selection.

display_columns_error 


Set Filters

Filters are the main way to specify the records that you want to include in the report. For example, running the Membership Detail report without choosing any filters will show you all membership records. You could then filter the report to show all members of a specific membership type who joined last year.

The Date Range Filter

Most reports will have a date range filter. This can be configured in two ways:

date_range_rel

Relative date ranges are very useful for reports that you want to run on an ongoing basis.

The Ending date ranges are particularly useful when used in combination with Group By Columns.  Combining "Ending Year" with "Group By Month" gives a report that summarises data by month for the previous 12 months.

The report below shows the total amount of contributions received in the past 12 months, as well as each month's total.

  past_12_months_income

Once you have selected your report criteria, click Preview Report. If the report displayed isn't exactly what you wanted, open the Report Criteria section at the top of the screen to modify your criteria. You may need to make several modifications before you achieve the report you want.

Report settings 

Once you are happy with the report criteria you have entered into the template, save it as a report instance so that it is available to use again. It will appear in the drop down list of reports under the Reports navigation menu. 

Title, description and formatting options

Click Create Report to open the report settings section. Give your report a title and description that will help other people understand its usage, for example, "Student members joined so far this year".

You can optionally create a report header and footer in HTML. The header and footer will be displayed at the beginning and end of any PDF or downloaded versions of the report. This can be used to personalise your reports with your organisation's logo and to other useful information.

report_settings_general

Email settings

CiviReport allows you to email reports to specific people on a regular basis. To do this, fill in the Subject, To and CC fields in the Email Delivery Settings. You can enter one or more email addresses in the To and CC fields; multiple email addresses should be separated by commas.

You will need to configure a cron job for each report that you want to send. The cron job runs a script in the civicrm/bin directory (CiviReportMail.php) which takes several parameters, including the ID of the report instance that you wish to send. For example, if you want to send a Donor Report to your board members, you can configure a cron job with the ID of the particular report instance to email the report in HTML or PDF format. Refer to the "Command-line Script Configuration" documentation for more information:

http://wiki.civicrm.org/confluence/x/LIK9AQ

Adding reports to navigation menu

The most straight-forward way to share reports with other users is to add them to the navigation menu.  Do this by specifying the parent menu item under which the report should be listed, in Other Settings. For example, if you would like it to appear in the Reports menu, select Reports as the "Parent Menu". Alternatively, you might want to add an event report to the event menu.

report_settings_menu_email 

Permissions to view reports

You can set up permissions to view reports on a report-by-report basis. This allows you to simplify the user interface for junior users and set sensitive reports to be accessible only to certain users.

Permission to edit report criteria

Drupal installations only

The ability to edit report criteria is a separate permission that can be configured globally in Drupal.  Users with this permission will be able to edit report criteria, while users without this permission will be able to view reports but not edit the criteria.

Adding reports to the Dashboard

Finally, you can set a report to be available on users' dashboards by checking the box, Available for Dashboard? in Other Settings. Users with appropriate permissions will be able to add this report to their dashboard by clicking the Configure Your Dashboard button.

ConfigureDashboardBtn 

Every day tasks with reports

This chapter assumes that CiviReport is already configured and you are a user wanting to access reports that have been configured for you. If you want to learn more about how to set up and configure reports, read the section on configuring CiviReport.

Viewing reports

To view a report:

  1. Click on the navigation menu "Reports -> Report listing". 
  2. All reports are listed on this page, grouped by the component they report on. 
  3. To view a report, click on the report name.

Reports can also be configured to be directly accessible from navigation menus. They would normally appear in the Reports menu, but can be configured to appear in any menu. For example, an event report might appear in the Events menu.

When you open a report it will appear on screen as a table. Some reports can also be viewed as a bar or pie chart. When this is the case, a dropdown menu will allow you to select the format you want.

report_graph

The appropriate report should then be displayed.

past_12_months_income

As well as viewing reports on screen you can create a PDF version of either tables or graphs, suitable for printing or emailing.

report_pdf 

If you want to perform further calculations on your report data, you can output the data as comma separated variable (CSV) for import into a spreadsheet by clicking Export to CSV.

If you have the appropriate permissions, you will be able to adjust the report criteria and settings when you view the report. Read the section configuring reports for detailed information about how to do this.

Reports on your dashboard

Reports can be configured to appear on your dashboard (the first page you see when you log in to CiviCRM). You can configure this yourself, although not all reports may be available to put on your dashboard.

dashboard

To display specific reports on your dashboard:

  1. Click on Configure Your Dashboard (from your dashboard, i.e. CiviCRM home).
  2. Select a report from the list of available reports.
  3. Drag the report onto your dashboard.
dashboard_config

Emailing reports

Reports can be automatically emailed to certain people on a regular basis. This requires modifying the report settings, which is explained in the section on configuring CiviReport. If you do not have the permissions to do this, you will need to ask your administrator to configure it for you.

Adding report results to a group

Sometimes it is useful to add contacts returned in a report to a group. This functionality isn't available in all reports but where it is, you can choose the group you want to add the contacts to from the dropdown menu as shown below.

report_group

What is CiviEngage?

CiviEngage is a drupal module that enhances CiviCRM's core functions for non-profits focused on community organizing and civic engagement work.

Purpose

CiviEngage was built to aid community organizing, base-building and civic engagement, specifically with regards to managing walk lists for door-to-door campaigns and caller lists for phone banks.

CiviEngage provides:

Scenarios

Community organizing groups that do base-building and civic engagement work have taken advantage of the features in CiviEngage in various ways. The following are scenarios in which CiviEngage can help organizations further their ongoing community organizing.

Mobilizing Constituents for a Direct Action

An organization needs to mobilize several hundred people for a direct action at the state capitol in less than two weeks.  The organizers know that the best way to contact their particular constituency is by phone.  Organizers want to know who is coming to the direct action, so they can track that individual's involvement with the organization over time.

  1. Organizers will identify who they want to mobilize for direct action based on specific criteria and information they know about their constituency, such as geographic location, issue interests, volunteer interests, leadership level, etc.
  2. A staff member will create a Direct Action event in CiviCRM and add groups of individuals to the event.
  3. Organizers will call the list of possible participants from a Phonebank List report or through a participant listing and enter each call's results; such as whether they will attend, or if it's a wrong number, or if the organizer left a message.
  4. An organizer may contact the participants several times to ensure that they will attend the direct action, so the organizer will record the responses each time they attempt to contact the participant.  Most organizers attempt to contact up to 3 times to ensure that the participant commits to attending.
  5. After the Direct Action event, staff can analyze how many people attended or didn't who said they would attend, as well as if their method of outreach was effective.

Door Knock Canvassing

An organization wants to engage constituents based on what they learn from individual responses during a door knock canvass around a particular issue, such as workers' rights.  To find out more about how their constituencies feel about the issue and to see if they would like to help, the organization decides to do a door knock canvass in several neighborhoods.

  1. Staff will define the target audience based on specific districts in a city and use CiviCRM's Smart Groups to build the list of people to canvass.
  2. Staff will set up a Campaign Event to record the questions that will be asked during the door knock canvass.
  3. Staff will identify the volunteers who will do the door knocking and then add them as participants to the event. This way they can track who is door knocking and what group or list of individuals they will be visiting.
  4. Staff will print the Walk List Report based on the Smart Group, and will also export the walk list information to a spreadsheet to collect the responses and identify the volunteer canvasser.
  5. Each volunteer canvasser will door knock the locations on the Walk List and gather responses on their report. At the end of the night, other volunteers will gather the Walk List reports, and enter the responses on the spreadsheet. Staff can then import the spreadsheet information back into CiviCRM.
  6. After the canvass campaign, staff can use the Activity Report to analyze campaign responses to determine their next step to engage their constituency in the issue.

Planning with CiviEngage

CiviEngage packages a set of custom data groups and fields, reports, and other features for use in civic engagement and community organizing work. This chapter will describe the general concepts and planning needed to use CiviEngage effectively.

What You Need to Know

The following are concepts, custom fields and values to keep in mind when preparing to use CiviEngage.

Campaign Source Code

Campaign Source Codes are descriptive values used to identify related activities, events, contributions, and memberships and map how these activities and transactions are linked together. Campaign Source Codes are also useful for identifying these sets of activities or transactions as part of a larger campaign, project, or program.

For example, an organization is conducting a door knock canvass around a particular issue during a specific range of dates.  The organization may want to use campaign source codes to link together the activities (where responses to door knock canvass questions are captured), the event (the door knock canvass campaign itself), and any contributions made during the canvass to be able to analyze the effectiveness of the campaign.

Activity, Event, Contribution, Participant, and Membership records each contain a custom field to store a Campaign Source Code, that all share a common option list where Campaign Source Code values can be added and edited.

Your organization can establish a standard method for creating new Campaign Source Codes so that the codes are consistent and easy to sort and understand at a glance. For example, you can specify that annual campaigns always include the year at the either the beginning or the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual Campaign" and "Annual Campaign 2010."

Issue Interests

Issue Interests are issues that your organization works on or tracks. They are included in CiviEngage as a single option list shared across multiple contexts: 

It is important to remember that despite appearing with different labels in these different contexts, you are still dealing with just one shared list of options.

In planning to use CiviEngage you should come up with a list of distinct issues that are important to your organization and that you will want to utilize when tracking individuals' interest in your organization's work, the issues that your media contacts may be interested in covering, funders' general interests and the specific areas of work included in particular grants.

Volunteer Interest

Volunteer interests are activities that your organization's volunteers can take on and participate in; you can indicate each individual's interest in participating in these ways. They are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a list of your organization's current volunteer activities as well as any activities that you are planning to launch in the future. Some examples of volunteer interests are canvassing, phone banking, and tabling.

Cleaning your Address Data

Cleaning your address data means standardizing addresses to conform to the conventions defined by the United States Postal Service's Standards for Addresses. Standardizing how addresses are entered into CiviCRM will allow for more accurate search results when searching by address and is essential to generate accurate Walk List reports. CiviCRM will parse addresses based on the USPS standards. To find out more about how Address Parsing is handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding or editing contacts you will be entering or editing address elements including street number, street name, and Apt/Unit/Suite number according to these standards.

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that you plan to clean up address data before importing.

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 at http://pe.usps.com/text/pub28/welcome.htm.

Tracking Civic Engagement and Campaigns

CiviEngage is designed to manage interactions with constituents around an organization's civic engagement and base-building work, such as door knock canvassing and phone banking. There are several concepts and details to consider when preparing for these types of campaigns.

Working with Your Universe of Contacts

In preparing for your campaign, you will need to identify the audiences you will be targeting for your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular Groups as the mechanisms to target specific groups of contacts. Here are a couple of examples of how you can use Smart Groups and regular Groups for targeting during your campaign:

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" chapter of this book.

Preparing a Campaign Event

To prepare a campaign event in CiviCRM, there are several setup items you may want to consider:

Working with Voter History

When using CiviEngage, plan how you will manage voter history and other voter information collected during a voter engagement or electoral cycle. Many organizations have access to a voter file from which they manage all their voter engagement work outside of CiviCRM.  Once the voter engagement or electoral campaign is over and voter information is updated with who voted and other demographics, organizations most often will only want to keep information on the actual contacts they made during the campaign.  In this case, only those selected records from the voter file and additional voter information, such as responses to specific electoral campaign questions, will be imported and maintained in CiviCRM.  These voter records then become contacts that organizers will continue to engage and target with base-building efforts.

If you wish to collect voter contacts with their demographics, history, and additional information, first import voter contacts (with their contact information and demographics) into the Voter Info custom group. Then import additional information as Activities, such as responses to electoral campaign canvass questions.

Mobilizing Individuals to Attend an Event

The Participant Info custom data group that comes with CiviEngage contains fields that hold information about prospective event participants, including a history of interactions between your organization and prospective participants. Use this information (such as needs for childcare or rides) to bring these individuals to your events. Tracking the history of your organization's contact with individuals around events such as an annual membership meeting, a direct action, or leadership training can help you to understand the effectiveness of your outreach methods and determine how committed or engaged an individual is based on if the individual actually attends events after multiple contacts.

This feature is mostly useful for organizers or staff who have a list of individuals they are recruiting to attend an event through multiple phone calls or face-to-face meetings.  The following CiviCRM tasks could be used to mobilize individuals:

  1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of the contacts you want to mobilize or invite to the event.
  2. From the search results or Group Contacts screen, you can add the list of contacts to the event by selecting Add Contacts to Events from the Actions list. To find out more about how to add contacts to events, refer to the Managing Participants chapter in the Events section in this book.
  3. Once you add the contacts to the event, you can enter participant information or responses from multiple interactions in the Participant Info area in a contact's participant record. You can either enter information for one participant by editing the participant record itself, or you can add information for a list of participants at one time. For example, if you plan to call through your list by viewing the participant list from the event listing, you could use Batch Update Participants Via Profile and select one of the following custom profiles provided by CiviEngage:

Tracking Funders and Foundations

You can  track information about and due dates for grant proposals, letters of inquiries, and reports for funders by adding an activity related to the funder's contact record and choosing from the Proposal, Letter of Inquiry, or Report activity types.

You can also tailor information about an individual funder, such as their funding areas and issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you will need to use the Individual sub-contact type, Funder, when you create a new contact that is identified as a  funder.

You can tailor information about a foundation (organization record), such as their program areas for funding, using the Grant Info custom group. 

Tracking Media Contacts

As part of civic engagement and community organizing work, it can be useful to track information about your media contacts in CiviCRM, especially if you want to know which media contacts or outlets are interested in your organization's issues, or have written articles about your work, or for identifying who to contact when you want to publicize the work the organization is undertaking.

You can tailor information about an individual media contact, such as their media type (e.g., TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind custom group. Use the Individual sub-contact type, Media Contact, when you create a new contact for a media contact. You can then view and edit the Media Info - Ind tab.

You can also tailor information about a media outlet (organization) such as their media type (e.g., TV, Newspaper, Magazine, etc.)  using the Media Info - Org custom group. As with the individual media person, use the Organization sub-contact type, Media Outlet, when you create a new contact for a media outlet. You can then view and edit the Media Info - Org tab.

Tracking Elected Officials

Identifying and collecting information about your elected officials could be useful for your community organizing and civic engagement work.  You may want to know who is an elected official in a specific district, or who to contact on their staff, such as the scheduler, or spokesperson.

You can tailor information about an individual elected official, such as their elected position (e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the Individual sub-contact type, Elected Official, when you create a new contact for an elected official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, or spokespeople for an elected official can be entered as the Elected Official subtype.

Reporting and Analysis

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, the Activity Report is enhanced to filter custom activity fields such as those associated with the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information and demographics such as Member Type, Sex, Age, Party Registration, Voter history,  along with response codes  and notes where a volunteer can collect responses during a door knock canvass.

The Phonebank List report is similar to the Walk List report except that this report is used exclusively during a phonebank and contain response codes pertaining to phone responses.

The Walk List and Phonebank List reports are used to collect information during a campaign to later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific responses from a door knock canvass or phonebank campaign. Use this report not only to analyze the effectiveness of your campaign (e.g., how many people you contacted and collected responses from) but also to analyze responses from your constituency around an issue, or to determine whether individuals may become more involved with your organization.   

Disabling vs. Deleting Custom Data

If you decide you don't need to use or view particular custom groups, fields, or values, we strongly recommend that you disable the group, field, or value rather than delete them.  The Walk List and Phonebank List reports rely on these fields, so deleting certain custom data could potentially "break" the reports.

Installation

Several tasks are required to install CiviEngage. Given the level of detail involved, we refer you to the wiki for the procedure: http://wiki.civicrm.org/confluence/display/CRMDOC/CiviEngage+Installation

A few aspects of CiviEngage lead to special requirements:


Configuration

You will need to configure both Drupal and CiviEngage to use the module.

Configuring CiviCRM for CiviEngage

CiviEngage can be configured using the following CiviCRM core features:

Custom Data Groups

Configure custom data groups and fields to track voter demographics, issue interests, leadership levels, volunteer interests, and information about funders, media contacts, and elected officials.

Contact Subtypes

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups associated only with specific subtypes. The following are new contact subtypes:

    Individual subtypes:

    Organization subtypes:

Campaign Source Codes

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related activities, events, event participants, contributions, or memberships.  Campaign Source Codes can be used to describe a group of related activities, events, contributions, or memberships for a specific campaign, project, or program.

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking

Reports

Grant Proposal and Report Tracking

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom fields to track information and schedules for proposals, letters of inquiries and reports related to an individual funder or foundation.

Custom Profiles

CiviEngage configures several custom profiles for easier batch updating of individual or organization information, such as voter demographics, issue interests, volunteer interests, or event participant information. To learn more about profiles, please refer to the "Profiles" section of the book.

Configuring CiviEngage

When you install CiviEngage a number of custom fields are automatically created. These fields are designed to support your community organizing work. Most of these fields are multiple choice fields which have been pre-populated with sample options. Before you start using CiviEngage, you need to review and modify the supplied options to meet your needs.

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the following list bolded items are Group Header entries in the Custom Data screen. The bulleted items are custom fields under those Group Headers that have been added by CiviEngage; the other fields under these group headers are standard to CiviCRM. The choices for these custom fields should be edited before you use CiviEngage. You should add, delete, or edit the available options for each custom field to make them better fit your organization's needs.

Communications Details

Voter Info

All of the fields in this custom data group are added by CiviEngage, so you should review and edit them all to suit your needs. You may also want to add specific local voter fields that apply to you.

Constituent Info - Individuals

Grassroots Info


Constituent Info - Organizations

Grant Info

Participant Info

Contribution Source

Event Details

 Activity Source Details

Organizational Details

This custom group is used to store information that is specific to organizations. There is only one example currently.

Demographics

 Media Info - Org

This custom group is only applicable to the New Media Outlet contact subtype.

Media Info - Ind

This custom group is only applicable to the New Media Contact contact subtype.

Elected Info

This custom group is only applicable to the New Elected Official contact subtype.

Funder Info

This custom group is only applicable to the New Funder contact subtype.

Membership Source Details

Essential Tasks

This chapter provides instructions on how to do some of the common tasks associated with the CiviEngage module.

Printing a walk list

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing canvassing, Get Out the Vote (GOTV) or other door knocking activities.

  1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create the groups you want.
  2. Click on Reports -> Create Reports from Templates in the navigation menu.
  3. Click on the walk list report. Choose whether you want the Country or Email field to display.
  4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All your Groups and Smart Groups appear in the Group filter.
  5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now seeing the report results, but if you click on "Print Preview" you will see your walk list. You can use your browser's Print Preview feature to see the walk list on a per-page basis.

Printing a phone list

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing phone banks or other mass phoning activities.

  1. If you want to use Groups or Smart Groups to develop your phone list, be sure to create the groups you want.
  2. Click on Reports -> Create Reports from Templates in the navigation menu.
  3. Click on the phone list report. Choose the columns you want to display from the template screen.
  4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain results. All your Groups and Smart Groups appear in the Group filter.
  5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now seeing the results but if you click on "Print Preview" you will see your phone list. You can now use your browser's Print Preview feature to see the phone list on a per-page basis.

Create a Campaign Source Code

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all your activities to.

  1. Click on Administer -> Customize -> Custom Data.
  2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" link. This gives you a list of Custom Fields.
  3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you are seeing a list of the interests.
  4. Scroll down and click on "New Option" and add your new campaign.
Please note that this new campaign code will now be available for Event, Membership and Contribution Campaign Codes as well as in the Participant Campaign Code that it was just created in.

Add an issue interest

To better understand and track the areas that your members and constituencies are interested in working on, CiviEngage provides a field that collects this information. Customize this list to meet the needs of your particular organization.

  1. Click on Administer -> Customize -> Custom Data.
  2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom Fields" link. This gives you a list of Custom Fields.
  3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a list of the interests.
  4. Scroll down and click "New Option" and add your new interest. 
Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as well as in the Issue Interest that it was just created in.

Track Walk List/Call List Responses

Responses to the questions your canvassers or phone bankers ask are tracked in an individual's activity record. The text of the questions are tracked in the event record. In order to properly configure this, start with creating the event.

  1. Click on Events -> New Event.
  2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details section.
  3. Scroll down to the Event Campaign Details section and add the text to the questions for this particular campaign.
  4. You will also want to add an Event Campaign Code, which is in the Event Details section.

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and finish configuring this functionality.

  1. Go to a contact's record and click on "new activity."
  2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen.
  3. Scroll down and click on the Call List Responses section.
  4. Now you can record the responses.
  5. You then add the Activity Campaign Code in the Activity Source Details section. Make sure you choose the same campaign as you did for the Event.
Activisim_walklistresponses

Print an Activity Report

One of the features of CiviEngage is the ability to track the different activities that your members are engaged in. Use the activity report to better understand what your members are doing.

  1. Click on Reports -> Create Reports from Template.
  2. Choose the Activity Report. This brings up the Activity Report Template. You are now looking at all the options available for printing a report based on the activities CiviEngage offers that your contacts are engaged in.
  3. The first section lists the columns that are available for your report. Use the check boxes to decide what information you want your report to show. The default values are , Target Contact Name, Activity Type, Subject, Activity Date and Activity Status. You can choose columns from Walk List Responses, Leadership Level (from Activities), Call List Responses, Proposal Info or Activity Source Details.
    If, for example, you want a report of Walk List Responses from a specific campaign, you would check boxes from the Walk List Responses section and choose the Activity Campaign Code from the Activity Source Details section. Please note that the default value for Activity Date is "this month." If you want a different range of dates you have many options. Click on "this month" and you will see all the options available. Included is Date Range, where you can choose a specific range of dates.
  4. The next section allows you to group your data by the Source Contact (the default value), Activity Date or Activity Type. Check the appropriate box for your report.
  5. The final section is for filtering your data. Here you can choose data from any of the activity fields that CiviEngage offers.
    To continue our example, you might choose to include data where the first two Walk List questions were answered yes. Choose Y in the appropriate boxes and scroll down to the Activity Source Detail section and choose the appropriate Activity Campaign Code. Click Preview Report and view your results.
  6. Once you have your results, you have a number of options. You can "Preview" the report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a spreadsheet), or "Add the contacts to a group."

Search for Activities

The are a number of ways to search for the activities that you create using CiviEngage:

Using the Find Activities search option

  1. Click on Search -> Find Activities.
  2. You are presented with a number of search criteria options. You can enter the name or email address of a contact in the database. You can choose one or more activity types. You can add a range of dates during which activities happened. You can search for contacts in specific Activity Roles: With, Created By and Assigned to. You can look for specific subjects, test activities or by the status of the activity. Each criterion you select will narrow your search results.
  3. Click Search and you will get to the Search Results screen.
  4. Select some or all of the search results and click on "- actions."
  5. You can then choose to export your results, send an email to all the contacts you found or add these contacts to a group or smart group, among other options.

Using Advanced Search to find Activities

  1. Click on Search -> Find Contacts - Advanced Search.
  2. Scroll down to the Activities section and click on it. Here you find all the options available in CiviEngage for activities.
  3. Once you choose your search options and click Search you will get to the Search Results screen.
  4. Select some or all of the search results and click on "- actions."
  5. You can then choose to export your results, send an email to all the contacts you found or add these contacts to a group or smart group, among other options.

Using the Custom Search: Activity Search

  1. Click on Search -> Custom Searches... -> Activity Search.
  2. You are presented with different criteria by which you can search for information. Enter your search terms and click Search.
  3. The Search Results provides the Name of the person, the Status, Type and Subject of the Activity and who assigned the activity. You also have a button for viewing and editing each activity record. 
  4. Select some or all of the search results and click on "- actions."
  5. You can then choose to export your results, send an email to all the contacts you found or add these contacts to a group or smart group, among other options.

Extending CiviCRM

This section contains developer documentation for CiviCRM. It should be useful for developers wishing to extend CiviCRM and also for organizations who want to ensure that their developers are using best practices to extend CiviCRM.

There are many different ways you can extend and customize CiviCRM, and this section takes you through them in order of simplest to most difficult. If you find that you cannot do something you're trying to do using the tools and techniques outlined in this section, please get in touch with the CiviCRM developers in the forums (http://forum.civicrm.org/) or on the IRC channel (#civicrm on irc.freenode.net) and let them know.  Hacking on the core code should always be a last resort and done in consultation with the core team who will always be happy to help you find the best way to cover your use case.

When do you need to code?

There are a lot of different options to customize CiviCRM to fit your specific needs. They are listed roughly in order of complexity:

  1. Change the configuration: (ok, this isn't coding but it is worth repeating) you can use custom fields, profiles, components and many existing Drupal modules and Joomla! extensions to customize CiviCRM without writing a line of code. This book covers many of these options in other sections, so make sure you've exhausted all of those possibilities before you dive into extending the code.
  2. Edit CSS: You can create a new Cascading Style Sheet (CSS) file and use it, for example, to adapt the style to your site or hide elements that don't make sense in your environment.  Administer -> Configuration -> Global settings -> Resource URLs field "Custom CiviCRM CSS URL".
  3. Edit the templates: Useful to change the layout of forms, and to add more data or features via AJAX. Read about templating and APIs to know more.
  4. Implement hooks: Hooks are called at specific points in the code as users interact with CiviCRM and are useful, for example, when you want to change the default behavior when you create, update or delete an entity, create a new custom mail merge token, or to populate a custom field automatically based on your own business logic.
  5. Add custom searches or reports: Use these to fetch information and display it in a unique way.
  6. Extend your CMS: Create a Drupal module or Joomla! extension that integrates with CiviCRM.
  7. Override PHP files: In the same way that you can override templates, you can override any file in CiviCRM. If you have to modify core, it's much better to override files than to edit them.
  8. Write a new CiviCRM component or patch CiviCRM: Regardless of which path you take to extending and customizing CiviCRM, chances are that someone else would be interested in what you did. Share it with the community! If others start using your contribution, you're likely to get bug fixes, improvements, and documentation as a bonus. Let us know what you did in the forums or IRC channel (see above).
Where possible use the documented APIs in your extensions, this will make them less likely to break when you upgrade CiviCRM.

Before venturing into any development, we strongly suggest that you discuss what you want to do, and how you want to do it, with the community.  We will help you find the simplest way to reach your goal and may be able to point you to others doing similar work.

Please consider using the Academic Free License to open more opportunities to share your work. This also makes contributing your work back to the CiviCRM project very simple.

Developing Page Templates

CiviCRM uses page template files to display all the pages. This makes it possible for a person to customize any CiviCRM screen to suit a special requirement or preference. The HTML for CiviCRM pages is not embedded in PHP code, instead a template engine (Smarty) sends the correct page to the web browser.

A person should be familiar with HTML and CSS syntax to be comfortable editing page templates.  Some page templates additionally make use of JavaScript and an Ajax utility, JQuery.

Changing page templates is the wrong choice when ...

If it is possible to make the needed changes by updating the CSS styles. For example, if a requirement is to hide o⁞r move some information or form fields on a screen, a CSS style for that HTML element can be changed to display: none, or position: absolute within the CSS file.

If there is a CiviCRM hook available that can control the page. For example, there is a hook that can modify the information on the Contact Summary screen.

If there is no process in place to update the page templates after an upgrade to a new version of CiviCRM. Page templates are stored in a separate folder and are not touched during an upgrade, However new versions of CiviCRM often change which placeholder elements are available in various templates. Proper source control procedures are needed to simplify upgrades to new versions.

Smarty templates introduction

CiviCRM uses a page template engine called Smarty.  This documentation is focused on how Smarty is used within the CiviCRM environment.  Every Smarty element is enclosed between braces like these: "{}". All the other text is going to be displayed directly as HTML in the rendered page.

Each page template is stored in a file with the extension .tpl. The PHP code assigns variables for content that needs to be displayed, and then lets the template engine take care of presenting it.

The Smarty template engine always does this process :

  1. Load the contents of a .tpl file.
  2. Scan the .tpl file for placeholder elements.
  3. Replace each placeholder element with the corresponding variable value.
  4. Send the resulting HTML to the web browser.

These are the most commonly used Smarty template elements:

Please read the Smarty documentation for more information.

Tip:  To see what variables have been assigned to the template, enable debug (Administer -> Configure -> Global Settings -> Debugging) and on any URL, add &smartyDebug=1. It opens a new browser window listing all the variables and values.

CiviCRM introduces some extra features to Smarty:

How to find and modify the templates ?

All the templates are under the folder templates/CRM in your CiviCRM installation. Finding which template is used on a given page can be difficult, but the easiest way to find out the answer is to view the source of the page from a web browser and search for ".tpl". For example, for the Contact Summary page, use the web browser to open the Contact Summary page, then click "View Source" in the browser.  You should find an HTML comment such as: 

<!-- .tpl file invoked: CRM/Contact/Page/View/Summary.tpl. 
      Call via form.tpl if we have a form in the page. -->

You can then view the file at templates/CRM/Contact/Page/View/Summary.tpl to see how the HTML is generated. If you want to modify the layout; for instance to reorder the content, do not modify directly these files, as all the modifications will be lost on the next upgrade of CiviCRM. The proper way is to create a new folder outside of your CiviCRM folder, then navigate to "Administer -> Configure -> Global settings -> Directories" in the navigation menu, and set the complete path of the folder that is going to contain your custom templates in the field Custom Templates.

Scenario: The Contact Summary screen needs to be changed

If you want to alter the Contact Summary page template for Acme organization, perform these steps:

  1. Create the folder /var/www/civi.custom/acme/templates/CRM/Contact/Page/View
  2. Update the Custom Template field in the Global Settings directories  to /var/www/civi.custom/acme/templates. You can use any directory. We found it easier to put the custom templates under /var/www/civi.custom/yourorganisation.
  3. copy templates/Contact/Page/View/Summary.tpl from your CiviCRM install to /var/www/civi.custom/acme

Tip:  Say you want to modify the template for a specific profile form, or a specific event. Instead of copying the Form template to its default place (templates/CRM/Profile/Form/Edit.tpl), you can create a subfolder with the ID of the profile and put the template file you want to change in the subfolder (templates/CRM/Profile/Form/42/Edit.tpl to modify only the form for ProfileID 42).

You might be willing to modify a template that isn't directly the page you load, but added later via Ajax. For instance, perhaps you want to change all the tabs beside the Content Summary (Activities, Groups, etc.). The easiest way to do this is to install a development oriented plug-in to your web browser. If using Mozilla Firefox, the Firebug plug-in is indispensable.  Open the Firebug console (or equivalent in your browser)  and click the tab. You will see what URL has been loaded for the tab (e.g., for the notes tab:  http://example.org/civicrm/contact/view/note?reset=1&snippet=1&cid=1). Open it in a new window or new tab of the web browser, and view the source. It also contains a comment identifying the template used (CRM/Contact/Page/View/Note.tpl).

Keep in mind that when you modify a template, you might have a template that doesn't work properly anymore after an upgrade of CiviCRM, because the layout has changed or the name of variables assigned to the template was modified. In our experience, the easiest is to use a source code management system (SCM) to keep track  of the changes you have made. Before doing any modification of the template you copied, add it to your SCM, and obviously also commit the template after having modified it. That way, you can easily generate a patch of your changes, and see how to apply them to the latest version of the template.

Semantically meaningful HTML attributes

To make it as easy as possible for you to style any element in the page (e.g. put a yellow background on all the contacts of the subtype "members"), or add Ajax (clicking on the status of the activity changes it to complete), we strive to have a consistent and coherent schema for class names and ids for the generated HTML. This makes it easier to isolate the elements you want to alter from a custom style or from JavaScript:

At the time of the writing, some of the templates don't follow these conventions. Please update them and submit a bug tracking issue with a patch if you need to use a template that isn't yet complying. For more information about submitting a bug or issue, read About the CiviCRM community. 

Displaying more content and adding Ajax features

If your modifications go further than "simple" modifications of the layout, but need to display more content than the one assigned to the template by default, or to add Ajax functionality, use the CiviCRM API. Please read more information about using the CiviCRM API from Ajax to pursue this approach.

In most cases, using the CiviCRM APIs should be simple and only takes a few extra lines of modifications.

Some useful variables and examples

On each page template, you have extra Smarty variables populated by CiviCRM.

{$config}  Contains a lot of useful information about your environment (including the URL, if it's Drupal or Joomla!, etc.)

{$session} Contains information about the user.

If you want to modify the template only for a logged-in user but leave it identical for anonymous users, do the following:

{if $session->get('userID') > 0}
Insert your modifications here
{/if}

Writing custom reports

This chapter is a brief introduction to creating a new report in the CiviReport system. You can use the same programming techniques to extend an existing report template. These tasks call for a strong grasp of PHP. More details are available in the wiki page on customizing reports:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviReport+structure+and+customization.

Creating or changing a report template is the wrong choice when ...

If you want a batch action on an existing result set. CiviReport does not support most of the batch actions.  If your main purpose is to print or send an email to a list of contacts that meet specific criteria, write a custom search.

Report specification

Before starting on a custom report, fill out the form on the CiviCRM wiki for report specifications.  Add your specification there and ask for comments in the forum or on IRC.

Creating a custom template

This section creates a custom report listing all contacts' Display Name, First Name and Last Name.  Note that we'll be talking about both Smarty templates (.tpl files) and PHP report templates--be careful not to confuse the two.
Replacing an existing report with your own version is not recommended because you may need the original too, and because an upgrade of CiviCRM will overwrite your changes with the CiviCRM version. In this section, therefore, we'll create a new Smarty template and a new PHP template for the report. You can also copy a template and report to a new location and edit them to create your custom report.

All reports are located under CRM/Report/Form/ and grouped by component.

Create a new Smarty template and a new PHP template for the report. Because this example creates a report about contacts, we'll create a new report template named Contact.php and a Smarty template named Contact.tpl, both in a custom directory (the Contact.php in the custom directory for php scripts, the Contact.tpl in the custom directory for templates). The paths will look like:

PHP_CUSTOM_PATH/CRM/Report/Form/Contact/Contact.php

TPL_CUSTOM_PATH/CRM/Report/Form/Contact/Contact.tpl

Add a base class named CRM_Report_Form_Contact_Contact in Contact.php, Your class must inherit the form class used for the report framework. So Contact.php looks like:

<?php
require_once 'CRM/Report/Form.php';
class CRM_Report_Form_Contact_Contact extends CRM_Report_Form {
}

Your Smarty template file must include the report framework template. Thus, Contact.tpl is:

{include file="CRM/Report/Form.tpl"}

Register your report template in CiviCRM. Go to: Administer ->⁞ CiviReport -> Register Report. Enter the details shown in the following screenshot.
Reports_register
In a constructor, create an array to hold a contact, which in turn hold an array specifying two fields you want to display.

function __construct( ) {
    $this->_columns = array( 'civicrm_contact' =>
    array(
        'dao' => 'CRM_Contact_DAO_Contact',
        'fields' => array( 'first_name' => array( 'title' => ts( 'First Name' ) ), 'last_name' => array( 'title' => ts( 'Last Name' ) ),
    ) ) );
parent::__construct( );
}
Build the display by issuing a SELECT against the database. You can create column headers and fill in each field in the display with the results returned by the SELECT.
    function preProcess( ) {
        parent::preProcess( );
    }
// build select query based on display columns selected
    function select( ) {
        $select = $this->_columnHeaders = array( );
        foreach ( $this->_columns as $tableName => $table ) {
            if ( array_key_exists('fields', $table) ) {
                foreach ( $table['fields'] as $fieldName => $field ) {
                    if ( CRM_Utils_Array::value( 'required', $field ) ||
                    CRM_Utils_Array::value( $fieldName, $this->_params['fields'] )) {                       $select[] = "{$field['dbAlias']} as {$tableName}_{$fieldName}";           // initializing columns as well
           $this->_columnHeaders["{$tableName}_{$fieldName}"]['type']  =
               CRM_Utils_Array::value( 'type', $field );
           $this->_columnHeaders["{$tableName}_{$fieldName}"]['title'] = $field['title'];
                    }
                }
            }
        }
        $this->_select = "SELECT " . implode( ', ', $select ) . " ";
    }
    function from( ) {
        $this->_from = "FROM civicrm_contact {$this->_aliases['civicrm_contact']}";
    }
Your custom report template is ready. Press the Preview button to see the results.Contact Report
After you've installed and tested your report, add it to the CiviCRM wiki as a patch to the project so that it can be used by others in the community.

Developing Custom Searches

A custom search is a method of providing new functionality within the standard CiviCRM navigation structure. This chapter looks at how to develop a Custom Search and is written for programmers.

Custom searches produce a screen showing a set of contacts, from where you can execute actions such as sending email, printing mailing labels, and all the other actions that are available for contact search results within CiviCRM. The results page displays the same as any other search results page, such as results delivered from an Advanced Search, however, a predefined set of functions is controlling which information is delivered to the result page.

Custom Searches follow the Hollywood principle, "Don't call me, I'll call you." In this case CiviCRM calls your functions at the appropriate time.

CustomSearches_AggregateTotals

 

CustomSearches_Results

When to use Custom Searches

A custom search is the right choice when ...

A custom search is the wrong choice when ...

CiviReport is a better choice if ...

Getting started creating a new custom search

In this section we will create a new custom search called "BirthdaySearch" that will find all contacts whose birthdays fall in June. 

Custom searches are written using PHP and SQL. Very little knowledge of PHP is needed, as you start with a template file and only make minor changes. In many cases the only changes are the SQL Select statement and which columns to display in the results.

Plan and test

Before writing the code, it is important to plan and test the SQL query and verify the results. It is valuable at this stage to review the database tables and test the SQL select statements within the database using an SQL tool such as PHPMyAdmin.

It may be helpful for you to review the information at:

Setting the filepath

Your custom search files can be stored almost anywhere, but you must tell CiviCRM where these files are. 

  1. Within CiviCRM, go to: Administer > Configure > Global Settings > Directories
  2. Fill in the Custom PHP Path Directory. This needs to be an absolute path to your PHP directory, such as /home2/jsmith/public_html/civicrm_custom_code/
  3. Create a copy of an existing custom search file, such as the EventAggregate.php file. You will find this file at: 
    <joomla root>/administrator/components/com_civicrm/civicrm/CRM/Contact/Form/Search/Custom  
    or
    <drupal root>/sites/all/modules/civicrm/CRM/Contact/Form/Search/Custom
  4.  Place the EventAggregate.php file in the directory: /home2/jsmith/public_html/civicrm_custom_code/CRM/Contact/Form/Search/Custom
  5. Rename the copied EventAggregate.php file to BirthdaySearch.php

Understanding and updating the search code

Start by opening the file BirthdaySearch.php in a text editor. The first change needed is to change the class declaration to:

class CRM_Contact_Form_Search_Custom_UpcomingBirthdays
   implements CRM_Contact_Form_Search_Interface {

Functions you will probably need to modify:

if ( $onlyIDs ) {
     $select  = "DISTINCT civicrm_contact.id as contact_id,
      civicrm_contact.display_name as name";
    } else {
    $select = "DISTINCT civicrm_contact.id as contact_id, CONCAT(
     monthname(civicrm_contact.birth_date) , ' ', day(civicrm_contact.birth_date))
     as sort_name , civicrm_contact.display_name as name, 'birthday' as oc_type" ;

    }
   
    $from  = $this->from( );
    $where = $this->where( $includeContactIDs ) ;
    $sql = "SELECT $select FROM  $from WHERE $where ";

⁞

Functions you may need to modify:

Prepare to run the custom search

Before you can run the custom search, CiviCRM needs to be informed that it exists. This is accomplished by the following steps:

  1. Go to: Administer > Customize > Manage Custom Searches.
  2. Scroll to the bottom of the page and click the button New Custom Search.
  3. Provide the class path as: CRM_Contact_Form_Search_Custom_BirthdaySearch
  4. Provide the title as: Birthday Search

The new Birthday Search should now appear in (and can be run from) the list of custom searches in the navigation menu. It will also appear on the page reached by going to Search > Custom Searches.

The new custom search will not appear in the black navigation menu unless the navigation menu is edited.  This can be done by going to Administer > Customize > Navigation Menu.

Testing the custom search

 Always test the following behaviors of the new search:

Working with the API

CiviCRM provides an Application Programming Interface (API). This is a stable, coherent and standardised set of functions and it is the recommended way for any external programme to interact with CiviCRM.

CiviCRM is open source software, which means you can modify the source code or call methods and objects directly. But if you did, you would probably encounter difficulties when upgrading to a new version of CiviCRM because those methods and objects may have changed in the new version.

On the other hand, the API is designed to remain the same so it should behave identically across versions, or at the very least warn developers well in advance of a change. An API change between minor versions will be considered a regression bug and you should report it to the CiviCRM development team so they can fix it.

Most of the API functions are low level methods that allow you to interact with one of the entities in CiviCRM (contact, tag, group, activity, etc.). For each entity type, there are at least 3 actions: add (handles add and update), get (one specific entity), and delete. Some entities work slightly differently. Read the API docs in the wiki for the most up-to-date information:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Public+APIs

Additionally, the API test directory http://svn.civicrm.org/civicrm/trunk/tests/phpunit/api/v2/ contains examples of most of the APIs, along with what parameters to use as input and what return parameters to expect.

There is an ongoing effort to better standardise the APIs, and help is certainly appreciated. If you're interested in lending a hand, post to the API section of the developer forum here: http://forum.civicrm.org/

How to use the API

The naming convention for API functions is civicrm_entityname_action. For instance, the function to create a contact is civicrm_contact_add, and the method to delete a group is civicrm_group_delete.

Every API function takes one single array of parameters as input. If the function needs a single parameter (e.g. the identifier of the group you want to delete), this will be an array containing a single item like so: array( 'id' => XX );

Every API function returns a single array. All the delete and add/modify functions contain an item "is_error". If the function couldn't delete or modify the entity as you requested, is_error = 1 and a second item error_message returns details about the error (eg. "DB Error: already exists"). If you have turned on debugging (see the Developer Tips & Tricks section), you have an extra item "debug_info" that contains a more detailed explanation (e.g. "INSERT INTO civicrm_tag (name) VALUES ('existing tag name') [nativecode=1062...").

They are at least 5 different ways of using an API function:

  1. as a php function, to run your own code on the same server as CiviCRM
  2. via the AJAX interface, to be called from JavaScript code
  3. via the REST* interface, can be called from another server via http calls
  4. as a Smarty function to add data to templates
  5. from drush on the command line for Drupal installations.

Tip: When using the API, be sure to verify the proper name of each parameter, which parameters are mandatory, and the structure of the resulting array. The easiest way to test the API is to make AJAX calls from a test web page. See the AJAX section below for more information.

*It's not really REST, but it's not SOAP either. It doesn't work for many API functions because it assumes a certain level of standardisation that just isn't in place yet (as of version 3.2). Test, test, test if you use the REST (REST, REST) interface, and don't hesitate to file bugs when things don't work the way they should.

Calling the API as a PHP function

If you write custom code that is going to run within the same environment as CiviCRM, calling the API as a PHP function is the recommended way of modifying or fetching data. You will see examples of API calls throughout the developer documentation.

For example, you could create several tags from a script rather than doing it manually from the CiviCRM admin page. The code below shows you how to do it using the API. 

Following the API convention described above, the function to call is civicrm_tag_create. The input parameters are: name, description, parent_id.

<?php
require_once 'civicrm.config.php';
require_once 'CRM/Core/Config.php';
require_once 'api/v2/Tag.php';

$param = array("name"=>"Topic of interest");
$result = civicrm_tag_create( $param );

if (civicrm_error( $result ))
  die ("Topic of interest already exists");

$parentid = $result['tag_id'];

$tags = array("Animal Protection", "...200 other tags", "Zen");

foreach ($tags as $tag) {
  $params = array("name"=>$tag, "description"=> "Example of Topic of interest",
      "parent_id" => $parentid);
  $result = civicrm_tag_create ($param);
  if (civicrm_error( $result )) {
        echo "\n ERROR creating $tag: ". $result['error_message'];
  } else {
        echo "\n Tag $name created with id:".$result['tag_id'];
  }
}

Some explanations:

Tip: It is very easy to create a custom API class to add new methods to the API. Simply create a new file in api/v2/ with any name you want (and a .php extension) and put the functions in it. They should follow the naming convention explained above. Your new API functions will automatically be available.

Calling the API as Ajax back-end

With Ajax, you can retrieve data from the CiviCRM server asynchronously in the background without interfering with the display and behavior of the existing page. 

This section assumes you are familiar with over-riding templates and using jQuery. There is a chapter in this section on over-riding templates, and you can find more information on jQuery using any web search engine.

All the API functions are directly usable from an Ajax call and available to all logged-in users with CiviCRM access privileges. This is very useful to update a value in the database without having to reload the whole page (which might contain a long list of records, for example). You could use it on the  activities list page to set the status as "completed", on a list of participants to set the status as "attended", or to tag a contact in a search result, each time without having to reload the page.

Using the jQuery plug-in

The file js/rest.js contains a jQuery plug-in to make it simpler to call any CiviCRM API function.

The general syntax is $().crmAPI (entity,action,params)

For example, to dynamically create a tag, using JavaScript, in any page:

 $().crmAPI ("civicrm_tag", "create", {"name": "Wonky", "description": "Broken, please fix."});

Upon completion of the Ajax call, the default behaviour is to display a "Saved" message in a div with id "restmsg" (you will need to be sure this div exists in your page if you want to see the message). However, you might want to alter this default behaviour, for instance to change the colour of a row, the name in a field or to hide a button the user has clicked. This is done via a special parameter, "success", that is a function called when the Ajax API has returned the result. The next example shows how this is used.

Large organisations often have many contact records in CiviCRM and staff don't have time to update every detail of every record, even if they notice that the phone number doesn't work or the address isn't correct anymore. One solution is to allow them to flag the record for later follow-up if they suspect it may be inaccurate.

To make this as simple as possible, create a button that tags the contact "To be checked". We can modify the contact summary screen (CRM/Contact/Page/View/Summary.tpl) and add a button "To be checked", that adds the tag via an Ajax call to the API.

tobechecked_600x22.png

Here's what we added to the contact summary template to make this work (don't forget to create the "To be checked" tag):

{literal}
<script>
jQuery(document).ready(function($){
  $("#actions").append(''<li><a href="#" id="tobechecked" class="button"
     title="If the contact details need to be updated"><span>
          To be checked</span></a></li>');
   $("#tobechecked").click(function(){
     $().crmAPI ('entity_tag','add',{
                  tag_id       : 6
                 ,entity_table : 'civicrm_contact'
                 ,entity_id    : {/literal}{$contactId}{literal}
                 },{
                 success:function (){
                   $("#tobecheked").fadeOut('slow');
                 }
                 });
     return false;
   });

});
</script> {/literal}

A few points of explanation:

Ajax behind the scenes

It is useful to know what happens when you use the Ajax interface to help you debug problems with it.

The $().crmAPI call accesses a URL like this (for Drupal with clean URLs enabled):

http://eg.org/civicrm/ajax/rest?fnName=civicrm/<entity>/<action>&json=1&param1=xxx&param2=yyy...

To create a tag, for example, the following URL gets accessed:

http://eg.org/civicrm/ajax/rest?fnName=civicrm/tag/create&json=1&name=
     example&description=direct

Tip: In order to test an API function that you want to use in your PHP code, a template, or via the REST interface, you can use the Ajax interface to figure out the right parameters. For instance, if you want to fetch all the tags of a contact (method civicrm_entity_tag_get), log in to CiviCRM and then paste this URL into your browser:

http://example.org/civicrm/ajax/rest?fnName=civicrm/entity_tag/get&json=1

It should return {"is_error":1,"error_message":"entity_id is a required field."}. So you add the entity_id (which should be the contact id in this case). Now try this one:

http://example.org/civicrm/ajax/rest?fnName=civicrm/entity_tag/get&json=
    1&entity_id=1

... which returns:

[{"tag_id":"4"},{"tag_id":"3"},{"tag_id":"1"},{"tag_id":"14"}]

You can also now see the format of the returned data. This should give you a good idea of how to use this API function in other contexts.

Autocomplete and search contacts

If you create a profile for individual contacts that contains the current employer, you might want to add an autocomplete on that field, such as you have on the normal contact edit form. When a user starts to type the name of the current employer, the system will attempt to autocomplete the name from your database of organisation contacts.

For security reasons, the Ajax interface is restricted to users who have access to CiviCRM - otherwise, it would be fairly easy for anyone to download all the contacts you have in your database. So that's the first thing we check for here:

{if $session->get('userID') > 0}

<script type="text/javascript" src="../{$config->resourceBase}js/rest.js"></script>{literal}
<script>
jQuery(document).ready(function($){
  $('#current_employer').crmAutocomplete({params:{contact_type:'Organization'}});
});
</script>
{/literal}

{/if}

You might want to add additional filters. For instance in a profile "new volunteer from a member", you want to populate the list only with the organisations that belong to the group "members" (group id 42).

$('#current_employer').crmAutocomplete({params:{contact_type:'Organization',group:42}});

Calling the API from a template

This section assumes you know how to find the template used to render a page and you know how to over-ride a template. Read the section on templating in the developer documentation if you're not sure.

On some templates, you might want to display more information than what is available by default, for example, displaying the list of groups a contact belongs to next to his or her tags.

You can use the API to fetch that information from within the template and assign it to a Smarty variable that you can then display just like any other variable.

The general syntax is {crmAPI var="new variable name" entity="entity name" action="action name" param1="xxx" param2="yyy"}

For example to fetch all groups the user id 42 belongs to and assign them to the variable groups:

{crmAPI entity="group_contact" action="get" var="groups" contact_id=42}

The following code adds the list of groups below the list of tags on the contact summary page (CRM/Contact/Page/View/Summary.tpl)

<tr>
  <td class="label">Groups</td>
  <td id="groups">
{crmAPI entity="group_contact" action="get" var="groups" contact_id=$contactId}
{foreach from=$groups item=group}
{$group.title},
{/foreach}
 </td>
</tr>

Calling the API from an external server via the REST API

The syntax and principle are identical to the other methods, but with one major difference: the external server needs to authenticate itself before being able to use any API functions.

To call the API with a browser, use:

http://www.example.org/path/to/civi/codebase/civicrm/extern/rest.php?q=civicrm/<function>

The first call is to authenticate the caller on the CiviCRM server:

https://eg.org/path/to/civi/codebase/civicrm/extern/rest.php?q=civicrm
   /login&name=user&pass=password&key=yoursitekey&json=1

The key is in the CIVICRM_SITE_KEY variable defined in your civicrm.settings.php file.

Note: On the first call, you might get an error message like "This user does not have a valid API key in the database, and therefore cannot authenticate through this interface". This means that you need to generate a key for the user, and add it to the api_key field in the civicrm_contact table in the database.

{"is_error":0,"api_key":"as-in-your-setting.civicrm.php",
   "PHPSESSID":"4984783cb5ca0d51a622ff35fb32b590",
   "key": "2e554f49c9fc5c47548da4b24da64681b77dca08"}

 

It returns a session id. You can then use any API adding the extra param PHPSESSID = the value returned by the log-in call.

For example:

http://www.example.org/civicrm/ajax/rest?fnName=civicrm/contact/search&json=1&key=
yoursitekey&PHPSESSID=4984783cb5ca0d51a622ff35fb32b590

Note: An action that modifies the database (such as creating a contact or group) should have the parameters passed as POST, not GET. The REST interface accepts both a GET and a POST, but you should follow the web standard and use POST for things that alter the database. You'll win the respect of your peers and the admiration of your friends and family.  

Access the REST API from other languages

The REST interface is language neutral (any language can use it as soon as it operates over HTTP requests), and 3 external libraries have been written by others in the CiviCRM community (and are in various states of completion):

  1. perl: http://search.cpan.org/~wmorgan/
  2. ruby: http://github.com/cap10morgan/civicrm-client-rest-ruby
  3. python: http://dev.plone.org/collective/browser/collective.civicrm.pycivicrm/trunk
Please refer to the documentation provided with each library to see how to use them (or complain to their authors if it is lacking).


Hooks

Hooks are a common way to extend systems. The way they work in CiviCRM is that, at key points in processing--such as saving a change or displaying a page--CiviCRM checks to see whether you've "hooked in" some custom code, and runs any valid code it finds.

For example, let's say you want to send an email message to someone in your organization every time a contact in a particular group is edited. Hooks allow you to do this by defining a function with a specific name and adding it to your organisation's CiviCRM installation. The name of the function indicates the point at which CiviCRM should call it. CiviCRM looks for appropriate function names and calls the functions whenever it performs the indicated operations.

Hooks are a powerful way to extend CiviCRM's functionality, incorporate additional business logic, and even integrate CiviCRM with external systems. Many CiviCRM developers find themselves using them in nearly every customization project.

Using a hook is the wrong choice when ...

If you just want to invoke an activity from CiviCRM in a program, it's more appropriate to use the API (covered in another chapter). For example, if you want CiviCRM to output everyone in a particular group so that you can feed them into an external database, you probably should use the API instead of a hook.

A good test for whether or not to use a hook is to ask yourself whether what you're trying to do can be expressed with a sentence like this: "I want X to happen every time someone does Y."

How to use hooks

How you use hooks depends on whether you're using CiviCRM with Drupal or Joomla!.

Using hooks with Drupal

Check the CiviCRM wiki page for the most up-to-date information on setting up hooks with Drupal: http://tiny.booki.cc/?hooks-in-drupal

In order to start using hooks with a Drupal-based CiviCRM installation, you or your administrator needs to do the following:

  1. Create a file with the extension .info (for instance, myhooks.info) containing the following lines. Replace the example text in the first 2 lines with something appropriate for your organization:
    name = My Organization's Hooks
description = Module containing the CiviCRM hooks for my organization
dependencies[] = civicrm
package = CiviCRM
core = 6.x
version = 1.0
  2. Create a new file with the extension .module (for instance, myhooks.module) to hold your PHP functions.
  3. Upload both the .info and .module files to the server running CiviCRM, creating a new directory for them under /sites/all/modules (for instance, /sites/all/modules/myhooks/) inside your Drupal installation. The directory name you create should be short and contain only lowercase letters, digits, and underlines without spaces.
  4. Access the Drupal Administration page to enable your new hooks module.

Using hooks with Joomla!

Check the CiviCRM wiki for the most up-to-date information on setting up hooks with Joomla!: http://tiny.booki.cc/?hooks-in-joomla

In order to use hooks with Joomla!, you or your administrator needs to do the following:

  1. Create a file named civicrmHooks.php to contain your functions.
  2. Create a new directory anywhere on your server outside of your Joomla! / CiviCRM installation (so that upgrades will leave your hooks alone). /var/www/civicrm_hooks might be a good choice.
  3. Upload the civicrmHooks.php file to the directory you just created.
  4. Go to: CiviCRM Administer > Global Settings > Directories. Change the value of Custom PHP Path Directory to the absolute path to the new directory (e.g., "/var/www/civicrm_hooks" if you used that suggestion in the earlier step).

Refine what you want to act upon

When you create a hook, it will be called for all the types of entities. For instance, a civicrm_post is called after the creation or modification of any object of any type (contact, tag, group, activity, etc.). But usually, you want to launch an action only for a specific type of entity.

So a hook generally starts with a test on the type of entity or type of action. For instance, if you want to act only when a new individual contact is created or modified, start your civicrm_post hook with:

if ($objectName != "Individual" || $op != "edit") {
  return;
}

On the other hand, if you want to run multiple hooks within the same function, you don't want to return from any single hook. Instead, you can nest the entire code for each hook within your test:

if ($objectName == "Individual" && $op == "edit") {
  // Your hook
}

Pitfalls of hooks

Because you have little control over what CiviCRM passes to your hook function, it is very helpful to look inside those objects (especially $objectRef) to make sure you're getting what you expect. A good debugger is indispensable here. See the Developer Tips & Tricks chapter at the end of this section for more information on setting up a debugger for your development environment. 

Examples of using hooks

Some example hooks follow. Consult the hooks reference documentation on the CiviCRM wiki to see the full extent of what you can do: http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification

In all of these examples, you'll put the code we provide into your myhooks.module file if using Drupal, or the civicrmHooks.php file if using Joomla!. Be sure to upload the file after each change to the appropriate location on your server to see the new code take effect.

Additionally, if you are using Drupal and add a new hook to an existing module, you will need to clear the cache for the hook to start operating. One way of doing this is by visiting the page Admin > Build > Modules.

Sending an email message when a contact in a particular group is edited

In order to have CiviCRM tell you when a contact is edited, define the civicrm_pre hook. This lets you see the incoming edits as well as the values of the existing record, because you may want to include that information in the email.

If you are using Drupal, create a function named myhooks_civicrm_pre. If using Joomla!, create a function named joomla_civicrm_pre. We'll assume you're using Drupal for the rest of the example, so please adjust the code accordingly if you're using Joomla! instead.

<?php

function myhooks_civicrm_pre( $op, $objectName, $objectId, &$objectRef ) {
    # configuration stuff
    $theGroupId = 1; # group id we want the contacts to be in
    $emailRecipient = 'johndoe@example.org'; # person to e-mail

    # Make sure we just saved an Individual contact and that it was edited
    if ($objectName == "Individual" && $op == "edit") {

        # Now see if it's in the particular group we're interested in
        require_once 'api/v2/GroupContact.php';
        $params = array('contact_id' => $objectId);
        $groups = civicrm_group_contact_get( $params );
        $found = false;
        foreach ($groups as $group) {
            if ($group['group_id'] == $theGroupId) {
                $found = true;
            }
        }
        # Exit now if contact wasn't in the group we wanted
        if (! $found) {
            return;
        }

        # We found the contact in the group we wanted, send the e-mail
        $emailSubject = "Contact was edited";
        $emailBody = "Someone edited contactId $objectId\n";
        # Here's where you may want to iterate over the fields
        # and compare them so you can report on what has changed.
        mail( $emailRecipient, $emailSubject, $emailBody );
    }
}

Validating a new contribution against custom business rules

If you have experience with other hook-based systems, you might think that the civicrm_pre hook is the one to use for validations. But this is not the case in CiviCRM because, even though the civicrm_pre hook is called before the record is saved to the database, you cannot abort the action from this hook.

This is where validation hooks come in. When you return true from a validation hook, CiviCRM saves the new or updated record. When you return an error object instead, CiviCRM aborts the operation and reports your error to the user.

An example follows of using a validation hook to validate new contributions against a business rule that says campaign contributions must have a source associated with them. In this example, we'll assume you are using Joomla!, so if you are using Drupal instead, be sure to change the function name accordingly.

<?php

function joomla_civicrm_validate( $formName, &$fields, &$files, &$form ) {
    # configuration stuff
    $campaignContributionTypeId = 3; # adjust for your site if different

    $errors = array();

    # $formName will be set to the class name of the form that was posted
    if ($formName == 'CRM_Contribute_Form_Contribution') {
        require_once 'CRM/Utils/Array.php';
        $contributionTypeId = CRM_Utils_Array::value( 'contribution_type_id',
            $fields );
        if ($contributionTypeId == $campaignContributionTypeId) {
            # see if the source field is blank or not
            $source = CRM_Utils_Array::value( 'source', $fields );
            if (strlen( $source ) > 0) {
                # tell CiviCRM to proceed with saving the contribution
                return true;
            } else {
                # source is blank, bzzzzzzzzzzzt!
                # assign the error to a key corresponding to the field name
                $errors['source'] =
        "Source must contain the campaign identifier for campaign contributions";
                return $errors;
            }
        } else {
            # not a campaign contribution, let it through
            return true;
        }
    }
}

Automatically filling custom field values based on custom business logic

This example uses a hook to write some data back to CiviCRM. You can make a custom field read-only and then set its value from a hook. This is very handy for storing and displaying data that are derived from other attributes of a record based on custom business logic.

For example, let's say you are storing employee records and you want to auto-generate their network login account when new employees are added. By doing it in your code, you can enforce a policy for login account names. For this example, let's say the policy is first initial + last name. So if your name is Jack Frost, your network login name would be jfrost.

Add a new read-only custom field to CiviCRM called "Network Login" and then find its ID. You can find it either by:

The code must refer to the ID as custom_id. So if you find that the id of the new field is 74, refer to is as custom_74 in your code.

Now that we have our Network Login field, let's see how to populate it automatically with a hook. We'll switch back to the Drupal naming convention for this example.

Note that we use the civicrm_post hook here because we need the new contact record's ID in order to save a value to one of its custom fields. New records don't have an ID until they have been saved in the database, so if we ran this code in the civicrm_pre hook, it would fail.

<?php

function myhooks_civicrm_post( $op, $objectName, $objectId, &$objectRef ) {
    # configuration stuff
    $customId = 74;

    if ($objectName == 'Individual' && $op == 'create') {
        # generate the login
        $firstName = $objectRef->first_name;
        $lastName = $objectRef->last_name;
        $firstInitial = substr( $firstName, 0, 1 );
        $networkLogin = strtolower( $firstInitial . $lastName );

        # assign to the custom field
        $customParams = array("entityID" => $objectId,
            "custom_$customId" => $networkLogin);
        require_once 'CRM/Core/BAO/CustomValueTable.php';
        CRM_Core_BAO_CustomValueTable::setValues( $customParams );
    }
}

Custom mail merge token

The CiviMail component lets you customise a bulk email message using mail merge tokens. For instance, you can begin your message with, "Hi, {recipient.first_name}!" and when John Doe receives it, he'll see, "Hi, John!" whereas when Suzy Queue receives it, she'll see, "Hi, Suzy!" You can find out more details about working with custom tokens on the CiviCRM wiki: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data.

Besides the built-in tokens, you can use a hook to create new custom tokens. Let's make a new one that will show the largest contribution each recipient has given in the past. We'll use Drupal syntax again for this one.

<?php

# implement the tokens hook so we can add our new token to the list of tokens
# displayed to CiviMail users
function myhooks_civicrm_tokens( &$tokens ) {
    $tokens['contribution'] =
        array('contribution.largest' => 'Largest Contribution');
    /*  just array('contribution.largest'); in 3.1 or earlier */
}

# now we'll set the value of our custom token;
# it's better in general to use the API rather than SQL queries to retrieve data,
# but in this case the MAX() function makes it very efficient to get the largest
# contribution, so let's make an exception
function myhooks_civicrm_tokenValues( &$details, &$contactIDs ) {
    # prepare the contact ID(s) for use in a database query
    if ( is_array( $contactIDs ) ) {
        $contactIDString = implode( ',', array_values( $contactIDs ) );
        $single = false;
    } else {
        $contactIDString = "( $contactIDs )";
        $single = true;
    }

    # build the database query
    $query = "
      SELECT contact_id,
         max( total_amount ) as total_amount
      FROM   civicrm_contribution
      WHERE  contact_id IN ( $contactIDString )
      AND    is_test = 0
      GROUP BY contact_id
    ";

    # run the query
    $dao = CRM_Core_DAO::executeQuery( $query );
    while ( $dao->fetch( ) ) {
        if ( $single ) {
            $value =& $details;
        } else {
            if ( ! array_key_exists( $dao->contact_id, $details ) ) {
                $details[$dao->contact_id] = array( );
            }
            $value =& $details[$dao->contact_id];
        }

        # set the token's value
        $value['contribution.largest'] = $dao->total_amount;
    }
}

Importing data

The CiviCRM import system can be used to import contacts, activities, contributions, event participants, and memberships. You can extend the import system to allow it to parse different data sources, such as XML, JSON, Excel, or OpenDocument. The import system is especially useful when you have legacy data in another system (such as a spreadsheet), or have data you need to migrate from one system to another.

As of version 3.2, the import system has a few important limitations. It is currently not very good at importing:

These limitation apply to any extensions you build on the import. To overcome these limitations, one strategy would be to write a custom script using the CiviCRM API that parses the incoming data and makes the appropriate API calls to import it.

Note: If you're reading this in a printed copy, you may want to access the online version so you can copy and paste the code examples more easily. You can find the online version here: http://en.flossmanuals.net/civicrm

Data Sources

The import system supports two data sources out of the box. CSV and SQL. CSV is exported by most spreadsheets, many web sites, and a lot of legacy systems. SQL is the language of relational databases.

Here's your first insider tip on the import system: Every import is an SQL import. The CSV import data source, for example, starts out by dumping the CSV into a temporary database table and then running an SQL import on those data. If you write a custom data source, it's important to remember this because it will save you a lot of mental energy. You don't need to worry about formatting or validating the import data at all. Just get it into a database table and let CiviCRM take it from there.

When would you want to write an import data source? It might be useful if, say, a client were migrating from another CRM to CiviCRM and wanted to import their data themselves. Another example would be to support a different import file format.

To make things easy on yourself, check for an existing PHP library that can read the format of the data you want to import. If you fine one, use that library to read the data into a database table.

Data Source API

The data source API is essentially a set of functions you should implement in a new PHP class. Many software developers refer to this as an "interface" or "protocol." The abstract class that defines this interface is located in CRM/Import/DataSource.php. You should also look at the CRM/Import/DataSource/CSV.php file, because this implements the interface for the CSV import feature.

Here are the functions you will implement and what they should do:

getInfo(); # should return an array with the title of your data source plugin

preProcess( &$form ); # if you need to set anything up before the form is
displayed, this iss the place to do it

buildQuickForm( &$form ); # here you should build a form snippet that asks the user
for the appropriate information to access the incoming data

postProcess( &$params, &$db ); # this is where you dump the incoming data into the
database table

After defining your import data source, you need a new Smarty template to create your form snippet. This is pretty specific to the type of import data source you're defining. Let's look at an example of a real custom data source.

Example Data Source

This example of a custom import data source reads a JSON file and imports its contents as new contacts. This file should be named JSON.php and be added to the CRM/Import/DataSource/ directory.

<?php

/* My awesome JSON importer of dubious utility and efficiency (but still awesome!)
 *
 * JSON should look like this:
 * {
 *   "contacts" : [
 *      {
 *        "first_name" : "Foo",
 *        "last_name" : "Bar",
 *        "other_field" : "baz"
 *      },
 *      {
 *        "first_name" : "Other",
 *        "last_name" : "Contact",
 *        "something_else" : "yep"
 *      }
 *   ]
 * }
 */

require_once 'CRM/Import/DataSource.php';

class CRM_Import_DataSource_JSON extends CRM_Import_DataSource
{
    function getInfo()
    {
        return array('title' => ts('JavaScript Object Notation (JSON)'));
    }

    function preProcess(&$form)
    {
        # nothing to do here, but we still define the function
    }

    function buildQuickForm(&$form)
    {
        ### In this function we're calling a lot of QuickForm functions.
        ### If you're unfamiliar with that library, it might be good
        ### to look up the documentation for it.

        # define a hidden field that tells the system which
        # data source class we're using
        $form->add( 'hidden', 'hidden_dataSource', 'CRM_Import_DataSource_JSON' );

        # grab the config object so we respect some system settings
        $config = CRM_Core_Config::singleton();

        # get the max upload file size from the config
        $uploadFileSize = $config->maxImportFileSize;
        $uploadSize = round( ( $uploadFileSize / (1024*1024) ), 2 );

        # assign the max upload file size to a template variable
        # see the template documentation for more info on this
        $form->assign( 'uploadSize', $uploadSize );

        # add the file selection field to the form
        $form->add( 'file', 'uploadFile', ts('Import Data File'),
            'size=30 maxlength=60', true );

        # now set the max file size so the form enforces it
        $form->setMaxFileSize($uploadFileSize);
        $form->addRule( 'uploadFile',
            ts('File size should be less than %1 MBytes (%2 bytes)',
            array(1 => $uploadSize, 2 => $uploadFileSize)),
            'maxfilesize', $uploadFileSize );

        # not a very smart rule, but it'll do for now
        $form->addRule( 'uploadFile', ts('Input file must be in JSON format'),
            'utf8File' );

        # make sure we end up with a file after the form posts
        $form->addRule( 'uploadFile', ts('A valid file must be uploaded.'),
            'uploadedfile' );
    }

    function postProcess(&$params, &$db)
    {
        # grab the name of the file that was uploaded
        $file = $params['uploadFile']['name'];

        # call a helper function we'll define below to parse the JSON
        $result = self::_JsonToTable( $db, $file,
            CRM_Utils_Array::value( 'import_table_name', $params ) );

        # grab the import table name (CiviCRM determines this for us)
        $table = $result['import_table_name'];

        # create a new ImportJob object for our table
        require_once 'CRM/Import/ImportJob.php';
        $importJob = new CRM_Import_ImportJob( $table );

        # the ImportJob modifies the table name a bit, so let's update it
        $this->set( 'importTableName', $importJob->getTableName() );
    }

    /**
     * We define this function just to keep things cleaner, the import data source
     * interface doesn't look for it; it's a private function. We use an
     * underscore at the beginning of the name to indicate this.
     */
    private static function _JsonToTable(&$db, $file, $table )
    {
        # read the JSON into a string variable
        $jsonString = file_get_contents($file);
        if (!$jsonString) {
            # oops, reading the file didn't work, generate an error
            CRM_Core_Error::fatal("Could not read $file");
        }

        # grab the config object again
        $config = CRM_Core_Config::singleton();

        # this is a bit presumptuous of us, but oh well
        $db->query("DROP TABLE IF EXISTS $table");

        # create the table where we'll store the incoming data
        $create = "CREATE TABLE $table LIKE civicrm_contact";
        $db->query($create);
        # drop the id column because the import system will add one
        $dropId = "ALTER TABLE $table DROP COLUMN id";
        $db->query($dropId);

        # decode the JSON and INSERT the records one by one;
        # it might be more efficient to build one big multi-insert,
        # but we'll leave that as an exercise for the reader

        ### BE CAREFUL THAT YOU DON'T RUN THIS ON A MASSIVE JSON FILE!!
        ### It creates one big object from the entire JSON file, so you'll quickly
        ### eat up every bit of memory PHP can use if you try to import a large
        ### file.

        # this requires that the JSON PECL extension is installed and
        # enabled in PHP
        $importObj = json_decode( $jsonString, true );

        # loop through each record in the JSON object, put it into an SQL query,
        # and insert it into the database
        foreach ($importObj['contacts'] as $newContact) {
            $fields = array_map( '_civicrm_mysql_real_escape_string',
                array_keys( $newContact ) );
            $sqlFields = "(" . implode( ',', $fields ) . ")";
            $values = array_map( '_civicrm_mysql_real_escape_and_quote_string',
                $newContact );
            $sqlValues = "VALUES (" . implode( ',', $values ) . ")";

            # construct the query and run it
            $sql = "INSERT IGNORE INTO $table $sqlFields $sqlValues";
            $db->query($sql);
        }

        # get the import tmp table name and return it
        $result = array( );
        $result['import_table_name'] = $table;
        return $result;
    }
}

# Another couple private helper functions we define
function _civicrm_mysql_real_escape_and_quote_string( $string ) {
    return _civicrm_mysql_real_escape_string( $string, true );
}

function _civicrm_mysql_real_escape_string( $string, $quote = false ) {
    static $dao = null;
    if ( ! $dao ) {
        $dao = new CRM_Core_DAO( );
    }
    $returnString = $quote ? "\"{$dao->escape( $string )}\"" :
        $dao->escape( $string );
    return $returnString;
}

And here's the Smarty template. It should be saved in templates/CRM/Import/Form/JSON.tpl.

<fieldset><legend>{ts}Upload JSON File{/ts}</legend>
  <table class="form-layout">
    <tr>
        <td class="label">{$form.uploadFile.label}</td>
        <td>{$form.uploadFile.html}<br />
            <div class="description">{ts}File format must be JavaScript
              Object Notation (JSON). File must be UTF8 encoded if it contains
              special characters (e.g. accented letters, etc.).{/ts}</div>
            {ts 1=$uploadSize}Maximum Upload File Size: %1 MB{/ts}
        </td>
    </tr>
  </table>
</fieldset>

Summary

The CiviCRM Import system has a few limitations, but it is by far the easiest way for end users to get data from other systems into CiviCRM. When a client has ongoing data import needs and wants non-technical users to initiate and manage the imports, writing a custom data source may be a good solution.

If the import system cannot handle the type or amount of data you need to import, your options are to write a separate import program that calls the CiviCRM API, write your own improvements to the import system, or sponsor other developers to write improvements. If you write or sponsor improvements to the import system, make sure you contribute them back to the core system! The CiviCRM development team would be happy to discuss potential improvements with you. You can find them in the #civicrm IRC channel on irc.freenode.net.

Tips and Tricks

There are a few practices that seasoned CiviCRM developers have found very helpful when working on CiviCRM projects. This chapter contains a few of them, as well as some guidance on how to make use of them yourself. You don't have to use any of these tips, but they have made many other developers' lives easier, so give them a try and see if you agree.

Run a Local Development Instance of CiviCRM

When hacking on CiviCRM customizations and extensions, you don't want to interrupt your users' work or corrupt the data in the CiviCRM database. That's why you should never, ever hack on the same instance of CiviCRM that other people are using to store and work with live data. That's a recipe for disaster. Instead, load CiviCRM and its associated programs onto your own development "sandbox," where you can do whatever you want to CiviCRM without disturbing anyone else.

If your computer runs Linux or Mac OS X, running CiviCRM on your local machine is pretty easy. If your computer runs Windows, you have a little more work to do, but it's not impossible. You should seriously consider running Linux inside a virtual machine (there's a free program called VirtualBox that makes this pretty easy). We recommend running the latest version of Ubuntu Linux inside the virtual machine. You can download that here: http://www.ubuntu.com/

Preparing your machine to run CiviCRM

These instructions will tell you how to prepare your system to run CiviCRM. Jump to the section that matches your operating system.

Debian / Ubuntu Linux

sudo apt-get install apache2 php5 libapache2-mod-php5 mysql-server \
libmysqlclient15-dev php5-mysql php-db

Red Hat / CentOS Linux

sudo yum install php-xml

Mac OS X

Mac OS X does not have a built-in package manager like most Linux distributions do, but there are some third-party ones you can install. MacPorts is a good choice. The installation instructions can be found here: http://www.macports.org/install.php

Once MacPorts is installed, open up Terminal (in Applications -> Utilities) and run this command (quit Terminal first and re-launch it if you already had it running):

sudo port install apache2 mysql5-server php52 +pear +mysql5

Be sure to read the output of that command carefully, because there are often further tasks you need to perform to enable some of the packages (especially PHP and MySQL).

Next Step for All Operating Systems

Follow the CiviCRM installation instructions already provided in the documentation. You can find these instructions here: http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

Use XDebug

This is our main recommendation for developers. Readers familiar with what a debugger is and how it works should feel free to skip ahead to the "Setting Up XDebug" section.

What is a debugger?

A debugger is a software program that watches your code while it executes and allows you to inspect, interrupt, and step through the code. That means you can stop the execution right before a critical juncture (for example, where something is crashing or producing bad data) and look at the values of all the variables and objects to make sure they are what you expect them to be. You can then step through the execution one line at a time and see exactly where and why things break down. It's no exaggeration to say that a debugger is a developer's best friend. It will save you countless hours of beating your head against your desk while you insert print statements everywhere to track down an elusive bug.

Debugging in PHP is a bit tricky because your code is actually running inside the PHP interpreter, which is itself (usually) running inside a web server. This web server may or may not be on the same machine where you're writing your code. If you're running your CiviCRM development instance on a separate server, you need a debugger that can communicate with you over the network. Luckily such a clever creature already exists: XDebug.

Setting Up XDebug

XDebug isn't the only PHP debugger, but it's the one we recommend for CiviCRM debugging.

The instructions for downloading and installing XDebug are here: http://xdebug.org/docs/install

Those instructions are a bit complex, however. There is a far simpler way to install it if you happen to be running one of the operating systems listed here.

Debian / Ubuntu Linux

sudo apt-get install php5-xdebug

Red Hat / CentOS Linux

sudo yum install php-pecl* php-devel php-pear

sudo pecl install Xdebug

Mac OS X

sudo port install php5-xdebug

Next Step for All Operating Systems

Tell XDebug to start automatically (don't do this on a production server!) by adding the following two lines to your php.ini file:

xdebug.remote_enable = On
xdebug.remote_autostart = 1

Once XDebug is installed and enabled in your PHP configuration, you'll need to restart your web server.

Installing an XDebug Front-End

After you have XDebug running on your PHP web server, you need to install a front-end to actually see what it is telling you about your code. There are a few different options available depending on what operating system you use:

All Operating Systems

NetBeans is a heavyweight Java IDE (Integrated Development Environment). It offers lots of features, but isn't exactly small or fast. However, it is very good at interactive debugging with XDebug. And since it's written in  Java, it should run on any operating system you want to run it on. You can find it at http://www.netbeans.org/

After installing NetBeans, open your local CiviCRM installation in NetBeans and click the Debug button on the toolbar. It will fire up your web browser and start the debugger on CiviCRM. You may went to set a breakpoint in CRM/Core/Invoke.php to make the debugger pause there. For more information, see the NetBeans debugging documentation.

Mac OS X

A much lighter-weight option for Mac users is a program called MacGDBp. You can download it here: http://www.bluestatic.org/software/macgdbp/

After installing MacGDBp, launch it and make sure it says "Connecting" at the bottom in the status bar. If it doesn't, click the green "On" button in the upper-right corner to enable it. The next time you access CiviCRM, the web browser will appear to hang. If you click on MacGDBp, you'll see that it has stopped on the first line of code in CiviCRM. From there you can step through the code to the part you're interested in. But it's probably a better idea to set a breakpoint in the part of the code you're interested in stopping at. See the MacGDBp documentation for more information.

Debugging Tips

Note that to use these tips this you need to enable your Debugging in CiviCRM.

Log emails to a file

For this you need to modify your CiviCRM settings (http://civicrm.settings.php) and add following line:

define('CIVICRM_MAIL_LOG', '<path to of the file >/mail.log');

Check the queries fired by Dataobject

define( 'CIVICRM_DAO_DEBUG', 1 );

Foreign constraint errors

If you are getting foreign key constraint errors, try logging out from CiviCRM and logging in again.

How to find the template file

Finding which template is used on a given page can be difficult. The easiest way is to view the source of the page from a web browser and search for ".tpl". For instance, for the contact summary page, use the web browser to access the contact summary page, then click "View Source" in the browser.  You should find an HTML comment such as:

<!-- .tpl file invoked: CRM/Contact/Page/View/Summary.tpl. Call via form.tpl 
    if we have a form in the page. -->

Use a source code management system

The source code of CiviCRM is accessible via Subversion. Although installing Subversion on your own computer is a bit complex, it is worthwhile using source control for your development website.

You should also use a local source code manager (git or mercurial are good solutions) to keep track of your modified files. The workflow that has been proven most efficient is to copy the original file, add it to your repository and then modify it.

The CiviCRM Community

Like many open source projects, CiviCRM is shaped, guided, and driven by its community, a far-flung ecosystem of users, developers, and implementers who utilize CiviCRM in many different ways and bring to it a wide array of skills, experiences, and perspectives. These varied and diverse offerings are crucial to the continued success of CiviCRM, but they can move the project forward only if they find their way back into the public stream of discussion and collaboration. This chapter is a guide to finding and engaging in the community of people who are working together to make CiviCRM what it is and what it will become.

Finding the Community Online

As might be expected of a web-based software project, much of the CiviCRM community's activity occurs online. This means that if you have access to the Internet you also have access to and can participate in the CiviCRM community regardless of where you live or work. English is the predominant language for discussion and contributions.

The CiviCRM website itself (http://civicrm.org) is a good starting point for exploring and participating in the community. In addition to general information about getting and using CiviCRM, you'll find blog posts from community members, announcements about upcoming events, and a Participate section (http://civicrm.org/participate) that lists and links to many of the resources described below.

The CiviCRM Forums (http://forum.civicrm.org) are a central location for CiviCRM discussion and support. The forums are divided into topical boards for:

Registration for the forums is completely free and most of the boards are very active with frequent new posts and responses.

Another great source of support and discussion is Internet Relay Chat (IRC). The #civicrm IRC channel is hosted by Freenode at  irc.freenode.net.  You can access the channel using an IRC client (a program that you run on your computer) or through the web interface at http://webchat.freenode.net. Enter #civicrm in the Channels field and a nickname of your choosing in the Nickname field. For more information on using IRC, check out the IRC section of the Drupal website (http://drupal.org/irc). Although the information is targeted to the Drupal community it can also be useful for CiviCRM users, especially because the Drupal IRC channels are also hosted on Freenode.

You'll hopefully find that both the forums and the IRC channel are great sources for help, support, and good ideas. That's all attributable to the good will and generous efforts of people like you! Everyone who visits the forums and the channel is encouraged to give back to the community by responding to questions and requests for help and contributing their own ideas and feedback to the conversations. And simply asking your own questions is also a significant contribution to the community. It's likely that someone else is having the same problems or wondering the same thing, and the responses you solicit help build the community's knowledge base.

The CiviCRM blog (http://civicrm.org/blog) is another good source of information and discussion. Blog posts are written by both the CiviCRM core team and other community members and cover a wide range of topics, including general news and announcements, upcoming events and accounts of events that have occurred, case studies, use cases and ways to get things done with CiviCRM, and new features and development. Comments are encouraged and can create lively discussions that can in turn direct future CiviCRM development. If you've got something that you'd like to post on the blog, we encourage you to write to info@civicrm.org  with your ideas and your request to post.

Much discussion of CiviCRM also occurs outside of these official channels. Using your favorite engine to search for CiviCRM will turn up many articles and posts from other folks' websites and blogs. The CiviCRM team is good at keeping an eye out for these posts and often publicize them through Twitter. To keep abreast of the stream of comments, follow @civicrm and find CiviCRM tweets and tag your own tweets with the #civicrm hashtag.

Hooking In Offline

Though the online community is both accessible and active, participating in the CiviCRM community offline can be even more rewarding and can help you connect with others in your area who are developing, implementing, and using CiviCRM.

Many cities and regions hold CiviCRM meetups where people gather to learn about CiviCRM, share new ideas, developments, and use cases, and meet other folks involved with the community. You can find out more about meetups at http://civicrm.org. Some meetup and local user groups (or LUGs) also maintain discussion boards at http://civicrm.org/groups. Contact the CiviCRM crew if you'd like a discussion board for your own group on the site.

CiviCRM recently held the first CiviCon conference in April 2010 in San Francisco. More are being planned, including one in Chicago in 2011. CiviCRM core developers and community members also make appearances at other conferences, including DrupalCon, the NonProfit Technology Conference, Joomla! events, and Aspiration Tech events.

CiviCRM also conducts user and developer training in cities around the globe. Check out http://civicrm.org for info about upcoming trainings and contact CiviCRM if you'd like to host trainings in your own area.

Open Source = Community Sourced

Here are some additional ways that you can participate in and contribute to the CiviCRM community.

Internationalisation

CiviCRM is written with English-language code and strings for display. It has, however, also been built for organisations worldwide. They need to be able to adapt the tool to local circumstances and demands without modifying the tool technically.

Localising CiviCRM (or any software) affects much more than you might initially think. To adapt CiviCRM to a local language is not just a matter of translating the text displayed on the screen. Consider for example the currency used in a given country (USD or $ in United States, GBP or £ in Great Britain), date and time formats (for example: November 16th, 2009 will be commonly written as 11/16/2009 in United States, but in Russia the format will be 16.11.2009) or the formatting of numbers (the same number will be written slightly differently in different countries: 1 234 567,89 in Slovakia or Hungary, but 1,234,567.89 in Japan or the United States).

CiviCRM provides plenty of functionality to support these language and region specific needs. The development team is constantly developing new tools in this area too.  The Localization screen (shown in the following screenshot) lets an administrator select the right locale for the language and country of the organization using CiviCRM. Go to: Administer > Configure > Global Settings > Localization.

2 

Translations

CiviCRM accommodates different languages, however the developers rely on the community to translate the text displayed.

A number of languages have already been provided to a greater or lesser extent. Some have more than 90% of the text translated, others only 5%, and a number of languages have not been translated at all. Please check the online translation tool Transifex (http://www.transifex.net/projects/p/civicrm/) to find out about your language of interest. Download and install it on your CiviCRM installation to find out how well it will suit your needs.

You may find that although the translation is correct, you would want to use different terms in your situation. You are very much encouraged to take part in the translation of your language.

Facilities

A number of facilities in CiviCRM support the community in its translation efforts, though some are still under development.

  1. Transifex is an online tool that enables groups of translators to translate strings of text and keep an overview on its progress. Register there, look for your language, join the team or, if your language is not available, start translating.
  2. A glossary (http://wiki.civicrm.org/confluence/display/CRM/Glossary+for+translations) on CiviCRM's wiki will help you maintain consistency in your translations. It will also help you get some insight on how much work it will be to translate those strings of text that your users will most often see and that would therefore be the first to translate.
  3. A tips and tricks wiki page (http://wiki.civicrm.org/confluence/display/CRM/Localisation+community+building+howto) explains how to set up your localization community.
  4. A FAQ (http://wiki.civicrm.org/confluence/display/CRM/Getting+started+with+CiviCRM+Localisation+FAQ) on the CiviCRM wiki covers localisation.

Getting Started

Feel like helping translating CiviCRM to a new language or improving the current translation? Here's how to do it (provided you have a bit of a technical background):

  1. Go to transifex.net and create an account.
  2. Look for your language on http://www.transifex.net/projects/p/civicrm/teams/ and either join a team, or request the creation of a new one if needed.
  3. Start translating!

Team work

The CiviCRM translation work flow is still a work-in-progress and until the process becomes more mature, you should probably refer to http://wiki.civicrm.org/confluence/display/CRM/Localisation+community+building+howto  for the most current instructions.

The work flow is heavily based on teamwork. Hopefully, there is already a team of translators for your language that you can join. This team will have built a glossary, will have started a translation set and will be able to review your translations and give constructive criticism.  If such a team does not yet exist, the opportunity is all yours to create one.

Components and files

There are quite a lot of strings (phrases) to translate in CiviCRM. To make it easier to translate the part that you are interested in (hopefully the one you know best), the strings that need translation have been divided into components, which are CiviCRM plugins (e.g., CiviCRM core, CiviMail, CiviContribute, etc.). A separate component should be available for each version of CiviCRM, starting with version 3.2 (or 3.1, for language teams that have chosen to do so).

Each component itself contains a number of files, which themselves contain the strings to translate. The main component "CiviCRM" (the core) has close to 20 files (for countries, provinces, menu, etc.).

Tools and technical details

The process you use to do translation depends on whether you prefer to do translation online or offline. Online translation does not require installation of any software. Offline translation is done with files downloaded from the translation website, using software that offers more features than the online system.

Online translation

Transifex is the tool to use for online translation. It does not have as many features as an offline tool such as PoEdit, but it's the easiest way to contribute translations and do the occasional quick correction. Every translator should have an account on the Transifex site, because translation teams can use the forums and messaging system to coordinate their work.

The basic steps in online translation are:

  1. Select a component on http://www.transifex.net/projects/p/civicrm/. This will display the list of language teams for this component.
  2. Click on the icon in the Options column next to the language you are interested in. This brings you to the list of files for this component.
  3. Click on the "pencil and paper" icon. This brings you to the online translation screen, which lists all the translatable strings in this file.
  4. For each string, you can then enter a translation.
  5. When you are finished, you can click on the "Send for review" button at the end of the page.

Offline translation

Most translation is usually done with an offline translation tool. One of the most common is PoEdit (see http://www.poedit.net), which is free software and has a big community of users. The exact steps in translation using an offline tool depend on your tool of choice, but should follow the following steps:

  1. Download the files from transifex.net you want to translate,
  2. Load the files up in your translation tool and do your translations.
  3. Send them back to the site when you are done.

Building a translation memory

PoEdit and other translation software will help you build a translation memory for your language. This translation memory can either be restricted to translations done in CiviCRM, or include translations from other projects. If you include other projects, automatic translation might be able to translate more strings, but you will lose consistency and most strings will be marked as fuzzy. This could be a way to bootstrap a new translation, though.

Building a translation memory based on words from the glossary could go a long way in insuring the consistency of your team's work.

Using version control (mostly for programmers)

Transifex keeps files in a version control system, http://github.com/civicrm/l10n. This is useful to some users who find interacting with the Github site easier than downloading each file separately from Transifex.

Consistency & consensus

To insure a good consistency in the translation, every team is encouraged to build and use a glossary and employ peer review. You can find a glossary of common terms on http://wiki.civicrm.org/confluence/display/CRM/Glossary+for+translations. You definitely should translate these terms to your language, and make sure your team reaches a consensus on all terms.

Building and sharing a common translation memory, which is like a specialized glossary that can be used automatically by translation tools,  also helps to insure consistency. The PoEdit help system explains how to build this database (and most other translation software should do the same).

Team building and sprints

A good way to make progress in translation is to organize translation sprints. This means getting as many people as possible together in the same room to translate as many documents as they can. Here are a few things to keep in mind when organizing a translation sprint:

Bug Reporting

There will be times when you use CiviCRM - as there are when you use any software - when things don't work the way you expect them to.

When this happens, a good first step is to search the forums for similar problems and follow advice given there.  If your problem hasn't been addressed, posting to the forum is probably the right thing to do.

Have a look on the forum for good posting guidelines and spend a bit of time writing your post. Make sure you are detailed and specific about what software you are using, what you are trying to do and how you are trying to do it. For example letting people know the url you are using (with any confidential details removed) may cause them to realise that you are configuring the wrong page. Unclear posts are less likely to get good replies.

What causes problems with CiviCRM?

Check the following possible sources of problems before you report something on a forum. You can save yourself and a lot of people trouble by isolating the problem. CiviCRM forums try to be friendly and don't criticise you for misjudging a problem, but you'll certainly get more help and resolve problems faster by doing some checking of your own first.

Recreating your problem on the demo site

Recreating your bug on one of the demo sites helps determine whether your problem is a result of a bug in the source code, or as a result of changes on your site, such as your server setup or any customisations you've made to the code. If you can show us that the code on the demo site turns up your bug, it's very likely that the CiviCRM source code is the problem, and your demonstration will help us find and fix it.

Still, no demo site can cover all possibilities. So even if you can't reproduce your bug there, it might still be a bug in CiviCRM. It is, however, probably triggered by your server setup or other customisations.

Write to the forum and explain the problem you are experiencing. If the bug was reproduced on the demo site, describe exactly what you did there. If not, include as much information about your server setup as you feasibly can. Configuration files from the web server, CMS, and CiviCRM will be valuable.

If the forum suggests you discovered a bug in CiviCRM, you can report it to the CiviCRM bug tracker (http://issues.civicrm.org/jira/browse/CRM).

Using older versions of CiviCRM

If you are using an older version and the problem you are experiencing is a bug that has been fixed in the lastest release, be prepared for the answer that it is time to upgrade to the latest version. Although the CiviCRM community tries to be as helpful as possible, and we recognize that upgrading puts a burden on your organisation, it is difficult to support multiple versions simultaneously.

Fixing bugs

The amount of time taken for the bug to be fixed depends on the severity and complexity of the bug.  It could be as quick as the same day, but it could take much longer.

To get bug fixes, the easiest way is just to download and install the latest revision of CiviCRM. Downloading bug fixes between releases and fixing ('patching') your existing software is possible, but it's a more involved process and depends on your technical ability and server setup.

Contributing to this manual

If you would like to contribute to this book, please follow these steps:

1. Register

Register at FLOSS Manuals:
 http://en.flossmanuals.net/register

2. Write

Select the manual http://en.flossmanuals.net/bin/view/CiviCRM/WebHome  and a chapter to work on.

Make sure you are logged in, choose the WRITE version of the web site (the default is only READ) and click the "edit" link next to the chapter you want to work on. You can also create new chapters and put chapters in a different order.

If you need to ask us questions about how to contribute, join the chat room listed in the next step and ask us! We look forward to your contribution.

For more information on using FLOSS Manuals you may also wish to read our manual:
http://en.flossmanuals.net/FLOSSManuals

To help give our manual some continuity, we've come up with some agreed-upon writing conventions.  You should probably read this before contributing, but don't worry so much about the conventions that it hampers your writing.

3. Chat

It's a good idea to talk with us so we can help co-ordinate all contributions. We have a chat room embedded in the FLOSS Manuals website so you can use it in the browser.

If you know how to use IRC you can connect to the following:
server: irc.freenode.net
channel: #booksprint

4. Mailing List

For discussing all things about FLOSS Manuals, join our mailing list:
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

History of this book

This book is the result of the collaborative effort of many people.  A lot of the content was written during two book sprints held in 2009 and 2010 in Tahoe, USA. Many contributions have also been made by individuals in the times between these sprints.

Third edition

This edition includes minor updates to reflect changes in CiviCRM 3.3 which was released in December 2010. It is being published on the eve of the second annual CiviCon conference. Thanks to the generous contributions of our CiviCon Sponsors (listed in the front of the book) - a copy has been provided to each conference participant.

Second edition

The second edition of the CiviCRM manual was published after a four-day Book Sprint organised by CiviCRM and led by FLOSS Manuals. The sprint was sponsored by the Information Program initiative of the Open Society Institute (http://www.soros.org/initiatives/information). We are especially grateful to Janet Haven for pushing this forward.

The second edition includes new sections on CiviReports, CiviCase, CiviEngage and Extending CiviCRM.  This edition also included an extensive rewrite of nearly every section of the text, including a reorganization of all sections to break up information into Introduction, Planning, Configuration and Everday Tasks sections, the latter to serve as an easy-to-follow user manual for individuals working with CiviCRM on a daily basis.

We also added an entire new section to assist developers get into the code. Finally, we updated the book to match CiviCRM 3.2 (which is a few weeks away from release at the time of writing).

We think that the reorganisation adds a lot to the book and increases it's readability because it helps people who with CiviCRM in a specific capacity get directly to the chapter relevant to them.

The following photo shows the people who worked on this second edition of the book.

civi_team

In the back row, starting from the left, you are looking at Dave Greenberg (San Francisco, USA), Kyle Jaster (NY, USA), Xavier Dutoit (Geneva, Switzerland and Brussels, Belgium), Kurund Jalmi (Mumbai, India), Michael McAndrew (London, UK), Wes Morgan (Washington DC, USA) , Josue Guillen (DC, USA). The front row from the left is Jack Aponte (NY, USA), Mari Tilos (San Francisco, USA), Sarah Gladstone (Chicago, USA), and Alice Aguilar (NY, USA).

First edition

The first edition of manual was written during a five-day book sprint also organised by CiviCRM and led by FLOSS Manuals. The sprint was also sponsored by the Information Program initiative of the Open Society Institute (http://www.soros.org/initiatives/information), and again, we are especially grateful to Janet Haven for pushing this forward.

Having secured sponsorship, the CiviCRM Core team invited a group of people from around the globe to gather for a week at Lake Tahoe in California. The modest goal was to transform our diverse experience of CiviCRM into a manual that we hope will help people to use this great piece of software. This turned out to be an interesting, and at times difficult, challenge.

The following photo shows the people who wrote this book.

team

In the back row you are looking at Michael McAndrew (London, UK), Tony Guzman (Salt Lake City, USA), Brian Shaughnessy (Albany, NY, USA), Dave Greenberg (San Francisco, USA), Yashodha Chaku (Mumbai, India) and Adam Hyde (Berlin, Germany). In the front row are Mari Tilos (San Francisco, USA), Cynthia Tarascio (Philadelphia, USA), Michal Mach (Warsaw, Poland) and Peter Davis (Wellington, New Zealand). In the very front is Eileen McNaughton (Wellington, New Zealand).

We came from different backgrounds, had used CiviCRM in different ways, and had worked with very different organisations. It was often a challenge to meld these perspectives into a cohesive whole, but we hammered away at it and we think this made for a better book. We had some lively discussions about important issues, such as whether there is a "z" or an "s" in organis/zation or a "q" in check/que, and finally agreed to use both spellings in the spirit of internationalism. We also struggled with the word "constituent", which is core to the non-profit sector in America but was unfamiliar to those of us from outside America.

It was been a pretty intense five days. Adam (our friendly Floss manuals taskmaster) kept us realistic, on track, and hard at work - even hauling us back to work after dinner each evening. Overall it was both fun and productive and we really appreciate the way Adam has helped us to actually produce a book within a week. Thank you.

For most of us, however, the highlight of the week has been the breathtaking cuisine cooked by Jill Klein (http://www.partiesthatcook.com/about-us/). We love you, Jill, and wish we could take you home with us. We are also grateful to Dave Greenberg, Bob Concannon and Mari Tilos for their hospitality, and to Scout the dog just for being there.

scout

We had help from around the world during the preparation process, and over the course of the Sprint. Andy Oram helped us both in the planning process and then with editing and feedback during the Sprint. We also had a number of people log in to write and edit the manual during the Sprint. They include Robert Santiago, Xavier Dutoit, Joe Murray, Sarmeesha Reddy, Jay Maechtlen, Dream Gomez, Leila Johnson, Duncan Hutty, and Kurund Jalmi.

pteam

Our office for the week was Dave and Bob's house.

civi1

 We mitigated the hardship of late-night work with some tasty beverages.

log

 And occasionally they let us out for a bit....

Free Software?

CiviCRM is Free Software - this means it is developed by a community and licensed in a generous way so you can use it for free for whatever you want.

Free Software (sometimes also referred to as Free and Open Source Software,  FLOSS, FOSS, Software Libre,  or Open Source) is software that anyone can download, share, and -- significantly -- change in any way they want. Practically speaking, you might never want to change the software, or even have a staff person who can read the source code (the instructions written by programmers). But the ability to change the software protects you in many ways:

That may be enough for you, but for the sake of completeness we'll offer some widely used definitions:

"Free software or software libre is software that can be used, studied, and modified without restriction, and which can be copied and redistributed in modified or unmodified form either without restriction, or with minimal restrictions only to ensure that further recipients can also do these things and that manufacturers of consumer-facing hardware allow user modifications to their hardware. Free software is available gratis (free of charge) in most cases."
(from: http://en.wikipedia.org/wiki/Free_software)

"Open source software (OSS) is defined as computer software for which the source code and certain other rights normally reserved for copyright holders are provided under a software license that meets the Open Source Definition or that is in the public domain. This permits users to use, change, and improve the software, and to redistribute it in modified or unmodified forms. It is very often developed in a public, collaborative manner."
(from: http://en.wikipedia.org/wiki/Open_source_software)

Nearly any software that qualifies as free also qualifies as Open Source, and vice versa. The main reason that two different terms exist is that "free software" emphasizes the freedom aspect (that you aren't under the control of the original programmers) whereas "open source software" emphasizes the convenience and potential for innovation provided by having the source code available.

When you install and use CiviCRM, you'll notice there's no annoying click-through software license imposing a thousand things that you can or cannot do with it. That's because free software doesn't limit your right to do with the software whatever you want. Free and open source software have licenses, but they're simpler than and quite different from proprietary software ('closed software') licenses. CiviCRM itself is available under Affero General Public License version 3.0, one of the popular free software licenses used by many other projects.

Free Software and non-profits

Explaining all of the possible considerations on using FOSS in non-profit and advocacy work might take a really long time, so let's focus on the most important highlights:

Apart from the quite practical advantages listed above, there is also a more philosophical approach to answering the question of importance of FOSS for non-profits and advocacy organisations. Without getting too deep into philosophical discussions, there is a great overlap between values shared by non-profit organisations and these shared by Free and Open Source Software communities. By working with the community of users, providing your feedback, contributing your changes back into the project, you're actually strengthening the non-profit sector.

Further Reading

Free Software Foundation
http://www.fsf.org/

The Free Software Definition
http://www.gnu.org/philosophy/free-sw.html

Open Source Initiative
http://www.opensource.org/

The Open Source Definition
http://www.opensource.org/docs/osd

GNU Affero General Public License v3
http://www.opensource.org/licenses/agpl-v3.html

Choosing and Using Free and Open Source Software: A primer for nonprofits
http://www.nosi.net/projects/primer

Glossary

Accidental Techie

Someone who has inherited the role of IT technical support but whose primary role maybe something else; often has little or no formal IT training (which is not always a bad thing!).

Accordion

A javascript-based effect on a web page that allows additional content to be revealed or hidden (often referred to as collapsed or uncollapsed) without the user leaving the web page.

ACL (Access Control List)

ACLs define permissions for a group of contacts to perform an operation (e.g. edit, view, delete) on a set of data or a type of record. For example, you could set up a group called "Administrators" that allows people to view and edit all contact records, and a group called "Volunteers" that can view contact records but not edit them.

Activities

An activity in CiviCRM is a record of any scheduled or completed interaction with one or more contacts. Examples include meetings, phone calls, emails, event attendances and contributions. You can define additional types of activities as needed.

Admin / Administrator

The person or persons that maintain a server or a web-based software like CiviCRM. Administration includes maintenance, configuration, backup, security, creating and deleting user accounts and so on.

AGM (Annual General Meeting)

An AGM is a meeting held every year by an organisation to inform its members of previous and future activities. Certain types of organisations are required by law to hold an AGM.

AGPL (Affero General Public License)

A license for open source software. CiviCRM uses the AGPL version 3.0 license, which gives you the right to do with the software as you like and guarantees that the source code will always protect your rights in this way.

Alpha Version

A software version that contains very new source code with new functionality and bug fixes. An alpha version is released for testing purposes, and for people who want to follow its development, but it is not considered to be any where near ready for general release or use.

Apache

The most popular web server software. Apache is free and open source (see also FLOSS).

API (Application Programming Interface)

An interface employed by a software application to enable interaction between itself and other software.

Backup

Protecting your data by regularly making copies and storing them independently of the original files so they can be restored if necessary.

Bandwidth

The speed at which you can transfer information through a network or internet connection. If a connection can transfer a lot of information it is said to be "high bandwidth".

Beta Version

A software version that is in good condition but still needs testing to make sure it functions as intended before general release. Testing beta versions is a helpful way to participate in the CiviCRM community.

Blog

Short for web-log. A website which is regularly updated with news and views from one or more individuals.

Bug

An error that prevents software from behaving as the user would expect.

Bug Reporting / Bug Fixing

The process of reporting bugs to the software developer(s), and then fixing the bugs so the software operates as intended.

Bug Tracker

An official repository for recording bugs. The CiviCRM bug tracker can be found here: http://issues.civicrm.org/ (click on Issue Tracker).

Cache

A recent copy of frequently used data that can be quickly and easily accessed. This is especially useful if the data is complicated or takes a large effort to generate. The disadvantage of caching is that data can become out of date, but this normally isn't a problem. Even caching data for 5 minutes might be useful in certain circumstances. If a page is accessed 1,000 times in 5 minutes, having a cached version means the data will only need to be generated once.

A web cache holds copies of recently visited web page files. Sometimes a user may need to clear their web cache in order to see updated information on a web page.

Captcha

A spam prevention tool. See reCaptcha.

CiviCase

The case management component of CiviCRM. CiviCase provides service organisations with tools for structuring, scheduling and recording case activities.  

CiviContribute

CiviContribute is an online fundraising and donor management component which enables you to track and manage contributions to your organisation. 

CiviCRM

What this whole manual is about! CiviCRM is web-based, open source software that allows you to record and manage information about your various constituents including volunteers, activists, donors, employees, clients, vendors, etc.

CiviDog

See Scout.

CiviEvent

CiviEvent provides integrated online event registration and management for paid and free events.

CiviMail

CiviMail is a mass-mailing component which allows you to engage constituents with personalised email blasts and newsletters.

Client

A term used sometimes instead of constituent or contact, more often in a context involving a financial transaction.

Client is also a term for a system (computer) or application that accesses a remote computer such as a web server to receive information; examples include a personal computer that is connected to the internet, or an email application that downloads email from a server.

Closed Software

Software that does not allow users to access its source code, as opposed to open source software. See also proprietary software.

CMS (Content Management System)

An application used to create, edit, manage, search and publish various kinds of digital content (text and other media such as images and videos). Web-based CMS allow organisations to add and manage content on their website without requiring advanced technical skills. CiviCRM is often integrated with a CMS (commonly Drupal or Joomla!) which helps to facilitate client interaction.

Component

A part of a CMS or other application that can be enabled or disabled, according to the needs of the user. Examples include CiviEvent or CiviCase. See also module.

Community Advisory Group

A representative group of people from the CiviCRM community who work with the CiviCRM team on project development.

Cookie

A file stored on your computer and used by a website to identify you on return visits. Some websites cannot be accessed unless you allow your computer to accept and store cookies.

Constituent

A constituency is usually defined as a group of people bound by shared identity, goals, or loyalty. In CiviCRM, "constituents" is used to a describe all supporters, current or potential, of a given organisation. See also contact and client.

Contact

In CiviCRM a contact is either an individual, an organisation or a household about whom information is stored in the database. See also constituent and client.

Contact Summary Screen

A page that displays at a glance all the data about an individual, organisation or household that is stored in the CiviCRM database.

Core Code

The source code that constitutes the official code of CiviCRM. Also called core.

Core Data Field

A field that is included in a record structure "out-of-the-box". For example, the CiviCRM contact record includes First Name as a core field.

Core Team

The people most closely involved with CiviCRM development.

CRM

Acronym for Contact (or Constituent, Customer or Client) Relationship Management. CRM (or eCRM) software was originally developed from a sales perspective, to help companies track and organise their interactions with current and potential customers. CiviCRM is oriented specifically toward the needs of non-profits, advocacy and non-governmental organisations, so the term "customer" is replaced with "constituent". Outside the USA it is often referred to as Contact Relationship Management.

Cron Job

A cron job is a way of automatically scheduling a programme to run at certain intervals. Crons are often used in CiviCRM to handle daily or monthly events such as sending membership renewal reminders or processing ongoing payments.

CRUD

Create, Read, Update and Delete: the basic functions performed on databases.

CSS (Cascading Style Sheets)

A way to control the style of a website by defining design and layout elements in a single file which is linked to all files in a website and applies the style across the site. An element, such as the formatting of a heading or a background colour, can be changed once in the CSS file to effect a change on all pages of the site.

CSV (Comma Separated Values)

A simple format for a spreadsheet. CSV files are text files where each cell is separated by a comma, and each row is separated with a return. This very simple format is understandable by many different programmes.

Custom Data Field

A field that is added to the data structure of a CiviCRM record by your organisation. Custom data fields extend the information that can be stored in that type of record. For example, your organisation might need a custom field to record each contacts' professional qualifications, or the food preferences of event participants.

Dashboard

A user's homepage, which displays when the user logs in to CiviCRM and which can be personalised with dashlets.

Dashlet

A report on some data in the CiviCRM database, configured to appear on a user's dashboard. For example, monthly figures in graph and/or numerical form, appointments for the day, or a list of new memberships.

Data Centralisation

Storing all your data in one place.

Database

Demo Site

A website that allows you to test and explore the functionality of a piece of software. CiviCRM maintains three demos sites: one integrated with Drupal, one integrated with Joomla! and one in standalone mode.

Dedupe

Refers to the task of finding and merging multiple entries for one contact.

Developer

Someone who develops software.

Domain

See DNS.

Donor

Someone who makes a donation, i.e. voluntarily gives money to an organisation.

DNS (Domain Name System)

The Domain Name System (DNS) converts domain names, which are made up of easy-to-remember combinations of letters (example.com), to IP addresses (123.456.123.234) which are hard-to-remember strings of numbers. Every computer on the internet has an unique address (a little bit like an area code + telephone number).

Drupal

An open source CMS that integrates with CiviCRM to provide a user-interface and additional website functionality (http://drupal.org).

Encryption

A way of disguising data when it is being transferred from one computer to another so that it is unreadable by any other computer that it may pass through on the way.

Environment

The specific hardware and operating system on which you are running your software.

Event Listing Feed

A RSS feed containing the list of events defined in CiviEvent.

Firefox

A popular free and open source web browser, developed by the Mozilla Foundation (http://www.mozilla.com)

FLOSS (Free/Libre Open Source Software)

Software that is licensed so as to guarantee the essential freedoms of users to its source code and reuse. A combination of "free software" and "open source software", with "libre" added in to emphasise that software freedom is essentially a matter of rights, not price.

FOSS

Free and Open Source Software - see FLOSS.

Forum

A web-based online discussion tool (see http://forum.civicrm.org/).

Free Software

Software that is licensed so that you can use and distribute it without restriction. CiviCRM is free software. See also FLOSS.

FTP (File Transfer Protocol)

The FTP protocol is used for file transfers from one computer to another over the internet. Many people use it for downloads, and it can also be used to upload files to web servers. A popular free and open source FTP client for Windows is FileZilla. There are also web-based FTP clients that you can use with a normal web browser like Firefox.

Functionality

The set of tasks that a piece of software can perform.

Geocoding

The process of finding associated geographic coordinates (often expressed as latitude and longitude) from other geographic data, such as street addresses, or zip codes (postal codes).

GUI (Graphical User Interface)

User interface offering windows, icons, mouse control, multiple fonts, and so on - the normal way for non-programmers to communicate with their computers. The alternative to a GUI is a command line interface with text only.

Hook

[needs definition]

Hosting Service

A service (usually commercial) that provides server space for your website. Hosting services also can provide physical space to put your own server in so that it is connected to the internet.

ICT

Acronym for Information and Communication Technology.

Internationalisation: i8n

The process of making software ready for adoption in different countries and different cultures, without the need to modify it technically. This is done by the developer (software engineer) when writing the software. See also Localisation.

Internet Service Provider (ISP)

A business that provides services such as internet access, email, and website hosting.

Intranet

A network of computers that are connected within a home or office but not accessible from outside the local network.

IT

Acronym for Information Technology.

JavaSacript

A scripting language primarily used in web pages to display dynamic content.

Joomla!

A CMS that can integrate with CiviCRM to provide a user interface and additional website functionality (http://www.joomla.org).

LAMP

Linux

A type of operating system (other common operating systems are Windows and Mac OS). Linux has been popular as a web server for a long time and is now gaining popularity on personal laptops and desktop computers. Linux is free software and open source.

Local Computer

A computer that runs CiviCRM but is not publicly available via the internet. This could be your personal or home computer, or it can be in your office. It can also be called a client computer in the context of receiving information from a server

Localisation: L10n

The process of translating a product into different languages or adapting a language for a specific country or region. This is done by translators with no need for technical wizardry.

Mail Server

A computer that transfers email from one computer to another.

Mapping Provider

A service provider that allows displaying contact locations on maps - Google Maps or Yahoo Maps in CiviCRM.

Module

A part of a system, also called a component. CiviCRM includes a number of modules, each of which adds functionality to the basic contact management features. For example, the CiviEvent module provides event management functionality. Organisations using CiviCRM can turn modules on or off, according to their needs.

MySQL

A popular database engine. CiviCRM uses MySQL to hold its data. MySQL is free software. (http://mysql.com)

NGO (Non-Governmental Organisation)

A legally constituted non-business organisation with no participation or representation from government. In the United States, this type of organisation is more often referred to as a Non-profit. They may be also called civil society organisations or not-for-profits.

Non-Profit

see NGO.

Online Contribution Page

A function of CiviCRM which allows the creation of a page on the website where visitors can make online donations using credit cards.

Open ID

A convenient free system to use a single digital identity across the internet.

Open Source Software

Software with source code that is publicly available, as opposed to proprietary software; see also FLOSS. Open source software is based on the philosophy that sharing and collaborating on code leads to better software and greater benefit for everyone.

Payment Instrument

Medium or method that is used for online payments.

Payment Processor

A company (usually a third party) appointed by a merchant to handle credit card transactions for merchant banks. A payment processor is required to handle online transactions through a system such as CiviCRM.

Permissions

Allow you to limit access for different users to different parts of the system.

Personal Campaign Pages

A feature of CiviCRM that can be enable to allow constituents to create their own fundraising pages.

PHP

The programming language in which the majority of CiviCRM is written.

Ping

Sending and receiving small amounts of data to and from a server; often used to measure the response time across the network.

Point Person

Someone given the responsibility to keep their eye on a certain issue.

Premium

A gift that can be offered to contributor in exchange for donation. CiviCRM allows offering premiums as a part of the donation gathering process.

Price Sets

A way of storing and re-using complicated price structures for events. For example, you can charge for different elements of an event.

Primary Location

The information that a constinutent wants to be used as their main point of contact for mailings etc.

Profiles

A central concept in CiviCRM. In essence a subset of fields. See the chapter on Collecting and Sharing Data for a full explanation.

Proprietary software

Also called closed software or closed source software. Software licensed so that you cannot access the source code and modify it without first coming to an agreement with the authors. See also open source software.

Protocol

An agreed-upon method of doing something. HTTP and SMTP are two examples, one being an agreement on how to transfer website data across the web, the other an agreement on how email will be transferred across the web.

Radio Button

An element of a web-based application user interface that allows the user to choose only one of a predefined set of options. Usually indicated by a white circle that can be filled with a click.

reCAPTCHA

A common tool for testing whether a user is a human or a computer, used to prevent spam.

Requirements

The things that you require a particular software application to do.

Rich Text Editor

A text editor that allows you to add formatting, such as bold, italic and underline, to text (as opposed to just plain text).

Root Domain

The 'raw' URL of a website without 'www' or any other subdomain. For example, http://civicrm.org/ is the root domain while http://www.civicrm.org/ is not.

RSS (Really Simple Syndication) Feed

RSS feeds are a way to publish frequently updated information, either for inclusion on a website or to be read by an RSS reader.

RSVP

"Répondez s'il vous plaît", a French phrase that translates to "please respond". Commonly used to request confirmation (or declining) of attendance at an event.

Script

A script is a short programme that does one specific task. Many web pages include scripts to manage user interaction, so that the server does not have to send a new page for each change.

Scout

The CiviCRM Book Sprint official dog. Scout likes dog biscuits, rolling on the ground, eating snow and proof-reading.

Sendmail

Sendmail is one of the most popular mail transfer agents (MTA) used for handling email on a server. Sendmail is free and open source software.

Server

1. Software that "serves" content to a client. See Apache, or Mail Server for two examples.

2. A computer that is used primarily to serve content. Any computer can be set up this way, but the term traditionally refers to those that deliver web content. See also client computer.

Shared Hosting

A website hosting service, where multiple websites reside on single server.

Smart Group

A group in CiviCRM to which contacts are automatically assigned. Smart groups are created by running and then saving a search. They are useful for groups that might change frequently, for example "donations over $1000 in the last month".

SMTP

Simple Mail Transfer Protocol. A standard or protocol used by email software to transfer (send) email.

Soft Credit

Allows you to credit a contact for a donation made by someone, for example the person who inspired the actual donor to make a donation. See Personal Campaign Pages. 

Software

Applications (also called programs or programmes) that enable specific functionality on your computer. There are many broad categories of software such as web browsers, word processors and email clients. Within each category there are many available softwares that perform the functions you require. For example, Firefox and Internet Explorer are two commonly-used web browsers.

Software License

The terms you must accept before using a piece of software.

Source Code

Software is created by writing instructions that a computer understands. These lines of instructions are known as code or source code.

SSL (Secure Sockets Layer)

One way of making internet communication secure. You can easily see if you are using SSL by looking at the URL in your browser: if it starts with https instead of http, your connection is using SSL.

SSL Certificate

Provided by the server to prove its identity, in the same way that a person carries a passport or driving license. See also SSL (Secure Sockets Layer).

Stable Version

A version of software that has been tested and is considered to be ready for general use.

Standalone

An installation of CiviCRM which is not integrated with a CMS such as Drupal or Joomla!.

String

A string is a sequence of characters for example "Hello, World", the URL "http://www.flossmanuals.net/" or the text message "No such file or directory". Different character sets allow different strings. Unicode strings can include any combination of languages, such as "Japan (日本) and Korea (대한민국)".

Subdomain

A domain that is a part of larger larger domain. For example: en.flossmanuals.net and fa.flossmanuals.net are subdomains of the domain flossmanuals.net.

Token

Tokens are used in CiviCRM to insert elements such as a contact's name or a standard greeting into emails being sent from the system. In an email sent to a group of people, the token {first.name} will be replaced with actual name of each message recipient, in the email that each individual receives.

Upgrade

The process of replacing software with a newer version of the same software. An upgrade may fix bugs, improve security, enable the software to continue to work with upgraded operating systems, or provide new features and other enhancements.

URL

Acronym for Unique Resource Locator, sometimes referred to as a Universal Resource Indicator, or URI. The technical convention that identifies the location of a resource on a network. The resource might be a web page, in which case the URL refers to the location of that web page on the internet, for example www.civicrm.org is the URL for CiviCRM.

Use Case

Use case is a central concept in software development. A use case is a story or scenario that documents the experience of performing a specific task with the application. Generally, a use case should avoid technical or database-specific language, such as 'fields' or 'record', and concentrate on real world objects and scenarios in order to communicate the idea clearly to people who may not be familiar with technical terms.

Version

Updates to software are released periodically, and these releases are referred to as a version of the software. There are different types of version, for example the most recent release of a software which has been tested and is intended for general use is referred to as the stable version, while a very new untested version is the alpha version. 

VPN (Virtual Private Network)

A method of sharing information between members of an organisation over encrypted connections.

Web Application

A software application that provides a website with additional functionality. CiviCRM is a web application.

Webmail

Webmail is email service through a website. The service sends and receives email messages for users in the usual way, but provides a web interface for reading and managing messages, as an alternative to running a mail client like Outlook Express or Thunderbird on the user's computer. For example a popular and free webmail service is https://mail.google.com/

Web-Server

Wiki

A web-based software that enables anyone to edit content via a web browser. Wikipedia is the best known example of a wiki.

Wildcard

A character that can match an any number and collection of characters, normally represented by . For example, when used in searches, ab finds ab, abba and abracadabra but not fabulous; ab finds fabulous.

Work Station

A computer used for working; often in a situation such as an office where there are other computers that may include servers.

WYSIWYG (What You See Is What You Get)

An application that provides a visual tool for editing web content, so that the user can see how the page will look in the browser as they are editing, instead of working in the HTML code. See also rich text editor.

CREDITS

Cover Art (faces) by Kapor Creative: Jake Mix & Trevor Parham (Jake created the illustrations, and Trevor developed the concept of the civi logos as eyes). Cover Art is CC-BY-SA

All chapters copyright of the authors (see below). Unless otherwise stated all chapters in this manual licensed with GNU General Public License version 2

This documentation is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Authors

ABOUT THIS BOOK
© Michael McAndrew 2010
Modifications:
adam hyde 2010
David Greenberg 2010
helen jamieson 2010
HOW TO CONTRIBUTE?
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Kyle Jaster 2010
Michael McAndrew 2009, 2010
Yashodha Chaku 2009
LOCALISATION
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009, 2010
Cynthia Tarascio 2009
David Greenberg 2010
Dream Gomez 2009
Eileen McNaughton 2009
Erik Brouwer 2010
Jack Aponte 2010
Mathieu Petit-Clair 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
BUG REPORTING
© adam hyde 2009
Modifications:
Andy Oram 2009
Cynthia Tarascio 2009
Eileen McNaughton 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
INSTALLATION
© David Greenberg 2009
Modifications:
adam hyde 2009, 2010
Alice Aguilar 2010
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
Kurund Jalmi 2010
Michael Gross 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Tony Guzman 2009
PROFILES
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009
Brian Shaughnessy 2009
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
jay maechtlen 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
Yashodha Chaku 2009
CONFIGURING
© adam hyde 2010
Modifications:
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
PLANNING
© adam hyde 2010
Modifications:
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
CIVICOMMUNITY
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Jack Aponte 2010
Michael McAndrew 2010
EXTENDING CORE DATA
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Andy Oram 2010
David Greenberg 2010
Erik Hommel 2010
helen jamieson 2010
Kurund Jalmi 2010
Manuel Schmalstieg 2010
Mari Tilos 2010
xavier dutoit 2010
CONFIGURING
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Michael McAndrew 2010
PLANNING
© adam hyde 2010
Modifications:
Andy Oram 2010
Michael McAndrew 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Mari Tilos 2010
Michael McAndrew 2010
WHAT IS CIVICONTRIBUTE?
© adam hyde 2010
Modifications:
Andy Oram 2010
Kyle Jaster 2010
Michael McAndrew 2010
MENU AND DASHBOARD
© Michael McAndrew 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2010
CONFIGURING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
David Greenberg 2010
Jack Aponte 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Tim Homewood 2010
EVERYDAY TASKS
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Jack Aponte 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
INSTALLING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
PLANNING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Jack Aponte 2010
Michael McAndrew 2010
Michael McCallister 2010
CONFIGURING
© adam hyde 2010
Modifications:
Andy Oram 2010
David Greenberg 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
Mari Tilos 2010
Michael McAndrew 2010
Sarah Gladstone 2010
PLANNING
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Michael McAndrew 2010
xavier dutoit 2010
WHAT IS CIVIEVENT?
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Christopher Gervais 2010
Jack Aponte 2010
xavier dutoit 2010
CONFIGURING
© Kurund Jalmi 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2010
TWikiGuest 2010
EVERYDAY TASKS
© Michael McAndrew 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
TWikiGuest 2010
PLANNING
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
WHAT IS CIVIREPORT?
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
David Greenberg 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Sarah Gladstone 2010
CONFIGURING
© xavier dutoit 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
Graham Mitchell 2010
Mathieu Lutfy 2010
Michael McAndrew 2010
Sarah Gladstone 2010
Tim Homewood 2010
IMPORTING
© Peter Davis 2009
Modifications:
adam hyde 2009, 2010
Alice Aguilar 2010
Andy Oram 2010
Cynthia Tarascio 2009
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
CREDITS
© adam hyde 2006, 2007, 2009, 2010
Modifications:
Cynthia Tarascio 2009
Michael McAndrew 2009, 2010
HOW DATA IS ORGANISED?
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009, 2010
Brian Shaughnessy 2009
Brylie Oxley 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
jay maechtlen 2009
Janet Swisher 2009
Kurund Jalmi 2010
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Peter Davis 2009
TWikiGuest 2009
Tony Guzman 2009
xavier dutoit 2010
DEDUPING AND MERGING
© Jack Aponte 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Jeff Sherk 2010
Kyle Jaster 2010
Mari Tilos 2010
xavier dutoit 2010
API
© Wes Morgan 2010
Modifications:
adam hyde 2010
Brylie Oxley 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
CUSTOM SEARCHES
© Wes Morgan 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Sarah Gladstone 2010
HOOKS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
Kyle Jaster 2010
Mathieu Lutfy 2010
Michael McAndrew 2010
xavier dutoit 2010
IMPORTS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
INTRODUCTION
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
xavier dutoit 2010
REPORTS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Erik Hommel 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
TEMPLATES
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Sarah Gladstone 2010
xavier dutoit 2010
DEVELOPER TIPS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
EXPORTING
© Kurund Jalmi 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2010
EVERYDAY TASKS
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
David Greenberg 2010
Josue Guillen 2010
Michael McAndrew 2010
REAL WORLD EXAMPLES
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
jay maechtlen 2009
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Peter Davis 2009
Roberto Santiago 2009
Tony Guzman 2009
ABOUT FREE SOFTWARE
© Michal Mach 2009
Modifications:
adam hyde 2009, 2010
Cynthia Tarascio 2009
Mari Tilos 2009
Michael McAndrew 2009, 2010
EVERYDAY TASKS
© Jack Aponte 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Michael McAndrew 2010
Tim Homewood 2010
GLOSSARY
© adam hyde 2009, 2010
Modifications:
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2009, 2010
Lachlan Musicman 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
TAGS AND GROUPS
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
xavier dutoit 2010
Yashodha Chaku 2009
CONTACTS
© adam hyde 2009, 2010
Modifications:
alan zucker 2009
Andy Oram 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009
Michal Mach 2009
Peter Davis 2009
TWikiGuest 2009
Yashodha Chaku 2009
HISTORY OF THIS BOOK
© Michael McAndrew 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Sarah Gladstone 2010
WHAT IS CIVICRM?
© Michal Mach 2009
Modifications:
adam hyde 2009, 2010
Andy Oram 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Peter Davis 2009
IS CIVICRM FOR YOU?
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009
Benjamin Melançon 2010
Cynthia Tarascio 2009
Duncan Hutty 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Janet Swisher 2009
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
POSTAL MAIL
© adam hyde 2009, 2010
Modifications:
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
xavier dutoit 2010
WHAT IS CIVIMEMBER?
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009, 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
TWikiGuest 2009
Tony Guzman 2009
Tracy Smith 2009
EVERYDAY TASKS
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
David Greenberg 2010
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
TWikiGuest 2009
Tony Guzman 2009
CONFIGURING
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2010
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
PLANNING
© adam hyde 2009, 2010
Modifications:
Andy Oram 2010
Brian Shaughnessy 2009
Eileen McNaughton 2009
Joe Murray 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
TWikiGuest 2009
Tony Guzman 2009
ORGANISATIONAL ANALYSIS
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
helen jamieson 2010
Janet Swisher 2009
Mari Tilos 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Phil Mocek 2010
Tony Guzman 2009
PLANNING
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Michael McAndrew 2010
TWikiGuest 2010
PROJECT MANAGEMENT
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009, 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Erik Hommel 2010
helen jamieson 2010
Jack Aponte 2010
Janet Swisher 2009
Joe Murray 2010
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
SEARCHING
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2009, 2010
Kyle Jaster 2010
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
Yashodha Chaku 2009
SYSTEM CONFIGURATION
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Christoph Berendes 2010
Joe Murray 2010
Kurund Jalmi 2010
Michael McAndrew 2010
WHAT IS CIVIENGAGE?
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Josue Guillen 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Tim Homewood 2010
WHAT IS CIVIMAIL?
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Graham Mitchell 2010
Lachlan Musicman 2010
Michael McAndrew 2010
TWikiGuest 2010
WHAT IS CIVICASE?
© adam hyde 2010
Modifications:
Andy Oram 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
WHO IS CIVICRM?
© adam hyde 2009, 2010
Modifications:
David Greenberg 2009
Eileen McNaughton 2009
Jack Aponte 2010
Mari Tilos 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Michal Mach 2009
Peter Davis 2009
 

100.gif

Free manuals for free software

 

General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:


a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:


a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

The CiviCRM Community

Like many open source projects, CiviCRM is shaped, guided, and driven by its community, a far-flung ecosystem of users, developers, and implementers who utilize CiviCRM in many different ways and bring to it a wide array of skills, experiences, and perspectives. These varied and diverse offerings are crucial to the continued success of CiviCRM, but they can move the project forward only if they find their way back into the public stream of discussion and collaboration. This chapter is a guide to finding and engaging in the community of people who are working together to make CiviCRM what it is and what it will become.

Finding the Community Online

As might be expected of a web-based software project, much of the CiviCRM community's activity occurs online. This means that if you have access to the Internet you also have access to and can participate in the CiviCRM community regardless of where you live or work. English is the predominant language for discussion and contributions.

The CiviCRM website itself (http://civicrm.org) is a good starting point for exploring and participating in the community. In addition to general information about getting and using CiviCRM, you'll find blog posts from community members, announcements about upcoming events, and a Participate section (http://civicrm.org/participate) that lists and links to many of the resources described below.

The CiviCRM Forums (http://forum.civicrm.org) are a central location for CiviCRM discussion and support. The forums are divided into topical boards for:

Registration for the forums is completely free and most of the boards are very active with frequent new posts and responses.

Another great source of support and discussion is Internet Relay Chat (IRC). The #civicrm IRC channel is hosted by Freenode at  irc.freenode.net.  You can access the channel using an IRC client (a program that you run on your computer) or through the web interface at http://webchat.freenode.net. Enter #civicrm in the Channels field and a nickname of your choosing in the Nickname field. For more information on using IRC, check out the IRC section of the Drupal website (http://drupal.org/irc). Although the information is targeted to the Drupal community it can also be useful for CiviCRM users, especially because the Drupal IRC channels are also hosted on Freenode.

You'll hopefully find that both the forums and the IRC channel are great sources for help, support, and good ideas. That's all attributable to the good will and generous efforts of people like you! Everyone who visits the forums and the channel is encouraged to give back to the community by responding to questions and requests for help and contributing their own ideas and feedback to the conversations. And simply asking your own questions is also a significant contribution to the community. It's likely that someone else is having the same problems or wondering the same thing, and the responses you solicit help build the community's knowledge base.

The CiviCRM blog (http://civicrm.org/blog) is another good source of information and discussion. Blog posts are written by both the CiviCRM core team and other community members and cover a wide range of topics, including general news and announcements, upcoming events and accounts of events that have occurred, case studies, use cases and ways to get things done with CiviCRM, and new features and development. Comments are encouraged and can create lively discussions that can in turn direct future CiviCRM development. If you've got something that you'd like to post on the blog, we encourage you to write to info@civicrm.org  with your ideas and your request to post.

Much discussion of CiviCRM also occurs outside of these official channels. Using your favorite engine to search for CiviCRM will turn up many articles and posts from other folks' websites and blogs. The CiviCRM team is good at keeping an eye out for these posts and often publicize them through Twitter. To keep abreast of the stream of comments, follow @civicrm and find CiviCRM tweets and tag your own tweets with the #civicrm hashtag.

Finding the Community Offline

Though the online community is both accessible and active, participating in the CiviCRM community offline can be even more rewarding and can help you connect with others in your area who are developing, implementing, and using CiviCRM.

Many cities and regions hold CiviCRM meetups where people gather to learn about CiviCRM, share new ideas, developments, and use cases, and meet other folks involved with the community. You can find out more about meetups at http://civicrm.org. Some meetup and local user groups (or LUGs) also maintain discussion boards at http://civicrm.org/groups. Contact the CiviCRM crew if you'd like a discussion board for your own group on the site.

CiviCRM recently held the first CiviCon conference in April 2010 in San Francisco. More are being planned, including one in Chicago in 2011. CiviCRM core developers and community members also make appearances at other conferences, including DrupalCon, the NonProfit Technology Conference, Joomla! events, and Aspiration Tech events.

CiviCRM also conducts user and developer training in cities around the globe. Check out http://civicrm.org for info about upcoming trainings and contact CiviCRM if you'd like to host trainings in your own area.

Open Source = Community Sourced

Here are some additional ways that you can participate in and contribute to the CiviCRM community.

REPORTS AND ANALYSIS

Reports and Searches can be created with the default (or core) Report Templates and Searches in CiviCRM.  This chapter will describe some of the reports that can be used with CiviEngage.

To learn more about how to work with Reports, see the section called "Reporting".

Analysing Results from a Door-Knock Canvass

To analyse responses from a survey used during a door-knock canvass, you may want to use the Survey Report that's part of the Campaign component.

  1. After you have recorded responses from your contacts, Click on Campaigns > Create Reports from Templates > Survey Report (Detail)
  2. In Display Columns area, check the boxes for: enter the information you'd like to display such as Street Number, Street Name, Street Unit, Survey Responses
  3. In Group By Columns area if you'd like to group the responses, check the boxes for: Street Name, Odd/Even Street Number
  4. In Set Filters area, select your survey name in Survey, and select for" Respondent Status" 'Is Equal to" Interview.
  5. Click Preview Report.
  6. You can now review the results from the screen, or you can choose to export the the information to .CSV file to do further analysis and reporting

Analysing Results from a PhoneBank

To analyse responses from a phonebank, you may want to use the Survey Report that's part of the Campaign component.

  1. After you have recorded responses from your contacts, Click on Campaigns > Create Reports from Templates > Survey Report (Detail)
  2. In Display Columns area, check the boxes for: enter the information you'd like to display such, especially Survey Responses
  3. In Set Filters area, select your survey name in Survey, and select for" Respondent Status" 'Is Equal to" Interview.
  4. Click Preview Report.
  5. You can now review the results from the screen, or you can choose to export the the information to .CSV file to do further analysis and reporting.

Set-up

This chapter shows you how to set up CiviContribute and related components of CiviCRM to support fundraising. 

This chapter assumes you have a working understanding of custom fields, contact matching rules, CiviCRM Profiles, and the CiviMember and CiviMail components. The chapter also assumes you have already set up your payment processor and created any custom fields you want to use when tracking contributions. If you have not done these things, please refer to the appropriate sections of this manual for more information.

General Configurations

You may need to configure the following fields before you begin setting up various methods for managing contributions.

Contribution Types and Accounting Codes

If you need to add contribution types or accounting codes, do this first. 

  1. Navigate to Administer > CiviContribute > Contribution Types, where you can edit one of the existing contribution types or create a new one by clicking Add Contribution Type. 
  2. Once you edit or add a contribution type, you can define an accounting code that corresponds to your accounting system (the accounting code will be exported along with the contribution data if you do an export), and indicate whether this type of contribution is tax-deductible. 

Be careful when editing core contribution types or adding new types, because CiviCRM has useful built-in functionality that depends on the core contribution types.

Premiums

Configure premiums, such as T-shirts or subscriptions, that you want to offer on your contribution pages:

  1. Navigate to Administer > CiviContribute > Premiums (Thank-You Gifts). 
  2. You can edit an existing premium or click Add Premium to add a new one.
  3. Once you edit or add a premium, you can then enter additional information: Name, Description, SKU (an optional product code), Premium Image (an optional image of the item), Minimum Contribution Amount to receive the premium, Market Value of the premium, Actual Cost, and Options (e.g., colors and sizes). 
  4. If you're offering a subscription or service, you can also click on the Subscription or Service Settings and define additional information here, such as Period type (e.g., Fixed or Rolling), the Fixed Period Start Day, the Duration, and the Frequency. 

Accepted Credit Cards

Navigate to Administer > CiviContribute > Accepted Credit Cards to edit existing acceptable credit cards or define a new option through Add Accept Creditcard. 

Payment Instruments

Navigate to Administer > CiviContribute > Payment Instruments to edit existing options that can be used for contributions or to add a new option through Add Payment Instruments.  The common options - credit card, cash, check, debit card, and EFT - are installed by default.

Creating Contribution Pages

To create a new contribution page: 

  1. Navigate to Contributions > Manage Contribution Pages and click on Add Contribution Page.
  2. Give the page title, select the contribution type (donation, campaign contribution, etc.), goal amount, introductory message and any other relevant information such as dates. You will be able to go back and modify all aspects of this page at any time after completing the setup wizard. Click Continue.
  3. The Execute real-time monetary transactions box is checked by default, to enable monetary donations. You would only uncheck this box if you are using this contribution page to solicit in-kind (non-monetary) donations.
  4. Select the Currency and Payment Processor (which you have previously configured).
  5. Check the Contribution Amounts Section Enabled box to allow various specific amounts to be presented. Leave this unchecked if, for example, you are using the page for membership sign-ups that have fixed amounts, which will show only the fixed membership amounts and not allow custom amounts to be entered. 
  6. Check the Pay Later box if you want to give users the option to submit payment offline (e.g. mail in a check, call in a credit card, etc.).
  7. Select a pre-defined Price Set, or enter up to 10 fixed contribution amounts in the table.
  8. Check the Pledges box to give users the opportunity to pledge future payments.
  9. Check Allow other amounts to give users the option to pay any amount they choose.
  10. Click Save and Done.

Include Profiles

If you want to collect information from contributors beyond what is required to make a contribution, such as volunteer availability and skills, you can include existing CiviCRM Profiles at the beginning or end of a contribution page. You can also create profile(s) specifically for use in contribution pages.

Profiles used in a contribution page can ONLY contain fields which belong to:

If you add fields that are associated with any other record types, you will get an error when you preview your contribution page.

  1. Navigate to Manage Contribution Pages then for the page you wish to configure, click on Configure > Include Profiles.
  2. Select a CiviCRM Profile from the dropdown menu to be included at the top of the contribution page (immediately after the introductory message) and/or at the bottom of the page.
  3. If you're building a new page, click <<Previous to save and return to the previous step, Continue>> to proceed or Cancel to cancel the configuration wizard. Otherwise simply click Save.

Thank-you and Receipting

Once you have created your contribution page, you can customise the Thank-you and Receipt emails that are sent to contributors.

  1. Navigate to Administer > CiviContribute > Manage Contribution Pages.
  2. Use the Configure link at the right-hand side of a contribution page in the list to access and edit the page.
  3. Click on Thank-you and Receipting and enter the information that you wish to appear in the thank-you email. Donors usually expect a receipt as soon as their transaction is complete, so it is recommended to enable the automatic Email Receipt.
  4. Click Save and Done.

Publicizing your contribution page

Now that you've created your contribution page, it's time to bring people to the page so they can contribute. You will probably want to display a link to the page prominently on your website through a donate button or menu item. Here are some additional tips for promoting a contribution page in different CiviCRM configurations:

Menu item in Joomla!

The most direct way to expose your contribution page or membership signup/renewal page on the front of your web site is by creating a menu item. 

  1. Navigate to a menu and create a new CiviCRM item. 
  2. From the list of menu options, choose Contributions. 
  3. In the basic parameters section, select the contribution page you would like exposed from the dropdown menu. 
  4. Save the menu item and view the website to confirm the page's functionality.

Menu item in Drupal

From the contribution page listing, select Live Page to view the finished page. You can then copy the URL and include it in a content page or assign it to a menu item. 

"Pretty" URLs 

CiviContribute contribution pages have "ugly" URLs - in other words, they are difficult to remember. An example is :

www.myorganization.org/civicrm/contribute/transact?reset=1&id=1

On the other hand, "pretty" URLs are much easier to remember and use in your organization's outreach, for example:

www.myorganization.org/donate

A pretty URL is simply a URL redirect (autmoatically taking people from one page of your web site to another). Drupal provides a helpful module called Path Redirect (http://drupal.org/project/path_redirect) that lets you can create URL redirects from the user interface without complicated web server configuration. Joomla! users also have a work-around if Search Engine Friendly URLs are enabled in Global Settings. You can then create a menu link to the contribution page and define the "pretty" URL using the alias field.

Personalised Email

Emailing your current membership is the other critical way to publicize the campaign. The CiviMail component of CiviCRM allows you to send targeted emails to any group of contacts in your database. Within a CiviMail message you can include links to the contribution form and use CiviMail's tracking capability to see how many people click on that link.

One time-tested way to increase contributions is to send each targeted constituent a personalized email with a link to the contribution form that has all of their contact information already filled in. This saves them the hassle of filling it out and raises the chances that they donate. Using CiviMail, you can use this feature by creating a special link in the body of your CiviMail message that includes a checksum token. A checksum is a unique and pseudo-random number assigned to each recipient of the mailing that points back to their contact information, securely stored in your database.

When people click on the special link, CiviCRM looks them up in the database and pre-fills fields on the contribution form (core fields or fields exposed via a profile) with any information in their contact record.  To read more on how to do this and what the link path must be, visit: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data

Automatic Contribution Recording

Regardless of how donors get to your contribution page, CiviCRM automatically records their donations, freeing your staff from doing manual data entry. If the donors already exist in the database, CiviCRM adds the contribution to their existing record. If they don't exist, CiviCRM creates a new record for them.

In situations where people have multiple email addresses, or where more than one person shares an email address, it can be possible for contributions to be credited to the wrong contact. To mitigate the chance of this happening, you can adjust CiviCRM's default duplicate matching rules. For instructions on how to do this, see the chapter Merging and Deduping in the Basic Concepts section of this book.

Offline fundraising

Your organisation may collect donations at events, solicit donations via postal mailings and other offline methods. Any money raised through offline activities needs to be manually entered into CiviCRM in order to ensure that final reporting is accurate.

There are three steps within CiviCRM for offline fundraising: creating your lists, creating your mailings, and manually entering contributions.

Creating your lists

This process is fairly straightforward if you are familiar with CiviCRM's search capabilities.

  1. Go to Search > Find Contacts to create a list of records to receive your offline postal mail appeal (it could be your entire database).
  2. If you want to track the success of a mailing or who receives certain appeals, save the search results as a group. Use the check box to select all and choose the appropriate option from the "- actions -" dropdown menu (e.g. New Smart Group or Add Contacts to Group). Later, you can mark everyone in that group as recipients of that appeal using the Record Activity for Contacts option under the "- actions-" dropdown menu.
  3. , export the list as a CSV file. 
  4. Select all records or a subset using the checkboxes, and from the "- actions -" dropdown menu choose Export Contacts and click Go.
  5. Choose whether to Export PRIMARY fields or Select fields for export. If you elect to export primary fields, the CSV file will be immediately generated when you click Continue. If you opt to select which fields you want to export, click Continue and a list of dropdown options will appear.
  6. Select the required fields; if you wish to save the list of exported fields as an export mapping for future use, check the Save this field mapping box. 
  7. Click Export to generate the CSV file.
  8. Click Done when you have finished to return to the contact list.

Creating your mailings

Once your spreadsheet is created, you can do a mail merge using any word processing software (such as OpenOffice, the free software word processor) that will insert any fields you want in the letter.

CiviCRM can also create mailing labels for you. Perform the same search you used in the previous section to create your list of recipients, then:

  1. From the "- actions -" dropdown menu, select Mailing Labels. 
  2. Select the mailing label number, determine whether you want to exclude people with "do not mail" checked in their privacy options (checked by default and recommended), and whether you want to merge two records that have the same mailing address into one label. This last option is very useful when you are mailing a household or organization and you don't want them to receive duplicate mailings. When the records are merged, each name at that address appears on its own line on the label. 
  3. Click Make Mailing Labels and a printable PDF document will be created.

Note that many non-profit organizations in the United States have to sort recipients of a mailing based on zip code for bulk mailing purposes. If this is true for your organization, it is recommended you do not create your mailing labels within CiviCRM, but instead create them using word processor merge functions where you have control over the sort order. You can reuse the same spreadsheet for the mail merge you exported in the previous section.


Reports and analysis

There are a number of techniques for reporting on and analysing contributions.  The contribution dashboard gives a quick overview of your current contributions, with breakdowns for months and years, which you can view as a chart or table.



That's a good start but there are a couple of ways that you can create more detailed and customised analysis using CiviCRM's search features and CiviReport.

Contribution reports

Out of the box, CiviCRM comes with eleven contribution reports designed to help you analyse your contributions.

A contribution summary report allows you group contributions by different criteria including including the contact that made the contribution, time period, type, location and view summary statistics for these contributions.  The accompanying contribution detail report is automatically called when clicking on any rows from the summary report.  It can also be called on its own to provide a detailed report for a specific subset of contributions.  These two reports can be useful for analyses such as what percentage of our income is coming from different fundraising campaigns, or from events vs. memberships, etc.

The repeat contribution report compares the total amount of contributions that contacts have made in two different time periods.  As well as the totals, it shows the percentage increase/decrease.  This report is useful for tracking contacts who have stepped up their giving, or who giving less than before. SYBUNT AND LYBUNT are two strangely named but useful reports that allow you to find donors that gave in 'some years / last year but not this year'.

Two reports, the contribution by household and contribution by organisation allow you to agregate contributions by household or organisation.  This is useful for organisations that make use of these two concepts.  For example, you can see all contributions that have been made by employees of one organisation and thank them as a whole, or see the contributions made by a particularly active family.  These reports will also include any donations that are attached to the organisation or household record, for example a donation made by the organisation after an collective office fundraising event.

The top donors report provides a list of the top donors during a time period you define. You can include as many donors as you want (for example, top 100 of your donors).

The personal campaign pages report is useful to get an overview of the status of all personal campaign pages.  You can filter by contribution page to see personal campaign pages for a single campaign and other appropriate criteria.

The soft credit report is useful for looking at all your soft credits and seeing who are at least partially responsible for other people's donations.

Pledge reports

CiviCRM comes with two pledge reports that are useful when analysing pledges.  The Pledge report and Pledge summary report work in much the same way as the contribution detail and summary reports.  An additional Pledged but not paid report pledges which are not completed and have a due date in the past.

Searching based on contribution data

CiviCRM makes an important distinction between contributions and the people that made the contributions.  It is important to appreciate the difference between the two when you are searching contributions.  For example, if you want to send a gift to all people that made a contribution in the last year, what would be more appropriate? Contacts or contributions?  The answer depends on whether you want to send two gifts to people that made two contributions and there is of course no right or wrong answer - it just depends on your approach.  It is important to think about this each time to do a search.

The Find contributions search allows you to search based on contribution data and return contribution records.  The Advanced search allows you to search based on some limited contribution data (and combine that with other contact information) and return contacts.  You can also choose contribution from the column to show contributions rather than contacts.

Searching based on criteria gives you access to simple totals and also the option to export as CSV for further analysis.

More analysis

If you can't do what you want with a built in report or search, consider commissioning a new report or custom search. Read the CiviReport section for more information.

Contacts

Contacts are the main building block of CiviCRM. There are three types of core contacts by default in a standard installation:

Each contact record holds contact information, including:

All of the other building blocks of CiviCRM such as relationships, contributions and groups are connected to contacts in some way, so you can see events that a contact has attended, or what contributions they have made.

You can define further contact types to suit your needs, for example "students", "farms" or "churches".  Each contact type you define is based on one of the three core contact types. For example, students would based on the individual contact type, and farms could be based on the organisation contact type, or perhaps on the household contact type, depending on your situation.

A contact can be only one contact type. For example, they can't be a student and a teacher (but contact types are not the only way to differentiate your contacts).

All users of your content management system are also stored in CiviCRM as individuals. Their contact record in CiviCRM is linked to their user record in the CMS (Drupal or Joomla!). Note that only individuals can be linked to user records in your CMS. Organisation and household records in CiviCRM cannot be directly linked to user records in your CMS. 

Adding a contact

The simplest way to add a single contact to CiviCRM is to use the navigation menu at the top of any non-public page. To create a new Individual, go to: Contacts > New Individual:

Contact_createIndividual

Note that the Contacts menu item allows you to create every kind of contact and contact sub-type.

Clicking on New Individual will bring you to the New Individual form. All of the contact creation forms are similarly arranged, with basic information (name, email etc.) at the top of the form and more specific fields below grouped by type or subject in accordions (such as address fields, communications preferences and any custom fields that you have added for the contact type).

You can fill out as many of these fields as you like, however it's recommended that you have at least a name and email address (it is only required that you have first and last name OR email address). Remember that there is no difference between the contact add and edit screens, so you can always go back and make changes as needed.

Once you have filled out the form, you have the choice of three buttons to click:

The contact screen

The best way to understand contact management is to have a look at the different screens that are used to store and display information about contacts.

You can find a contact from your CiviCRM dashboard (or any other CiviCRM page) by entering part of their name or e-mail address into the Quick search box in the navigation menu. If you leave the search box blank and click the Search button, it will find all the contacts in your database.

Below is a search for "sa" that has returned Sam Jones, as well as other contacts with the letter combination "sa":

NavMenu_quicksearch;

Contact Actions Ribbon

Across the top of all contact records is an Actions Ribbon with a variety of buttons that allow you to perform actions related to the current contact. Clicking the Actions button will produce a dropdown menu with a number of actions that can be performed on this contact. For example, you could add a note to this contact, or record a new contribution, meeting or other activity.

Some of the activities you can perform here are:

If you're using CiviCRM in conjunction with Drupal or Joomla, you may also see a link to View User Record. This link is shown when the contact is a registered user of your site. It links to a CMS-specific User Account screen. 

Contact tabs

A list of tabs underneath the Actions Ribbon break up the contact's information into related chunks. We will cover the contact summary tab here in some depth, and then look at other tabs that may be available to you depending on your configuration.

If you think that some of the tabs are not useful and will not be used in your deployment, you can disable or enable specific tabs from Administer > Global Settings > Site Preferences. If you don't see some of the tabs described below, you may need to enable them. The visibility of some tabs is dependent on which components are enabled in your installation. For example, the Contributions tab will be hidden if the CiviContribute component is disabled.

Summary tab

The summary tab gives you an overview of information about your contact. Here you will find names, addresses and contact details. The information on this page appears fairly straightforward, but take a closer look and you will find some pretty clever stuff is going on. 

CiviCRM includes a complete set of fields "out-of-the-box" to store basic contact information. These are usually referred to as built-in fields and include:

Note one small but important feature of the summary screen: if you have a number of long sets of fields, it may become useful to collapse some of them. In the example below, Communication Details has been collapsed, while Constituent Info - Individuals is expanded. Some field sets can be set to be expanded or collapsed by default. This happens for example when a contact has more than one location entered. The first one is shown by default, the rest of them will be collapsed. Clicking on the header will toggle the status of the field set.

Contact_expandCollapse

Name Fields

Each contact's name can include the following fields: Prefix, First, Middle and Last Names, Suffix and Nickname. You don't have to use all of them, but they are available in case you want to store all of this information.

If you wish to record a prefix such as Mr., Ms. or Dr. for your contact you can do so using the dropdown menu on the edit screen. If you require other prefixes such as Sir or Father, you can add these to the dropdown menu from Administer CiviCRM > Option Lists > Individual Prefixes (Ms., Mr...). The same applies to name suffixes.

Locations

A location is a group of address-related fields consisting of phone, email and postal address field groups. 

CiviCRM can hold more than one location for a contact. For example, if a person has a home address, a billing address and a work address, these can be recorded as separate locations. One of these locations will be marked as Primary. It will be used for any postal mailings that you do. You can explicitly choose which location will be primary for a particular person, or let it default to the first one entered. If a person pays you by credit card, the details used for Billing Address in credit card payments will be stored in the Billing location for the contact.

You can share addresses between contacts. For example, you may need to keep information about individual contacts and the organizations where they work. When creating or editing the "work" address for an individual, check the "Share Address With" box. If their employer already exists in your database, you can select them from the quick search box that appears. Otherwise, you can create the employer's organization record on the fly by selecting "New Organization" from the "create new contact" dropdown..

You can also store multiple phone numbers and email addresses for each location. One of these email addresses can be explicitly marked as the address which receives all bulk mailings (e.g. emails your organisation sends using the CiviMail component).

Relationships tab

Relationships are connections between contact records in your database. Each connection can be named to describe the nature of the connection, and a contact may have many relationships to other contacts in the database. In the example below you can see a list of Current Relationships as well as a list of Inactive relationships. Contacts can have relationships with set start and end dates. For example, a contact could have a relationship "Committee Chair" to an organisation for a one year period. In order to track past Committee Chairs, you can keep a record of the contact having an inactive Committee Chair relationship.

Contact-RelatoinshipTab_1

Another example of a relationship that might be tracked in CiviCRM is the Employee-Employer relationship. Richard is an employee of the organisation Acme Org, and to store this information in the database you can set Richard to be an "Employee of" Acme Org. You do this by creating a relationship between Richard and his employer. Once you do this, you will be able to see this connection from both Richard's and Acme Org's records.

The Employee/Employer relationship is a special one. If you look at the Summary tab again you can see that the Current Employer field shows the name of the employer. This name is a link to the ABC Org contact record. Entering in an Employer in this field is a shortcut way to define an employment relationship. Whenever you fill in the Current Employer field, a record with a matching name will be looked up and the appropriate relationship will be created. If no record for this organisation exists, one will be automatically created before creating the relationship.

The Household Member relationship is used for connecting individuals with households. When editing a contact, you can opt to "Share Address With" a household. You can either select an existing household, or create a new one by selecting "New Household" from the "create new contact" dropdown. When you have opted to use a household address for a contact, a link to the Household's contact record will be displayed along with the usual address information in the contact Summary tab. Using a household address for a contact also automatically creates the Household Member relationship between the contact and household.

Apart from the two special relationship types, you can create and register any other type of relationship. The Relationships tab shows all of a contact's existing relationships with other contacts (individuals, households or organisations in the database).

To create a new type of relationship, go to Administer CiviCRM > Option Lists > Relationship Types. Relationships can be also extended with custom fields if you need to store additional information for them.

Additional powerful characteristics of relationships include the ability to set a start and end date, or disable them manually if they are not valid anymore. This means that you can store the history of relationships in your contact records.

Activities tab

The Activities tab does two things. First, it displays all your interactions with the contact over time; this includes all CiviCRM's built-in activities like event attendance, contributions, membership sign-up and renewal, phone calls, emails and user-defined activities. Second, it allows you to record activities with contacts. Clicking on the icons at the top of the screen (Send an Email, Meeting, Phone call) will bring up a screen where you can enter those details.

This tab can also be used to record any custom activities that you've defined for your CiviCRM installation (from Administer CiviCRM > Option Lists > Activity Types). The ability to define custom activity types, and extend them with custom fields provides a powerful tool for tracking a wide variety of organisation activities. For example, you could choose to track activities such as press releases, press conferences, site visits or voluntary work.

Activities are a great way to store interactions that happen at a specific time, or that link specific people.  If it is important for you to know who at your organisation carried out a task, then record it as an activity. Another advantage of activities is that they record when something has happened, which is useful if you need to report on the volume of activities performed during a specific time period. You can record an activity between a given contact and multiple other contacts by adding as many contacts as you like in the With Contact field on the Add Activity form.

Activities usually have their status set to Completed or Scheduled, however you may add other types of activity status as appropriate for your organisation.

 Contact_ActivityTab

Contributions tab

The Contributions tab shows any financial contributions made by the contact whose details you are viewing, as well as a summary of the contribution activity of the contact (total amount of contributions over time, total number of contributions, and average amount of contributions).

The Contributions tab also allows you to record off-line contributions using the Record Contribution button, or record a credit card transaction on behalf of the contact (useful if the contribution has been made by phone) using the Submit Credit Card Contribution button. Both of these buttons lead to forms that allow you to select the contribution type in addition to the normal contribution information collected from public contribution pages.

Contact_COntribTab

Memberships tab

This tab displays the memberships a contact has signed up for. From this tab you are able to add memberships and submit credit card payments for memberships that require a fee. You can also renew or delete memberships from the "more" link on each membership in the contact's existing memberships.

Contact_MembershipTabs

Events tab

The Events tab displays events related to this contact, whether they are events the contact has registered for, attended, volunteered at or is any other of the user-configurable event statuses.

From this page you can register the contact for an event, and use the Submit Credit Card Event Registration button if the event requires payment. The related payment will then appear up on the contact's Contributions tab in the first row.

You can also modify the event information as it relates to the contact by clicking the Edit link. For example, you can change the contact's event status from "registered" to "attended".

Contact_Eventstab

Groups tab

The Groups tab shows the groups that the contact is a member of. Groups can be used in a variety of ways including mailing lists and permissions (ACLs).

You can add and remove the contact from groups, and see a history of groups the contact has unsubscribed or been removed from.

The Status column displays who has added the contact to the group. Whether users can add themselves to a group is one of the settings you can configure when creating a group. When you set a group's visibility to "Public Listings" users can join via Profile forms. You may want to familiarise yourself with the discussion on using Profiles for mailing list sign-ups covered in a later section. 

Contact_GroupsTab

Notes tab

The Notes tab is a place where you can record random bits of information about a contact. Generally you would use custom fields for information you plan to collect about your contacts, but in some cases it may be useful to record additional, ad-hoc notes about a contact. Since this information is unstructured, you should be careful about using the Notes tab, unless you know that you or other people using your CiviCRM implementation will remember to look at that tab. When creating a Note both the subject and the content are free-text fields (i.e. the subject field does not have to be chosen from predefined options).

You can specify "Author Only" privacy for a note. This means that only the person who wrote the note, or someone with "view all notes" permission (Drupal only) can view or edit it.

Contact_NotesTab

Tags tab

Tags are one way of categorising contacts in your database (other methods are Custom Data and Groups). You can configure which tags you wish to use for your organisation. You can search on tags and create Smart Groups based on them.

The tags next to Keywords are part of the Keywords Tagset. A Tagset is a specific grouping of tags that you can create. Tagsets are non-hierarchical, and you can create a new tag in a tagset simply by typing a new tag into the field. Existing tags that match what you type will also show up as a list from which you can select.

Contact_TagTab 

Change Log tab

This tab gives limited information about changes made to a contact record. It shows the change date and who made the change, but not what was changed.

Contact_ChangeLog

NOTE: Administrators can use the Contact Logging Report to get detailed information on changes to contact records (who, what and when).

Modifying the contact screens

After working with the contact editing and summary screens for a while, you may realise that there are sections and/or fields that aren't useful for your organisation. The good news is that you can easily hide some fields and sections. For example, if your organisation doesn't need to store demographics information, you can remove it by configuring the Site Preferences:

Similarly, if you want to remove (or add) fields in the postal address section:

CREDITS

WHAT IS CIVICRM?

Modifications:
adam - adam hyde 2011

REAL WORLD EXAMPLES

Modifications:
WHO IS CIVICRM?

Modifications:
adam - adam hyde 2011
IS CIVICRM FOR YOU?

Modifications:
adam - adam hyde 2011
IDENTIFYING YOUR NEEDS

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
TRANSITIONING TO CIVICRM

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
INSTALLATION & BASIC SET-UP

Modifications:
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
adam - adam hyde 2011
EMAIL SYSTEM CONFIGURATION

Modifications:
techczech - Dominik Lukes 2011
SECURITY

Modifications:
adam - adam hyde 2011
OVERVIEW

Modifications:
reperry - Robyn Perry 2011
davem - Dave Moreton 2011
adam - adam hyde 2011
CONTACTS

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
GROUPS AND TAGS

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
ACTIVITIES

Modifications:
davem - Dave Moreton 2011
michaelmcandrew - Michael McAndrew 2011
RELATIONSHIPS

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
CUSTOM FIELDS

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
PROFILES

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
MENU, DASHBOARD & DASHLETS

Modifications:
reperry - Robyn Perry 2011
WHAT IS CIVICRM?

Modifications:
SEARCHING

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
REAL WORLD EXAMPLES

Modifications:
IMPORTING DATA

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
EXPORTING DATA

Modifications:
adam - adam hyde 2011
helen - helen varley jamieson 2011
WHO IS CIVICRM?

Modifications:
ABOUT THIS BOOK

Modifications:
DavidGreenberg - David Greenberg 2011
DEDUPING AND MERGING

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
TOKENS AND MAIL MERGE

Modifications:
techczech - Dominik Lukes 2011
adam - adam hyde 2011
IS CIVICRM FOR YOU?

Modifications:
WHAT IS CIVICONTRIBUTE?

Modifications:
helen - helen varley jamieson 2011
ORGANISATIONAL ANALYSIS

Modifications:
WHAT YOU NEED TO KNOW

Modifications:
davem - Dave Moreton 2011
helen - helen varley jamieson 2011
PROJECT MANAGEMENT

Modifications:
PAYMENT PROCESSORS

Modifications:
davem - Dave Moreton 2011
helen - helen varley jamieson 2011
HOW DATA IS ORGANISED?

Modifications:
PLEDGES

Modifications:
davem - Dave Moreton 2011
adam - adam hyde 2011
EXTENDING CORE DATA

Modifications:
SET-UP

Modifications:
helen - helen varley jamieson 2011
PROFILES

Modifications:
DavidGreenberg - David Greenberg 2011
EVERYDAY TASKS

Modifications:
helen - helen varley jamieson 2011
INSTALLATION

Modifications:
DavidGreenberg - David Greenberg 2011
REPORTS AND ANALYSIS

Modifications:
Abril - Abril Rocabert 2011
michaelmcandrew - Michael McAndrew 2011
WHAT IS CIVIEVENT?

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
MENU AND DASHBOARD

Modifications:
DavidGreenberg - David Greenberg 2011
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
CONTACTS

Modifications:
DavidGreenberg - David Greenberg 2011
TAGS AND GROUPS

Modifications:
SET-UP

Modifications:
reperry - Robyn Perry 2011
helen - helen varley jamieson 2011
SEARCHING

Modifications:
DavidGreenberg - David Greenberg 2011
EVERYDAY TASKS

Modifications:
Abril - Abril Rocabert 2011
helen - helen varley jamieson 2011
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
adam - adam hyde 2011
IMPORTING

Modifications:
DEDUPING AND MERGING

Modifications:
EXPORTING

Modifications:
WHAT IS CIVIMEMBER?

Modifications:
davem - Dave Moreton 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
POSTAL MAIL

Modifications:
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
avaguilar - Alice Aguilar 2011
SET-UP

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
EVERYDAY TASKS

Modifications:
EVERYDAY TASKS

Modifications:
Abril - Abril Rocabert 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
REPORTS AND ANALYSIS

Modifications:
Abril - Abril Rocabert 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
WHAT IS CIVICONTRIBUTE?

Modifications:
PLANNING

Modifications:
CONFIGURING

Modifications:
WHAT IS CIVIMAIL?

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
EVERYDAY TASKS

Modifications:
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
reperry - Robyn Perry 2011
techczech - Dominik Lukes 2011
EVERYDAY TASKS

Modifications:
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
WHAT IS CIVIEVENT?

Modifications:
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
PLANNING

Modifications:
CONFIGURING

Modifications:
WHAT IS CIVIREPORT?

Modifications:
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
EVERYDAY TASKS

Modifications:
DavidGreenberg - David Greenberg 2011
WHAT YOU NEED TO KNOW

Modifications:
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
WHAT IS CIVIMEMBER?

Modifications:
PLANNING

Modifications:
EVERYDAY TASKS

Modifications:
helen - helen varley jamieson 2011
CONFIGURING

Modifications:
EVERYDAY TASKS

Modifications:
WHAT IS CIVICASE?

Modifications:
reperry - Robyn Perry 2011
helen - helen varley jamieson 2011
WHAT YOU NEED TO KNOW

Modifications:
davem - Dave Moreton 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
reperry - Robyn Perry 2011
davem - Dave Moreton 2011
demeritcowboy - Dave D 2011
helen - helen varley jamieson 2011
WHAT IS CIVIMAIL?

Modifications:
EVERYDAY TASKS

Modifications:
reperry - Robyn Perry 2011
demeritcowboy - Dave D 2011
helen - helen varley jamieson 2011
PLANNING

Modifications:
REPORTS AND ANALYSIS

Modifications:
Abril - Abril Rocabert 2011
davem - Dave Moreton 2011
SYSTEM CONFIGURATION

Modifications:
CONFIGURING

Modifications:
EVERYDAY TASKS

Modifications:
WHAT IS CIVICAMPAIGN?

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
WHAT IS CIVICASE?

Modifications:
EVERYDAY TASKS

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
PLANNING

Modifications:
CONFIGURING

Modifications:
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
EVERYDAY TASKS

Modifications:
WHAT IS SURVEY?

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
WHAT IS CIVICAMPAIGN

Modifications:
avaguilar - Alice Aguilar 2011
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
CAMPAIGN PLANNING

Modifications:
michaelmcandrew - Michael McAndrew 2011
SET-UP

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
CAMPAIGN CONFIGURATION

Modifications:
michaelmcandrew - Michael McAndrew 2011
EVERYDAY TASKS

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
CAMPAIGN EVERYDAY TASKS

Modifications:
michaelmcandrew - Michael McAndrew 2011
WHAT IS CIVIENGAGE?

Modifications:
WHAT IS PETITION?

Modifications:
reperry - Robyn Perry 2011
helen - helen varley jamieson 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
PLANNING

Modifications:
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
INSTALLING

Modifications:
CONFIGURING

Modifications:
EVERYDAY TASKS

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
EVERYDAY TASKS

Modifications:
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
WHAT IS GOTV VOTER TRACKING?

Modifications:
reperry - Robyn Perry 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
WHAT IS CIVIREPORT?

Modifications:
PLANNING

Modifications:
CONFIGURING

Modifications:
WHAT IS CIVIENGAGE?

Modifications:
reperry - Robyn Perry 2011
helen - helen varley jamieson 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
EVERYDAY TASKS

Modifications:
WHAT YOU NEED TO KNOW

Modifications:
reperry - Robyn Perry 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
helen - helen varley jamieson 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
INTRODUCTION

Modifications:
EVERYDAY TASKS

Modifications:
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011
TEMPLATES

Modifications:
REPORTS AND ANALYSIS

Modifications:
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
REPORTS

Modifications:
CUSTOM SEARCHES

Modifications:
theMusician - Max Bronsema 2011
WHAT IS CIVIGRANT?

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
API

Modifications:
JoeMurray - Joe Murray 2011
WHAT YOU NEED TO KNOW

Modifications:
michaelmcandrew - Michael McAndrew 2011
helen - helen varley jamieson 2011
SET-UP

Modifications:
michaelmcandrew - Michael McAndrew 2011
helen - helen varley jamieson 2011
HOOKS

Modifications:
IMPORTS

Modifications:
EVERY DAY TASKS

Modifications:
michaelmcandrew - Michael McAndrew 2011
helen - helen varley jamieson 2011
DEVELOPER TIPS

Modifications:
REPORTS AND ANALYSIS

Modifications:
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
CIVICOMMUNITY

Modifications:
CIVICRM COMMUNITY

Modifications:
adam - adam hyde 2011
LOCALISATION

Modifications:
BUG REPORTING

Modifications:
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011
BUG REPORTING

Modifications:
LOCALISING CIVICRM

Modifications:
adam - adam hyde 2011
CONTRIBUTING TO THIS MANUAL

Modifications:
adam - adam hyde 2011
HOW TO CONTRIBUTE?

Modifications:
HISTORY OF THIS BOOK

Modifications:
DavidGreenberg - David Greenberg 2011
HISTORY OF THIS BOOK

Modifications:
adam - adam hyde 2011
ABOUT FREE SOFTWARE

Modifications:
ABOUT FREE SOFTWARE

Modifications:
GLOSSARY

Modifications:
Abril - Abril Rocabert 2011
helen - helen varley jamieson 2011
GLOSSARY

Modifications:
CREDITS

Modifications:
adam - adam hyde 2011
CREDITS

Modifications:

Cover Art (faces) by Kapor Creative: Jake Mix & Trevor Parham (Jake created the illustrations, and Trevor developed the concept of the civi logos as eyes). Cover Art is CC-BY-SA

All chapters copyright of the authors (see below). Unless otherwise stated all chapters in this manual licensed with GNU General Public License version 2

This documentation is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Authors

ABOUT THIS BOOK
© Michael McAndrew 2010
Modifications:
adam hyde 2010
David Greenberg 2010
helen jamieson 2010
HOW TO CONTRIBUTE?
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Kyle Jaster 2010
Michael McAndrew 2009, 2010
Yashodha Chaku 2009
LOCALISATION
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009, 2010
Cynthia Tarascio 2009
David Greenberg 2010
Dream Gomez 2009
Eileen McNaughton 2009
Erik Brouwer 2010
Jack Aponte 2010
Mathieu Petit-Clair 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
BUG REPORTING
© adam hyde 2009
Modifications:
Andy Oram 2009
Cynthia Tarascio 2009
Eileen McNaughton 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
INSTALLATION
© David Greenberg 2009
Modifications:
adam hyde 2009, 2010
Alice Aguilar 2010
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
Kurund Jalmi 2010
Michael Gross 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Tony Guzman 2009
PROFILES
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009
Brian Shaughnessy 2009
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
jay maechtlen 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
Yashodha Chaku 2009
CONFIGURING
© adam hyde 2010
Modifications:
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
PLANNING
© adam hyde 2010
Modifications:
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
CIVICOMMUNITY
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Jack Aponte 2010
Michael McAndrew 2010
EXTENDING CORE DATA
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Andy Oram 2010
David Greenberg 2010
Erik Hommel 2010
helen jamieson 2010
Kurund Jalmi 2010
Manuel Schmalstieg 2010
Mari Tilos 2010
xavier dutoit 2010
CONFIGURING
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Michael McAndrew 2010
PLANNING
© adam hyde 2010
Modifications:
Andy Oram 2010
Michael McAndrew 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Mari Tilos 2010
Michael McAndrew 2010
WHAT IS CIVICONTRIBUTE?
© adam hyde 2010
Modifications:
Andy Oram 2010
Kyle Jaster 2010
Michael McAndrew 2010
MENU AND DASHBOARD
© Michael McAndrew 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2010
CONFIGURING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
David Greenberg 2010
Jack Aponte 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Tim Homewood 2010
EVERYDAY TASKS
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Jack Aponte 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
INSTALLING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
PLANNING
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Jack Aponte 2010
Michael McAndrew 2010
Michael McCallister 2010
CONFIGURING
© adam hyde 2010
Modifications:
Andy Oram 2010
David Greenberg 2010
EVERYDAY TASKS
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
Mari Tilos 2010
Michael McAndrew 2010
Sarah Gladstone 2010
PLANNING
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Michael McAndrew 2010
xavier dutoit 2010
WHAT IS CIVIEVENT?
© adam hyde 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Christopher Gervais 2010
Jack Aponte 2010
xavier dutoit 2010
CONFIGURING
© Kurund Jalmi 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2010
TWikiGuest 2010
EVERYDAY TASKS
© Michael McAndrew 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
TWikiGuest 2010
PLANNING
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
WHAT IS CIVIREPORT?
© Michael McAndrew 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
David Greenberg 2010
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Sarah Gladstone 2010
CONFIGURING
© xavier dutoit 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
Graham Mitchell 2010
Mathieu Lutfy 2010
Michael McAndrew 2010
Sarah Gladstone 2010
Tim Homewood 2010
IMPORTING
© Peter Davis 2009
Modifications:
adam hyde 2009, 2010
Alice Aguilar 2010
Andy Oram 2010
Cynthia Tarascio 2009
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
CREDITS
© adam hyde 2006, 2007, 2009, 2010
Modifications:
Cynthia Tarascio 2009
Michael McAndrew 2009, 2010
HOW DATA IS ORGANISED?
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2009, 2010
Brian Shaughnessy 2009
Brylie Oxley 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
jay maechtlen 2009
Janet Swisher 2009
Kurund Jalmi 2010
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Peter Davis 2009
TWikiGuest 2009
Tony Guzman 2009
xavier dutoit 2010
DEDUPING AND MERGING
© Jack Aponte 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Jeff Sherk 2010
Kyle Jaster 2010
Mari Tilos 2010
xavier dutoit 2010
API
© Wes Morgan 2010
Modifications:
adam hyde 2010
Brylie Oxley 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
CUSTOM SEARCHES
© Wes Morgan 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Sarah Gladstone 2010
HOOKS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
Kyle Jaster 2010
Mathieu Lutfy 2010
Michael McAndrew 2010
xavier dutoit 2010
IMPORTS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
INTRODUCTION
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
xavier dutoit 2010
REPORTS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Erik Hommel 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
TEMPLATES
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Sarah Gladstone 2010
xavier dutoit 2010
DEVELOPER TIPS
© Wes Morgan 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
xavier dutoit 2010
EXPORTING
© Kurund Jalmi 2010
Modifications:
adam hyde 2010
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2010
EVERYDAY TASKS
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
David Greenberg 2010
Josue Guillen 2010
Michael McAndrew 2010
REAL WORLD EXAMPLES
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
jay maechtlen 2009
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Peter Davis 2009
Roberto Santiago 2009
Tony Guzman 2009
ABOUT FREE SOFTWARE
© Michal Mach 2009
Modifications:
adam hyde 2009, 2010
Cynthia Tarascio 2009
Mari Tilos 2009
Michael McAndrew 2009, 2010
EVERYDAY TASKS
© Jack Aponte 2010
Modifications:
adam hyde 2010
helen jamieson 2010
Michael McAndrew 2010
Tim Homewood 2010
GLOSSARY
© adam hyde 2009, 2010
Modifications:
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2009, 2010
Lachlan Musicman 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
TAGS AND GROUPS
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
xavier dutoit 2010
Yashodha Chaku 2009
CONTACTS
© adam hyde 2009, 2010
Modifications:
alan zucker 2009
Andy Oram 2009
David Greenberg 2009
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009, 2010
Michael McAndrew 2009
Michal Mach 2009
Peter Davis 2009
TWikiGuest 2009
Yashodha Chaku 2009
HISTORY OF THIS BOOK
© Michael McAndrew 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Sarah Gladstone 2010
WHAT IS CIVICRM?
© Michal Mach 2009
Modifications:
adam hyde 2009, 2010
Andy Oram 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Peter Davis 2009
IS CIVICRM FOR YOU?
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009
Benjamin Melançon 2010
Cynthia Tarascio 2009
Duncan Hutty 2009
Eileen McNaughton 2009
helen jamieson 2010
Jack Aponte 2010
Janet Swisher 2009
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
POSTAL MAIL
© adam hyde 2009, 2010
Modifications:
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2010
helen jamieson 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
xavier dutoit 2010
WHAT IS CIVIMEMBER?
© adam hyde 2009, 2010
Modifications:
Andy Oram 2009, 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
TWikiGuest 2009
Tony Guzman 2009
Tracy Smith 2009
EVERYDAY TASKS
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
David Greenberg 2010
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
TWikiGuest 2009
Tony Guzman 2009
CONFIGURING
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
Brian Shaughnessy 2009
Cynthia Tarascio 2009
David Greenberg 2010
Eileen McNaughton 2009
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Tony Guzman 2009
PLANNING
© adam hyde 2009, 2010
Modifications:
Andy Oram 2010
Brian Shaughnessy 2009
Eileen McNaughton 2009
Joe Murray 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Mari Tilos 2009
Michael McAndrew 2009, 2010
TWikiGuest 2009
Tony Guzman 2009
ORGANISATIONAL ANALYSIS
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009, 2010
Cynthia Tarascio 2009
Eileen McNaughton 2009
helen jamieson 2010
Janet Swisher 2009
Mari Tilos 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Phil Mocek 2010
Tony Guzman 2009
PLANNING
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Josue Guillen 2010
Michael McAndrew 2010
TWikiGuest 2010
PROJECT MANAGEMENT
© adam hyde 2009, 2010
Modifications:
Alan Schacter 2009
Andy Oram 2009, 2010
Cynthia Tarascio 2009
David Greenberg 2009
Eileen McNaughton 2009
Erik Hommel 2010
helen jamieson 2010
Jack Aponte 2010
Janet Swisher 2009
Joe Murray 2010
Mari Tilos 2009, 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
SEARCHING
© adam hyde 2009, 2010
Modifications:
Alice Aguilar 2010
Andy Oram 2010
David Greenberg 2009, 2010
Eileen McNaughton 2009
helen jamieson 2010
Kurund Jalmi 2009, 2010
Kyle Jaster 2010
Mari Tilos 2010
Michael McAndrew 2009, 2010
Michal Mach 2009
Peter Davis 2009
Tony Guzman 2009
Yashodha Chaku 2009
SYSTEM CONFIGURATION
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Christoph Berendes 2010
Joe Murray 2010
Kurund Jalmi 2010
Michael McAndrew 2010
WHAT IS CIVIENGAGE?
© Alice Aguilar 2010
Modifications:
adam hyde 2010
Josue Guillen 2010
Kurund Jalmi 2010
Kyle Jaster 2010
Michael McAndrew 2010
Michael McCallister 2010
Tim Homewood 2010
WHAT IS CIVIMAIL?
© xavier dutoit 2010
Modifications:
adam hyde 2010
Andy Oram 2010
Graham Mitchell 2010
Lachlan Musicman 2010
Michael McAndrew 2010
TWikiGuest 2010
WHAT IS CIVICASE?
© adam hyde 2010
Modifications:
Andy Oram 2010
helen jamieson 2010
Josue Guillen 2010
Kyle Jaster 2010
Lachlan Musicman 2010
xavier dutoit 2010
WHO IS CIVICRM?
© adam hyde 2009, 2010
Modifications:
David Greenberg 2009
Eileen McNaughton 2009
Jack Aponte 2010
Mari Tilos 2010
Michael Lenahan 2009
Michael McAndrew 2009, 2010
Michael McCallister 2010
Michal Mach 2009
Peter Davis 2009
 

100.gif

Free manuals for free software

 

General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:


a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:


a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

Deduping and Merging

Duplicate contacts can turn up in your data for many reasons, such as mistakes by users who don't realise they're creating a contact for someone who is already in CiviCRM, duplicates that aren't caught in the import process and duplicate records created when people fill in forms about themselves (maybe with their names spelled differently or with a different email address) on your site without realising they're already in your list of contacts.

CiviCRM is equipped with duplicate matching rules that are applied automatically when new contacts are created, and can be run manually at any time to search for duplicates. You can configure these rules to suit your needs.

To view the dedupe rules, go to Contacts > Find and Merge Duplicate Contacts in the navigation menu. This displays the following screen:

rules

From the screen, here's an example of a process to dedupe all individuals in your data:

  1. Start by looking for dupes using a strict rule: click the Use Rule link for the third row (Contact Type: Individual, Level: Strict).
  2. Select All Contacts or a particular group.
  3. Click Continue.
  4. If duplicates are found, merge or delete the duplicate contacts.
  5. Now look for dupes using a fuzzy rule to find those dupes that were missed with the stricter rule: Click the Use Rule link for the fourth row (Contact Type: Individual, Level: Fuzzy).
  6. Select All Contacts or a particular group.
  7. Click Continue.
  8. If duplicates are found, merge or delete the duplicate contacts.

Different rules are configured for each contact type (individuals, organizations, and households.)  A default fuzzy rule and a default strict rule is set for each contact type. The default rules are used when CiviCRM invokes automatic checking, in ways we'll explain in detail shortly.

Strict and fuzzy rules

CiviCRM includes two categories of dedupe rules:

Configuring rules

To determine whether two contacts are duplicates, CiviCRM checks up to five fields that you can specify. You can also set a length value which determines how many characters in the field should be compared. For example, if you set a length of 2 on the First name field, a first name of "Mike" would match "Michael" and they would be recognized as duplicates, because the first 2 characters are the same. However, if you set the length to 3 instead, "Mike" would no longer match "Michael" and they would be accepted as different contacts. If the length value is left blank, the comparison is done on the entire field value.

Each field is also configured with a numeric weight that determines the relative importance of a match on that field. When a match is discovered on a field, that field's weight is added to the total weight for the rule. After each field is checked, if the total weight is equal to or greater than the numerical threshold set for the rule, the contacts being compared are flagged as suspected duplicates.

Using rules and merging duplicate contacts

  1. Go to Administer > Manage > Find and Merge Duplicate Contacts. 
  2. Click the Use Rule link to scan for duplicate contacts using the selected rule. 
  3. You can then select to search all contacts for duplicates or to search only a particular group. Contacts of the type to which the rule is assigned will be scanned and compared. If the match between two contacts exceeds the rule's threshold, the contacts will be displayed on the following screen of possible duplicates.
  4. Clicking Merge for any pair of contacts brings up a table showing details for each contact. CiviCRM designates one record as the duplicate record and displays its information in the left column. The record in the right column is considered the original record into which selected data from the duplicate record will be merged. 
  5. If you want to move the information in the opposite direction, you can swap the duplicate and original contacts by choosing Flip between original and duplicate contacts.
  6. For each field, you can choose whether to keep the original data shown on the right (don't check the check-box in the middle column), or use the value from the duplicate contact instead (check the box). For the email addresses or phone numbers, you can decide to keep both the value of the duplicate and of the original (check both the checkbox in the middle column and the "add new" on the right column) to copy the duplicate data. Note that associated tags, groups and activity data (including event attendance, contributions, etc.) will appear in addition to data already recorded in the original record, not in place of it. It is safer in general to keep the tags, groups and activities of both contacts after the merge.

Merging contacts from search results

If you notice duplicate contacts within a set of search results you can quickly merge them directly from the search results instead of using the separate Find and Merge Duplicate Contacts process. This is a great way to clean up your database during your everyday workflow with minimal disruption.

  1. Select the duplicate contacts from your search results by clicking the check box at the left side of each record. 
  2. Select Merge Contacts from the - more actions - menu.
  3. Click Go.
  4. Follow the normal steps for merging duplicate contacts.

REPORTS AND ANALYSIS

CiviMail has a number of tools for reporting and analysis, indeed reporting is one of the key reasons to use CiviMail.

Individual mail reports 

You can view a report for each individual mailing from the scheduled and sent mailings screen.  These reports are based on live information about your data you should feel free to track your emails in real time on this screen by refreshing the page.  Each mailing report is broken down into a few sections.

Delivery summary

report_email 

The delivery summary shows some high level statistics about the mailing.

Intended recipients shows the number of people that the mailing was  intended to be sent to.  Clicking on Intended recipients will show each of the contacts.

Tracked opens shows the number of people that CiviCRM 'thinks' have opened the email.  In the world of email, there is no 100% reliable way of knowing when someone has opened an email.  CiviCRM uses a trick that is common amongst mass mailers - it embeds a small image with a unique name in each email. When a client views the email and downloads the image, CiviCRM knows that they have read the email. Because this technique is common, to protect people's privacy, most email clients ask users to confirm whether they want to download images in emails.  Hence you'll only get an accurate picture of how many people have opened your email if they all choose to download pictures.  Because this never happens in practice, tracked opens statistics should be taken as indicative, rather than accurate.

Click throughs shows the total number of times that people have clicked links in email. Forwards show the amount of times people have forwarded the email using the forward link which is a token that you can include in your mailing.  Replies shows the number of times that people have replied to the email if you have enabled reply tracking.  Bounces show the number of email addresses that could not be successfully delivered to if you have enabled bounce processing.  Unsubscribe requests shows the amount of people that have clicked on any unsubscribe links that you include in your email.

Click through summary 

In this section, click through statistics are shown for each link.  There are two statistics, Clicks (i.e. the number of times that a link has been clicked) and Unique clicks (i.e. the number of people that have clicked on links).

Mailing reports with CiviReport

CiviReport has four reports, Bounce, Summary, Clickthroughs and Opens, which offer similar functionality to what is described above.  The major advantages of looking at the reports via CiviReport are that:

Read the CiviReport section for more information on CiviReport.

 

Reports and analysis

There are a number of techniques for reporting on and analysing your events and participants. 

The event dashboard gives a quick overview of your upcoming events showing for each event the number of registrations and their statuses (how many are registered, how many are counted, how many are pending for different reasons). The dashboard is limited to 12 events scheduled to start at a date closest to today. This is most likely not to be sufficient to organizations with many scheduled events.

[insert screenshot]

Other ways that provide more detailed and customised analysis using CiviCRM's search features and CiviReport.

If you are interested in the financial aspects of events, you may also find the reports and analysis chapter in contributions useful. 

Event and participant reports

Reports have several features that cannot be accomplished by search.  For instance, you cannot agregate data from multiple events at once or limit the date of registration very flexibly. Also, repeating the same searches over and over can be very time consuming. Searches can be set as Smart Groups but this leads to a proliferation of groups.

The solution is to set up reports for each event or a collection of events. The reports can be automatically assigned to a designated submenu (e.g. under Events > Reports) or made available as dashlets for the main dashboard.

Out of the box, CiviCRM comes with five reports designed to help you analyse events. Of these, Event Participant Report (List) is the most useful. It will display both participant and individual data and all custom data. All of these can also be used as filters.

The Event income report (detail) and Event income report (summary) work together to show details of revenue from events. The summary report is suitable for showing total income for a series of events, all your conference in 2011, for example.  Clicking on one of those events will give you more details about the event breakdown of the income per role and per status. It can also be displayed in graphical form as Pie Chart or Bar Chart.

Searching based on participant data

CiviCRM makes an important distinction between contacts and event participants.  Sometimes it is useful to get the answer to your event related question in terms of contacts, e.g. which contacts came to events in 2011.  Other times it is more useful to have the answer in terms of participants, e.g. how many training sessions did we deliver as part of our sexual health education programme this year. It is important to take this into consideration when carrying out a search for event attendees.

The Find participants search allows you to search based on participant data and return participant data.  The Advanced search allows you to search based on most participant information and combine that with other contact information and return contacts.  You can also choose Participant from the column to show participants rather than contacts.

Searching based on these criteria gives you access to simple totals. You can also export your search results as CSV for further analysis in your spreadsheet software.

More analysis

If you can't do what you want with a built in report or search, consider commissioning a new report or custom search. Read the CiviReport section for more information.

 

EVERY DAY TASKS

This section discusses the every day tasks associated with administering grants with CiviGrant. 

CiviGrant Dashboard 

Go to Other > Grants > Dashboard to access the CiviGrant Dashboard. Here you will see a summary of the grants registered in your CiviCRM database, and a table of recent grant recipients.

Viewing grants

There are a couple of ways to view grants:

Adding and editing grant recipients

After Wookie Hole Community Action selected its grant recipients for the Cave Festival, their grant administrator looked up the contact record of each successful applicant and entered a new grant record for each one.

To add or edit grant recipients: 

  1. Go to Other > Grants > New Grant.
  2. Either select an already existing contact or create a new contact to add the grant to.
  3. Complete the details of the grant. Fill in as many details as possible, including any custom data that has been set up; but you can also edit and update the grant details at a later stage.
  4. Click Save.

Grants can be edited and updated at any time using the edit link which appears in the grant record. 

Recording Reports

When reports are received from grant recipients, you can edit the grant information (either from the CiviGrant dashboard or the contact's record). Check the Grant Report Received? box in the form and add any appropriate notes.

Everyday Tasks

This chapter describes a list of everyday tasks that you might perform using CiviCase, and how to go about them.

Viewing the Case Dashboard

The Case Dashboard gives you an easy way to keep track of case-related tasks. It provides:

If you have permission to view cases other than ones that you are working on, you also have the option to see:

You can switch between viewing Your Cases and All Cases by clicking on the link at the top right of the content area.

Click the Edit icon next to the Next Sched. activity name to work on that task. In the case shown in the following screenshot, the Next Sched. activity is Medical evalution. You can view this activity in a pop-up window by clicking directly on the title. If you're ready to work on that activity, click the edit pencil to the right of the activity title.

CaseDashboard  input field

Click on the triangular expand icon (►) to the left of the client name to see the complete list of activities for that case. From this list you can view or edit any activity in that case. Click Manage Case when you want to work on a number of tasks within a case or to change the status of the case, print a case report, or view case roles.

To add a new case from the Case Dashboard, click the Add Case button at the top left of the content area.

Finding cases

If you know the Case ID, you can quickly find the case by using full-text search, either from Search > Custom Search > Fulltext Search or from the fulltext search block if you have enabled it.

You can search for cases by going to Search > Find Cases or under Cases in the menu bar at the top of the CiviCRM screen. The Cases search form gives you a number of options. You can search by each option individually, or combine them for further filtering.

You can search by:

If you make selections in multiple criteria (e.g. adding a client name, checking off a case type, and selecting "all cases") the search criteria will be combined so that the results must fulfill at least one requirement in each set of criteria (the cases found will contain the client name AND case type). In contrast, making multiple selections within one set of criteria (e.g., checking two case types) will ensure that the returned results fulfill at least one of the selections in the criteria set (in this example, cases must match at least one of the case types).

Opening a new case

You can open a new case with either an existing contact or a new contact not yet in your system.

Creating a case from an existing contact's summary screen or actions menu automatically links the case to that contact. To open a case on an existing contact, follow these steps:

  1. Go to the contact's summary screen.
  2. Select Add Case from the Actions dropdown menu, or alternatively click on the Cases tab.
  3. Fill in the required fields in the Add Case form.
  4. Click Save.

If you open a new case for a new contact, the contact's record in CiviCRM is created at the same time as you create the case. Follow these steps:

  1. Go to Cases > New Case or select the Create New > Case dropdown button. This button is provided as a block in Drupal or on the left hand side in Joomla!. (Remember, if you haven't made Case a top-level menu item, you'll have to navigate to Other > Cases > New Case.)
  2. If you've opted to create a new case without navigating to an existing contact first, you may want to check whether the contact already exists in the database. Type the name or email of the contact you are looking for in the Select Contact field, and you will see a list of potential matches (as illustrated by the following screenshot).

    NewCaseSelectContact 

  3. If you don't find the contact, you can create it immediately by selecting the type of contact from the create new contact list. This opens a pop-up window (shown in the following screenshot) that allows you to fill out the new contact's name and other information while opening the case. The fields in this pop-up window are controlled by the fields in the Add Individual profile. This means you can easily add or modify the fields provided. You can read more about profiles in the Profiles chapter.

    NewCaseCreateContact

    Use the Medium and Location fields to record information about where and how this case came to your attention. For example, you might select In Person for Medium and At the Annual Gala for Location.

    Use the Details text area to add information pertaining to the overall case, but not to a specific activity of the case. An example might be "Jane is concerned about some illegal land use that she has witnessed in her neighbourhood, and would like us to see what can be done about it. I told her that the best person to look into this was Tom, and she asked whether her husband could be included on any correspondence."

    The Subject field is displayed in search results and in other listings of cases, next to the name of the case client. Keep this in mind when entering the subject text: a brief and unique description of the case will be more helpful than using the client's name as the subject.

    The Case Type selector allows you to choose the type of case that you are creating. Many case types have specific activities and timelines, so it is important to choose the appropriate case type at this point. You can change to a different case type at a later point by clicking Manage Case next to the case when it's displayed in the CiviCase Dashboard, or from the contact's record Case tab. Then select Change Case Type from the New Activity dropdown menu. Changing an ongoing case may require you to then update or re-enter some data.

    The Case Status selector allows you to indicate the current status of the case. Generally you will use a status such as Ongoing or Urgent, but if you are adding a case that has already been completed (for tracking purposes) select Resolved.

    The Case Start Date field defaults to the current day. If you are creating a case that has already been completed or entering data for upcoming cases (not yet started), adjust the case start date accordingly.

    The Duration field records the time spent collecting the data needed to fill out the create case form, not the amount of time it took to fill the form out. Fill out the number in minutes. For example, you might use this field to record the number of minutes spent on the phone with a constituent as they described the case.

  4. After you complete the fields in the pop-up window, clicking the Save button saves the case and loads the Manage Case page, where you can then modify activities, add attachments and assign case roles. Alternatively, clicking Save and New saves the case and resets the form so that you can add further new cases uninterrupted (this is particularly useful if you are doing data entry). Clicking Cancel discards the case data you have entered and sends you back to the CiviCRM dashboard.

Assigning case roles

You can assign case roles to contacts who are working on the case or need to stay informed about case activities. Users who have access to CiviCase and are assigned a role in the case will then see that case in their My Cases view. The phone number and email address of each person with a case role will be displayed on the case, making it easy to communicate with them (see screenshot).

CaseRoles

Within a case, you can assign a case role to a contact:

  1. Click the Case Roles area to open it.
  2. Case roles that have not been assigned display (not assigned) in the Name column. Click the edit icon to assign someone to that role.
  3. The Assign Case Role pop-up window will appear. Begin typing the last name of the contact until you see the name in the dropdown list.
  4. Select the contact you want to assign to the role and click OK.

Generally, anyone who might be assigned to a case should already be in the database, but if you can't find the person you're looking for, you must add her as a contact first (navigate to Contacts > New Individual).

Each assigned case role has mail, edit and delete icons under the Email and Actions columns. You can email contacts with roles in the case, or modify their relationships to the case. Change the case role by clicking the edit icon, or delete a case role by clicking the delete icon. Emails that you send from here are automatically added to the list of case activities in the proper sequence. This provides an audit trail of case-related communications, and ensures that the case story is complete.

Finding activities within a case

You may need to find a specific activity within a case, for reference or modification. To view the activities in the case, scroll down to the Case Activities section and click it to open it. In the default view, scheduled activities are listed first, sorted by date, followed by completed activities. Click on the column headers to sort by a specific column (for example, by activity type).

If there are many activities, you can filter them to see a smaller subset. You may want to view activities of a certain type (for example, to see all of the Follow up activities that have been performed for this case). Click the Search Filters button, which opens a form that allows you to filter by:

Once you have selected your search criteria, click the Search button to the right and the table will automatically filter out all of the activities not matching your criteria.

CaseActivitySearch 

Adding and managing activities

Several tasks are commonly performed on activities. After performing the necessary work, click the Save button to save the activity and be sent back to the case page, or Cancel to discard your work.

To add a new activity to a case

  1. Navigate to the case (either using Find Cases or via the Cases Dashboard).
  2. Choose an activity type from the select list labeled New Activity in the Case Summary.
  3. Click Go.
  4. Fill out the activity form. The Client field will be pre-populated with the case's client data.

To send a copy of the activity to anyone with a case role for the case

  1. Open the Send a Copy area.
  2. Check the contacts or case roles whom you would like to be alerted about this activity.

To schedule a follow up activity

  1. Open the Schedule Follow-up area.
  2. Select the follow-up activity type, the number of days until the follow-up should occur, and subject of the follow-up (e.g. "confirm that Jane's problem is fixed").
  3. Click Go.
  4. Complete the form and click Save.

To add an attachment to the activity

  1. Open the Attachments area.
  2. Click a Choose file button.
  3. Up to five files can be attached to an activity. Select an attachment from your file browser.
  4. Click Choose. The name of the attachment will appear to the right of the Choose file button.

The attachment will not be saved into CiviCRM until you have saved the activity.

Editing an activity in a case

To edit an activity in a case:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click Edit at the far right side of the activities table at the bottom of the case form.
  3. This brings you to the activity form, which you can edit in the same way as when creating an activity for a case. The only difference is that many of the fields will already be filled in.

To assign a scheduled task to a staff member while adding or editing a case:

  1. Start typing the staff member's name into the Assigned to field; a list of possible contacts will appear.
  2. Select from the list of suggestions and make sure the staff member's full name shows up in the Assigned to field.

You can assign multiple contacts to an activity. If you accidentally select the wrong contact, click the X by the contact's name to remove him from the list.  

Changing the status of a case

The case status lets you quickly determine how a case is progressing. Sample status values include Ongoing, Resolved, Not Assigned, and Urgent. 

To change the status of a case:

  1. Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.
  2. Click Manage Case.
  3. Click the Edit icon next to the current status column in the Case Summary table. 
  4. This will open the Change Case Status form (an activity with an additional field called Case Status).
  5. Set the case status to the new status.
  6. Modify the other the fields as you would when editing an activity in a case. Make sure to set the Status field. It is required, but not set by default. 
  7. Click Save to return to the case page, with a message stating that the Change Case Status Activity has been created.

An activity is recorded because when a case status changes, it changed because something happened. It is usually equally as important to record the who and the why as well as the what. This behaviour is consistent throughout CiviCase. 

For information on reporting, see the following chapter on Reports & Analysis.  

Exporting Your Contacts

Exporting lets you share data with external applications by providing a copy of data from CiviCRM in a standard comma separated value (CSV) format. This format can be viewed and edited in spreadsheet applications, imported into other database applications, or merged with word processing documents.

You can either export a predefined set of fields or create your own custom export mapping which can be saved for reuse.

CiviCRM's export functionality is available:

Here's how you can export contact information:

  1. Search for contacts. Carry out a search based on your desired criteria using one of the available search tools, e.g. Quick search, Find Contacts, Advanced search, Search Builder, or a custom search (you can find out more about performing searches in the Searching chapter earlier in this section).
  2. Select contacts you wish to export. Select all records, or choose individual records for export using the check-boxes to the left of each record. 
  3. From the - actions - dropdown menu, choose Export Contacts as shown in the following figure.
  4. Click Go. This takes you to the export wizard.

    ExportFromSearch
  5. Export primary (default) or selected fields. Choose between exporting the primary fields or selecting your own set of fields for export. The primary fields include all core contact fields with email, phone, and address data. 
  6. If this is satisfactory, click Continue and skip step 7 of this list. If you want to add or remove fields to be exported, choose Select fields for export and continue with step 7. The default export uses primary location data, so if you wish to export non-primary addresses you need to select fields for export and explicitly specify the address type
  7. Select Fields to Export Choose the fields you want to export. CiviCRM allows you to save this export mapping, which enables you to reuse the export field mapping at a later time. To save your selection of fields, click Save this field mapping at the bottom of the form and enter a descriptive name for this type of export.

    ExportSelectFlds
  8. Click Export to create your CSV file. By default, a comma is used as the field separator for import and export functions. In some locales, other characters are used (e.g. a semi-colon). You can change the separator value by going to Administer > Configure > Global Settings > Localization and modifying the Import/Export Field Separator.

    s2

Creating Custom Fields

This chapter explains how you can collect information beyond what CiviCRM allows by default by adding custom fields to hold the data that you want to collect.

For example, you could add a set of checkboxes to organisations so that you could track the clients that they serve. You can also restrict custom fields to certain types of that object. For example, if you have a contact type Student, you might have a custom field listing the subjects they study.

Custom data fields are always stored as sets of custom fields in CiviCRM.  Therefore, adding custom data is a two-stage process:

  1. Create a custom field set, which is simply like a container to hold these custom fields together.
  2. Add custom fields to this set. (You may find it helpful to read the information about custom fields first, but you will need to create the field set before you create the fields in it). 

To clarify, a field is a unit of information entered into the database, such as someone's primary spoken language, or high school graduation date. A custom field set is a group of fields containing related data - that is, a set of fields related to a certain activity type, to participation in events, or to contributions.

Custom field sets

Custom fields are always part of custom field sets, and each set has a scope as wide or as narrow as you choose. For instance, you might associate a custom field set called "nationality" with all contact types, another set such as "immigration status" with a specific contact type (e.g. Individuals), and yet another set with a specific component (CiviMember, CiviEvent), or with other elements such as Relationships and Groups. The scope of a custom field set is one of the few decisions that is irreversible (you will not be able to change it after creating it) so it is important to consider carefully what you want to associate your custom field set with when you start.

When creating custom field sets, you should ask:

Taking the time to think through these questions helps keep your application screens as relevant and clear of superfluous fields as possible. For example, if your custom field set contains contact characteristics such as a field for the "color of eyes", you should associate them with the Individual contact type rather than the generic Contacts option, as this field would be irrelevant to Organization and Household contact types. Another example would be if custom data is specific to a particular event registration page. You should create this custom data for an Event type Participant for the specific Event.

Depending on how many custom fields you are creating, you should also consider grouping the fields topically. For example, you may associate 20 custom fields with Individual contacts, 12 of which fields relate to an online membership directory. Rather than group all 20 fields in a single custom field set, you may want to split them into two sets - one for the directory-related fields, and a second for more general Individual details.

To create a custom field set and custom fields, go to: Administer CiviCRM > Custom Data > New Set of Custom Fields. This form lets you assign a title to the field set, specify what type of records it will be used for, select the display characteristics, and enter help text. The form appears in the following image, and we'll describe each field.

NewCustomFieldSet 

Set Name

For custom field sets which are displayed inline, this name appears as the legend of the field set. If this set uses the tab display style, the name appears as the navigation tab label.

Used For

You can use this option to ensure that the fields appear only where they are relevant. The choices are:

Order

This controls the order in which your custom field sets are presented when you have created more than one set. Lower numbers (1, 2) are displayed above higher numbers (8, 9).

Multiple records

Each field usually contains a single option. For example, a person has either blue eyes or brown eyes, not both. However, some fields are more complex and may require multiple entries, such as a person's educational history. A single person may have multiple educational degrees, so a custom field set about educational history should allow multiple records.

CiviCRM provides this functionality for custom field sets assigned to contacts (whether to all contact types or to a specific type). To use this option, select the "Does this Custom Field Set allow multiple records?" option. This option has several restrictions:

Display style

Custom field sets for Contact records are displayed either "inline" on the contact summary page (the Summary tab), or as a new tab at the top of the contact record, along with Summary, Contribution, Group, Note, etc. We suggest using tab display for infrequently accessed fields and large sets of fields.

Custom field sets used for components, relationships, or other resources are always displayed inline. Also note that custom field sets configured to handle multiple records will be displayed in the Summary tab.

Is this Custom Field Set active?

If a custom field set is active, its fields can be viewed and changed. Otherwise, the fields are in the CiviCVRM  system but hidden from the user interface. This option can be valuable for managing your data, especially if you are migrating from an existing database system.

For example, your existing database may have fields you would like to transfer to CiviCRM for historical data keeping purposes, but plan to then deprecate or migrate to a new data structure. Suppose you are importing membership records from an MS Access database. Each record in Access has a unique ID (key) field, which has no direct benefit in CiviCRM. Rather than ignoring it altogether, you could create a custom field to hold the value, import the records, and then disable (keep the Activate option unchecked) the field, thereby hiding it from view and minimising the interface clutter.

Though not visible to users, the field value is stored in the system and can be referenced at a later date. For instance, if you ever need to investigate archived data for a possible discrepancy or compare the field value with a printed record.

Individual fields can be made inactive in the form defining those fields, once the custom field set is active.

Pre-form Help and Post-form Help

If you enter text in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field. Use help at this level to provide instructions related to the entire set of custom fields.

Other settings

You can specify that you want the custom field set to be "collapsed" on initial display. If you check this box, only the title for this field set is displayed when the page is initially loaded, because the fields are hidden. This is helpful for field sets that are infrequently used because it reduces the screen real estate taken up when the page opens. A similar "collapsed" property is available for the display of custom data in Advanced Search.

Custom fields

Once you have created a custom field set, you can create custom data fields within the set. Click "View and Edit Custom Fields" followed by "New Custom Field" and you will see the screen in the image below. We'll explain each of the options in this section.

After completing the field configuration options, click Save to record the field and return to the field listing for your current custom field set, or click Save and New to save the field and begin defining a new field. You can view a listing of all the custom fields in a custom field set at any time by navigating to Administer > Customize > Custom Data and clicking View and Edit Custom Fields.

With the exception of the data and input field type selection, all of the configuration options may be modified after your initial creation of the field. You may also find it useful to preview your custom fields, as well as the whole set of custom fields, as you are defining them. This is particularly useful for checking the layout of radio button and check-box fields with a large number of choices.

customdatafield.png 

Field label

What you want to appear next to the field when it is displayed to the user. The text you enter here is also the label shown when you export data. When using fields in a profile, you can overwrite the Field Label.  So on this screen you can choose names that are suitable for administrators, and give more user-friendly names when exposing them in profiles.

Type

Custom fields can be of many different types, many of which you've probably encountered when you have filled out forms on web sites. When you create a custom field, CiviCRM shows you a dropdown list of types from which you can choose the type that best represents the data you plan to store. The menu on the left (shown open in the following figure) indicates what kind of data you want to store, whereas the menu on the right indicates the way you want to interact with the user.

datainputfieldtype.png

The types of fields are:

We suggest you experiment with creating different field types to get an idea of how they behave. Different options have implications for use. For example, check-boxes enable you to use OR as well as AND searches in Advanced Search, whereas multi-select will not.

Database Field Length

The database field length allows you to specify the number of characters that this field will contain.  You should normally leave this at the maximum.  In certain cases (for example if you are dealing with extremely large field sets) it might make sense to shorten this field to improve performance and decrease storage space, but setting a shorter length won't make any difference to the vast majority of users.

Order

Controls the order in which the fields appear. You may assign the order in the field edit form, or use the up/down icons on the main field listing table to adjust the field presentation. By default, new fields appear at the bottom of the field list within a set.

Default Value

Where applicable, you may designate a default value for a field. This value is automatically displayed or selected when users go to a form containing this field. Note the format required for date fields (YYYY-MM-DD).

Pre-form Help and Post-form Help

Ideally, your field name is self-explanatory and users will immediately know what to enter. But in those cases where there is some ambiguity, or where you wish to help regulate how a certain field is used, you may enter help text here. If you enter it in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field.

You help text identified appears in all uses of the field in administration pages and is inserted as the default help text when fields are assigned to a profile. The person creating the profile can remove or change the help text there without impact on the original custom field definition.

Required

When selected, this means that a value must be provided for this field before the form can be submitted. Failure to do so will result in an error message directing the person to complete the required fields.

If you want a field to be required only when a user fills out a particular profile, you can leave this box unchecked but check the Required field in the profile.

Is this Field Searchable?

Makes this field appear in a panel of custom fields in CiviCRM's Advanced Search page. While you may be tempted to mark every field as searchable, doing so may unnecessarily clutter the Advanced Search custom field panel, when in fact certain fields will probably never be used in that way. You may toggle this option on or off at any time, so don't be overly concerned about arriving at a final decision when you first define a custom field.

Active

As with the active check-box in the form defining the custom field set, this box determines whether the field is disabled or enabled when CiviCRM shows it to the user.

View Only

This allows you to designate a field as visible but uneditable. There are two general uses for this field:

Multiple choice options

For field types that involve selecting from a set of multiple options (such as Select, Radio, Check-box, Multi-select and Advanced Multi-select) you are given the choice of either using an existing set of options that you've already created for another custom field or creating a new set. You can enter these values while creating the field, and you can enter the values later. The option's label is displayed on the form, while the option's value is stored in the contact record. The label and value may be the same or different.

If you choose to use the same set of options for several fields, you will be notified when making any changes that this will affect an option set used by several fields.

When you create a new set, you have the option of initially entering up to ten multiple choice options in a table. If you need more than ten options, you can create an unlimited number of additional choices after saving this new field by using the Edit Multiple Choice Options link. Go to: Administer > Customize > Custom Data > View and Edit Custom Fields > Edit Multiple Choice Options.  You can go to this screen at a later date to modify the label, order and active status of any multiple choice option, as well as add more choices. 

CustomMultipleOptions

If desired, you can also mark one of the choices as the default option.

Inactive options are hidden when the field is presented.

Choosing between fields, groups and tags

Data fields, groups and tags are three major ways to associate information with contacts. Although it can be tempting to just create a custom data field for every attribute of your data, take time to learn about the alternatives. They offer powerful functionality that you may miss out on if you rely only on custom data. Furthermore, using data fields for information stored more appropriately as groups or tags can slow your system. Finally, proper use of groups and tags makes it much easier for administrative staff to maintain the records.

Some tips that may help you choose are:

What is GOTV (Voter Tracking)?

CiviCampaign includes a "Get Out the Vote" GOTV (Voter Tracking) feature so you can indicate the contacts (who you have or plan to survey) who have voted at the polls.

You will need to enable the CiviCampaign component to be able to use GOTV (Voter Tracking). See the Campaign section for more information about CiviCampaign.

Tracking Contacts Who Voted at the Polls

To use the GOTV (Voter Tracking) feature:

  1. Click Campaigns > GOTV (Voter Tracking).
  2. On the GOTV (Voter Tracking) search screen:

Glossary

Accidental Techie

Someone who has inherited the role of IT technical support but whose primary role maybe something else; often has little or no formal IT training (which is not always a bad thing!).

Accordion

A javascript-based effect on a web page that allows additional content to be revealed or hidden (often referred to as collapsed or uncollapsed) without the user leaving the web page.

ACL (Access Control List)

ACLs define permissions for a group of contacts to perform an operation (e.g. edit, view, delete) on a set of data or a type of record. For example, you could set up a group called "Administrators" that allows people to view and edit all contact records, and a group called "Volunteers" that can view contact records but not edit them.

Activities

An activity in CiviCRM is a record of any scheduled or completed interaction with one or more contacts. Examples include meetings, phone calls, emails, event attendances and contributions. You can define additional types of activities as needed.

Admin / Administrator

The person or persons that maintain a server or a web-based software like CiviCRM. Administration includes maintenance, configuration, backup, security, creating and deleting user accounts and so on.

AGM (Annual General Meeting)

An AGM is a meeting held every year by an organisation to inform its members of previous and future activities. Certain types of organisations are required by law to hold an AGM.

AGPL (Affero General Public License)

A license for open source software. CiviCRM uses the AGPL version 3.0 license, which gives you the right to do with the software as you like and guarantees that the source code will always protect your rights in this way.

Alpha Version

A software version that contains very new source code with new functionality and bug fixes. An alpha version is released for testing purposes, and for people who want to follow its development, but it is not considered to be any where near ready for general release or use.

Apache

The most popular web server software. Apache is free and open source (see also FLOSS).

API (Application Programming Interface)

An interface employed by a software application to enable interaction between itself and other software.

Backup

Protecting your data by regularly making copies and storing them independently of the original files so they can be restored if necessary.

Bandwidth

The speed at which you can transfer information through a network or internet connection. If a connection can transfer a lot of information it is said to be "high bandwidth".

Beta Version

A software version that is in good condition but still needs testing to make sure it functions as intended before general release. Testing beta versions is a helpful way to participate in the CiviCRM community.

Blog

Short for web-log. A website which is regularly updated with news and views from one or more individuals.

Bug

An error that prevents software from behaving as the user would expect.

Bug Reporting / Bug Fixing

The process of reporting bugs to the software developer(s), and then fixing the bugs so the software operates as intended.

Bug Tracker

An official repository for recording bugs. The CiviCRM bug tracker can be found here: http://issues.civicrm.org/ (click on Issue Tracker).

Cache

A recent copy of frequently used data that can be quickly and easily accessed. This is especially useful if the data is complicated or takes a large effort to generate. The disadvantage of caching is that data can become out of date, but this normally isn't a problem. Even caching data for 5 minutes might be useful in certain circumstances. If a page is accessed 1,000 times in 5 minutes, having a cached version means the data will only need to be generated once.

A web cache holds copies of recently visited web page files. Sometimes a user may need to clear their web cache in order to see updated information on a web page.

Canvassing 

Is the systematic initiation of direct contact with a target group of individuals commonly used during political campaigns. A campaign team (and during elections a candidate) will knock on doors of private residences within a particular geographic area, engaging in face-to-face personal interaction with voters. Canvassing may also be performed by telephone, where it is referred to as telephone canvassing. 

Captcha

A spam prevention tool. See reCaptcha.

CiviCase

The case management component of CiviCRM. CiviCase provides service organisations with tools for structuring, scheduling and recording case activities.  

CiviContribute

CiviContribute is an online fundraising and donor management component which enables you to track and manage contributions to your organisation. 

CiviCRM

What this whole manual is about! CiviCRM is web-based, open source software that allows you to record and manage information about your various constituents including volunteers, activists, donors, employees, clients, vendors, etc.

CiviDog

See Scout.

CiviEngage

CiviEngage is a Drupal module that enhances CiviCRM's core functions for non-profits focused on community organizing groups and civic engagement work. CiviEngage provides a package of custom fields, reports and features to track the history of engagement, involvement, and activities of constituents over time. This package also integrates Campaigns and Surveys to provide WalkLists and PhoneBank Lists. 

CiviEvent

CiviEvent provides integrated online event registration and management for paid and free events.

CiviMail

CiviMail is a mass-mailing component which allows you to engage constituents with personalised email blasts and newsletters.

CiviPledge 

CiviPledge is a component that allows the flexibility to create various types of fundraisers. Allows to individuals to donate daily, weekly, monthly or yearly.   

Client

A term used sometimes instead of constituent or contact, more often in a context involving a financial transaction.

Client is also a term for a system (computer) or application that accesses a remote computer such as a web server to receive information; examples include a personal computer that is connected to the internet, or an email application that downloads email from a server.

Closed Software

Software that does not allow users to access its source code, as opposed to open source software. See also proprietary software.

CMS (Content Management System)

An application used to create, edit, manage, search and publish various kinds of digital content (text and other media such as images and videos). Web-based CMS allow organisations to add and manage content on their website without requiring advanced technical skills. CiviCRM is often integrated with a CMS (commonly Drupal or Joomla!) which helps to facilitate client interaction.

Component

A part of a CMS or other application that can be enabled or disabled, according to the needs of the user. Examples include CiviEvent or CiviCase. See also module.

Community Advisory Group

A representative group of people from the CiviCRM community who work with the CiviCRM team on project development.

Cookie

A file stored on your computer and used by a website to identify you on return visits. Some websites cannot be accessed unless you allow your computer to accept and store cookies.

Constituent

A constituency is usually defined as a group of people bound by shared identity, goals, or loyalty. In CiviCRM, "constituents" is used to a describe all supporters, current or potential, of a given organisation. See also contact and client.

Contact

In CiviCRM a contact is either an individual, an organisation or a household about whom information is stored in the database. See also constituent and client.

Contact Summary Screen

A page that displays at a glance all the data about an individual, organisation or household that is stored in the CiviCRM database.

Core Code

The source code that constitutes the official code of CiviCRM. Also called core.

Core Data Field

A field that is included in a record structure "out-of-the-box". For example, the CiviCRM contact record includes First Name as a core field.

Core Team

The people most closely involved with CiviCRM development.

CRM

Acronym for Contact (or Constituent, Customer or Client) Relationship Management. CRM (or eCRM) software was originally developed from a sales perspective, to help companies track and organise their interactions with current and potential customers. CiviCRM is oriented specifically toward the needs of non-profits, advocacy and non-governmental organisations, so the term "customer" is replaced with "constituent". Outside the USA it is often referred to as Contact Relationship Management.

Cron Job

A cron job is a way of automatically scheduling a programme to run at certain intervals. Crons are often used in CiviCRM to handle daily or monthly events such as sending membership renewal reminders or processing ongoing payments.

CRUD

Create, Read, Update and Delete: the basic functions performed on databases.

CSS (Cascading Style Sheets)

A way to control the style of a website by defining design and layout elements in a single file which is linked to all files in a website and applies the style across the site. An element, such as the formatting of a heading or a background colour, can be changed once in the CSS file to effect a change on all pages of the site.

CSV (Comma Separated Values)

A simple format for a spreadsheet. CSV files are text files where each cell is separated by a comma, and each row is separated with a return. This very simple format is understandable by many different programmes.

Custom Data Field

A field that is added to the data structure of a CiviCRM record by your organisation. Custom data fields extend the information that can be stored in that type of record. For example, your organisation might need a custom field to record each contacts' professional qualifications, or the food preferences of event participants.

Dashboard

A user's homepage, which displays when the user logs in to CiviCRM and which can be personalised with dashlets.

Dashlet

A report on some data in the CiviCRM database, configured to appear on a user's dashboard. For example, monthly figures in graph and/or numerical form, appointments for the day, or a list of new memberships.

Data Centralisation

Storing all your data in one place.

Database

Is a collection of information that is organized so that it can easily be accessed, managed, and updated. In one view, databases can be classified according to types of content: bibliographic, full-text, numeric, and images.

Demo Site

A website that allows you to test and explore the functionality of a piece of software. CiviCRM maintains three demos sites: one integrated with Drupal, one integrated with Joomla! and one in standalone mode.

Dedupe

Refers to the task of finding and merging multiple entries for one contact.

Developer

Someone who develops software.

Domain

See DNS.

Donor

Someone who makes a donation, i.e. voluntarily gives money to an organisation.

DNS (Domain Name System)

The Domain Name System (DNS) converts domain names, which are made up of easy-to-remember combinations of letters (example.com), to IP addresses (123.456.123.234) which are hard-to-remember strings of numbers. Every computer on the internet has an unique address (a little bit like an area code + telephone number).

Drupal

An open source CMS that integrates with CiviCRM to provide a user-interface and additional website functionality (http://drupal.org).

Encryption

A way of disguising data when it is being transferred from one computer to another so that it is unreadable by any other computer that it may pass through on the way.

Environment

The specific hardware and operating system on which you are running your software.

Event Listing Feed

A RSS feed containing the list of events defined in CiviEvent.

Firefox

A popular free and open source web browser, developed by the Mozilla Foundation (http://www.mozilla.com)

FLOSS (Free/Libre Open Source Software)

Software that is licensed so as to guarantee the essential freedoms of users to its source code and reuse. A combination of "free software" and "open source software", with "libre" added in to emphasise that software freedom is essentially a matter of rights, not price.

FOSS

Free and Open Source Software - see FLOSS.

Forum

A web-based online discussion tool (see http://forum.civicrm.org/).

Free Software

Software that is licensed so that you can use and distribute it without restriction. CiviCRM is free software. See also FLOSS.

FTP (File Transfer Protocol)

The FTP protocol is used for file transfers from one computer to another over the internet. Many people use it for downloads, and it can also be used to upload files to web servers. A popular free and open source FTP client for Windows is FileZilla. There are also web-based FTP clients that you can use with a normal web browser like Firefox.

Functionality

The set of tasks that a piece of software can perform.

Geocoding

The process of finding associated geographic coordinates (often expressed as latitude and longitude) from other geographic data, such as street addresses, or zip codes (postal codes).

GUI (Graphical User Interface)

User interface offering windows, icons, mouse control, multiple fonts, and so on - the normal way for non-programmers to communicate with their computers. The alternative to a GUI is a command line interface with text only.

Hook

Hooks are a common way to extend systems and a powerful way to extend CiviCRM's functionality, incorporate additional business logic, and even integrate CiviCRM with external systems.

Household

Is a family or group of people who share a physical location. 

Hosting Service

A service (usually commercial) that provides server space for your website. Hosting services also can provide physical space to put your own server in so that it is connected to the internet.

ICT

Acronym for Information and Communication Technology.

Internationalisation: i8n

The process of making software ready for adoption in different countries and different cultures, without the need to modify it technically. This is done by the developer (software engineer) when writing the software. See also Localisation.

Internet Service Provider (ISP)

A business that provides services such as internet access, email, and website hosting.

Intranet

A network of computers that are connected within a home or office but not accessible from outside the local network.

IT

Acronym for Information Technology.

JavaSacript

A scripting language primarily used in web pages to display dynamic content.

Joomla!

A CMS that can integrate with CiviCRM to provide a user interface and additional website functionality (http://www.joomla.org).

LAMP 

Is an acronym for a solution stack of free, open source software, originally coined from the first letters of Linux (operating system), Apache HTTP Server, MySQL (database software) andPerl/PHP/Python, principal components to build a viable general purpose web server.

Linux

A type of operating system (other common operating systems are Windows and Mac OS). Linux has been popular as a web server for a long time and is now gaining popularity on personal laptops and desktop computers. Linux is free software and open source.

Local Computer

A computer that runs CiviCRM but is not publicly available via the internet. This could be your personal or home computer, or it can be in your office. It can also be called a client computer in the context of receiving information from a server

Localisation: L10n

The process of translating a product into different languages or adapting a language for a specific country or region. This is done by translators with no need for technical wizardry.

Mail Server

A computer that transfers email from one computer to another.

Mapping Provider

A service provider that allows displaying contact locations on maps - Google Maps or Yahoo Maps in CiviCRM.

Module

A part of a system, also called a component. CiviCRM includes a number of modules, each of which adds functionality to the basic contact management features. For example, the CiviEvent module provides event management functionality. Organisations using CiviCRM can turn modules on or off, according to their needs.

MySQL

A popular database engine. CiviCRM uses MySQL to hold its data. MySQL is free software. (http://mysql.com)

NGO (Non-Governmental Organisation)

A legally constituted non-business organisation with no participation or representation from government. In the United States, this type of organisation is more often referred to as a Non-profit. They may be also called civil society organisations or not-for-profits.

Non-Profit

see NGO.

Online Contribution Page

A function of CiviCRM which allows the creation of a page on the website where visitors can make online donations using credit cards.

Open ID

A convenient free system to use a single digital identity across the internet.

Open Source Software

Software with source code that is publicly available, as opposed to proprietary software; see also FLOSS. Open source software is based on the philosophy that sharing and collaborating on code leads to better software and greater benefit for everyone.

Payment Instrument

Medium or method that is used for online payments.

Payment Processor

A company (usually a third party) appointed by a merchant to handle credit card transactions for merchant banks. A payment processor is required to handle online transactions through a system such as CiviCRM.

Permissions

Allow you to limit access for different users to different parts of the system.

Personal Campaign Pages

A feature of CiviCRM that can be enable to allow constituents to create their own fundraising pages.

PHP

The programming language in which the majority of CiviCRM is written.

Ping

Sending and receiving small amounts of data to and from a server; often used to measure the response time across the network.  

Point Person

Someone given the responsibility to keep their eye on a certain issue.


PhoneBank List

A list created using CiviReport  to make it easy for volunteers to call constituents en masse. This is often done to invite them to vote, request that they volunteer, take action, or donate.  

Premium

A gift that can be offered to contributor in exchange for donation. CiviCRM allows offering premiums as a part of the donation gathering process.

Price Sets

A way of storing and re-using complicated price structures for events. For example, you can charge for different elements of an event.

Primary Location

The information that a constinutent wants to be used as their main point of contact for mailings etc.

Profiles

A central concept in CiviCRM. In essence a subset of fields. See the chapter on Collecting and Sharing Data for a full explanation.

Proprietary software

Also called closed software or closed source software. Software licensed so that you cannot access the source code and modify it without first coming to an agreement with the authors. See also open source software.

Protocol

An agreed-upon method of doing something. HTTP and SMTP are two examples, one being an agreement on how to transfer website data across the web, the other an agreement on how email will be transferred across the web.

Radio Button

An element of a web-based application user interface that allows the user to choose only one of a predefined set of options. Usually indicated by a white circle that can be filled with a click.

reCAPTCHA

A common tool for testing whether a user is a human or a computer, used to prevent spam.

Requirements

The things that you require a particular software application to do.

Rich Text Editor

A text editor that allows you to add formatting, such as bold, italic and underline, to text (as opposed to just plain text).

Root Domain

The 'raw' URL of a website without 'www' or any other subdomain. For example, http://civicrm.org/ is the root domain while http://www.civicrm.org/ is not.

RSS (Really Simple Syndication) Feed

RSS feeds are a way to publish frequently updated information, either for inclusion on a website or to be read by an RSS reader.

RSVP

"Répondez s'il vous plaît", a French phrase that translates to "please respond". Commonly used to request confirmation (or declining) of attendance at an event.

Script

A script is a short programme that does one specific task. Many web pages include scripts to manage user interaction, so that the server does not have to send a new page for each change.

Scout

The CiviCRM Book Sprint official dog. Scout likes dog biscuits, rolling on the ground, eating snow and proof-reading.

Sendmail

Sendmail is one of the most popular mail transfer agents (MTA) used for handling email on a server. Sendmail is free and open source software.

Server

1. Software that "serves" content to a client. See Apache, or Mail Server for two examples.

2. A computer that is used primarily to serve content. Any computer can be set up this way, but the term traditionally refers to those that deliver web content. See also client computer.

Shared Hosting

A website hosting service, where multiple websites reside on single server.

Smart Group

A group in CiviCRM to which contacts are automatically assigned. Smart groups are created by running and then saving a search. They are useful for groups that might change frequently, for example "donations over $1000 in the last month".

SMTP

Simple Mail Transfer Protocol. A standard or protocol used by email software to transfer (send) email.

Soft Credit

Allows you to credit a contact for a donation made by someone, for example the person who inspired the actual donor to make a donation. See Personal Campaign Pages. 

Software

Applications (also called programs or programmes) that enable specific functionality on your computer. There are many broad categories of software such as web browsers, word processors and email clients. Within each category there are many available softwares that perform the functions you require. For example, Firefox and Internet Explorer are two commonly-used web browsers.

Software License

The terms you must accept before using a piece of software.

Source Code

Software is created by writing instructions that a computer understands. These lines of instructions are known as code or source code.

SSL (Secure Sockets Layer)

One way of making internet communication secure. You can easily see if you are using SSL by looking at the URL in your browser: if it starts with https instead of http, your connection is using SSL.

SSL Certificate

Provided by the server to prove its identity, in the same way that a person carries a passport or driving license. See also SSL (Secure Sockets Layer).

Stable Version

A version of software that has been tested and is considered to be ready for general use.

String

A string is a sequence of characters for example "Hello, World", the URL "http://www.flossmanuals.net/" or the text message "No such file or directory". Different character sets allow different strings. Unicode strings can include any combination of languages, such as "Japan (日本) and Korea (대한민국)".

Subdomain

A domain that is a part of larger larger domain. For example: en.flossmanuals.net and fa.flossmanuals.net are subdomains of the domain flossmanuals.net.

Token

Tokens are used in CiviCRM to insert elements such as a contact's name or a standard greeting into emails being sent from the system. In an email sent to a group of people, the token {first.name} will be replaced with actual name of each message recipient, in the email that each individual receives.

Upgrade

The process of replacing software with a newer version of the same software. An upgrade may fix bugs, improve security, enable the software to continue to work with upgraded operating systems, or provide new features and other enhancements.

URL

Acronym for Unique Resource Locator, sometimes referred to as a Universal Resource Indicator, or URI. The technical convention that identifies the location of a resource on a network. The resource might be a web page, in which case the URL refers to the location of that web page on the internet, for example www.civicrm.org is the URL for CiviCRM.

Use Case

Use case is a central concept in software development. A use case is a story or scenario that documents the experience of performing a specific task with the application. Generally, a use case should avoid technical or database-specific language, such as 'fields' or 'record', and concentrate on real world objects and scenarios in order to communicate the idea clearly to people who may not be familiar with technical terms.

Version

Updates to software are released periodically, and these releases are referred to as a version of the software. There are different types of version, for example the most recent release of a software which has been tested and is intended for general use is referred to as the stable version, while a very new untested version is the alpha version. 

VPN (Virtual Private Network)

A method of sharing information between members of an organisation over encrypted connections.

Walk List

Is a list created using CiviReport to make it easy for volunteers to go door-to-door. This is often done for voter engagement.

Web Application

A software application that provides a website with additional functionality. CiviCRM is a web application.

Webmail

Webmail is email service through a website. The service sends and receives email messages for users in the usual way, but provides a web interface for reading and managing messages, as an alternative to running a mail client like Outlook Express or Thunderbird on the user's computer. For example a popular and free webmail service is https://mail.google.com/

Web-Server

A Web server is a computer that is set up with software and networking capabilities to deliver Web pages on the Internet or an Intranet. Web servers use programs such asApache or IIS to deliver Web pages over the http protocol.

Wiki

A web-based software that enables anyone to edit content via a web browser. Wikipedia is the best known example of a wiki.

Wildcard

A character that can match an any number and collection of characters, normally represented by . For example, when used in searches, ab finds ab, abba and abracadabra but not fabulous; ab finds fabulous.

Work Station

A computer used for working; often in a situation such as an office where there are other computers that may include servers.

WYSIWYG (What You See Is What You Get)

An application that provides a visual tool for editing web content, so that the user can see how the page will look in the browser as they are editing, instead of working in the HTML code. See also rich text editor.

REPORTS AND ANALYSIS

There are a few techniques for reporting on and analysing grants. The grant dashboard gives a quick overview of your grant types. Aside from this there are

Searching for grant data

CiviCRM makes an important distinction between contacts and grants.  Sometimes it is useful to get the answer to your grant related question in terms of contacts, e.g. which contacts were successful grant applicants in 2011.  Other times it is more useful to have the answer in terms of grants, e.g. how many grants applications did we get for our Community Chest this year?  Think about whether you are interested in the grant or the contact before doing any grant searching.

The Find grants search allows you to search based on grant data and return grants. The Advanced search allows you to search based on most grant data and combine that with other contact information and return contacts.

Searching based on these criteria gives you access to simple totals. It also the option to export as CSV for further analysis. 

Grant reports

Out of the box, CiviCRM comes with one report that can be used for Grants. This report can be used, for example to show details for all grants of a particular grant type. The report has agregatted statistics at the bottom for amount requested and granted. 

More analysis

If you can't do what you want with a built in report or search, consider commissioning a new report or custom search. Read the CiviReport section for more information.

History of this book

This book is the result of the collaborative effort of many people.  A lot of the content was written during two book sprints held in 2009 and 2010 in Tahoe, USA. Many contributions have also been made by individuals in the times between these sprints.

Third edition

This edition includes minor updates to reflect changes in CiviCRM 3.3 which was released in December 2010. It is being published on the eve of the second annual CiviCon conference. Thanks to the generous contributions of our CiviCon Sponsors (listed in the front of the book) - a copy has been provided to each conference participant.

Second edition

The second edition of the CiviCRM manual was published after a four-day Book Sprint organised by CiviCRM and led by Adam Hyde (FLOSS Manuals). The sprint was sponsored by the Information Program initiative of the Open Society Institute (http://www.soros.org/initiatives/information). We are especially grateful to Janet Haven for pushing this forward.

The second edition includes new sections on CiviReports, CiviCase, CiviEngage and Extending CiviCRM.  This edition also included an extensive rewrite of nearly every section of the text, including a reorganization of all sections to break up information into Introduction, Planning, Configuration and Everday Tasks sections, the latter to serve as an easy-to-follow user manual for individuals working with CiviCRM on a daily basis.

We also added an entire new section to assist developers get into the code. Finally, we updated the book to match CiviCRM 3.2 (which is a few weeks away from release at the time of writing).

We think that the reorganisation adds a lot to the book and increases it's readability because it helps people who with CiviCRM in a specific capacity get directly to the chapter relevant to them.

The following photo shows the people who worked on this second edition of the book.

civi_team

In the back row, starting from the left, you are looking at Dave Greenberg (San Francisco, USA), Kyle Jaster (NY, USA), Xavier Dutoit (Geneva, Switzerland and Brussels, Belgium), Kurund Jalmi (Mumbai, India), Michael McAndrew (London, UK), Wes Morgan (Washington DC, USA) , Josue Guillen (DC, USA). The front row from the left is Jack Aponte (NY, USA), Mari Tilos (San Francisco, USA), Sarah Gladstone (Chicago, USA), and Alice Aguilar (NY, USA).

First edition

The first edition of manual was written during a five-day book sprint also organised by CiviCRM and led by FLOSS Manuals. The sprint was also sponsored by the Information Program initiative of the Open Society Institute (http://www.soros.org/initiatives/information), and again, we are especially grateful to Janet Haven for pushing this forward.

Having secured sponsorship, the CiviCRM Core team invited a group of people from around the globe to gather for a week at Lake Tahoe in California. The modest goal was to transform our diverse experience of CiviCRM into a manual that we hope will help people to use this great piece of software. This turned out to be an interesting, and at times difficult, challenge.

The following photo shows the people who wrote this book.

team

In the back row you are looking at Michael McAndrew (London, UK), Tony Guzman (Salt Lake City, USA), Brian Shaughnessy (Albany, NY, USA), Dave Greenberg (San Francisco, USA), Yashodha Chaku (Mumbai, India) and Adam Hyde (Berlin, Germany). In the front row are Mari Tilos (San Francisco, USA), Cynthia Tarascio (Philadelphia, USA), Michal Mach (Warsaw, Poland) and Peter Davis (Wellington, New Zealand). In the very front is Eileen McNaughton (Wellington, New Zealand).

We came from different backgrounds, had used CiviCRM in different ways, and had worked with very different organisations. It was often a challenge to meld these perspectives into a cohesive whole, but we hammered away at it and we think this made for a better book. We had some lively discussions about important issues, such as whether there is a "z" or an "s" in organis/zation or a "q" in check/que, and finally agreed to use both spellings in the spirit of internationalism. We also struggled with the word "constituent", which is core to the non-profit sector in America but was unfamiliar to those of us from outside America.

It was been a pretty intense five days. Adam (our friendly Floss manuals taskmaster) kept us realistic, on track, and hard at work - even hauling us back to work after dinner each evening. Overall it was both fun and productive and we really appreciate the way Adam has helped us to actually produce a book within a week. Thank you.

For most of us, however, the highlight of the week has been the breathtaking cuisine cooked by Jill Klein (http://www.partiesthatcook.com/about-us/). We love you, Jill, and wish we could take you home with us. We are also grateful to Dave Greenberg, Bob Concannon and Mari Tilos for their hospitality, and to Scout the dog just for being there.

scout

We had help from around the world during the preparation process, and over the course of the Sprint. Andy Oram helped us both in the planning process and then with editing and feedback during the Sprint. We also had a number of people log in to write and edit the manual during the Sprint. They include Robert Santiago, Xavier Dutoit, Joe Murray, Sarmeesha Reddy, Jay Maechtlen, Dream Gomez, Leila Johnson, Duncan Hutty, and Kurund Jalmi.

pteam

Our office for the week was Dave and Bob's house.

civi1

 We mitigated the hardship of late-night work with some tasty beverages.

log

 And occasionally they let us out for a bit....

Overview

This chapter covers the main building blocks that CiviCRM uses to store data, and describes their intended usage. It is recommended reading for working out how you should organise your data in CiviCRM. 

Using CiviCRM successfully depends on having your data stored in the right place. The following is an introduction to how contacts are dealt with in CiviCRM, how CiviCRM stores data related to contacts by default, and how to add fields to store additional data. This chapter introduces the following concepts: Contacts, Relationships, Groups and Tags, Activities, Custom Fields, and Profiles. This should also help you to understand why you would store data in one place and not another.

Contacts

CiviCRM uses contact records as central hubs for data about your organisation's contacts. There are three distinct contact types defined in CiviCRM, each suited to a common type of contact your organisation may want to track: 

CiviCRM provides different fields for each contact type, according to the different kinds of data you will probably want to track. For example, gender only applies to individuals, not organisations or households, so the gender field is only available for Individual contact types and subtypes. You can also define additional data that you want to collect and apply it to only one type. You could choose to create a custom data field to record the Chairperson or CEO's name and only apply this field to organisations.

Relationships

Relationships are a way to connect two contacts to each other. Two default relationship types in CiviCRM are the "employer - employee" and the "parent - child" relationship types.

There are always two ways to describe a relationship in CiviCRM: one describes the relationship of A to B, and the other of B to A. For example, Adam is Bernard's son and Bernard is Adam's father. Sometimes both descriptions will be the same: Charlie is Diane's friend and Diane is Charlie's friend.

CiviCRM comes with a number of relationship types in the standard installation. You can define further relationship types to meet your needs, for example you might define a relationship type of "vicar - church".

It may be helpful to compare relationships to groups: relationships connect two contacts, while groups contain two or more contacts who have something in common.

Groups

Groups are useful to identify two or more contacts with something in common. For example, the advisory board of your organisation could be modeled as a group.

Groups are often used as mailing lists. For example, you could create a group containing all your newsletter subscribers, then use the group to send an email newsletter.

Groups are also used in many other situations. For example, a search can be saved as a group (known as a smart group) which means that it will automatically update as more/fewer contacts match the search criteria as you put updated information in your database.

Groups can also be used to provide permissions in Drupal. To find out more about groups and how they are used, read the chapter on groups and tags.

Tags

Tags are in many ways similar to groups, but as well as being used to identify contacts they can also be applied to activities and cases that have something in common. To find out more about tags, and how they are different from groups, read the chapter on groups and tags. 

Activities

Activities are a key concept in CiviCRM. Activities track interactions between the organisation and its clients or contacts at a specific point in time. While all of CiviCRM's components make extensive use of activities, such as recording contributions, event attendance, membership subscriptions, and emails, you can also create additional activity types to define specific activities that your organisation carries out, for example, training, review, support etc.

Custom Fields

CiviCRM makes it possible to collect and track information beyond what's possible with the default set-up. 

According to your organisation's needs, you might want to add additional fields than those present in CiviCRM. For example, as part of your event management process, you might need to enter information about dietary preferences for participants. CiviCRM lets you add custom fields to collect this data and associate it with participant records.  

Read the chapter in this section on Custom Fields for more detailed examples and information on how to add them. 

Profiles

CiviCRM allows you to pull together sets of fields for different purposes, and help you reduce the amount of time staff spends on administrative tasks. These sets of fields are known as profiles.

A few examples where profiles are necessary include the following: collecting information or letting people join your mailing list via online forms, facilitating event registration and getting everything you need to know from registrants, or creating data entry screens for volunteers with ONLY the fields that volunteers should see. 

Read the Profiles chapter in this section for detailed information about how to make use of profiles. 

CiviCRM Components 

In addition to these basic building blocks, CiviCRM provides what are known as components to help streamline administrative tasks related to event management, membership, sending communications, receiving contributions and donations, case management, conducting campaigns, administering grants programs, and more.

Each of these components is covered in a separate section of this book.  The components are CiviEvent, CiviMember, CiviMail, CiviContribute, CiviCase, CiviCampaign, and CiviGrant. 

The sections on Survey, Petition, and CiviEngage (the latter is actually a Drupal module) relate closely to CiviCampaign and their special functionality is described in the respective chapters. 

There is also a separate reporting section related specifically to using reports and doing analysis on your data for ongoing evaluation of your work. 

Contributing to this manual

If you would like to contribute to this book, please follow these steps:

1. Register

Register at FLOSS Manuals:
 http://booki.flossmanuals.net/register

2. Write

Select the manual http://en.flossmanuals.net/bin/view/CiviCRM/WebHome  and a chapter to work on.

Make sure you are logged in, choose the WRITE version of the web site (the default is only READ) and click the "edit" link next to the chapter you want to work on. You can also create new chapters and put chapters in a different order.

3. Mailing List

For discussing all things about FLOSS Manuals, join our mailing list:
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

Importing Data into CiviCRM

Most organisations have data in sources outside CiviCRM, such as previously used database platforms, spreadsheets created on the fly for specific events or other purposes, and email address books. Because manually entering large amounts of data can be tedious, CiviCRM provides a way do import data en masse if the source can export it into some common format such as a Comma Separated Version (CSV) file.

Considerations before importing

It might be useful to think about your pre-existing data in the same way as the contents of a house or apartment when you need to move. People often use moving as a chance to say, "Do we really need this? This stuff is too old; let's trash it and get some new stuff once we have moved in."

To apply this metaphor to your data, look for fields that have no purpose, such as old organisational divisions that you've abandoned or office locations in a facility you no longer occupy.

Some old data will have continuing value. For instance, one organisation in a financial pinch decided to use an old list of founding donors who had not given money for many years. It turned out that these lapsed donors still had strong emotional ties to the organisation that they had founded and they came to its financial rescue. In that case, saving old data was crucial.

Moving to a new living space doesn't just provide an opportunity to evaluate what's really important to keep and what can be left behind; it also gives you a chance to clean up everything that you do decide to take with you. Just as you wouldn't pack up dusty picture frames and dirty dishes because that would make your nice new clean place as dirty as your old place, you'll want to clean up your data before moving it into CiviCRM so that you're starting off with as clean and useful a database as possible.

In planning for a move to CiviCRM, prepare to spend a good amount of time looking at your old data; standardising how different elements of contacts' records are stored (e.g. are states entered as NY or New York?) and deleting obvious duplicates, accidental entries, outdated information, and corrupted records.

Preparing to import data

Importing data requires considerable attention and care, so we'll present some concepts here that you should know before you start your first import. You can import both core and custom data for contacts, as well as data for event attendance, activities, memberships and contributions. This chapter focuses solely on the import process for contacts, though the processes for other data are similar.

There are two ways to import data:

If you do not have a clear understanding of your existing data and how it will map to CiviCRM fields, you will experience frustrations and problems when you try to import the data. Please read about each type of data in other sections of this CiviCRM Manual and visit the CiviCRM online documentation for more information: http://wiki.civicrm.org/confluence/display/CRMDOC/Importing+Data

The following rules and recommendations will help you to import data with minimal problems:

Setting up a CSV file for importing

Example of spreadsheet .csv format

student_sample

When thinking about setting up your spreadsheet, think about the data that you are collecting and plan out your column headings. Keep in mind that you may need to create more than one .csv file and perform multiple imports before you are finished.

If you plan to import related data that pertains to a specific contact, e.g. event participant information, contribution data, etc., you will need to make sure that each contact record has a unique identifier or the contact record should have First Name, Last Name and Email, so that you can link their related data during later imports.  If you have unique ID, you would map the ID to CiviCRM's External Identifier on import.

Running an import

The import process has four steps.

Step 1: Setup

Setup lets you specify the basic details of your import, including the source of the data. Data can come from either a CSV file, or an SQL query of a database on your server. A check-box lets you indicate whether the first row of your file contains column headers.

Step1a

Imports use the default strict rule to decide whether a contact record is a duplicate (refer to the Deduping and Merging chapter in this section for information on duplicate matching rules in CiviCRM).  You can specify what action to take when an import encounters a duplicate:

Step1b

Import mappings tell CiviCRM how the fields of data in your import file correspond to the fields in CiviCRM. The first time you import from a particular data source, it's a good idea to check the box to "Save this field mapping" at the bottom of the page before continuing. The saved mapping can then be easily reused the next time similar data is imported, by requesting that it be loaded at this step.

Step 2: Match the fields

If you had column headings in your file, these headings will appear in the first column on the left-hand side of the Field Map, while the next two columns show two rows of data in your file to be imported, and the fourth column is the Matching CiviCRM Field. If you loaded an import mapping in Step 1, your choices will be reflected here. You can change them if they are inappropriate for this import.

ImportMatchFields 

The matching CiviCRM fields include standard CiviCRM data such as First Name and Last Name as well as any custom data fields that have been configured for use with contact records on your site. Match the fields by clicking the dropdown list and selecting the appropriate data. For example, if the heading of the second column in your input is Surname, you should choose Last Name as your Matching CiviCRM Field.

Select "- do not import -" for any columns in the import file that you don't want to import into CiviCRM.

If you have a saved mapping for a specific set of spreadsheet columns, and your spreadsheet layout has changed (for instance, you need to import additional fields, so you add the appropriate columns of data in the spreadsheet), you can modify and save the field mapping. One tip to ease the mapping process when you need to import additional fields is to place the additional columns of data in your import spreadsheet to the right of the columns you've previously mapped in CiviCRM. This allows you to use the existing saved field mapping to map the initial import fields, and then continue mapping the new data fields.

Step2d

Note that if you add new data columns in your spreadsheet and do not position the columns AFTER the columns you previously mapped, you then can't use the saved mapping and will have to map all your import fields again.

Once you've mapped your fields, you can decide if you want to keep the original saved mapping unchanged, or check the box to "Update this field mapping" to include the new field mappings.

Step 3: Preview

This screen previews the results of importing your data, reports the number of rows to be imported, and allows you to double check your field matches.

If some of the rows in your spreadsheet contain data that doesn't match CiviCRM's requirements for one or more fields, you'll see an error message with a count of the invalid rows (see the screenshot below). Click the Download Errors link and review the errors reported in the downloaded file, so you can fix them before doing the import. 

ImportPreviewErrs

At the bottom of the form, you can choose to add the contacts to an existing group, import to a new group, create a new tag, or tag imported records. Adding imported records to a separate group is strongly recommended in order to be able to quickly find the imports and, if necessary, delete and reimport them.

Step3b_1

Step 4: Summary

The final screen reports the successful imports along with Duplicate Contacts and Errors. If you have set the import to add all contacts to a Group or Tag, you can click through to see your imported contact records.

Step4a_2

At this point it makes sense to check to make sure that your import has worked as expected.  Search for the contacts that you just imported and examine their fields and custom data to make sure all is as expected.

Importing relational data

We have just described the process of importing one data file.  But what about if you want to import related data, like parent child relationships, activities, contributions, etc.?  For each type of data you want to import, you will need to import a seperate CSV file.

CiviCRM has specific tools for importing related contact data and a set of specific import tools for contributions, memberships, event participation etc. (and you should see specific chapters for details of how to use these tools).  To import relationships, you should run multiple contact imports.

For example if we want to import data for children and then for both parents, we run three imports, one for the child, one for the father and one for the mother.

We first import the child remembering to include an external identifier that we can use to match the child to their parents.  We then import the father, and then the mother, as related contacts, linking them to the child using the child's external identifier.

In the example below we have one CSV file which contains father and mother information.  We use this CSV file twice as part of the import.  Have a look at the fields below to understand what is happening.

Parent1a

We are linking the father to the original child using the external identifier and are then importing the related father name using the 'Child of' relationship type.

Parent1b

When the import is done, go back and verify the data by searching for the parent and examining the relationship tab.  They should have a relationship linking them to the child.

You can then repeat this process for the mother, and also for other relationships as necessary. 

Address standardisation 

For many organisations, an important element of cleaning your data is standardising addresses. In the US, this means conform to conventions defined by the United States Postal Service's Standards for Addresses. Standardising how addresses are entered into CiviCRM will allow for more accurate search results when searching by address, as CiviCRM can parse addresses based on the USPS standards if you choose to do so.  To find out more about how Address Parsing is handled and used in CiviCRM, refer to the Installation chapter of the Configuration section of this manual. When adding or editing contacts, you will enter and edit such address elements as street number, street name, and Apt/Unit/Suite number according to these standards.

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 athttp://pe.usps.com/text/pub28/welcome.htm  orhttp://pe.usps.com/cpim/ftp/pubs/Pub28/pub28.pdf for the pdf version.

 

Installation & Basic Set-up

Before reading further, please be aware that much of the information contained here is intended for technicians and may be difficult to understand if you have little or no experience in setting up web applications. If you don't understand this topic, you may wish to either seek help, or point your organisation's technical staff to this material.

Prerequisites

CiviCRM must be installed on a computer that has been configured with a web-server (such as Apache or ngnx), PHP 5.2 or later, and MySQL. Some people prefer to try out CiviCRM on their own local computer before installing it on a dedicated web-server. If you are doing this and don't have the per-requisites just mentioned, you can download packages from the Internet such as WAMP, XAMPP, MAMPP and LAMP, which will quickly install an Apache web server, PHP, and MySQL. (The first two packages are for Windows and the second two are for the Macintosh and Linux respectively).

Before you can begin installation, you need to decide whether you are going to use CiviCRM integrated with Drupal or Joomla!. Refer to the appropriate section in the online CiviCRM Installation Guide for the latest system requirements and specific installation steps:
http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

Network Access

Once you are ready to start using CiviCRM in your organization, you'll probably want CiviCRM to be available on the Internet. However, some organizations only want internal staff to have access. In this case they may choose to install CiviCRM on an intranet or local area network.

Upgrades

New versions of CiviCRM are released two or three times a year, and you will need to apply upgrades to your CiviCRM site periodically in order to take advantage of new features and improvements. Some upgrades contain security fixes and it is crucial that these are applied in a timely manner. It's important that you plan for the resources (people and time) required to apply upgrades to your site. You need to plan on testing upgrades on a copy of your live site to make sure the process runs smoothly. It's also critical to make backups of your site and database prior to running an upgrade on your live site even if you had tested the process on a test site.

Refer to the appropriate section of the online CiviCRM Installation Guide for specific upgrade procedures. Be sure to select the procedure that is targeted for the environment you are running (Drupal or Joomla!), and the version you are upgrading to.

Configuration

Now that you have CiviCRM installed and running on your web-server, it's time to review the initial configuration tasks which allow you to customize CiviCRM for your organization.

You can easily access each of the configuration screens described in the following screen from the Configuration Checklist. Log in to your CiviCRM site and navigate to Administer CiviCRM > Configure > Configuration Checklist. This section will cover the general tasks, while component-specific configuration will be covered in each component section.

Picture_10

Localization

Localization involves adapting CiviCRM for use in a specific country or language by translating the text displayed on the screen and setting region specific formats for dates and money (including currency). By default, CiviCRM is localized for the United States. If you are using CiviCRM in a different country, need to store contact addresses that appear in countries other than the United States, or want to use CiviCRM in another language, you will need to review and update the values on this screen.

CiviCRM has been translated into a number of different languages. These translations are contributed by community members. So your first step is to determine if a complete translation exists for the current version by visiting the Translation Server home page at http://translations.civicrm.org/. If you find a completed translation, you can download it and select it on this screen. Otherwise you will need to consider whether you have resources for contributing a translation.

It is also possible to configure your site to support multiple languages. In this mode, your users will be able to choose from a list of available languages after logging in. You can also create and store multi-language versions of text. Examples include custom field labels, an online contribution page, campaign information, and event descriptions.

Further reading:
Localization overview - http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Localisation

Domain Information

Use this screen to enter identifying information for the organization or entity which "owns" this CiviCRM installation. The organization name and address are used to identify your organization in CiviMail mailings when you include the domain.name and domain.address tokens.

You should also enter a valid email address belonging to your organization, which will be used as the From field in system-generated (automated) emails.

Site Preferences

This screen allows you to modify the screen and form elements for the following tasks:

Address Settings

CiviCRM allows you to modify the default fields for adding and editing contact and event address data. You can also change the address field layout used for screen display and mailing labels. Review the out-of-the-box defaults by adding a new contact record and noting the address fields provided on the form. Save the record and note the order in which the fields are displayed on the Contact Summary screen. If you plan on generating mailing labels for contacts, review the label layout (select Mailing Labels from the -actions- drop-down after doing a search using the Find Contacts menu option).

After reviewing the default fields and layouts, review the Address Settings screen and make changes as needed.

Mapping and Geocoding

CiviCRM includes support for both the Google and Yahoo mapping services. These services allow your users to display contact addresses and event locations on a map. To enable this feature, select your mapping provider and obtain a key for your site from that provider.

Once a mapping provider is enabled, your contact and event records will be automatically geocoded (the latitude and longitude for that address is inserted) as you add or edit address data.

Search Settings

These let you adjust search behaviors such as the use of wildcards and which data to include in quick search results. Adjusting search settings can improve performance for large datasets.

A wildcard character is a special character that can be used to substitute for any other character or characters in searches. CiviCRM allows you to use the percent (%) character to substitute for zero or more characters, and the underscore (_) character to substitute for any single character. Wildcards are useful for broadening your search results.

For example, typing 'Volunteer%' as your Activity Subject will match any record whose subject starts with "Volunteer" (e.g. "Volunteer for Open House" or "Volunteering Opportunities").

Miscellaneous: Version Checking, reCAPTCHA, Use Trash, Logging

Use the Miscellaneous Settings screen to configure and control the following behaviors:

If you want to use reCAPTCHA protection for online contribution, membership signup or event registration forms, you'll need to configure a Profile with reCAPTCHA enabled, and then include it in those forms.

Contact Types

Here you can modify the names of the built-in contact types (Individual, Household, Organizations), and create or modify "contact subtypes" for more specific uses (e.g. Student, Parent, Team, etc.).

Sending Emails

CiviCRM will use the default From address defined here when sending automated emails. If you've already entered an email address in the Domain Information screen, that address will be listed here (as illustrated on the leftmost field of the following screenshot).

Picture_12

When users send an email using CiviCRM, their primary email address is used as the From address by default. However, they can also select one of the general email addresses defined here as an alternative.

Outbound email

If you are sending emails to contacts using CiviCRM, you need to enter settings which allow CiviCRM to connect to your mail server. Such emails include sending receipts to contributors, sending confirmations to people registering for events, and using CiviMail to send bulk mailings.

CiviCRM supports three different methods of connecting to a mail server: mail (the built-in PHP mail function); SMTP (Simple Mail Transport Protocol); and Sendmail. Each method requires that you enter specific settings. If you're unfamiliar with these terms, or unsure of the correct values for these settings, check with your system administrator, ISP or hosting provider.

You should always send a test email after you enter or modify the settings. Simply click "Save and Send Test Email"(shown in the following screenshot). An email will be sent to the email address associated with your user login account. The From email address will be the default From address you've configured in the previous section.

Picture_11

If CiviCRM is unable to send the test email, you will see a message on your screen with the specific error and some suggestions for trouble-shooting the problem.

Disabling outbound email

If you do not want users to send outbound emails from CiviCRM at all, select "Disable Outbound Email". However, if you disable outbound email, and you are using Online Contribution pages or online Event Registration, you will need to turn off the automated receipting and registration confirmation features (these are enabled by default). Otherwise your constituents will see error messages after they've completed a contribution or registration.

See Email System Configuration for more details.

Payment Processors

Payment processors are companies that handle credit card transactions for merchants and non-profit organizations and that transfer funds to the organization's bank account. If you plan on using CiviCRM to accept online contributions, online membership signup and renewal or online event registration, you will need to select and configure a payment processor for your site.

CiviCRM includes support for several different processors, and provides a way for third-party developers to add support for additional processors based on their clients' needs. Each processor has their own pricing structure and features, and you will want to investigate each available option to determine the best fit for your organization. Refer to the "Contributions" section for a list of factors to consider in selecting a processor.

The actual steps involved in configuring and testing your payment processor connection are different for each processor. For more information, visit:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviContribute+Payment+Processor+Configuration 

Permissions for anonymous users

Note: This section applies to Drupal sites only.

If you are using CiviCRM with Drupal, you will need to review Drupal's user permissions to ensure that people can get to your signup forms, contribution pages, membership pages and event registration pages.

You must be an administrator for your Drupal site to review and modify user permissions. Log in to your Drupal site, and navigate to Administer > User Management > Permissions.The following screen is displayed.

Picture_13

Picture_14

Review each of the permissions listed. You should enable them for the anonymous user role if you want these features to be accessible to people who visit your site without logging in--outsiders registering for membership or events, for instance:

Now that you have reviewed all the basic configuration tasks, you're ready to begin exploring the ways in which you can record and use contact data.

System Workflow Templates

Review and modify the templates used for system-generated emails, including contribution receipts and event registration confirmations.

Is CiviCRM for You?

This chapter will help you to decide whether CiviCRM is the right tool for your organisation.

CiviCRM is powerful software and has the potential to help your organisation reach its goals - but it won't be the right choice for every organisation. Here are some ways that you can find out whether CiviCRM is right for your organisation:

Demonstration sites

CiviCRM hosts several demo sites - there is at least one for each of the two supported Content Management Systems (CMS) - Drupal and Joomla!. The demo sites present a working copy of the latest stable version of CiviCRM with sample data. You can use them to play around with CiviCRM but be aware that they are publicly viewable so you shouldn't enter personal data.

A list of the available demos can be found at http://demo.civicrm.org/

Other people are likely playing on the demo sites at the same time as you, so they may be configured strangely, missing functionality or appear in different languages.

The demos have some limitations - you can't send emails from them, you can't set permissions for Drupal users or do a full exploration of online payment options.

If you are having trouble working on a demo site, contact the CiviCRM core team via the forum or IRC.  If you want a more controlled environment for exploring CiviCRM, install your own test site.

Test installations

If you have technical skills or are feeling adventurous, you can download and set up a local version of CiviCRM, that is a version that is stored on your local computer rather than on a server on the internet. You'll still access it through a browser, but it will only be visible on your computer. The advantage of a test installation is that you can configure CiviCRM in the way that you want to use it, and experiment with your data.

Up-to-date information for installations (including troubleshooting tips) is maintained at http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades.

Talking to others who use CiviCRM

If you know of another organisation that uses CiviCRM, talk to them about their experience. Obviously the more similar they are to your organisation, the better. If you don't know anyone that is using CiviCRM, have a look on the CiviCRM forums, at case studies on the community site, or try your local non-profit technology mailing list.

The CiviCRM forums (http://forum.civicrm.org) have a few boards for people who are new to CiviCRM, such as "Pre-installation Questions" (http://forum.civicrm.org/index.php/board,5.0.html). Remember that the forums are staffed mainly by volunteers so you will get a better response if you spend some time formulating an easily answerable question. You can also search the forums and browse for questions that others have asked. If you wish to ask questions or contribute to the discussions you must register first.

Talking to CiviCRM Consultants

Another option to help you understand CiviCRM is to make use of a professional. The CiviCRM website lists professional vendors and consultants that can walk you through CiviCRM (http://civicrm.org/professional), and there are many others; you may find a local website company who has experience with CiviCRM. Consider hiring a consultant for a day to discuss with you how CiviCRM could help your organisation.

Localising CiviCRM

CiviCRM is written with English-language code and strings for display. It has, however, also been built for organisations worldwide. They need to be able to adapt the tool to local circumstances and demands without modifying the tool technically.

Localising CiviCRM (or any software) affects much more than you might initially think. To adapt CiviCRM to a local language is not just a matter of translating the text displayed on the screen. Consider for example the currency used in a given country (USD or $ in United States, GBP or £ in Great Britain), date and time formats (for example: November 16th, 2009 will be commonly written as 11/16/2009 in United States, but in Russia the format will be 16.11.2009) or the formatting of numbers (the same number will be written slightly differently in different countries: 1 234 567,89 in Slovakia or Hungary, but 1,234,567.89 in Japan or the United States).

CiviCRM provides plenty of functionality to support these language and region specific needs. The development team is constantly developing new tools in this area too.  The Localization screen (shown in the following screenshot) lets an administrator select the right locale for the language and country of the organization using CiviCRM. Go to: Administer > Configure > Global Settings > Localization.

2 

Translations

CiviCRM accommodates different languages, however the developers rely on the community to translate the text displayed.

A number of languages have already been provided to a greater or lesser extent. Some have more than 90% of the text translated, others only 5%, and a number of languages have not been translated at all. Please check the online translation tool Transifex (http://www.transifex.net/projects/p/civicrm/) to find out about your language of interest. Download and install it on your CiviCRM installation to find out how well it will suit your needs.

You may find that although the translation is correct, you would want to use different terms in your situation. You are very much encouraged to take part in the translation of your language.

Facilities

A number of facilities in CiviCRM support the community in its translation efforts, though some are still under development.

  1. Transifex is an online tool that enables groups of translators to translate strings of text and keep an overview on its progress. Register there, look for your language, join the team or, if your language is not available, start translating.
  2. A glossary (http://wiki.civicrm.org/confluence/display/CRM/Glossary+for+translations) on CiviCRM's wiki will help you maintain consistency in your translations. It will also help you get some insight on how much work it will be to translate those strings of text that your users will most often see and that would therefore be the first to translate.
  3. A tips and tricks wiki page (http://wiki.civicrm.org/confluence/display/CRM/Localisation+community+building+howto) explains how to set up your localization community.
  4. A FAQ (http://wiki.civicrm.org/confluence/display/CRM/Getting+started+with+CiviCRM+Localisation+FAQ) on the CiviCRM wiki covers localisation.

Getting Started

Feel like helping translating CiviCRM to a new language or improving the current translation? Here's how to do it (provided you have a bit of a technical background):

  1. Go to transifex.net and create an account.
  2. Look for your language on http://www.transifex.net/projects/p/civicrm/teams/ and either join a team, or request the creation of a new one if needed.
  3. Start translating!

Team work

The CiviCRM translation work flow is still a work-in-progress and until the process becomes more mature, you should probably refer to http://wiki.civicrm.org/confluence/display/CRM/Localisation+community+building+howto  for the most current instructions.

The work flow is heavily based on teamwork. Hopefully, there is already a team of translators for your language that you can join. This team will have built a glossary, will have started a translation set and will be able to review your translations and give constructive criticism.  If such a team does not yet exist, the opportunity is all yours to create one.

Components and files

There are quite a lot of strings (phrases) to translate in CiviCRM. To make it easier to translate the part that you are interested in (hopefully the one you know best), the strings that need translation have been divided into components, which are CiviCRM plugins (e.g., CiviCRM core, CiviMail, CiviContribute, etc.). A separate component should be available for each version of CiviCRM, starting with version 3.2 (or 3.1, for language teams that have chosen to do so).

Each component itself contains a number of files, which themselves contain the strings to translate. The main component "CiviCRM" (the core) has close to 20 files (for countries, provinces, menu, etc.).

Tools and technical details

The process you use to do translation depends on whether you prefer to do translation online or offline. Online translation does not require installation of any software. Offline translation is done with files downloaded from the translation website, using software that offers more features than the online system.

Online translation

Transifex is the tool to use for online translation. It does not have as many features as an offline tool such as PoEdit, but it's the easiest way to contribute translations and do the occasional quick correction. Every translator should have an account on the Transifex site, because translation teams can use the forums and messaging system to coordinate their work.

The basic steps in online translation are:

  1. Select a component on http://www.transifex.net/projects/p/civicrm/. This will display the list of language teams for this component.
  2. Click on the icon in the Options column next to the language you are interested in. This brings you to the list of files for this component.
  3. Click on the "pencil and paper" icon. This brings you to the online translation screen, which lists all the translatable strings in this file.
  4. For each string, you can then enter a translation.
  5. When you are finished, you can click on the "Send for review" button at the end of the page.

Offline translation

Most translation is usually done with an offline translation tool. One of the most common is PoEdit (see http://www.poedit.net), which is free software and has a big community of users. The exact steps in translation using an offline tool depend on your tool of choice, but should follow the following steps:

  1. Download the files from transifex.net you want to translate,
  2. Load the files up in your translation tool and do your translations.
  3. Send them back to the site when you are done.

Building a translation memory

PoEdit and other translation software will help you build a translation memory for your language. This translation memory can either be restricted to translations done in CiviCRM, or include translations from other projects. If you include other projects, automatic translation might be able to translate more strings, but you will lose consistency and most strings will be marked as fuzzy. This could be a way to bootstrap a new translation, though.

Building a translation memory based on words from the glossary could go a long way in insuring the consistency of your team's work.

Using version control (mostly for programmers)

Transifex keeps files in a version control system, http://github.com/civicrm/l10n. This is useful to some users who find interacting with the Github site easier than downloading each file separately from Transifex.

Consistency & consensus

To insure a good consistency in the translation, every team is encouraged to build and use a glossary and employ peer review. You can find a glossary of common terms on http://wiki.civicrm.org/confluence/display/CRM/Glossary+for+translations. You definitely should translate these terms to your language, and make sure your team reaches a consensus on all terms.

Building and sharing a common translation memory, which is like a specialized glossary that can be used automatically by translation tools,  also helps to insure consistency. The PoEdit help system explains how to build this database (and most other translation software should do the same).

Team building and sprints

A good way to make progress in translation is to organize translation sprints. This means getting as many people as possible together in the same room to translate as many documents as they can. Here are a few things to keep in mind when organizing a translation sprint:

Menu, Dashboard & Dashlets

This chapter gives an overview of CiviCRM's dashboard (it's 'home page') and the navigation menu available for people working in CiviCRM.

The navigation menu

The navigation menu is a small bar at the top of every "back office" page of CiviCRM.

NavMenu_menu ...

It provides access to nearly every function of CiviCRM and is broadly organised into headings by individual CiviComponents (such as Contributions, Events and Mailings), with a few exceptions for Search and Administer, both of which cover all of the enabled CiviComponents.

NavMenu_SearchPulldown 

The menu also features a Quick search field for finding contacts. Typing any part of a contact's name or email address into the Quick search field will pull down a list of possible matches that you can click on to go directly to the contact's summary page:

NavMenu_quicksearch

You can modify the navigation menu by going to: Administer > Customize > Navigation Menu and then adding or rearranging menu items on the screen. Remember that changes you make to the navigation menu will be seen by everyone who has the appropriate permissions to see the menu, for better or for worse, so be careful when modifying the navigation menu.

The dashboard

When you first log into CiviCRM, the first page that you will see is the dashboard (CiviCRM Home). The dashboard allows you to see important information about your site and CiviCRM by displaying a series of "dashlets". A dashlet is a snippet of information about a part of CiviCRM: many dashlets come with CiviCRM by default, and you or your administrator can create additional dashlets that are specific to your organisation's needs. Some examples of dashlets that come with CiviCRM include:

Dashboard_homescreen

You can add these dashlets to your CiviCRM dashboard by clicking the Configure Your Dashboard button. You will see a list of dashlets that can be dragged into the right or left column of your dashboard.

Dasboard_editscreenClicking the Done button will allow you to save the dashlets to your dashboard. From now on, you will see updates to the status of your dashlets every time you log in (if you'd like to check and see any changes that have occurred more recently, you can always click Refresh Dashboard Data - this will reload each dashlet and pull in any new information).

Almost any CiviCRM report can be made available as a dashlet. Select a report from Reports > Create Reports from Templates. Update the report criteria as needed. For example, you may want the dashboard version of the report to always show data for "This Quarter" or "This Year". You can also choose to display the report as a table or as a bar or pie chart. Preview the report display. Then check the "Available for Dashboard" checkbox under Report Settings. (Refer to the Reporting section for more details on working with reports.)

Identifying Your Needs

This chapter covers some basic strategies for identifying your organisational needs, and how they could be met by CiviCRM. It doesn't go into detail about CiviCRM functionality or how CiviCRM stores data (you will find that in other chapters). Instead, we encourage you to first take a step back and think about your organisation.

Your organisational goals and practices

For now, forget about technology and focus on your organisational goals and processes. Here's a list of questions to start you off:

Understand your "contact relations"

The CRM in CiviCRM stands for Contact Relationship Management. By contact, we mean an individual, household or organisation that your organisation has contact with (you may call them members, constituents, clients or some other term).

Many organisations make the mistake of not thinking about who their contacts actually are. Spend some time identifying all the people involved with your organisation. What different types of people do you interact with, and how do they differ from each other? The better you understand them and their interactions with your organisation, the better you can model them in CiviCRM. Anecdotal or systematic feedback from your contacts may be useful here.

Take advantage of institutional knowledge

In thinking about your contacts and their interactions with your organisation, talk to your co-workers, including those who have been around the longest and those who have just joined. Talk to as many people as possible to get a complete picture of their interactions with all kinds of contacts.

As well as talking to people, look at your organisation's data repositories: your databases, spreadsheets, file servers, address books, and any existing stored information you may have that can help you understand who your contacts are and how they interact with your organisation.

Map your needs to CiviCRM

CiviCRM has been designed to be flexible and adaptable, based on feedback from many different non-profits, but it may not map exactly to the ways that your organisation currently works. Doing things the CiviCRM way could mean adapting your workflow and adopting best practice in non-profit technology. Be pragmatic and flexible and consider whether your current working practices need to change.

It's worth remembering that CiviCRM offers many opportunities to interact with your contacts in ways that you have not previously had. Taking advantage of these new possibilities can lead to positive changes and improvements.

PAYMENT PROCESSORS

Using CiviCRM you can accept online card and PayPal payments for events and contributions. There is a wide and growing range of processors available but only a handful are actually distributed with CiviCRM. Check on the wiki at http://wiki.civicrm.org/confluence/display/CRMDOC/CiviContribute+Payment+Processor+Configuration or the extensions directory http://directory.civicrm.org/ to see whether the processor you need is available. There is also a forum board with information on community contributed processors at http://forum.civicrm.org/index.php?board=38.0. For many countries there aren't payment processors written that support their currencies while for others there is a choice. Paypal is the most widely available option. If you need to get integration with a particular payment processor, you might ask about this on the forums or approach one of the companies on the professional services page.

Set up 

You can configure one or more Payment Processors for your CiviCRM installation. You will then need to assign an active Payment Processor to each Online Contribution Page and each paid Event. If no Payment Processors have been configured for your site, go to the New Payment Processor form Administer -> Configure -> Global Settings -> Payment Processors. On the Payment Processor form:

 

Choose Payment Processor Type  from the drop-down list 

Assign a descriptive Name to this processor configuration and an optional description. This is particularly important if you are configuring multiple merchant accounts for different chapters or sub-organizations within your site.

Make the processor active so it's available to events and contribution pages.

Finally fill in the details of you test and live accounts so you can use it in both test and live environments.  You will of course need to do some further set up on the actual payment gateway but that is beyond the scop of this book and should be documented by your gateway.

Once you've done all that, the processor will be available in your paid events and contribution pages. 


Set-up

This chapter describes the steps needed to set up a petition.

The CiviCampaign component must be enabled before you can use Petition. See the section Campaign for information about this. 

Set Drupal permissions

For Drupal sites, you will need to set the appropriate Drupal permissions so that specific roles can sign the petition, particularly anonymous users if you're planning to make the petition public.

  1. Go to Administer (in Drupal; if you don't see the Drupal Administration menu, then you have not got the appropriate permissions to do this). 
  2. Select User Management > Permissions.
  3. Under civicrm module check the box for Sign CiviCRM Petition for the roles you require. For example, if this is to be a public petition, you must check this box for anonymous users.

To learn more about setting Drupal permissions, go to the Drupal documentation at http://drupal.org/getting-started/6/admin/user/permissions.

Create two Custom Profiles

In order to create a new petition, you must create two custom profiles: one to capture the contact information of the signer, and the other to capture the responses to the petition questions. The responses to the petition questions are recorded in the activity record of type Petition for each individual who signs the petition.

  1. Create a custom profile for the contact information you want to collect, such as First Name, Last Name, and Email. You may want to make some of these fields required so you capture enough information to communicate with signers at a later date. Note: you must collect at minimum an email address in the contact profile, because the Petition feature will send an email to the signer of the petition to prompt them to verify their email address. Only those verified email addresses can be counted.
  2. Create a custom profile with custom fields to capture responses to the petition questions.  When creating the custom field set, from the Used For dropdown menu select Activities, and for the activity type select Petition. 

For both profiles, you may want to select the following settings in the Advanced Setting area:

To learn more about how to create custom field sets, see the chapter Custom Fields in the Organising Your Data section. To learn about how to create a custom profile, see the Profiles chapter.

Create a New Petition

Once you have created the two profiles, you are ready to create a petition.

  1. Go to Campaigns > New Petition, then enter the following information about your petition: 

Everyday Tasks

This chapter describes the everyday tasks to conduct and manage petitions.

Manage Your Petitions

To view, manage and edit your petitions, click Campaigns > Dashboard > Petitions.

Send out a petition for signing

When your petition is ready, you will want to publicise the URL where people can sign it.

  1. Go to Campaigns > Dashboard > Petitions.
  2. Click More > Sign next to the name of your petition.
  3. You will see your petition; copy the URL and use this link to email to your existing contacts, or add to your web site for individuals to sign your petition.

Collect Responses Online

Once you have publicised the URL for your petition, people will be able to complete the form, answer the questions and submit their response. 

After completing the form and clicking Sign the Petition, they will see the following message prompting them to check their email and verify their email address:


Collect Signatures

To view who has signed the petition:

  1. Click Campaign > Dashboard > Petitions.
  2. Click More > Signatures next to the name of your petition.
  3. You can then choose to view the petition activity for an individual, or select contacts and perform activities such as sending an email to the contacts, or a batch update via profile. 

Review results with Activity Report 

To review all or some of the results from a petition, use the Activity Report.

  1. Go to Reports > Create Reports from Templates > Activity Report.
  2. In the Display Column area, select any fields you would like to view on the report, such as Target Contact Email.
  3. Expand the Petition Questions area and select the criteria you want to see, such as specific responses to a petition question.
  4. Click Preview Report to view the results. You can also export the survey report information to a CSV file to do more detailed reporting of the results. 



What You Need To Know

The following concepts are important to understand before creating and using petitions, and the key questions will help you to plan your petition.

Key Concepts

Petitions are a function within the CiviCampaign component of CiviCRM. When an individual responds to a petition, an activity record of the type Petition is created that contains the individual's responses to the petition questions. 

Petitions and campaigns

Petition is a feature of CiviCampaign; but a petition doesn't necessarily have to be connected to a specific campaign. For example, if the Toft Organisation For Tenants (TOFT) used a petition to assess members' satisfaction with TOFT's web site, it probably would not need to be connected to a campaign. But the petition described in the scenario in the previous chapter is part of TOFT's Demand for Better Housing campaign, which includes a survey and other activities. Connecting the petition to the campaign enabled the organisation's staff to analyse petition responses in the context of the other strategies and activities in the campaign.

Profiles and custom fields

Using petitions in CiviCRM requires setting up two profiles. One profile is to capture basic contact information, including email address. Capturing email addresses via petitions is necessary to validate and accurately count signatures. The other profile contains custom activity fields that hold the responses to the petition questions.

You will want prepare your questions and the standard responses, if any, you want to gather before creating your custom field sets and custom profiles. 

To learn more about how to create custom field sets, see the chapter on Custom Fields in the section Organising Your Data. To learn how to create a custom profile, see Profiles in the section Organising your Data. 

Key Questions

Think about the online strategies you will use and consider these questions before creating your petition:

What is a Petition?

CiviCampaign includes a function that lets you create a petition to publicly gather responses and information online.

Typically when we think of petitions, we think about individuals signing a petition for a particular cause that will then be presented to an elected official or for education about a specific issue. But petitions can also be used as an online surveys, to gather responses about questions and then allow the an organization to build support about their causes based on the analysis of the responses.

Scenario: City Council petition

Townsville Organisation for Tenants (TOFT) wanted to demonstrate to the Townsville City Council the public's dissatisfaction or satisfaction with the Council's work to provide safe public housing for the community. In order to do this, they created a petition that would gather responses to questions at the same time as gathering signatures. The results were then presented to the City Council.

A TOFT staff member used CiviCampaign to create the petition then sent it via email to all of their existing contacts. She linked the petition to the organization's web site so that the community could respond online, and worked with the Communications Director on various communication strategies to drive individuals to the web site to fill out the petition. 

The petition also allowed respondents to elect if they wanted to receive ongoing email updates from TOFT about the campaign's progress throughout the year. 

After the duration of the petition drive, the staff member compiled the electronic signatures and responses, created reports to analyse the results and then the organisation communicated the results to City Council. The results of the petition were also used to frame TOFT's messages and communicate their story to build interest about the campaign.

REPORTS AND ANALYSIS

There are a couple of simple tools to report and analyse petitions.

View signatories

To view who has signed the petition:

  1. Click Campaign > Dashboard > Petitions.
  2. Click More > Signatures next to the name of your petition.

Review results with activity report 

To review all or some of the results from a petition, use the Activity Report.

  1. Go to Reports > Create Reports from Templates > Activity Report.
  2. In Display Column area, select any fields you would like to view on the report, such as Target Contact Email.
  3. Expand the Petition Questions area and select the criteria you want to see, such as specific responses to a petition question.
  4. Click Preview Report to view the results. You can also export the survey report information to a CSV file to do more detailed reporting of the results. 



 

What You Need To Know

The CiviCase component allows for a high degree of customisation to meet the needs of a wide variety of organisations and workflows. It is important to understand CiviCase's underlying principles and assumptions, as well as the elements that can be customised, before you begin to plan and configure the component based on your requirements.

You should also understand that the configuration of CiviCase goes beyond the user interface and requires the production of an XML file to define the activity types allowed, time offsets between them, roles and other elements.

Key  Concepts

CiviCase tracks interactions in two ways: cases and activities.

Activities are single interactions. For example, if a constituent calls to request information and the staff person directs them to a web site, this would be recorded as an activity. Activities have a start and end date, a status and several contacts that they may be associated with: a creator, an assignee and a target.

Cases are used to track more complex interactions or communication processes. Multiple activities can be grouped together into one case, and these activities can be optionally structured in a timeline. A case can be used to track a specific workflow that must be followed, for example: a client fills out an intake form, then has an initial meeting with a staff person, and finally receives a certificate from the organisation for meeting certain goals.

As well as linking activities around a common case, CiviCase identifies the people involved and their role(s) in the case. So while the staus options may be broadly similar, the options for contacts are far more flexible than for activities and the time span is usually less determined at the outset.

Case Types

The Physician Health Program provides support for physicians who are experiencing problems related to emotional health issues, the inappropriate use of alcohol and/or drugs or coping with physical illness. Some of the case types they use are:

For a community services organisation, examples of case types might include:

Think about the complex tasks that staff in your organisation do on a regular basis and make a list of potential case types.

Case Activities

Activities track specific interactions and tasks within a case. Activities may be scheduled in advance or created ad-hoc, and may involve the case client or constituent, or a third party such as a family member or a professional who is assisting with the case and other case workers. Each organisation needs to determine the level of detail to be recorded, but many organisations find it helpful to include every phone call, meeting or internal discussion in the case story by recording it as an activity.

Activity Types

CiviCRM is preconfigured with a number of activity types including Phone Calls, Meetings, Emails Sent, Interviews and Follow-ups. These may be sufficient for your needs. However many organisations will want to track other specific tasks, and activity types can be added for these.

During the life of each case, some activities will be automatically created, such as:

For a community services organisation, additional activity types might include:

For each of the case types you identified, create a list of the specific activities involved. Creating new types instead of relying only on Follow-up will make the list of activities easier to read.

Activity Data

A standard set of information can be entered whenever a case activity is recorded in CiviCase:

This is sufficient for some types of activities, however it is often useful to collect additional structured data. The Open Case (intake) activity is a common example where you may want to include a set of specific questions about the client and their situation.

Create a list of additional requirements (custom data) for each activity type, including the type of data being recorded (free text, multiple choice, date, etc.) in order to set up the required custom fields. For more information about custom data fields refer to the Custom Fields chapter in the Organising Your Data section. 

Timelines

CiviCase allows you to define a workplan or an expected sequence of tasks and activities for each type of case. These are called standard timelines, and one is created automatically when a new case is opened.

For really simple cases, the timeline might include only two items:

Even in this example, the timeline is useful as it allows you to predefine when the people assigned to the case should follow up with the client or constituent.

For more complex processes, the timeline provides a case plan that can help the people involved to stay on track. The timeline lists all the activities which are expected to occur and should be accomplished within a certain timeframe. You can define the expected number of days between the beginning of the case and each of the subsequent activities in the timeline.

If necessary, an activity can also define an offset from another activity. For example: for a Referral to Specialist case, the "facilitate first appointment" activity might be expected to occur within 2 days after the case is opened. "Survey client satisfaction" might be scheduled for 30 days after "facilitate first appointment".

You might also want to define a timeline based on the end date. If a case has to be completed by a specific date, each activity can be defined as needing to happen a number of days before this end date. You then set a negative offset on the timeline. 

Case Roles and Relationships

CiviCase provides three mechanisms for relating people to cases and clients:

CiviCRM provides relationship type definitions for most of the standard relationships you might track (e.g. Spouse, Child). However you will probably need to define additional relationship types for your case roles, such as:

Make a list of the expected case roles for each type of case you've listed, then determine which role will normally be considered the case manager for that case type.

Key Questions

Think about these questions with regard to your organisation's use of CiviCase: 

Assumptions

Although CiviCase is quite flexible, there are a number of case-management assumptions built-in to the component. These assumptions have been arrived at through an extensive trial and error process and although some of them may seem new or foreign at first, we encourage you to approach them with an open mind.

PLEDGES

Within your online CiviContribute donation form, you may allow your constituents to make pledges for future donations. By allowing pledges, donors have the flexibility to choose the frequency in how they will donate. For example, twice a year, twice a month for five months, etc. Some payment processors will not allow this kind of automation and the payments may come in as cheques, electronic payments or whatever else you allow. However, you can record future income against a current source such as an event or email campaign, etc. It also provides an automated mechanism to remind pledgers of their commitment.

Setting up Pledges is a simple part of configuring a contribution page. On the Amounts tab (second screen in the process), select the pledges checkbox and further options will appear like this:

Select the frequency and reminder options and  allow other amounts if applicable, and the pledge option will appear on the contribution page as below. 

 

Once you've started collecting pledges, you'll want to check on these through the Pledge home page. This is reached through the Contributions menu: Contributions -> Pledges -> Dashboard. and displays a summary of all pledges along with a list of individual pledges.

Then when you collect the payment for these pledges, you will need to visit the contribution page for the contact and click on the link at the top of the page entitled Click here to enter a pledge payment.  

Tokens and Mail Merge

You can use data in your CiviCRM database to set up mail merge communications both for emails and printed materials such as letters and mailing labels.  The mail merging functionality relies on Tokens which represent items in your database. This chapter explains how tokens work and how to use them in generating printing materials. Using tokens in emails and mass mailings is covered in the Email section.

Tokens

Tokens perform the equivalent of mail merge in CiviCRM. This means that it is possible to insert information from the database into an email or a letter that is different for every recipient.  Tokens are accessible via the Insert Token link in the top right corner of the message editing area.

Most of the tokens contain information that is in the database fields. However, there are some special tokens that accomplish specific tasks such as a link to an optout page or link to choose mail formats. Some tokens are only available for mass mailings such as the token to provide a link to a message stored online.

Only contact fields and actions can be inserted in your email as tokens. Related records, such as the name of the event for which the contacts have pending enrollments, cannot be included. However, in emails, you could provide a link to the person's contact dashboard so that they can review their registration details for themselves (once logged in). In emails, you can also use a checksum token that generates a unique URL for each contact so they can modify their information without having to login.

See here for details on using Checksums: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data

It is also possible to have custom tokens created by a developer. For instance, the total amount of contributions from a contact. To find out more about working with custom tokens, refer to the discussion about custom mail merge tokens in the Hooks chapter of the Extending CiviCRM section of this book and look at the wiki: http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data.

Another task for a developer is to create if/then logic for your mail merge. This is done using the smarty template language as described here http://www.smarty.net/docs/en/language.function.if.tpl.

Postal Mail Communications

This chapter discusses the different ways that CiviCRM helps with postal mail and post mail campaigns. It will help if you already have a strong understanding of CiviCRM's search features as well as custom fields, activities, profiles, and how to perform mail merges using word processing software.

Planning Your Mailing

Before beginning any communication activity, take the time to identify your goals and plan the steps. For our purposes, there are a few key questions to ask before sending out postal mailings.

There are three ways that you can use CiviCRM in postal mailings:

  1. Generate labels: print out standard address labels when you don't need to personalise the content, for instance to send a printed brochure.
  2. Export contacts and do a mail merge to an external tool (such as OpenOffice or Microsoft Word). Refer to the chapter on Exporting in the Getting Around section.
  3. Generate PDF letters and do the merge directly in CiviCRM.

Many nonprofit organisations in the USA need to sort recipients of a mailing based on zip code for bulk mailing purposes. If this is true for your organisation, it is recommended that you create your mailing labels using a word processor where you can control the sort order, rather than in CiviCRM. You can reuse the same spreadsheet for your mail merge.

Greetings and salutations

You can set a specific postal greeting format for each contact. There are several options from the friendly "Dear John", to more formal "Dear Mr. John Doe". You can also enter a customized greeting ("Your royal highness"). Postal greetings can be edited in the Communications Preferences section of the contact edit form. If you need to set or reset postal greetings en mass, refer to the Command Line Script Configuration documentation:

http://wiki.civicrm.org/confluence/x/LIK9AQ

Print PDF letters

The workflow is to first select the group you want to target, then choose the action "Print PDF letter" from the dropdown menu. The letters will then be outputted as a PDF, allowing you to easily print them.

To create the letter:

  1. Go to Search > Find Contacts or Find Contacts > Advanced Search.
  2. Enter your search criteria and click Search.
  3. Select the contacts who will receive the letter.
  4. From the Actions dropdown menu, choose "Print PDF Letter for Contacts" and click Go.
  5. Create your letter, using the formatting options provided. You can personalise the letter by using tokens, for example Postal Greeting is a commonly used token in this situation. Click in the body of the letter where you want to enter the token. Then click on "Insert Tokens" located above the letter at the top right and select the desired token.
  6. Before you move to the next screen, decide whether the format of this letter could be used again. If so, check the Save New Template box and enter the Template Title.
  7. When your letter is finished scroll to the bottom and click Make PDF Letters.
  8. A pop-up window will offer the option of opening or saving the PDF. Open and review your letter and then print it, or save the PDF and review at your leisure.

PostalGreetingToken

You can use this feature for any kind of document, not only letters. For example, you could use it to print attendance certificates for a workshop.

Generate mailing labels

Generating mailing labels is a very easy and useful function.

  1. Perform the search to select the contacts you want to target.
  2. Choose Mailing Labels from the Actions dropdown menu and click Go.
  3. Select the mailing label style
  4. Determine if you want to exclude people with "do not mail" checked in their privacy options (checked by default and recommended), and whether you want to merge any records with the same mailing address into one label.

This last option is very useful when sending a mailing to a households or organisations where you don't want them to receive duplicate mailings. When the records are merged, each name at that address is listed on a separate line on the label.

Your system administrator can configure the fields included in mailing labels. Read the information on configuring address settings in the Contacts chapter to learn more about the options.

Using CiviCRM Profile

A profile is a collection of fields (both predefined and custom) from your database. By creating a profile you are able to take only those fields relevant for a specific purpose, such as collecting information about a person registering for an event or displaying a directory of members on your website. The diagram below provides a visual explanation of how existing fields are assigned for use in a profile.

Profiles

Scenarios

Profiles provide powerful tools for collecting information from your constituents as well as sharing that information through your website. These features can save significant staff time by allowing people to update their own data, and you can display up-to-date information from your database in a variety of ways.

For example, a membership-based organisation can provide a searchable membership directory on their website that is updated as soon as a new member joins. Another example is a form where people can sign up to receive emails from your organisation. Once submitted, they are automatically added to the correct email list. Profiles can also be embedded in online contribution or event pages to collect additional information about the constituent.

This section will outline how to use profiles for both collecting and sharing data.

Overview

Profiles provide an flexible set of options for creating forms, directories, and much more. Think of a profile as providing a window into your data. Just as you can have many windows in a house giving different views of the various objects inside, you can have multiple profiles which refer to the same or different fields.

There are many ways that profiles can be used:

Another important point about profiles is that the same profile can be reused in multiple ways.

Collecting data from constituents

This section reviews the different methods by which you can use profiles to collect information from your constituents. A later section will discuss how to share information from CiviCRM with your constituents.

Volunteer sign-up form

Let's walk through an example of a profile used as a volunteer sign-up form. This simple form includes fields for First Name, Last Name, and Mailing Address. It also includes a reCAPTCHA widget to protect your site from automated abuse (described further below).

Picture_4_200

To build a a form similar to this one:
  1. Go to: Administer > Customize > CiviCRM Profile and click on Add CiviCRM Profile.
  2. Give the profile a meaningful name, and mark it to be used for a Profile:

    Profile_checkProfile_2
  3. The next two text fields allow you to include help text to assist the person filling out the form.
  4. The remaining options are listed under Advanced Settings (click on the gray bar to expand this section):
    1. Limit listing to a group: this is very important. If the profile is used for a searchable directory, by default CiviCRM will expose every record in your database; this is not ideal in many cases. Use this setting to limit the available records to contacts who are part of a regular or smart group. For example, if an organisation needs to limit a profile listing to show only active members, they can create a smart group of all members that have a status of New and Current. They then limit the directory to only show contacts in that smart group. Remember, smart groups are dynamic lists of records; when new memberships are added, the corresponding contact will automatically be included in the directory. 
    2. Add new contacts to a group: this is applicable when using a profile as a sign-up form.  You are able to directly add all the contacts who fill out the profile form to a particular group. For example, if your profile form asks contacts to offer their services as a volunteer, then all those who fill out the form can be automatically be added to a volunteer group.
    3. Notify when profile form is submitted?: who in your organisation should receive an email when someone fills out the form? Enter their email address here. If you want to send email to multiple addresses, separate them with a comma.
    4. Redirect URL: when someone clicks Save to submit the form, do you want to take them to a specific URL? Normally you would create a special thank-you page on your website to redirect people to. If this field is left blank, the user will be directed to a page which displays the information they've just entered (a profile view page). This setting does not apply if you embed your form in an event sign-up or contribution form.
    5. Cancel Redirect URL: similar to the previous item, what is the URL you want to redirect people to if they click Cancel on the form? Again, this setting does not apply if you embed your form in an event sign-up or contribution form.
    6. Include reCAPTCHA: CAPTCHA is a type of spam blocking software that requires the visitor to fill in text generated from a graphic. This prevents automated spiders (robots) from completing the form. It is highly recommended that you include it. You must have configured a free reCAPTCHA account before enabling this. Go to Administer > Configure > Global Settings > Miscellaneous Settings to configure your account (click the help icon for on that form for detailed instructions).
    7. What to do on duplicate match: use this option to control what happens when the contact data submitted from this profile matches an existing contact record. Options are to  update the matching record, create a duplicate record, or give the user a "duplicate record" warning (in which case their input will not be saved). This setting is ignored if the profile is embedded in an online contribution, membership sign-up or event registration form. In these cases, a contact match always results in the transaction being linked to the matching contact. Note that if there are multiple matching contacts, the first matching record is used.
    8. Proximity search: if you are using this profile as a search form, you can choose to include proximity searching. When enabled, a proximity search block will be added to the search criteria. This block contains fields to set the proximity start address, and a field to set a "radius" (distance from that address). Set the proximity search as required if you want all searches using this profile to force the user to enter a start address and a radius.

Once you have saved the profile settings, it's time to add fields to the profile. If you plan to reference custom fields in a profile form, make sure that those fields have already been created.

Some important notes on adding fields:

Profile_FieldSettings

Linking to your Form

Once your profile sign-up form is built, it is ready to be used! There are several ways to do this.

Data entry tool

If you have volunteers or interns who perform manual data entry for your organisation, you can make their task easier by creating a profile form which shows only the fields they need to input. This greatly simplifies data entry and reduces the chance of data being incorrectly entered.

Including profiles on event registration and contribution pages

Often you will want to define certain fields for inclusion in event registration and contribution pages. This process is similar to the volunteer sign-up example above. The only significant difference is that you can include fields in your profile that are specific to participant records (for event registration forms) and contributions (for contribution pages). Read the sections covering creating contribution pages and event registration pages for more information.

Including profiles in Drupal's User Registration screen

For websites that have logged-in users, you may want to allow people to provide additional information as they register for an account on your website. Similarly, when people fill out a profile form you may want to encourage (or force) them to sign up for a user account. 

To include a profile form during the user registration process:

  1. Create a profile that is used for User Registration:

    addprofile_usedfor_reg 
  2. Add the fields you want people to fill out as they register, using the same process described above. Make sure the field visibility is set to Public User Pages.

Including profiles in Drupal's My Account screen

You can embed one or more CiviCRM profiles directly into Drupal's My Account screen. This makes it easy for logged-in users to review and update their information whenever they visit their My Account page.

To create a profile for this purpose:

  1. Create a new profile, or navigate to an existing profile and click Settings.
  2. Select in Used For.
  3. Click Save.
  4. Add the fields you want people to be able to edit from their Drupal My Account page.

New account creation during profile sign-up

If you want your constituents to create a Drupal or Joomla! account when filling out a profile, you can enable this with the "User account registration option" under Profile Settings > Advanced Settings. Anonymous (not-logged-in) users will then be invited (or required) to create an account when they visit the profile. Logged-in users will just see the profile fields.  

Profile user registration options

You must include a Primary Email Address field in the profile for this feature to function properly. This feature also works when the profile is embedded in an online contribution page or event registration page. Hence you can invite or force anonymous visitors to sign-up for an account when they register for an event.

Sharing information

Profiles and directories

Many organisations have data they would like to display on their website. Historically this has been difficult because it required updating the same data in two places - a website and a database. Using CiviCRM profiles solves this problem because it allows you to expose data from your database on your website while only needing to manage and update the data in CiviCRM.

For example, an organisation called Native Americans in Philanthropy (NAP) wanted to create a membership directory that their members could use to search and connect with other fellow members. Before CiviCRM, they would create a very expensive annual print directory and mail it to every member. This process was time-consuming and expensive, and some data would be out-of-date before the members received their directory. Switching to CiviCRM meant significant resource savings and, because their website became a portal for their members to connect, it helped to advance their mission.

To build your directory:

  1. Go to: Administer > Customize > CiviCRM Profile.
  2. Click Add CiviCRM Profile.
  3. Set Used For to Profile:

    NewProfileMemberDir

  4. Advanced Settings: there are a few options under advanced settings that are helpful when using profiles for directories.
    1. Enable mapping: a really cool feature available in CiviCRM is to allow visitors to map contacts in your directory using Google or Yahoo! maps. They can then obtain directions to a record's address dynamically. To use this feature, you must have already enabled mapping under Administer > Configure > Global Settings > Mapping and Geocoding.
    2. Include profile edit links: check this box if you want to include a link in the directory listings to allow people to edit the profile's fields. Only users with permission to edit the contact will see this link. More often than not you will not need to enable this setting as it is not commonly used in the membership directory scenario.
    3. Include Drupal user information (Drupal only): check this box if you want to include a link in the directory listings to view a contacts' Drupal user account information (e.g. their My Account page). This link will only be included for contacts who have a user account on your website.

      profile_adv_settings

Now it's time to include the fields that will make up the directory. For profiles used as directories you have total control over which fields:

The important options you must configure in the fields for directory purposes are shown below:

directory_fields

The image below shows the search mode for our membership directory.

Member Directory Search Form

Once you hit search you get this result set. Profile fields that have Results Column checked are shown in the listing.

MemberDirResults

Clicking the view link gives you more details about the constituent, showing all profile fields.

Profile Member View
As we've seen, building a directory for your website can provide a valuable tool for your constituents.

Linking to Your Directory

You have several options to link to your directory:

Other profile uses

Search results

Searching is outside the scope of this section but, assuming you are familiar with searches, you may wish to change the columns used to display the results of an advanced search. To do this:

  1. Create or open a profile and mark it as used for Search Results:

    profile_searchresults
  2. When adding fields to this profile, you will need to set Visibility for the fields to Public Pages and check the Results Column box.

When conducting your advanced search, use the Search Views dropdown menu in the top right of the page to select your profile.

Batch updates

The final way that profiles can be used is to perform batch updates of data. For example, you have a custom field called "volunteer interests" and you want to update the volunteers group with a certain interest. You can easily update the entire group using a profile.

  1. Create or open a profile and mark it as used for Profile:

    profile_batch

    No other profile settings are relevant for this type of usage.

  2. Add your fields to the profile. Only add the fields you want to batch update. In the above example, the only field you would need is your custom "volunteer interests" field (contact name is always displayed when doing batch update). Remember, fields added to the profile must all be of the same contact type. You cannot add fields that are specific to both organisations AND individuals.

Once your profile is created, and you have conducted your search, select Batch Update via Profile from the actions dropdown menu and click Go. Then select the profile you want to use.

batchscreen


You will see a grid with the fields in your profile. You can update each field and row individually. If there is a field where you want to enter the same value for ALL records, you can enter that value in the first row and then click on the "copy values" icon to the left of the column header. This will copy the field value to all the rows in your grid.

Batch Update via Profile

Don't forget to click the Update Contacts button at the bottom of the page to save your changes.

Batch update limitations

Combining record types in a profile

A profile usually contains fields of one record type. For example: First Name and Last Name (Individual fields). But in some cases, such as online event registration and online contribution pages, you can combine fields from two different record types (e.g. Individual + Participant fields or Individual + Contribution fields). You can also combine Individual fields with general Contact fields (e.g. Last Name + Email Address).

If you try to combine fields with an unsupported combination of record types, you'll get an error when you try to save the field.

Transitioning to CiviCRM

This chapter outlines the parts that typically make up a CiviCRM project and should be read by people about to embark on a CiviCRM project. Some of this information may be obvious to experienced project managers. A comprehensive guide to project management is beyond the scope of one chapter but we have outlined things that are typically encountered in a CiviCRM project and provided pointers on some things to watch out for.

First, some pop philosophy courtesy of Cynthia Tarasco:

"Life is a series of making decisions. Some decisions are easy because they do not require a substantial investment of time or money. Deciding which flavor ice cream to buy fits into this category: if you get vanilla today you can always get chocolate tomorrow. Other decisions are much more difficult because they require substantial investments of resources, and you will be living with your choice for the foreseeable future. Adopting a new CRM fits into this category, so planning and project management are vital".

When you start out on a new CiviCRM project you should spend time thinking about:

People and the project team

Including a wide range of people that represent the different parts of your organisation will help with delivery of your project. A mixture of management and day-to-day staff helps the team to keep an eye on the big picture as well as ensure that the project is ultimately useful to frontline staff.

You'll be exploring new territory with your CiviCRM installation and this can sometimes be stressful. It might be helpful to share project management of the project with others who can give you a different perspective and moral support when you need it!

Managing a CiviCRM project will require a major time investment from people within your organisation, even if you employ an external consultant. Organisations often under-estimate the amount of time that will be required from their staff in implementing an IT project - such as training, modifying existing processes and providing new or updated information to relevant people. It's not something that can be tacked on to the end of an already busy schedule and this should be taken into consideration.

Goals

You should have a good idea of the goals for implementing CiviCRM. This could be something like: reduce administrative work in managing events by 25% or manage 25% more donations with the same staff. The goals should be SMART (specific, measurable, attainable, relevant, timely)!

These business goals will help you in directing and managing your project. For example, if the project group for example want some customization that requires budget and effort, your business goals will help you decide one way or the other. The business goals will help you to focus on why you are implementing CiviCRM and what you want to achieve in the long run.

Development

It often makes sense to break development up into smaller more manageable sections, which can be implemented in discrete stages or iterations. A common first phase of development is to choose something simple to implement in CiviCRM, or specific functionality for a team who can then act as CiviCRM evangelists within the organisation.

Implementing in stages allows staff to get used to changes gradually without feeling overwhelmed, and gives the developer or implementer the ability to be responsive to feedback from users during the development process.

Another reason that people choose to develop iteratively is that it is very hard for users to correctly or fully articulate their requirements at the start of the project. Giving users hands-on experience of an early version of the system helps them understand how it works and what is possible. They can then provide valuable feedback and might articulate requirements that they haven't thought of previously.

Implementing your CMS (Drupal or Joomla!) either before or after implementing CiviCRM is another convenient way to split up a CiviCRM project. As well as the normal advantages of breaking up the development into manageable chunks, this helps staff understand the important differences between a CMS and a CRM.

Pilot projects

Pilots help to reduce risk during a project implementation. For example, rather than moving your organisation's entire event management infrastructure to CiviCRM, run one pilot event using CiviCRM and evaluate it. You can then incorporate the learning back into the development process.

Ongoing support and development

It is a mistake to think about a CiviCRM project as a one-off development that will meet the needs of your organisation for the foreseeable future. Organisations constantly change and evolve and your CRM should evolve with you, otherwise it will eventually become out-of-sync with the organisation.

Once you have been using CiviCRM for a while and staff are comfortable with it, you will likely want to take advantage of other functionality. Each improvement or new piece of functionality that you decide to implement in CiviCRM will take resources, so you'll need to plan for these.

Even if your organisational needs don't change, there are ongoing support implications, including:

Training

Training is a significant aspect of most CiviCRM projects. Your training could take many shapes and sizes depending on your users, but it often makes sense to spend resources on formal and reusable training resources (user guides, lesson plans and so on).

CiviCRM's range of functionality can be overwhelming at first (especially to the less technically-minded). Remember that staff who were not involved in the project's early stages will need to have concepts explained clearly to them - things that are obvious to you may be quite foreign to others. 

Trying to cover everything in one training session probably won't be effective; your staff will need time to digest the new ideas. Instead, hold smaller training sessions that introduce concepts and specific functionality, followed by periods of testing, piloting and feedback. Tailor your training for your audience: not everyone needs to sit through a two-hour training session on how to manage events if there is a single person responsible for event management and planning. And where possible, involve staff in training other staff members as this increases the sense of ownership and helps to embed learning.

Training is also ongoing. New staff will need to be trained, users familiar with the system can benefit from learning about more advanced topics, and staff will need further training when there are significant upgrades or new functionality added. If you plan to use CiviCRM for any large or mission-critical events, allow adequate time for additional staff training and testing. 

Hosting and infrastructure

Hosting is a key aspect of any CiviCRM project. You will need to provide maintenance of the server on which CiviCRM is stored, and have someone available to fix problems that inevitably occur from time to time. If your site needs to be accessible 24 hours a day, you should have a support agreement with your ISP that covers this. Ensure that your budget is sufficient for appropriate hosting, and that effective backup procedures and policies are in place.

Keep in mind that in the hosting provider world, you get what you pay for. In many cases, cheap hosting providers keep their prices down by limiting the services or flexibility they provide. CiviCRM doesn't work well on poor hosting, and under-budgeting for hosting may lead to other problems. Similarly, make sure that the computers your staff are using are powerful enough to provide a good experience with CiviCRM.

Change management

Introducing a new (or the first) CRM will cause changes in work flow and processes at your organisation. These changes may be "political", practical or technical. Either way, a lot of change at the same time can be difficult and stressful.

To mitigate this, give staff time to accept and support each change so that they share in ownership of the new system rather than feeling as if something has been forced on them. Focus on simple tasks at the beginning of deployment and introduce more difficult tasks as staff understanding of the system grows. Show staff how the new system will make their work easier and where their feedback has been incorporated.

Good planning can minimise the risks around change, but it is important to be flexible within your plan; unforeseen things often occur, and a rigid plan could prevent you from reaching the best solution.

Real World Examples

CiviCRM is used by all shapes and sizes of organisations that are located all over the world. Some have no paid employees, while others might have several hundred. Their needs range from very simple to fairly complex. In this chapter, we will have a look at real world examples of how organizations are using CiviCRM.

Throughout this chapter you will see references to CiviCRM features such as CiviEmail, CiviMember, CiviPledge, CiviCRM Profiles and others. These are all components of CiviCRM and we have included references to them so you can become familiar with the language of CiviCRM; however, it's not important to understand the finer detail of these features at this point.

A Spectacular Performance

garland_logo

This example shows how clubs can use CiviCRM for summer camps, regular classes and other events.

Wellington Circus Trust in Wellington, New Zealand is run entirely by volunteers. They have a mailing list of 500-600 people and run blocks of classes in circus skills such as trapeze and hula hoop. They also host events. For safety reasons, the Trust needs to gather information about who to contact in the case of a student being injured. The Trust processes about 200 enrolments a year.

Prior to using CiviCRM, the Trust maintained a Microsoft Access database, but data entry was time-consuming, keeping information up-to-date was difficult and emailing the resulting contact information to the tutors on a regular basis was challenging. The treasurer wanted members to be able to maintain their own details and wanted the tutors and volunteers to be able to access member's contact details from anywhere.

What They Did

After some research, the Trust decided that CiviCRM could enable them do the things they needed to do, and as soon as the system was up and running they began to make the most of it.

The Results

Simply by implementing CiviCRM, tutors and volunteers can now access and manage information from anywhere in the world where they have internet connectivity.

By implementing CiviEvent with a payment processor and custom data fields, people are able to enroll in and pay for classes online and provide the important emergency contact information at the same time. Allowing people to sign-up online has greatly reduced the amount of time spent on data entry.

By integrating CiviCRM with Drupal and setting up user accounts, contacts are able to maintain and update their own information, greatly reducing administration time and improving the accuracy of the data.

Implementing CiviMail has made it easy to email tutors, volunteers and students, and removed the administrative burden of manually updating the mailing list and contact information because contacts can do their own updates. The treasurer also found that it saved her from having hundreds of sent items in her email client, which used to be the result of using Microsoft Office mail merges to send out email newsletters.

Prior to implementing CiviGrant, the Wellington Circus Trust had not been effective at tracking the status of grant applications. By using CiviGrant, they are now able to see at a glance what grant applications had been sent and the status of each application.

All up, the Trust estimates that installing CiviCRM has saved hundreds of volunteer hours over the course of a year.

After moving to CiviCRM, the Trust found that both contact management and class registration were easier. One issue they encountered was that some people were confused about having to reset their Drupal passwords. The Trust thinks that putting more effort into the way they explained this on their website would have helped. Another issue was the standard PayPal interface which was initially implemented as a payment processor; people found this difficult to use, and after six months the Trust invested in developing a payment processor more appropriate to New Zealand.

They also learned that a cheap hosting provider is not always the best option: quite a bit of time was wasted before they switched from a free provider to one that costs them approximately $NZD20 per month and provides significantly better service.

Suffering Relieved!

afsc_1

The American Friends Service Committee (AFSC) is a large, Quaker-based, peace and social justice organisation with over 400 employees. Worldwide, they run programmes that work to relieve and prevent suffering through both immediate aid and long-term development, and they seek to serve the needs of people on all sides of violent strife.

Their main headquarters are located in Philadelphia, Pennsylvania. They have nine regional headquarters located throughout the United States, some 50 area offices also located in the USA, and numerous international field offices located in Africa, Asia, Europe, Latin America, the Caribbean and the Middle East.

Lists of constituents are maintained by each office. The specific CRM system needs of each office vary but the general needs are: searching for constituents that meet certain criteria; sending emails, newsletters, postal mail and announcements; and collecting the contact information of people who sign online petitions and register for events online.

Through a survey conducted by the AFSC Information Technology Department, it was revealed that AFSC staff were using a variety of systems to keep track of their constituents. It also became obvious that these systems were not working effectively: repositories of data were everywhere, contact information was duplicated, staff were having a hard time managing their contacts and the IT Department was unable to provide adequate support.

The survey also found that staff members were frustrated with the systems they were using because they lacked the necessary functionality for them to effectively communicate and do outreach. Specifically: search capability was limited; there was no ability to send high-volume emails which meant that it was not possible to send newsletters or announcements; and there was no ability to collect information online.

After investigating several database systems, the IT Department finally decided that, all things considered, CiviCRM might be the best fit for the AFSC.

What They Did

Initially, CiviCRM sites with CiviMail, managed by an external vendor, were established for offices in Los Angeles, Rhode Island, San Francisco and Seattle. Los Angeles also chose to use the CiviEvent component to track event registrations and the CiviMember component to track contact information of committee members.

After implementation, an LA staff person discovered that certain functionality was missing from the CiviMember export component and this was preventing them from being able to compile a membership directory. AFSC talked to the CiviCRM Core development team and contracted them to add the missing functionality. This was a win-win situation: AFSC got the functionality they needed and because it was integrated back into the CiviCRM product, the entire CiviCRM community was able to benefit from the addition. An extra advantage for AFSC is that because the functionality became a standard part of CiviCRM they don't have to worry about compatibility with future upgrades.

The Results

The decision to have their sites hosted and managed by an external vendor turned out not to be a good one when the vendor ran into difficulties and was not responsive to issues or in providing the services that had been promised, such as timely updates for CiviCRM. Once the hosting issue was resolved, staff were able to take full advantage of the capabilities of CiviCRM and do all of the things that they had previously been unable to do.

The Los Angeles office is in full swing, using CiviCRM as the main repository to track their constituents, board, committee members and volunteers. Their constituents are able to sign up for events and petitions online, and staff can send volume emails for newsletters and announcements.

Getting rid of their old system and being able to send out a monthly newsletter was the main goal for the Colorado office, who came on board with CiviCRM a little later in the process. They are now able to identify newsletter subscribers and send the newsletter to them via CiviCRM. They couldn't be happier!

The AFSC currently has nine CiviCRM sites and the IT Department is now recommending CiviCRM as the "database of choice" for all of its offices. Support from the CiviCRM community is excellent and CiviCRM itself is improving every day, as more and more functionality being added. AFSC staff are now able to access their data from any place that has internet access, run complex searches, manage online event registrations and send online newsletters and postal mailings. CiviCRM has enabled them to better manage their constituents. This makes their life easier and in turn, is of great benefit to AFSC.

Activating the Community

heal

The Healthy Environment Alliance of Utah (HEAL) is a grassroots environmental organisation working to protect Utahns from nuclear and toxic waste. Before moving to CiviCRM, they were stuck with a Microsoft Access database. They may have called it a database, but in fact it was a glorified spreadsheet that did little to facilitate their day-to-day operations. The goal for the CiviCRM project was to move to a system that would centralise all of their information across their organisation including email lists, volunteer tracking, donor history and more. As an advocacy and community action organisation, effective engagement with their supporters and tracking the relationships they build with their constituency over time is critical to their mission. They needed a tool to support that mission.

What They Did

HEAL has been using CiviCRM since the early days of the software and CiviCRM is now the central place to track all donors, volunteers, legislators, foundations and contacts. They use CiviCRM for donor management, email communications, event management, volunteer tracking, and advocacy.

The Results

There is no question that CiviCRM streamlined and consolidated HEAL Utah's data management and saved the organisation valuable resources. It is interesting to note that over the last several years their advocacy campaigns have been more successful and their impact in their community more noticeable - perhaps in part because they have been able to redirect limited resources away from administration and into the real work.

The biggest lesson that CiviCRM has brought to HEAL is to force them to always think about what role technology will play in their outreach and organising work.

A CRM Education

Schoolhouse_Supplies_medium72dpi

Schoolhouse Supplies (SHS) is a Portland, Oregon, USA-based non-profit organisation which gathers and distributes school supplies to students and teachers.

Prior to implementing CiviCRM, SHS used a combination of software programmes including Exceed, EROI, Constant Contact, Salesforce, Auction Pay (for online contributions) and, of course, hundreds of spreadsheets. In addition, SHS had a custom web application for managing its online store inventory and processing in-kind donations.

What They Did

By moving to CiviCRCM, SHS has centralised their operations and the management all their constituent data, and been able to unify and coordinate several of their core business processes.

All data from each source has been migrated to CiviCRM Standalone (an installation that is not integrated with either Drupal or Joomla! CMS). CiviContact and CiviContribute have replaced Exceed and Auction Pay. CiviMail has replaced EROI and Constant Contact. Salesforce data was moved into CiviCRM and the custom e-commerce application it supported was integrated with CiviCRM. Lastly, the inventory and in-kind management system was integrated with CiviCRM. Spreadsheets have been imported.

The Results

Each business process at SHS can now take advantage of their full constituent database and business activities are easily coordinated. More importantly, SHS is now in the process of taking manual business processes (such as volunteer coordination) and moving them to CiviCRM. New campaigns are now being planned and executed which would previously have been impossible or prohibitively expensive.

Growing Satisfaction

nysnla

The New York State Nursery Landscape Association (NYSNLA) is a member-based association providing resources and advocacy support for nursery and landscape professionals throughout New York State. The organisation seeks to advance the interests of New York State's nursery and landscape businesses and professionals by promoting sound business practices, expanding state and local markets, and exercising leadership in the development of sustainable communities.

Prior to migrating to CiviCRM the Association went through several iterations of member-management solutions, beginning with a series of spreadsheet documents and later moving to a Microsoft Access database. The move to CiviCRM was prompted by the desire to consolidate data, provide members real-time access to contact details, and to create a searchable member directory to website visitors who may be looking for a nursery or landscape professional.

What They Did

Working with a CiviCRM consultant, NYSNLA began the process of analysing the structure and content of their existing database and mapping the various functions to CiviCRM structures. They determined that they would use CiviMember, CiviEvent, CiviContribute, and CiviMail to address their core database needs, and would consider using CiviPledge at some point in the future for soliciting contributions to their associated non-profit, the Nurserymen's Foundation.

One data area that required particular attention was their Certified Nursery Landscape Professional program (CNLP). CNLP is an intensive, on-going educational programme designed to increase the skills of garden and landscape employees. The programme was designed by members of the nursery and landscape industry with assistance from Cornell University. Interested individuals must apply to the programme and successfully pass a test. Certification lasts two years, after which time the individual must recertify.

NYSNLA used CiviCRM's membership functionality to track the status of CNLPs. The ability to define a rolling-period membership and to gauge when they are nearing expiration perfectly met their management needs. The initial application process, which also must be carefully tracked, was handled through CiviEvent, as an application to the programme is essentially a registration to attend one of the bi-annual test events.

The Association also took advantage of CiviCRM's open source platform to make some interface customisations that improved the way they view contact records. Because of the importance of the CNLP programme, they wanted to be able to look at all employees for a certain nursery/landscape company and quickly know if any of them are CNLPs or Lifetime CNLPs. They also needed to easily find out which employees are authorised to manage the company's records.

The Results

The Association has worked hard to communicate to the public the importance of using a qualified landscape professional. Essential to this effort was the inclusion of a searchable member directory on their website. Using CiviCRM, they were able to create a search page that included geographic segmentation (the Association divides members into 8 regions state-wide) and a list of services provided by members (using CiviCRM's tags feature). The resulting search tool, because it is directly connected with their contact data, ensures website visitors are always looking at current information. The Association is also able to provide members direct access to their own contact details so they can update and maintain their list of services provided and other information.

Campaigning for Efficiency

Newlogo_1

The Green Party has been the third largest party in New Zealand politics for most of the last decade, with strong roots in the Values Party (the world's first national Green party) of the early 1970s. They achieved parliamentary representation in 1996 and after the 2008 election had 9 Members of Parliament, 5,000 financial members and some 50,000 contacts. The Party has more than 50 branches around the country and contest elections across all 67 electorates in the last election.

Prior to adopting CiviCRM, the Party and its parliamentary units employed a range of systems for managing members, donations, contacts, campaigning, media and advocacy.

The Green Party policy states:

What They Did

CiviCRM was adopted by the Party in 2007 (version 1.7), with a switch to Drupal as a parallel project. This was inspired in part by work done by the Canadian Greens on developing a voter canvassing module for Drupal. A Party database was set up using CiviCRM and online donations, memberships and event registrations were instigated.

The Greens have over 100 different issues that they generate media releases about. These were reconstructed as a check-box custom data field, and Smart Groups were built for each of these, for use when sending out media releases via CiviMail.

The highly complex access control requirements of the party necessitated the development of an alternative approach to the use of ACLs (Access Control Lists) in order to provide a more easily managed, highly granular system. This approach has now been incorporated as a hook (something that can be utilised by developers to extend CiviCRM) into the core code.

For the 2008 election campaign, a look-up function was developed so that when new contacts were added to the database, addresses were checked against a table containing the Electoral Roll, and links were created where matches were made. "Soft" matches were also recorded.

The Results

In the 2008 election campaign, the Party made extensive use of online fundraising and greatly exceeded previous online income. Membership renewal has been streamlined with more online renewals occurring.

As of May 2009, the Party was still using CiviCRM v2.0 on Drupal 5 and therefore had not yet benefited from the many features that became available through the 2.1 and 2.2 releases. An upgrade was in progress at the time.

In a complex organisation such as the Green Party, training can be a limiting factor, as well as the need to nurture more in-house super-users. New features in CiviCRM have led to some rethinking about the Party's usage of custom data fields, particularly with regard to the use of CiviMail for media releases. New options for both nested groups and Drupal Organic Groups suggest that a more time effective approach may soon be possible.

Quest for Success

quest_bridge_logo

QuestBridge is dedicated to helping bright, motivated low-income high school students get accepted to and able to pay for college. QuestBridge recruits high school juniors throughout the USA and invites them to fill out the QuestBridge application online. QuestBridge also partners with the USA's most selective colleges and universities with the aim to increase the socio-economic diversity of their student bodies. QuestBridge's college partners accept the QuestBridge application in lieu of their own admissions application.

What They Did

QuestBridge has built most of its business processes around CiviCRM. They wrote their online admission application using CiviCRM and extended it using the PHP scripting language. CiviCRM is used to store biographical and application information and communication histories about the students.

The Results

QuestBridge

In the 2008-9 school year, QuestBridge helped more than 1200 students get accepted and pay for college at its 25 partner schools. They accomplished their goals in a very efficient manner, in part thanks to their effective implementation of CiviCRM. QuestBridge is currently planning to upgrade to the latest version of CiviCRM in order to take full advantage of the new email features.

If Questbridge were to start over they would have invested more in training on CiviCRM up-front.

Changing with the Times

SFS

The San Francisco School (SFS), is a Preschool through 8th grade coeducational school with a diverse student body of about 270 students. Like all schools, communication between the school and families is very important. Whether it's updating a home phone number, email address or allergy, it is essential in meeting the needs of the students. The head of school was a strong supporter of the project from the beginning which led the staff and parents to be able to make a strong commitment to help the project move forward.

What They Did

They used CiviCRM to create a Parent Portal to:

To ease the transition of the school community, each of the above features were shown gradually rather than all at the same time.

The Results

Enabling parents/guardians to view their contact information meant that they could confirm what the school sees and hence notify the school of any changes. Also, they could view their child's after school fees and view a record of what classes their child is signed up for. Online sign ups allow parents the flexibility to schedule parent/teacher conferences and after school classes on their own time. Changing the existing school systems to an online system allowed both parents and staff to work together, view the Parent Portal so that contact information is current, parent teacher conferences are scheduled in a timely manner, and that access to the information is widely accessible.

RELATIONSHIPS

CiviCRM allows you to represent connections between contacts by creating relationships. For example, if a mother and son are both in your database, it can be useful to be able to look at either record and see that they are related to each other. 

You can also track relationships between organisations, or between individuals and organisations. For example, entering an organisation in the Current Employer field of an individual contact's record automatically creates an "Employee of" relationship from the individual to the organisation, and an "Employer of" relationship from the organisation to the individual. 

Creating relationships between contacts 

  1. Navigate to one of the records that you want to relate.
  2. Click on the Relationships tab in the Contact's record.
  3. Click New Relationship.
  4. Select the Relationship Type. In this case it would be either "Child of" or "Parent of".
  5. Click inside the Find Target Contact box and begin to type the first name of the person you are relating to this contact. One or more options will be displayed. Click on the appropriate entry.
  6. Click Search.
  7. Click the checkbox next to the name of the person you are relating to this contact.
  8. You can scroll down and enter further information, which includes Start Date and End Date (in case the relationship is time limited), Description and Notes. There are also two permission-related options, which allow users of the database to edit this record. Finally there is an Enabled? box, which is checked by default.
  9. When you have made the changes you want, click Save Relationship.

Connecting employees and employers

A quick way to connect employees (which are stored in CiviCRM as individuals) to employers (stored as organisations) is to use the Current Employer field within an individual's record.  This will set the current employer field in the contact record and create a relationship between the contacts. 

  1. Navigate to the record of the individual who you want to connect to an organisation. 
  2. Click the Edit button to edit the individual's record.
  3. Begin typing the organisation name into the Current Employer field. As you type, matching names of organisations that already exist as contacts in CiviCRM will appear in a dropdown autocomplete list below the Current Employer field. If the organisation is already a contact in CiviCRM you can select it from the dropdown list by pressing the down arrow key or by clicking on it. If the organisation does not already exist as a CiviCRM contact, simply enter the full organisation name. 
  4. After the organisation's full name is entered in the Current Employer field either press the Enter key or click the Save button. If the organisation is a pre-existing contact, an Employee/Employer relationship will be created between the individual and the organisation. If the organisation does not already exist, a new organisation contact will be created and the relationship will be created between the individual and the organisation. You can click on the Relationships tab to view your newly created relationship Employee of and see any existing relationships. 

Adding contacts to organisations

  1. Select the desired contacts from your search results as described above.
  2. Select Add Contacts to Organization from the dropdown " - more actions - " menu, then click Go.
  3. On the Add Contacts to Organization screen, select the Relationship Type from the dropdown menu.
  4. Enter part of the desired organisation name in the Find Target Organization field, then click Search.
  5. Organisations that match your search will appear in the "Mark Target Contact(s) for this Relationship" section below the Search and Cancel buttons. If the organisation you're looking for appears in this list, click the radio button next to that organisation and then click the Add to Organization button below. If the organisation you're looking for does not appear in this list, try entering something different into the Find Target Organization field and clicking Search again. If you are still unable to find your desired organisation it may not exist; click Cancel, add a new organisation, and try again.
  6. After you've successfully chosen an organisation and clicked the Add to Organization button, you should see a message stating that the number of participants that you selected have been added to the organisation.
  7. Click Done to return to your search results. 

Adding contacts to households

  1. Select the desired contacts from your search results as described above.
  2. Select Add Contacts to Household from the dropdown " - more actions - " menu, then click Go.
  3. Select the Relationship Type from the dropdown menu. Note that while CiviCRM will not stop you from adding multiple contacts as Head of Household for a single household, this may cause problems later on in any situation where you are expecting Head of Household to refer to only one individual per household. Therefore, the "Household Member of" option may be the better choice in most situations.
  4. Enter part of the name of the household to which you are adding contacts (such as a last name shared by household members) in the Find Target Household field, then click Search.
  5. Households that match your search will appear in the "Mark Target Contact(s) for this Relationship" section below the Search and Cancel buttons. If the household you're looking for appears in this list, click the radio button next to that household and then click the Add to Household button below. If the household you're looking for does not appear in this list, try entering something different into the Find Target Household field and clicking Search again. If you are still unable to find your desired household it may not exist; click the Cancel button, add a new household, and try again. 
  6. After you've successfully chosen a household and clicked the Add to Household button, you should see a message stating that the number of participants that you selected have been added to the household.
  7. Click Done to return to your search results.  

Creating new relationship types

  1. CiviCRM comes with a set of common relationship types that can be used to indicate relationships between contacts. If you need to track different types of relationships between your contacts, you can create your own custom relationship types.
  2. In the navigation menu, go to: Administer > Option Lists > Relationship Types.
  3. Review the list of existing relationship types to ensure that you are not creating a duplicate.
  4. If the relationship type you need does not already exist, click the New Relationship Type button. 
  5. Enter descriptive labels for the relationship type you are creating in the "Relationship Label-A to B" and "Relationship Label-B to A" fields. The "Relationship Label-A to B" field describes the relationship between Contact A and Contact B; the "Relationship Label-B to A" field describes the relationship between Contact B and Contact A. You will designate which contact types are used for Contact A and Contact B respectively in step 5. 
  6. Some relationships can be described by the same label in both directions; in these cases you can enter the Relationship Label once in the "Relationship Label-A to B" field. For example, when describing the relationship between two domestic partners named Sylvia and Audre, you can say that Sylvia is the "Partner of" Audre and Audre is the "Partner of" Sylvia. Therefore you would enter the "Partner of" label only in "Relationship Label-A to B" field, leaving the "Relationship Label-B to A" field blank. 
  7. In other situations one Relationship Label cannot be applied in both directions; in these cases you need to enter different Relationship Labels in each of the Relationship Label fields. For example, you can say that Kiyoshi is the "Grandparent of" Yuki but you cannot say that Yuki is the "Grandparent of" Kiyoshi. Therefore you would enter the "Grandparent of" label in the "Relationship Label-A to B" field and either "Grandchild of" or "Grandparent is" in the "Relationship Label-B to A" field.
  8. Use the Contact Type A and Contact Type B fields to designate which kind of contacts are being linked by your relationship. Remember to check that the contact types you select for Contact A and Contact B make sense when corresponded to your Relationship Labels.
  9. Optionally enter a description for this relationship type. This is especially useful if the intended purpose of this relationship type may not be obvious to other users.
  10. Leave the Enabled box checked unless you intend to create this relationship type but not allow users to utilise it until a future date.
  11. Click Save. You will see a message telling you that the relationship type has been saved and you will see your new Relationship Type in the list below. 

Disabling or deleting unneeded relationship types

If an existing relationship type is no longer useful or relevant for your organisation you can either disable or delete it so it is no longer presented as an option for new relationships. Disabling rather than deleting the relationship type has two significant advantages: you will still be able to see existing data on relationships of this type, and you can easily enable the relationship type again should you find you need it later. 

  1. In the navigation menu, go to: Administer > Option Lists > Relationship Types.
  2. Click the "more" link in the row of the relationship type that you'd like to disable or delete. 
  3. Select either Disable or Delete from the pop-up menu.
  4. If you select Disable, a pop-up confirmation bubble will appear. If you select Delete, you will be directed to an additional screen that provides a more serious warning and requests confirmation. Review the information provided in either confirmation message and if you are sure you'd like to complete this action, click the OK or Delete button.
  5. If you have chosen to disable the relationship type it will appear in red in the Relationship Types list and relationships of this type will still be visible when viewing contacts. If you have chosen to delete the relationship type it will no longer appear in the Relationship Types list or in contact relationships data. In either case users will no longer be able to create new relationships of this type.
  6. To enable a previously disabled relationship type, follow steps 1 and 2 above and select Enable from the "more" pop-up menu.

Reports and analysis

There are a number of techniques for reporting on and analysing your memberships.  The membership dashboard gives a quick overview of your current membership, with rows for each membership type and columns that current totals, and year and month to date figures.

That's a good start but there are a couple of ways that you can create more detailed and customised analysis using CiviCRM's search features and CiviReport.

If you are interested in the financial aspects of membership, you may also find the reports and analysis chapter in contributions useful.

Membership reports

Out of the box, CiviCRM comes with three membership reports designed to tell you something specific about your membership.

The membership report (detail) shows a line for each member.  The membership report (summary) shows members grouped by any criteria you specify.  For example, you can look at the amount of members that have joined each year for the last 10 years or show members broken down by country of origin or any other custom data that you collect on them.  Clicking on any row in the summary report will take you to the a corresponding detail report for that row. The membership report (lapsed) provides a list of memberships that lapsed or will lapse before the date you specify.

Searching based on membership data

CiviCRM makes an important distinction between contacts and memberships, which is blurred when we talking about 'members'.  Consider the following question: 'How many members do we have?'  This could be taken to mean 'how many contacts do we have that are members?', or 'how many memberships have we granted to contacts?'.  The answer to these questions is often be the same but what happens if one of your contacts has more than one membership?  The answer is that you'll have two memberships but only one contact.

There's no right or wrong answer to the question should we look at contacts or memberships.  It just depends on what you are interested in.  It is important to take this into consideration when carrying out a search.

The Find members search allows you to search based on membership data and return membership data.  The Advanced search allows you to search based on some limited membership information (and combine that with other contact information) and return contacts.  You can also choose membership from the column to show members rather than contacts.

Searching based on criteria gives you access to simple totals and also the option to export as CSV for further analysis.

Further analysis

If CiviReport and the contact and membership searches aren't giving you want you want, consider commissioning a new report or custom search.  Read the CiviReport section and the 'Search and actions' chapter for more information.

Searching

This chapter covers different ways to find information you've stored in CiviCRM. Two of the techniques in this chapter - finding contacts and the "search-action" workflow, described in the second bullet below - are core functions in CiviCRM, so most if not all users will find this chapter helpful.

We will start off with some simple searches and then move on to more advanced techniques. CiviCRM beginners should be familiar with Quick search, Advanced search and the component searches. More advanced users should also look at reports, custom searches and search builder. 

There are three main reasons to search:

For reports, searching is often useful but has limitations. For example, you can't group results by particular criteria, summarise, or easily produce graphs of the results. For more advanced reporting, read about CiviReport in the section Reporting.

Note that when you search for character strings, the search is not case-sensitive. For example, if you search for 'brooklyn', the search will return strings with capitalised letters if the string exists, e.g. 'Brooklyn' or 'BROOKLYN'.

Quick search for contacts

The easiest way to find a specific contact, if you know part of their name or email address, is to use the Quick search box that appears in the navigation menu at the top left of the screen. Contacts that match the phrase you enter will appear in a dropdown list below the box. For example, entering "peter" will find

You don't need to type the full name of the person - just the first few letters. The following screenshot shows that two contacts turn up in our database when we search just for "pe".

quicksearch 

Advanced search

Advanced search allows you to search across all the information you have about your contacts. For example, you could find "all contacts in Venezuela" or "all advisory group members". If you specify two or more categories of information, the search displays every contact that matches all the categories. For instance, you can combine the two criteria just mentioned to find "all advisory group members in Venezuela".

The Advanced search screen is accessible from the navigation menu Search > Find Contacts > Advanced Search. On this screen, search criteria are grouped into sections which refer to different types of data that you can search on, such as address data, notes and information from components such as Contributions or Events. Each group of criteria is shown as a gray bar. If you click on a gray bar, it expands to reveal the options within that group. For example, if you want to search for all people in your database from 16 to 18 years old, click on the Demographics bar. It expands, as shown in the following figure, and you can specify the birth date range you are interested in.

AdvSearch

Combining search criteria

Different criteria are combined by "ANDing" them. For example, if you select the tag "major donor" and the country "Mexico", the search will return major donors from Mexico.  The search will not return major donors who are not from Mexico, nor those from Mexico who are not major donors.

Within criteria groups that allow you to check boxes for more than one value, these options are also combined by "ANDing". For example, if you can search for contacts whose Preferred Communication Method is both Email AND SMS.

With fields that allow you to select values from a dropdown list, options are combined by "ORing". For example, you could find contacts that live in Mexico OR the United States by selecting both countries in the country field. 

Display Advanced Search results as... 

Advanced Search returns your results as Contact records by default. However, you may want to get another record type instead. For example, you may want to see all the Contribution records which match your search criteria (while taking advantage of the rich set of search filters available in Advanced Search). Simply select the record type you want from the dropdown in the upper right corner of the Advanced Search form.

Modifying search columns

Advanced searches allow you to use to change the columns displayed in your search results. The default columns are Name, Street Address, City, State, Postal Code, Country, Email and Phone. If you want to display a different set of columns (perhaps to include a custom field or remove a column you don't need), create a Profile with the Search Results option selected. Make sure that the fields in this Profile are set to "Public User Pages and Listings" visibility, and are marked as Results Columns. (For more information about creating Profiles, which are described in detail in the Profiles chapter in the Configuration section.)

The Profile will appear in the Search Views dropdown menu in the upper right corner of the form, as shown below. The following screenshot shows what the menu displays after someone has created a Profile called "Birthday".

SearprifleFields

Combining this feature with the "Batch Update via Profile" action provides a powerful method of viewing and updating a specific set of fields across a batch of contact records.

Using groups in a search

When using Advanced Search, if you select several groups in the Group list near the top, it will treat the search as an OR search, and return results for contacts who are in any of the groups you select. If you want to find contacts who belong to all of the selected groups, you will need to use Search Builder. 

There is also a very useful built-in custom search, "Include/Exclude Contacts in a Group/Tag", that enables you to find contacts who are in one group but not in another, which you can find by going to Search > Custom Searches in the navigation menu.

Groups_searchIncExc 

Instant view pop-up 

You can see a pop-up box with detailed information for any contact listed in your search results by hovering over the contact icon in the left column, as shown below. You can adjust the fields shown in this "pop-up view" by modifying the fields included in the "Summary Overlay" profile (Administer > Customize > CiviCRM Profile).

SearsummaryOverlay

The "search-action" workflow

After you retrieve your search results, you can perform a number of actions. An Actions box appears above the results. You can select either all records or specific records, then carry out an action with the selected records. Different actions are covered in more detail in the chapter on Everyday Tasks.

Searresultsactions

Some of the most commonly used actions are Add Contacts to Group, Export Contacts, Map Contacts, and creating and printing Mailing Labels. (To use Map Contacts, you will need to configure Mapping and Geocoding. You can read more about this in the Installation chapter of the Configuration section of this manual).

For example, to send email to a selected  number of contacts, mark the contacts you are interested in and then select Send Email to Contacts in the dropdown list of actions. 

The wildcard (%)

Understanding wildcards greatly expands your search options. A wildcard represents any character (letter, numeral or punctuation mark). In CiviCRM, the wildcard is represented by the % symbol (you may be familiar with other symbols such as * from other applications). It is most easily understood through examples.

Suppose that somebody asked you to find a contact with a first name similar to "Michael", but possible something different such as "Michelle" or "Michał". If you search for "Mich%" you will find all these variations, including a contact who is supposed to be named "Michael" but whose name was misspelled as "Micheal". Wildcards can be used before, after, or even within words. For example, searching on 'Mich%el' will exclude "Michał" and "Micheal" but still find "Michelle" and "Michael".  

This search is not case sensitive. Entering "mi%el" in lowercase will also find contacts with an upper case 'M' in their name.

Component searching

Most CiviCRM components offer a search on the data they maintain, such as Find contributions, Find members, etc. These forms work in a similar way to Advanced search but return rows of the main objects associated with the components, instead of contacts. Find Members returns memberships, Find Participants shows event registrations, Find Contributions returns contributions and so on.

Each component search has its own Action list. See the Component sections for more details.

Search Builder

Advanced search lets you choose from a wide range of criteria, but it has limitations. The main limitation is that the search criteria you enter into different fields are "ANDed" together.

The Search Builder tool provides an alternative for situations when you need to search using OR for some criteria. For example, you can build a search for contacts who are born within a range of dates OR who are female. To do this, access the Search Builder tool and Edit Search Criteria from the navigation menu: Search > Search Builder. 

To AND criteria (which means to find results matching all criteria specified), click Another search field and enter criteria under Include contacts where. To OR criteria (which means to find results matching either one OR the other criterion), enter one criterion in Include contacts where and the other under Also include contacts where. 

SearchBuilder 

Search Builder is intended for advanced users and requires you to use specific formats for your search values. 

Fuzzy Matches
If you want to search on partial names or other incomplete phrases - use the LIKE operator, and use the % symbol before or after your search term. For example, to find contacts whose last name begins with "Gree": 

Record Type Field Operator Value
Individuals Last Name LIKE Gree%

Search Builder requires special values when matching on values which are stored as keys in the data. This includes Groups, Tags, States, Countries, yes/no (boolean) fields and multiple-choice custom fields. Specific date formats are also required. 

To search by... Use this value or format...
Group The Group ID. Find this integer value by checking the gid= value in the Members link for the group (from Manage Groups)
Tag The Tag ID. Find this integer value by checking the id= value in the Edit link from Administer CiviCRM » Tags
State Either the full state name (e.g. 'California') OR the state_province ID (e.g. 1004). Find the ID by viewing the HTML source for the State select field while editing a contact.
Country Either the full exact country name as stored in the CiviCRM database (e.g. 'United States') OR the country ID (e.g. 1228). Find the ID by viewing the HTML source for the Country select field while editing a contact.
Dates Use YYYYMMDD format. Example: Enter August 18, 2006 as 20060818
Yes/No Checkboxes This covers fields like DO NOT EMAIL, IS DECEASED, etc. Use a 1 for Yes and a 0 for No
Multiple Choice Custom Fields Use the Option Value you assigned when creating the Multiple Choice selections. This may not be the same as the displayed value - as the Option Label is displayed in select fields and when viewing the contact record.

You can search for matches on multiple Groups, Tags or other ID values using the IN operator. For example, if you want to find contacts who are members of either the Newsletter Subscribers group (Group ID=1) or the Advisory Board group (Group ID=3), you could enter:

*Individuals -> Group(s) -> IN -> (1,3)

IMPORTANT: Surround your set of values with parentheses, and do NOT use spaces between the comma-separated values.

Just like other searches, you can save your Search Builder search as a Smart Group. For more information on Smart Groups, see the Groups and Tags chapter.

Custom search

Custom searches are designed to answer specific questions that can't be easily answered using Advanced Search or Search Builder. 

Go to Search > Custom Search in the navigation menu and look at the list of available custom searches. These customised searches have been written by members of the CiviCRM community to meet their own needs, and then contributed back to the community to share with others who need the same or similar custom searches. It's worth spending some time exploring these searches as some may be useful to you, and they will give you an idea of the sorts of things that are possible.

A good example is the Include/Exclude Contacts in a Group/Tag.

By combining Include and Exclude options, you can find contacts who are in one group but remove just the group members who fit another criterion. For example, you may want to find all the contacts who are Newsletter Subscribers but exclude members of Advisory Board, perhaps to create a new mailing list to receive a message targeted at the most external circle of your constituents. 


There are many additional custom searches created for various purposes, including a search on aggregate contributions of contacts, a search on contacts within X miles/kilometers of a certain geographical area, and more. Here's a short description of the custom searches a

Contribution Aggregate: find aggregate totals of contributions from contacts within a range of dates.

Basic Search: search on contacts by contact type, group, and/or tag

Household Name and State: search households in a U.S. state

Postal Mailing: search for contacts in a given group and results display with mailing information. Use this search to batch update contact information, send an email, export contacts, or other actions. 

Proximity Search: search for contacts located within x miles/kilometres of a  specific geographical area.

1. Go to Search > Custom Searches > Proximity Search.
2. Enter the distance in miles or kilometres.
3. Enter the country within which you want to search.
4. Enter any other parameters you wish to give your search.
5. Click Search.


Contributions made in Year X and not Year Y: search for contributions that have been made in one year but not another; this is useful for following up semi-regular donors and encouraging them to donate more regularly.


1. Go to Search > Custom Search > Contributions made in Year X and not Year Y
2. None of the fields are required; you can choose whether to search a specified amount range as well as a time period, and whether you want to exclude minimum or maximum amounts.
Find Contribution Amounts by Tag: search on any tag for contributions within a range of dates. 

Event Aggregate: search on event-related payments for a given event and 

Price Set Details for Event Participants: get detailed information about which participants opted for which different paid options related to an event. For example, see who paid just the event fee, who paid for the additional workshop, and who paid for dinner.

Zip Code Range: find contacts in a specified zip code or postal code range. This is useful for targeted mailings or conducting surveys in a particular geographical area.
1. Go to Search > Custom Searches > Zip Code Range Search.

2. Enter the start and end range of the zip or postal codes.

3. Click Search.

Date Added to CiviCRM: search for contacts that have been added within a particular time period.

Checking this box allows you to enter multiple sets of values for a given contact.

Custom Group Multiple Values Listing: a special search for custom data best illustrated with the following example: 

Checking this box allows you to enter multiple sets of values for a given contact.

EXAMPLE: When creating a set of custom fields used to collect Employment History - you might have fields for Job Title, Start Date, End Date, and Reason for Leaving. Checking the "multiple records" box allows you to collect information for multiple jobs.

You can also set the maximum number of records which can be recorded per contact. Using the previous example, you might only want data for the three most recent jobs.

CAUTION: The following features are NOT available for custom fields in 'multiple record' custom set:

It is possible to write your own custom searches, but you'll need to be comfortable with MySQL and PHP. See the CiviCRM Developer Guide for more information about how to do this. If you create a custom search that you think could be useful for others, consider contributing it back to the community.

Please note: Documentation is needed for each of the custom searches. If you are developing additional custom searches, please contribute them with accompanying documentation so others will be able to take advantage of the functionality you have added. 

TAKING CARE OF SECURITY

Because CiviCRM is a web based solution, it requires webserver to run. It's most common situation that webservers are used for serving publicly available data, so some attention is required, when setting up CiviCRM for storing sensitive data. Recommended approach in such situations is using some kind of VPN (Virtual Private Network) solution, which will encapsulate data transfers over public networks using secure cryptographic methods. One of non-complicated methods of assuring VPN functionality is using SSH tunneling - blocking most kinds of access to the server and leaving only possibility to access services via secure, encrypted SSL tunnel. 

Encrypted data transfer

CiviCRM, being server based software accessed through the browser (client), requires internet connectivity. All the communication that's happening between the server and the client is not encrypted by default in non-configured, default installation, which means that somebody can intercept it and gain unauthorised access to your CiviCRM installation. In order to ensure security of communication, you need to make sure that your webserver (or hosting company) supports so called SSL (Secure Sockets Layer). Once that condition is met, you will need to create or obtain an SSL certificate from trusted issuer and put it on your server and than enforce encrypted communication (through HTTPS protocol) by changing configuration options in administration section.

Backups and their security

All of the computer systems are prone to failures - both hardware and software. The way to make sure that data is not lost is creating backups - periodically made copies of all the data and sometimes software as well. Making backups serves two important purposes: recovery and retention. In case of recovery, it helps organisation make sure that data gathered and stored in databases isn't lost in case of any failure. It can also help make sure that service continuity is assured - sometimes it's important that data gathering or analysis operations are not ceased due to lack of functioning database system - in such cases recovering working tool from backup minimises downtime. Second purpose: retention, is useful when organisation needs to be able to check the state of data gathered in given time in past. It might be quite important for human rights oriented organisation, especially around projects where data gathering process can be sabotaged by introducing unneeded modifications. Being able to verify the state of database in given moment in time (and compare to current state) can help in discovering any inaccuracies.

There is one more important issue to remember about when thinking about data backups. It sometimes happens, that the backed up system itself is well protected and there is a lot of attention being paid to its security, but the very backup security is forgotten. For example, it's important to have off-site backups (a copy of data that's stored in physically different location than original data - in case of natural disaster or fire), but it should be remembered that they contain all of the sensitive data. Therefore, it's a good practice to use strong encryption and physical protection (e.g. keep them in safe) for all the backups.

Data storage jurisdiction

As mentioned before, CiviCRM can be run from the server or from the cloud. When working with issues around human rights, or if an organisation is gathering sensitive information about a country's government or its officials, it is quite important to know where your data is stored. This is especially important when data is stored "in the cloud", when it's not obvious where the data is physically stored. Not getting into details, it might be good to have detailed information about where the servers are physically located, and which country's jurisdiction is used in case of governmental requests for information.

Other security concerns

It should be remembered that many successful attempts of unauthorised access don't have too much to do with IT systems security. It's often social engineering, physical access to server and client machines or using violence against people who have authorised access to data that are responsible for break-ins. Therefore, making sure that data is secure requires also extensive, on-going training of system users and making sure that they are familiar with all the necessary precautions.

Set-up

Set up of CiviGrant is reasonably straightforward. The first thing to do is to enable the CiviGrant module in Administer > Global Settings > Enable Components.

Grant types

Grant types are set up on the Administer > CiviGrant > Grant types screen. There isn't much to configure here, apart from a title and description of the grant.  

At the moment, you cannot add custom data to grant types but you can add it to grants (see below).

Grant statuses

Grant statuses can be administered from the Administer > Option lists > View all option lists screen. Create the appropriate statuses to match your grant giving workflow.

Custom data for grants

You can add custom data to grants:

  1. Go to Administer > Customize > Custom data. 
  2. Click on Add new custom fields.
  3. Choose Grant as the record type.

Consider adding custom data fields to upload the original application form; these could be converted to PDF before uploading to make them read only and reasonably future compatibile.  

See the custom data chapter for more information on setting up custom data.

Set-up

This chapter describes the steps to set up surveys. If you are connecting a survey to a specific campaign, you will want to review the Campaigns section as well.

Create a new survey

  1. Go to Campaigns > New Survey.
  2. Enter a Title for your survey and select the appropriate appropriate activity type.
  3. If the survey is part of a campaign, select the campaign from the dropdown menu.
  4. If you are using a custom profile for the survey, select if from the dropdown menu.
  5. Enter other relevant information on the form.
  6. Click Save, or Save and New if you want to create another survey.
Your survey will now appear in the summary on the Survey Dashboard. Use the links to the right of each survey to manage the survey.

Create a survey with multiple questions

In its default configuration, the survey feature allows you to capture responses to a single question; but often you will want to ask more than one question.

For example, the public housing survey had three questions. First, the TOFT staff member planned the questions to be asked and the standard responses for each question: Yes, No, Undecided, Declined. She then created custom fields for the questions, and when she created the survey she included the text of the questions so that they are saved for later reference (described below).

Once you have determined your survey questions and standard responses, the next step is to create the custom data fields:

  1. Create a custom data field set by going to Administer > Customize > Custom Data and clicking on Add a Set of Custom Fields.
  2. Name the set "Survey Responses" and in the Used For field select Activities of type Survey.
  3. Enter any help text that you wish to provide and click Save to create the field set for the responses.
  4. Now create the custom fields (called "Survey Q1 Response", "Survey Q2 Response", "Survey Q3 Response")  to hold the responses for the survey and configure the fields to share the same standard response options: Yes, No, Undecided, Declined. (The Survey Report creates a cover sheet to explains abbreviations or codes used for responses. This makes it easier to mark responses on a printed sheet, such as a WalkList, when doing a large door-knocking canvass. To keep your WalkList sheet neat and easy to record responses, you may want to consider using abbreviations or codes for the option values, and more descriptive text for the option labels.)
  5. Create the custom field set to hold the text of the three questions Used For "Survey" (called Survey Questions).
  6. Create custom fields for each of the 3 questions (called "Survey Q1 Text", "Survey Q2 Text", "Survey Q3 Text").
  7. Create the custom profile (called "Survey Response Profile") and use the custom fields for the three survey responses.

To learn more about how to create custom field sets, see the chapter called Creating Custom Fields in Your Data and CiviCRM. To learn about how to create a custom profile see the chapter Profiles in the in the CiviCRM Core Concepts section.

Now you are ready to create the new survey:

  1. Go to Campaign > New Survey and enter the following settings (this example uses the TOFT scenario, where the survey was part of a larger campaign called Demand Affordable Public Housing):
 Once you create a new result set, the result set will be named Public Housing Survey Result Set. (CiviCRM creates the name for the result set with the following naming convention: Title of the survey and Result Set.)



Click Save, or Save and New if you are creating several surveys. When you return to the Survey Dashboard you will see your new survey in the summary table.

Save the Survey Questions

If you would like to save the text of the questions of the Survey so you can refer to them later, you will need to:

  1. Create a custom field, e.g. with the Set Name Survey Questions and select Survey in Used For.  
  2. Add the custom fields to the custom field set for each question using a data type of Alphanumeric and a field type of Text. 

Survey Types

You can create new survey types to describe the type of activity you are conducting. Survey responses will be recorded in an activity record for an individual. The default CiviCRM survey types are Survey, Canvass, PhoneBank, WalkList, and Petition. 

To create or edit survey types: 

  1. Go to Administer > CiviCampaign > Survey Types.

  2. Click on Add Survey Type and complete the form. 
The next time you create a new survey (or edit an existing one) you will find your new survey type available in the dropdown menu of survey activity types.

Everyday Tasks

This chapter describes the everyday tasks for using the Survey feature.

Managing Your Surveys

To view and edit existing surveys, go to Campaign > Dashboard > Surveys. Here you will find a summary of your surveys.

Use the links at the right to manage existing surveys, or click Add Survey to create a new survey.  

Reserving Respondents

Before conducting a survey, you need to determine the group of individuals you want to interview; in CiviCRM this is called reserving respondents.

The reserved group can be divided into smaller subsets, as this may be a more manageable number of contacts to interview within available time periods.

To learn more about how to create a group, see the chapter called Groups and Tags. 

To reserve a group of respondents:

  1. Go to Campaigns > Reserve Respondents.
  2. From the Survey dropdown menu select the name of the survey (required).
  3. From the Group(s) dropdown menu select the name of the group of the contacts to be interviewed.
  4. You can enter additional criteria to limit your search to a geographic area, such as Street Address, Street Name, Street Unit, Street Number, City, Zip/Postal Code. (Note: CiviCRM will parse a street address into Street Name, Street Unit, Street Number - which is extremely useful if you're planning a large door-to-door canvass - only if you turn on address parsing by clicking on Administer > Configure > Global Settings > Address Settings, then in the Address Editing area, check the box for Street Address Parsing.)
  5. Click Search.

On the Find Respondents to Reserve search results screen, select the contacts to be reserved for interviewing on a particular street and building number:

  1. Sort the street number by clicking the arrows next to the column Street Number.
  2. Sort the street name by clicking the arrows next to the column Street number. 
  3. Select the individuals at a particular street name and number by checking the individual contacts to be interviewed (or select all of the contacts by clicking the radio button for All n records (where n is the number of contacts found in the reserve respondents search).
  4. Click Go to reserve the respondents.

 

On the Reserve Respondents screen, click Reserve. 


Interview Respondents

In our public housing survey scenario, the TOFT volunteers entered the data they had gathered each day directly into CiviCRM, using the following steps:

  1. Click Campaign > Interview Respondents.
  2. On the Find Respondents to Interview screen use the same criteria as for Reserve Respondents:

What You Need To Know

The following concepts and questions will help you to get the most out of using the survey tool in CiviCampaign.

Key Concepts 

These concepts are not about creating and undertaking surveys in general, but about the specific use of the survey tool in CiviCampaign. 

Custom Fields and Profiles

CiviCampaign surveys use custom profiles to capture survey participants' responses. Once you've decided on your questions and the types of responses, you need to create a custom field set for the questions and responses, and create option values if you're collecting multiple choice responses. You can then create the custom profile that will display the appropriate fields to enter the responses to the survey questions.

To learn more about how to create custom field sets, see the chapter called Custom Fields in the section Organising Your Data. To learn how to create a custom profile, see the chapter Profiles in the same section.

Reserving and releasing respondents

Before you can capture responses to your survey, you need to create a group made up of the contacts you are seeking responses from. This could be an existing group within your contacts, or you may need to create a group specifically for the survey. Survey describes this process as reserving respondents. When the contact has completed the survey and their data recorded, they are released from this group.

You can learn more about creating groups in the chapter Groups and Tags in the section Organising Your Data.

Surveys are designed to capture responses from existing contacts; if you are seeking responses from the wider public, use the Petition tool; see the Petitions section for information on this. 

CiviCampaign and CiviEngage

Surveys are part of the functionality of the CiviCampaign component, so you must have this enabled in order to use surveys; however, you can create surveys that are not connected to a specific campaign. For example, an organisation may wish to conduct a membership satisfaction service to assess the performance of their own service, without having it associated with a campaign.

See the Campaigns section for information about setting up CiviCampaign.

Drupal sites with the module CiviEngage enabled, will have additional custom field sets and profiles that configure surveys with the following survey types: Survey, PhoneBank, and WalkList. To find out more about how CiviEngage enhances the Survey feature, see the section called Civic Engagement. 

Drupal Permissions 

If you are using Drupal, you need to set permissions to allow specific roles to Reserve Campaign Contacts and Release Campaign Contacts when conducting the surveys. To learn more about setting Drupal permissions, go to the Drupal documentation at http://drupal.org/getting-started/6/admin/user/permissions.

Key Questions

survey REPORTS AND ANALYSIS

What is Survey?

CiviCampaign has a feature that enhances offline surveys by providing a standardised way to record survey responses and generate reports from the data. Survey responses are captured in an activity record (in an activity of the type Survey) for each individual.

Note that the Survey feature is used to record responses from your existing contacts. If you want to gather responses from individuals who may not exist in your database, you should use CiviCampaign's Petition feature; see the Petition section for more information.

For Drupal sites only, CiviCampaign interacts with the Drupal module CiviEngage to automatically provide additional options for your surveys; see the section Civic Engagement for more information. 

Scenario: Public housing survey

Toft Organisation For Tenants (TOFT) focuses on protecting tenants' rights and lobbying for affordable housing. The organisation wanted to gather information about the housing conditions in one particular neighborhood to gain a better understanding of the scale of the issues and which of them were most pressing for this community. They decided that one strategy would be to undertake a survey to capture basic information about housing conditions and complaints about landlords. A focus group met to determine what questions and who should be asked.

A TOFT staff member then created a new survey in CiviCRM and built the list of respondents from the existing contacts. She generated and printed a walk list report, which was given to the volunteers who would carry out the survey.

Over the period of a week, a team of volunteers visited selected public housing buildings to interview the respondents and record their responses on the walk list. At the end of each day, the volunteers entered the responses of each individual into the CiviCRM database; some were able to do this from their home computers, while others returned to TOFT's office and used computers there.

At the conclusion of the survey, the programme leader used CiviCRM to search activities for the group of individuals who were surveyed, and generated reports to analyse the responses and inform the next strategy for their campaign. The results of the survey were also used to frame their messages and communications about the issues that were affecting the neighborhood.

Email System Configuration

This chapter covers system configuration necessary so that CiviCRM can send and receive email.  This is a complex task which requires system administrator level skills.  Correct configuration is crucial to keep your server off spam lists and black lists. See Set Up of the Email section for tasks necessary to set up the sending of messages once the server settings have been configured.

Some parts of the configuration are core CiviCRM functionality (basic sending and receiving of emails) whereas others (mass mailings) require that the CiviCRM component be enabled.

You will need to be able to change the configuration of your DNS, create email accounts, configure a cron job, read the headers of email messages, and possibly change the configuration of your SMTP server.

This chapter assumes you are running CiviCRM on a Linux server and that you are comfortable working with the shell and running some simple commands.  Most of these steps will be similar on other operating systems, but you will need to adapt them to your system and tools. 

The configuration described works fine for mailings to up to about 10,000 people. If you plan on sending email to hundreds of thousands of contacts, you should benchmark several options and consider a dedicated SMTP server. This more complex configuration is outside the scope of this book.

In this chapter we'll use an external Gmail mailbox address to test configuration. So the first step is to create a Gmail account if you don't have one already; alternatively, you can use another address for testing the procedures in this chapter, but you will need to be able to view the source of the mails you receive.

Once your system is properly configured, you are going to run periodically (for instance every 10 minutes) two different programs:

Configuring outbound email

Outbound email setting are configured at: Administer > Configure > Global settings > Outbound Email. The choices here are:

After making a choice, send a test email to your account on Gmail and verify that you receive it.

If you receive the following error message, you'll need to configure a default FROM email address (covered in the chapter on CiviMail configuration).

Sorry. A non-recoverable error has occurred.
The site administrator needs to enter a valid 'FROM Email Address' in Administer ->
 Configure -> Domain Information. The email address used may need to be a valid
 mail account with your email service provider.

Once you have received the email, you will need to view the source.  This is done in Gmail by clicking on "Show original" in the email you receive.

The email should contain headers that resemble the following.

Received: from yourmailserver.example.org (xxx.example.org [12.45.120.30])
        by mx.google.com with ESMTP id e31si4519230wej.3.2010.04.26.00.38.16;
        Mon, 26 Apr 2010 00:38:17 -0700 (PDT)
Received-SPF: pass (google.com: best guess record for domain of
    youremail@example.org designates 12.45.120.30
    as permitted sender) client-ip=12.45.120.30

In particular:

Groups and tags

Groups and tags are two key methods of organising data in CiviCRM. When used properly, both allow for powerful segmentation and searching of your database.

Since both groups and tags are methods of categorisation, it can be difficult to determine whether a tag or a group is more appropriate in a given situation. Identifying the differences in their functionality will help you to decide which to use.

It can also be good to have a conceptual understanding of the differences between the two. Though there are different takes on how tags and groups should be used, a common philosophy is that tags should be used for descriptive categories and groups should be used for grouping people within an entity that needs to be treated like a cohesive unit (to send mailings to, for example). From this perspective, things like volunteer, ally organisation, vegetarian, and musician would be tags with which you could categorise contacts while Volunteer Committee, Allied Organisations Coalition, Vegetarian Newsletter, and This Awesome Band With A Bad Name would be groups to which you could add contacts.

Groups

Groups are an incredibly important feature within CiviCRM. In addition to their fundamental use as collections of contacts that have something in common, they play a critical role in CiviMail and Profiles, and can be used to set up advanced access rights (on Drupal). Well-defined groups are one of the most important tools available when segmenting your CiviCRM contact database.

There are two kinds of Groups - Regular Groups and Smart Groups.

Group settings and functionality

Each group should have a clear, easily understandable group name and a description of its purpose that other database users will be able to understand. Both the name and the description should allow users to quickly figure out what particular groups are for when working in different contexts (e.g. CiviMail). This clarity and specificity is especially important once your organisation has amassed many different groups. If a group is created for a specific person within your organisation, it is a good idea to mention who the group owner is in the description so that in the future someone can check if this group is still used or if it can be deleted.

Groups can be assigned the following types:

Visibility

Visibility determines permissions for joining and removing contacts from groups. Select "User and User Admin Only" if membership in this group is controlled only by authorised CiviCRM users. Select "Public Pages" if you want to allow contacts to join and remove themselves from this group via Registration and Account Profile forms.

Some organisations find it useful to create a hierarchy of groups. In CiviCRM, this is done by creating one or more parent groups and then assigning other groups to them. When a user sends a mailing to a parent group or searches for contacts in a parent group, all contacts in the associated child groups are automatically included.

For example, an organisation that has a national office and 5 regional offices puts constituents in each region into their own group. Then they create a National group which is assigned as the parent group for all regional groups. The national office can now send mailings to the National group, knowing that all contacts in the regional groups that are children of the National group will be included.

Group IDs

CiviCRM assigns a unique numeric ID to each group. These group IDs can be used for a variety of operations. For example, the group ID can be used to define a URL for group sign-ups. You can find a group's ID by checking the ID column in the tabled list of groups at Navigation Menu > Contacts > Manage Groups.

Tags

Tags are used to categorise contacts, activities and cases in CiviCRM. You can create as many tags as needed to classify the contacts in your database, though it is advisable to avoid duplicating existing tags or adding too many tags that aren't really necessary. It can be useful to create a standard process for creating and using tags within your organisation to avoid these problems.

Groups versus tags

This is a common question on any project, and the philosophy described in the introduction of this chapter is a guideline, but rules might need to be bent based on how you intend to use your contact segmentation.

One interesting benefit of having both groups and tags is that you can perform more refined searches using AND and OR. For instance, if you have journalists, volunteers and members as groups and use tags to identify topics of interests such as development, art and history, you can find all the journalists who are interested in art or development, all the volunteers or members that are interested in history, or any other combination.

Beside that, groups have some features that tags don't: 

Think of it this way: tags can be applied to contacts, activities, and cases, whereas groups can only consist of contacts.

Adding and removing contacts to groups and tags

You can add contacts to groups in multiple ways:

The first two methods also allow you to remove individual contacts from a group.  The last two methods allow you to add multiple contacts to groups at once.

Individual contacts can be added to a Group either in the contact edit screen or via the Groups tab. Multiple contacts can be added to a group at once by conducting a search, and then selecting Add Contacts to a Group using the More Actions menu. The second way allows you to add multiple contacts to a group by going to Manage Groups, selecting Members for the relevant Group and then using the Add Members to this Group option at the top of the screen.

Contacts can also be added to a group as a result of filling out a Profile (see below).

Managing Groups

To view and manage all groups, go to: Navigation Menu > Contacts > Manage Groups.

Groups_manage

You can use the Find Groups form at the top of the Manage Groups screen to search for groups by name, type, visibility and whether the group is enabled or disabled. You can also scroll or browse through the list of groups further down the Manage Groups screen. This list includes both regular and smart groups.

You can:

Finding contacts in a group

The Contacts page for each group includes a form for finding contacts within the group. You can search contacts within a group by name, email address, contact type, group status (added, removed, or pending) and tags.

Groups_searchwithin

Creating smart groups

Smart group are useful in many different situations. They are often used to assist organisational workflows. For instance, when you find yourself doing the same search over and over on your contacts, you can save the search as a smart group. Whenever you select that group, CiviCRM will run the search and display the results. Any new contacts that meet the search criteria will be added to the group, and contacts that no longer meet the criteria will be removed from the group.

Smart groups can be created from the search results generated by any of the search forms. For example, you can create a smart group of all donors who have not yet been sent a thank-you letter. As you send your letters, the donors receiving them will automatically leave the smart group, allowing you to always have an accurate list to work from. To create this smart group:

Go to: Search > Find Contacts > Advanced Search. 

Scroll down to the Contributions section and click on Contributions. 

Check "Thank-you date not set?" and choose Donation from the Contribution Type dropdown menu.

Click Search at the bottom of the page. 

Click the button that selects all the records

From the " - more actions - " dropdown menu select New Smart Group, then click Go.

The next screen provides a review of the criteria chosen for the smart group. Give the smart group a name, a description (optional) and decide if you want to make this smart group a Mailing List (allowing you to include the smart group in CiviMail). Then click Save Smart Group.

You can view your smart group by going to: Contacts > Manage Groups where you will see your smart group in the list.

Groups and ACL

Access Control Lists (ACL) provide finer grained permissioning than what is available through Drupal's Permissions and Roles. Setting up ACLs requires a good understanding of the concept, which is thoroughly explained in the online CiviCRM documentation here: http://wiki.civicrm.org/confluence/display/CRMDOC/Access+Control

As with many processes, the key is to make sure you have assembled all the parts before you try to join them together. In this case, you must set up the required Groups, Custom Data Groups, Profiles and Roles before you can use them in ACL.

Note that ACL support for Joomla was introduced in Joomla version 1.6. 

Groups and Organic Groups (Drupal only)

The Organic Groups CiviCRM module (http://drupal.org/project/og_civicrm) integrates Organic Groups from a Drupal site with CiviCRM groups. This is useful for groups that require Organic Group functionality on their website but also need to be tracked within CiviCRM. Once an Organic Group of Drupal users are integrated into CiviCRM, the Drupal group can be used for mailings, tracking address information, tracking activities or anything else normally done with CiviCRM contacts.

Once the Organic Groups CiviCRM module is installed and enabled in Drupal it automatically creates two CiviCRM groups for each existing Drupal Organic Group:

The groups are synchronised one way only, from the Drupal Organic Groups to CiviCRM groups. When a new user is added to or signs up for an Organic Group, they are automatically added to the corresponding CiviCRM group. If they leave the Organic Group then they are removed from the CiviCRM group. If an Organic Group is deleted, the CiviCRM group is also deleted. However, the reverse of each of this situations is not true; a contact added to the CiviCRM group will not appear in the Drupal Organic Group, a contact removed from the CiviCRM group will still remain in the Drupal Organic Group, and if you delete the CiviCRM group, the Drupal Organic Group will still remain. Therefore, this integration is meant to be used when you administer the group from the Drupal side.

Working with tags

To view tags, go to: Contacts > Manage Tags (Categories) in the navigation menu. 

A tag can be edited or deleted using the respective links in its row. New tags can be created by clicking the Add Tag button on the Manage Tags (Categories) screen or by going to Contacts > New Tag in the navigation menu.

admin_tags

Each tag should have a clear and unique name and an explanatory description to help users understand the tag's purpose. Tags can be structured hierarchically and designated as subtags of an existing tag by selecting a Parent tag from the dropdown list.

Tags can be designated for use for contacts, activities and/or cases. If a tag is designated for use for contacts, it will be available for all contact types and subtypes; tags cannot be specifically designated for use for only one type of contact.

Tags are a flexible tool and every user can create more if needed. However, very important tags can be locked to prevent them from being modified or deleted by users who do not have the "administer reserved tags" permission (this permission is available in Drupal only).

Tags can be assigned to contacts, activities and cases in the following ways:

You can also use the first two methods to remove tags.

Tag sets

Tag sets allow you to create free tagging taxonomies which users can add their own tags on the fly, without having to access the Manage Tags page described above.

Tag sets are created by going to: Contacts > Manage Tags (Categories) in the navigation menu and clicking the Add Tag Set button. Tag sets are configured identically to regular tags. However, they function quite differently. When you create a new tag set, it creates a new field on the edit pages of the entity's activities or cases as well as in the Tags tab for contacts.

This is a tokenising autocomplete field: as you begin to type, CiviCRM looks for matching tags in this tag set and displays any matches below the field. You can select an existing tag or create a new one by typing the entire tag and pressing the Enter key. The tag will then appear within the field in a box. Clicking on the X will untag the entity (contact, case or activity) that you are editing.

Tags created within a tag set can be viewed and edited from the normal Contacts > Manage Tags (Categories) list. However, tags created within a tag set will only be available within that particular tag set.

What is CiviCase?

CiviCase is a tool for tracking and managing sequences of interactions between people in your organisation and contacts in CiviCRM. It's similar to a case management system. In addition to tracking and managing your organisation's interactions with clients or constituents, CiviCase can also help you manage internal organisational interactions. 

Cases are used to track complex interactions or communication processes. A case can be used to:

CiviCase relies on Activities. To learn about how they work, see the Activities chapter.  

Organisations have employed CiviCase in a wide variety of situations. Here are a few examples of different types of organisations and how they might employ CiviCase. 

Scenario: managing legislator-constituent interactions

A legislator's staff manages hundreds of interactions with constituents and communities daily. Legislative staff can manage and track these interactions while avoiding duplicating work (for example, if a constituent calls in about a topic that a staffer is already working on). CiviCase also automates the task of remembering and scheduling follow up activities by presenting staffers with a list of upcoming case activities that require their attention.

CiviCase came in handy to track a series of related tasks that legislative staff do as a result of interactions with constituents, including:

Scenario: complex application process 

An organisation administering a health department grant programme to distribute several million dollars worth of grants used CiviCase to manage the grant applications process. When interested parties submitted their initial applications, a case was automatically created to manage each. The case created contained several activities which were automatically assigned to different staff managing the application process.

In this instance the users were actually from three separate organisations who each had to apply their assessment of the application in turn. First, a basic initial assessment was made to check that certain criteria were met. Then an external organisation made a more technical assessment. The activities were all offset from the start of the case by the number of days in which it was anticipated they should be completed and a coordinator from each organisation assigned the case activities to members of staff according to their capacity as they came in.

At various stages in the process the status of the case was changed for one reason or another. In this process the main options were:

Even though there were thousands of applications and tens of thousands of parts of the application review process, the coordinators from the first two organisations assigned activities to staff members so they each saw a case dashboard showing only the work assigned to them, helping them focus their energy on just their segment of the applications.

For the final assessment, the two organisations hired an external organisation to process the remaining applications. For this process, a review committee was able to view the key details of applications with different statuses, and finally, just the summary details of all applications with an accepted status to make a final determination. 

What is CiviContribute?

CiviContribute supports fund-raising and related money management. It has two main uses:

CiviContribute offers a number of tools for raising money through your web site. For example, you can create contribution pages with fundraising targets. Campaigns support a thermometer style widget that can be embedded on other web sites and blogs. Personal campaign pages (PCPs) and the "tell-a-friend" functionality engage your supporters in raising money for your organisation and give them credit for any money that they raise from other people on your behalf. 

Several other CiviCRM components require CiviContribute to be enabled. To use CiviContribute you will need to configure a payment processor; for information on how to do this, see (chapter / section). 

Scenario:

(Could use Green Party Australia?)

- mention CiviPledge in the scenario 

What is CiviEngage?

CiviEngage is a Drupal module that enhances CiviCRM's core functions for non-profits focused on community organising and civic engagement work. If your site is built with Joomla!, you cannot use CiviEngage. 

CiviEngage was built to aid community organising, base-building and civic engagement specifically within the USA context. It provides tools for managing walk lists for door-to-door campaigns and call lists for phone banks, and tracking how constituents interact with your organisation and move through various activities with increasing involvement over time.

CiviEngage provides:

CiviEngage enhances CiviCampaign, which you can read more about in the Campaign section. 

Scenario: Direct action

Townsville Organisation For Tenants (TOFT) focuses on affordable housing issues. To impact the decisions of the state legislators on an upcoming rent cap bill, TOFT made a decision to mobilise several hundred people for a direct action at the state capitol, but had only two weeks to do it. The organisers knew that the best way to contact their particular constituency was by phone and they wanted to know who would participate in the direct action so they could track each individual's involvement with the organisation over time.

First, TOFT organisers identified who they wanted to mobilise for direct action based on specific criteria and information they keep about their constituency, such as geographic location, issue interests, volunteer interests, leadership level, etc.

A programme leader then created a Direct Action event in CiviCRM, using CiviEvent, and added groups of individuals to the event.

Organisers called the list of possible participants from a phone bank list report (they could also have done this using a participant listing) and entered the results of each call, such as whether the person would attend, they reached a wrong number, or had to leave a message.

An organiser contacted each participant several times to ensure that they would attend the direct action, and recorded the responses each time. Most organisers reached out to possible participants up to three times to ensure their commitment to attending.

After the Direct Action event, TOFT staff were able to analyse how many people said they would attend, how many actually attended, and how effective their method of outreach was.

Scenario: Canvassing

An organisation wanted to engage constituents based on what they learned from individual responses during a door-knock canvass related to the fair treatment of workers at the local car manufacturing factory. To find out more about how their constituencies feel about the treatment of workers and to see if they would like to help, organisers decided to do a door-knock canvass in several neighborhoods where they knew there was a high concentration of factory workers.

Staff first defined the target audience based on specific districts in a city and neighborhood where they knew that there was a high concentration of factory workers.

To track all their strategies and the people who have interacted with the organisation with relation to this particular campaign, the staff created a campaign in CiviCampaign. They then created a survey in Surveys to record the questions asked during the door-knock canvass.

Staff created an event in CiviEvent to capture who would be attending the direct action event at the capitol, identified the community leaders who could help bring more constituents to the event, and added them as volunteers for the event. So that these volunteers could collect responses from people they contacted, staff created a walk list report and distributed it to them.

Each volunteer canvasser visited the locations on the walk list and gathered the responses on their report. At the end of each day, other volunteers gathered the completed walk list reports, and entered the responses directly into CiviCRM.

After the canvass campaign, the programme leaders analysed all the responses to the canvass survey and used this information to determine their next strategy to engage their constituency in the issue.

Because the organisation was able track information at every step of this canvassing work, they achieved a clearer sense of what their factory worker constituents needs and wants. TOFT was then more prepared to develop targeted communications that spoke directly to the needs of this constituency.

Finally, the careful tracking and collecting of data will be used to inform next steps in their overall strategy to gain fair treatment for workers in the community. Collecting data in this way over time will give TOFT a better sense of whether they're able to move their constituents effectively and achieve impact with their approach. 

What is CiviEvent?

CiviEvent provides a set of tools for running events and minimizes the usual amount of administration required. In CiviCRM, an event is something that happens at a specified time, with a registration process, and has participants.

CiviEvent helps you to organise and hold events by:

CiviEvent is integrated with CiviCRM's other components. For example, CiviMail makes it possible to promote the event to a targeted list and to communicate with event participants via email before and after the event (see the Set-up chapter in the CiviMail section for more information); and in order to accept online event fees, you must also set up a payment processor and CiviContribute.

Scenario: Youth leadership workshop

A community arts group, Arts in Action, conducts leadership workshops for youth aged under 25 throughout the year. Their goals include attracting new youth to attend and enlisting pas attendees to volunteer and teach. Youth from local schools and theater groups are invited to attend, and there are youth speakers and volunteers, as well as other speakers for the training workshops. 

The Arts in Action communications staff use CiviEvent to efficiently manage each event from the beginning of its planning to the end of its evaluation. First, an event page with an online registration form is created. Because this is a regular event, a staff member previously created an event template which pre-populates much of the form for each following event. There is a flat fee for registration, with additional fees for optional workshops which attendees can select and pay for online. The registration form uses a profile to gather information about participants' food and lodging preferences.

A targeted list of youth and groups is drawn from existing contacts, and staff send personalised invitations using CiviMail (also based on a template, so that information can be reused from one event to the next). The invitation includes a direct link to the event page so that with a single click arrive at the online registration. The event is also announced publicly by posting it on the website, and the "Tell-a-friend" function is enabled so that the information can easily be spread through people's networks. 

A staff person is designated to manage the process by which participants register themselves, periodically checking to make sure that payments are being made, managing the wait list when participant sign-ups exceed the maximum number, and answering any queries.

On the day of the event, organisers check in each attendee on-site to keep track of who has actually attending and whether there are any no-shows. The database can be updated immediately, freeing up spaces for those on the wait list and later helping to determine who has paid, who still owes fees and what the final financial picture is. 

After each workshop, Arts in Action staff evaluate the success of the event and use CiviEvent to quickly generate reports such as the number of attendees, total event fees paid, and total amount still due. The event and mail templates are updated if necessary and saved for the next event.

What is CiviMail

The CiviMail component extends CiviCRM's core email functionality with sophisticated tools for handling mass email campaigns. It can reliably deliver a high volume of email and provide detailed reports on the results and effectiveness of those emails.   CiviMail is often used to complement other CiviCRM components, for example to send emails to non members to encourage them to become members or to send emails to people that are yet to register for an event.

CiviCRM's mail features, including CiviMail, interact with your mail server software. Configuring the mail server and CiviMail are system administrator tasks, which may require professional assistance. You will also need to verify with your web hosting provider whether they meet the configuration requirements, and verify that they don't put limits you might exceed on the number of emails you can send per day. 

Scenario: Peace centre 

St Egeltina's Centre for Peace and Reconciliation use CiviEvent to run a yearly event programme on a number of different themes. They have set up a mailing list page where people can sign up to be informed of all events only events that interest them. They then use CiviMail to send out emails to those people based on those events. When someone unsubscribes from an event theme mailing list, CiviCRM keeps a record of the fact that they have unsubscribed. 

St Egeltina's also automatically subscribe anyone who has been to an event on a specific theme to receive emails about that theme. They don't have to worry about spamming people that have unsubscribed from a thematic event mailing list, as CiviCRM will remember that they have unsubscribed and not re-subscribe them.

From time to time, St. Egeltina's send out other emails to a mailing list that includes nearly all contacts on their database with personal messages from the centre director highlighting particular issues. Often two similar versions of the same email are sent to different groups in their database to test which message formats are more effective. They can do this by sending the email to half the contacts in a particular group and then sending another email which excludes contacts that have already received the first email.

Scenario: mobilising with email

The Townsville Organisation For Tenants (TOFT) held a survey and petition to gather data and support for the campaign Demand Affordable Public Housing. The survey was undertaken by volunteers visiting selected constituents in their homes while the petition was widely promoted to the public who could sign and answer questions online.

In the early stages of the campaign, the TOFT volunteer coordinator searched for contacts in the group Volunteers and used the Send email action to send a general email asking for volunteers to help with the survey. From those who responded that they were available, a small group were trained to carry out the home visits and record survey responses.

Once the online petition had been created using tools in CiviCampaign, the TOFT communications officer created an email including text, images and links to promote the campaign and encourage people to click through to the site and complete the online petition. This email was then sent out to the entire database using CiviMail, including a forwarding link so that recipients could easily distribute the email widely through their own networks.

CiviMail enabled TOFT to track responses to this mass emailing; reports were generated showing that 89% of recipients clicked through to sign the petition, and 75% forwarded it on to others. This data was then compared with previous offline petition and survey efforts to demonstrate the increased reach of the campaign through using CiviCRM. 

What is CiviMember?

CiviMember aims to automate membership administration as much as possible. CiviMember allows you to:

Memberships can be free or paid, and have simple or complex pricing structures. CiviContribute is required to handle membership fee payments.

All memberships show up on contact views and in the membership dashboard. They can be searched for through the Membership Search or Advanced Search and there is a built in report template.

Scenario: Driving membership forward

The Atlantic Region Public Transit Association (ARPTA) has a complex requirement with four membership categories:

When the ARPTA membership administrator, Sue, initially configured the membership types she created various separate membership types and rules to account for each. This was all easily managed by CiviMember. Initially, they carried on with manually processing membership renewals and new sign-ups while the system bedded in. 

Last year ARPTA's membership committee began a focused outreach to non-member public transit systems (Regular Member category) and non-member businesses working in the public transit industry (Affiliate Member category). They wanted their members to renew online and pay through a credit card.

To accomplish this, they created a membership sign-up/renewal page and publicised this in a series of emails, blog posts and promotions on various social media platforms. The sign-up page is available to all website visitors, whereas the renewal page is visible only to contacts who are already members, after they log in to the members-only section. This streamlines their sign-up process, eliminates a lot of paperwork and gives Sue a clear view of new sign-ups, recent renewals and expired members that need to be chased. Through CiviContribute, she canproduce a monthly spreadsheet for the accounts department with all membership fees received, which they import into their accounting software. With the time she saves on paperwork she is able to engage more with members and is more involved in the annual conference.

What is CiviReport?

Reporting helps your organisation to evaluate its impact and achieve its mission. Sometimes this is a requirement for funders or other stakeholders. CiviReport allows you to create, run and schedule reports based on the data CiviCRM has about your contacts and their interactions with your organisation.

These reports are queries on the database using criteria and fields available in a report template. Reports can be delivered on the page when you run them, as a dashlet on the dashboard or a scheduled email which can include a CSV file or PDF. 

Scenario: a simple report to help with fundraising

1two3, a support organisation for street workers, has launched a capital campaign to raise money for a new shelter. Anne, the development director wanted to reach out to donors who made a large donation last year but haven't given money this year.

She created an instance of the LYBUNT report ("Last year but unfortunately not this") which filters data to show people who gave more than €500 last year, then ran the report and used the Add to Group button to put these donors into a new group so she could send an email to everyone in the group with information about the capital campaign.

Finally she added the report to her CiviCRM Dashboard so she can review progress getting this group of prior donors to contribute to the campaign. Anyone who donates will automatically drop off this list since they will no longer meet the criteria, and the list remaining in the dashlet can be used as the basis for follow up phone calls or other personalised contact. 

Scenario: a regular financial report 

WAM is an academic membership organisation with about 1,500 members. Their members renew their membership online and pay either online by card or by offline by direct debit. Mark, the finance officer, needs several reports to keep track of the money coming in and automation of this process was a key reason for the implementation of CiviCRM. All these reports are regular and are sent to him by email with a CSV attachement so he can import the details into either their accounting software or their online banking interface. While a couple of the key reports are outlined here, their requirements were fairly complex and some custom report templates were required alongside the standard ones.

Every Monday morning, Mark receives a list of all completed online payments for the previous week to import into Sage; this report contains the amount and time of the payment along with what it was for (membership or event) and a reference ID so it can be tracked back to the record in CiviCRM. At the end of every month, he receives a list of all members who pay by direct debit whose membership is due to expire in the following month. This allows him to set up the direct debit payments for these membership renewals by importing part of the list into their online banking interface.

These email reports save Mark several hours a month and allow him to focus on issues that contribute more to the effective management of WAM's financial resources.

Scenario: determining total contributions for a household

A non-profit organisation in Ohio keeps records of individuals organised by households. A common situation is that the husband in the household has attended a number of paid events, while his wife has also registered for other events and made separate donations.

Staff at the organisation want to see the total contributions received from everyone in a household so that when someone calls the office to enquire about a donation or event payment made by someone else in the family, all the relevant information is at hand. Staff can run the Donation Summary Report (Household) as required, using the name of the household to find all contributions and relevant information to answer the caller's questions. 

What is CiviGrant?

CiviGrant is designed to be used by organisations that distribute funds to others, for example foundations, grant givers, etc. 

In contrast to CiviContribute, which tracks money going into your organisation, CiviGrant tracks money going out of your organisation. CiviGrant has a data structure and workflows that support the grant application process with the ability to manage the amount applied for, amount received and any reports necessary for the process.

If you have a more complicated grant application process with multiple pathways, you may wish to consider using CiviGrant in conjunction with CiviCase.

Scenario: Wookie Hole

Wookie Hole Community Action is a small umbrella organisation that distributes funds to support the annual Wookie Hole Community Festival held each year in Wookie Hole Cave.

They have a total grant pool of £40,000, which comes from local businesses and other grant giving organisations, that they make available each year to local organisations participating in the festival. Each organisation that applies for funds needs to complete an eligibility questionnaire, which is then entered into the applicant's contact record, and an application that details how they will spend the money, which they attach to the grant. As well as filling in certain fields for each grant, they also attach a read-only PDF copy of the original application form for future reference.

Ineligible applications are rejected and eligible applications are scored according to pre-defined criteria. The grant committee members then look at the total amount applied for by all applicants. If it is greater than £40,000, they look again at all eligble projects to decide which ones to fully or partially fund. CiviGrant has fields that they can use to store and search on this information.

Once the funds have been granted, the organisation uses CiviGrant in conjunction with CiviMail to solicit feedback and reports from all organisations that they have funded. Once the feedback is received they mark the grant as "feedback received". Multiple emails often have to be sent to organisations to get feedback. The organisation does this by using an email template and searching for all contacts who have successfully received a grant but not yet sent feedback.

Finally, once all reports are in, a staff member compiles a report and thank-you which they email to all organisations that gave funds toward the festival. The report details how their funds benefited the local community. Wookie Hole Community Action also prints a certificate for each local business and funder (directly from CiviCRM) which they can proudly display in their premises.

What You Need To Know

CiviGrant is designed to help grant-giving organisations to manage this process. CiviGrant is one of the simpler CiviCRM components so if you are familiar with other CiviCRM components, you will probably find CiviGrant quite straightforward.

Key Concepts

An understanding of the following key concepts will help you to make the best use of CiviGrant. 

CiviGrant workflow

The standard CiviGrant workflow starts with the details of the grant that a contact is applying for, including the amount applied for and when the application was received. You can then record the stages of the process including when the grant decision was made, how much was granted, when money was transferred, when the grant report was due and if it has been received.

Grant types

Use grant types to specifiy the different types of grant that your organisation distributes. You can set up as many grant types as you like, and you can also search based on grant type.

Grant statuses

CiviGrant comes with three default grant statuses: Pending, Granted and Rejected. You can add more grant statuses to match your workflow.

Application forms and eligibility criteria

You can create application processing forms and eligibility criteria in CiviGrant, using CiviCRM's custom data fields. Think about what fields should be attached to the contact who has applied for the grant, and what fields should be attached to the grant.

Key questions

Once you've familiarised youself with the concepts outlined above, and before you begin to work with CiviGrant, answer the following questions:

Who is CiviCRM?

CiviCRM has a unique and diverse community centered around developing, using, and documenting the software. Our community includes the CiviCRM core team, people at the non-profits that use CiviCRM; consultants working with a number of non-profit organizations; programmers and developers, power users, volunteers and community organizers! We are also closely related to many other open source projects.

Each member of the community interacts with CiviCRM in their own way, working to improve the software and how we organize ourselves. The strength of community comes from this diversity and the ease with which someone can join us, and means that we are constantly changing and improving, often in unexpected ways.

Like all communities your membership is characterised by your interactions. If you treat others well, have some fun, and help others, then you can expect to enjoy being a member of the CiviCRM community. But if you are prone to complaining or don't use a respectful tone in communications, or if you see the community just as a resource and not as a collection of very kind, generous and clever people, then you are probably not going to get much of a response. Treat people well and you can find the CiviCRM community fun and rewarding.

History

CiviCRM started in 2004 by Dave Greenberg, Donald Lobo and Michal Mach. The founders had a lot of previous experience working with non-profit organizations and tools. The group was influenced very early by Zack Rosen and Neil Drumm, who convinced them to use Drupal as a fundamental cornerstone for CiviCRM. This decision has meant that the developers have been able to leverage a lot of the functionality that Drupal provides, freeing the team up to focus on building the features necessary to make a great CRM.

In 2005 the first version of CiviCRM was released with two of the core modules in place: CiviMail and CiviContribute (you can read more about these later).

Since those early days CiviCRM has built a large community of users and contributors (there are now over 8000 installed sites), the software has gone from strength to strength (there are now 8 core modules and additional third party components), and the core team has expanded to 8 members. There is also a large ecology of free software contributors around the project and high-profile non-profit organisations such as Wikipedia, Creative Commons, Mozilla, and Amnesty International use CiviCRM.

It's good to talk

CiviCRM is an open and learning community, and people are ready to hear your ideas. If you have a good idea, there's nothing to stop you carrying it out - but the best way to start, is to start talking about it.

If you're not sure where to start, the best place is probably the community forum (http://forum.civicrm.org/). Ask people what they think about your idea. There's a wealth of experience on the forum, and with a bit of luck, someone will have tried something similar before. CiviCRM people are a friendly bunch and their guiding philosophy is collaboration.

Depending on your idea, you'll be directed to the next best place - maybe an article on the blog (http://civicrm.org/blog/), a page on the wiki (http://wiki.civicrm.org/), a teleconference or a meeting up with another community member in real life, yes that's right, REAL LIFE!

Be the change

So you have a great idea. Now you need an equally great action plan to accompany this idea and then you'll need to implement it. Although the CiviCRM community is friendly and supportive and will like to be involved and updated about your project, you'll need to be the driver. How will you get the resources together for your project? How can you fit it in with your day job? Finding a way to simultaneously achieve your own objectives and benefiting the CiviCRM community is the best way of getting things done.

And finally...

If you're a CiviCRM user who has an ongoing relationship with a consultant, there's nothing to stop you from also being an active member of the community. The community really benefits from direct feedback from end users - your consultant is only one person or organization - by asking on the forums you're opening yourself up to help and input from the entire community.