About this book

This book is a guide for users and administrators of CiviCRM.  It covers everything that normal users and administrators of CiviCRM need to know to work with CiviCRM on a day to day basis. Our aim is to cover all functionality that is available via CiviCRM's user interface.

Although we do not cover system administrator or developer topics, CiviCRM developers and system administrators will also find this book useful as a guide to everything you can do with an 'out of the box' CiviCRM.

Some aspects of CiviCRM (such as installation, or custom development) are technical and outside the scope of this book. Although they are not covered here, we do point to other relevant sources of technical document which should be useful for people (like your service provider, or technical staff) who understand them.

This book is freely available to read online and download in multiple formats. It is collaboratively written by the CiviCRM community (see the History of this book chapter for more details). You can help write this book and help with other documentation efforts. See https://civicrm.org/participate/documentation for more information.

What is CiviCRM?

CiviCRM is a powerful, web-based contact relationship management (CRM) system. It allows an organisation to record and manage information about the various people and organizations it interacts with. CiviCRM is more than just an address book, it also allows you to track your interactions with people and organizations, engage with constituents, and solicit donations through your website. The information you gather is all stored in one place but you can access it from almost anywhere.

CiviCRM focuses on the needs of non-profits. CiviCRM emphasizes communicating with individuals, community engagement, activism, outreach, managing contributions, and managing memberships.

CiviCRM is Free/Open Source software, which means there are no license costs or user fees associated with downloading, installing, or using the software. Being Free/Open Source also ensures that you have the freedom to view and modify the source code and to distribute copies of the original source to any person or organization.

CiviCRM is web-based, which means it can be accessed by many users at the same time from different locations. It has been developed with the international community in mind, and translations and multi-language options are supported.

One way to understand what a CRM does is to think of your personal address book with enhanced capabilities. Imagine that every time you make a phone call to a given person, your address book automatically makes a note of it, together with brief description of the conversation. It can also decide whether to ask this person for a particular favor, based on whether she did this favor for you a week ago, and schedule a follow-up meeting following the call. After using this address book for a while, you could ask "What were my interactions with Ji Lao?" or "How many people helped me this month?" and it would give you the whole history.

Now let's say you're organizing a dinner party and you want to invite all the people you've met during the previous year. Just write the invitation and tell your address book to send the email. You don't have to worry about anything else after this point (apart from preparing the dinner!). Your address book handles the RSVPs from all invited guests, together with information about who is vegetarian and who is not. It even lets you know two nights before the event how many people you can expect.

It would be great to have such an "assistant", right? Organizations need one even more. It's hard to remember all of your meetings, phone calls and other forms of contact (especially over the long term), but the more you know about the people and organisations you interact with, the more successful your work will be. You'll be able to target your message to specific groups, because you know who will be interested in specific topics, and you'll be able to observe their reactions and adjust your next interaction, and continue to improve how you talk to different groups.

CiviCRM is a modular system.  In the simplest set-up you can:

record basic contact information such as name, home or postal address, email address, phone number

define relationships between your contacts

send emails

keep a record of your interactions with your contacts

Components and extensions will let you do more things such as sign up members for your organisation, take registrations for your events, receive donations or distribute grants.  See the Components and Extensions chapters for more information.

CiviCRM works together with another common piece of software: a content management system (CMS).  A CMS is a tool for creating and managing websites, and most websites these days are based on a CMS.

CiviCRM integrates with Drupal, Joomla and WordPress. Integration with a CMS opens up a lot of useful possibilities.   Visitors to your website can carry out many activities on their own, such as renewing their membership, signing up for events, requesting email updates, and donating money and you can share parts of your CRM data, for example event information, with visitors to your website. You can read more about integrating with a CMS in the Website Integration section.

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

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 enrollments 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 to 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.

They set up online enrollment for circus skills classes with the CiviEvent component, and decided to pay a commission to a payment processing company so that credit cards could be used for online class payments. They also used CiviEvent to set limits on the number of students that could enroll in a given class.

To track emergency contact information, custom data fields were created and added to a profile that was used as a form for event registration. This information was then stored in CiviCRM.

They integrated CiviCRM with Drupal and set up user accounts for every contact in their database. The system's users were then instructed on how to use the Drupal 'reset my password' link to gain access to the system for the first time so that they could then update their own information.

CiviMail was implemented to contact tutors, volunteers and students.

Since the Trust applies for grants from funding bodies, they enabled the CiviGrant component.

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!

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 is 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.

A CRM Education

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 CiviCRM, SHS has centralised their operations and the management of 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

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

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:

Development of IT must be socially responsible and sustainable.

The use of free and open source software should be encouraged.

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

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

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

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:

required parents to log in to view their contact information and their child's school information 

had an automated system to schedule parent teacher conferences

used a computer to record after school class sign in and sign out

managed after school class registration (example: music, cooking, sports) and view their child's after school fees

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.

Components

Components give you more tools to interact with your contacts.  You can use as many or as few of these as you need and then can be turned on and off as necessary.  Turning off, or disabling modules that you aren't using removes them from the user interface, e.g. from the menu system, the advanced search page and so on. This simplifies the appearance of CiviCRM for your users. You can also set permissions so that only certain users can see certain components, for example so that only fundraisers can see financial information.

Turning off a component will not remove any data from CiviCRM - just hide it.  When you turn it on again, the data will re-appear.

Each component is explained in detail in its own section so only a brief description is given here.

CiviContribute

An online fundraising and donor management component which enables you to track and manage contributions to your organization. It also allows you to quickly and easily create customized web pages to accept one of and recurring online donations.  Part of CiviContribute is CiviPledge, which allows you to record and track pledges, send pledge acknowledgements and payment reminders, configure online contribution pages to support self-service pledging and pledge payments.

CiviMail 

A robust mass-mailing component which allows you to engage your constituents with personalized email blasts and newsletters.

CiviMember

A flexible membership management component which includes convenient online signup and renewal.

CiviEvent

Provides integrated online event registration and management for paid and free events. It allows you to quickly and easily create customized web pages to for event registration, and then track participants.

CiviReport

Report templates that can be configured to provide information on the data in your CiviCRM installation.

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.

CiviCase

Integrated case management component, including a dashboard with "my cases", automated case timelines and configurable audit reports.

CiviGrant

Designed to be used by organizations that distribute funds to others, for example foundations, grant givers, etc.

Extensions

Extensions provide additional functionality to core CiviCRM. Extensions are the recommended way to create new features and change the way that CiviCRM works, especially when these changes are not needed or desired by the entire CiviCRM community.

Many people write extensions for their specific use cases and install them it on their CiviCRM installation.  Many people write generic extensions that are useful for multiple organisations. Extensions that are useful to multiple organisations can be published in the CiviCRM extensions directory.

The extensions directory

The extensions directory is available at https://civicrm.org/extensions. It lists extensions that have been written by members of the CiviCRM community and made freely available for download by other organisations.  Extensions are by default listed in order of popularity (which is calculated by the number of sites that report using the module).

Extensions are organised into two broad categories: 'native' extensions which work with any CMS, and CMS specific extensions that add integration between CiviCRM and the CMS and hence are CMS specific. If you are familiar with your CMS, you may know CMS specific extensions by another name, for example Drupal specific extensions are typically called Drupal Modules and Wordpress specific extensions are called Wordpress Plugins.

Extensions that have been approved for automated distribution can be easily installed directly from your CiviCRM installation.

Installing extensions

When configured correctly, extensions can be installed directly into CiviCRM via the user interface. Go to Administer > System Settings > Manage Extensions.  You should see a list of extensions that are compatible with your version of CiviCRM.  Note that you may not see all the extensions that were listed in the extensions directory as they may not be compatible.

If you do not see a list of extensions here, it may be that your system is not properly configured to manage extensions. You should consult your system administrator if this is the case.

Writing extensions

Anyone is free to write an extension to enhance their CiviCRM installation (or commission someone to do so).  Writing an extension is a task for a developer so a detailed discussion of how to write one is outside the scope of this book. If you do write an extension to cater for your particular use case, you may wish to consider if other organisations would also be able to benefit from your work and hence whether you should publish your extension and make it more generic.  Publishing your extension and attracting users brings many benefits in the shape of feedback on how it can be improved, bug reports, and code contributions that may enhance your extension.

Who is CiviCRM?

CiviCRM has a unique and diverse community centred 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 Amnesty International, Creative Commons, Electronic Frontier Foundation,  Free Software Foundation, Mozilla, and Wikimedia Foundation 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 someone will, very possibly, 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.

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:

read the book! (you might be doing that right now)

identify your organisation needs

talk to others who use CiviCRM

talk to a CiviCRM consultant

play with a demonstration site

install a test database

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, contact a CiviCRM Ambassador (https://civicrm.org/ambassadors), 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/providers), 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.

Building internal support for a new Constituent Relationship Management (CRM) solution is a complex task that, when done thoughtfully, can yield great rewards.

Some organizations are comfortable appointing a team to do this internally while others rely on outside consultants. Following are our recommendations for how best to evaluate your organization’s needs and build internal support.

Goal

To start with, take a minute to articulate the goal of adopting a CRM. For example:

Investing in our organization’s database of 12,000 constituents will allow our team to better focus on raising funds and awareness to fulfill our mission now and in the future.

Evaluation

Evaluate your organization’s specific CRM needs by interviewing key stakeholders. This might include development, communications, marketing, events and programs staff as well as board members.

Help them identify the constituents they interact with on a routine basis and to articulate key challenges in managing constituent information (collecting, updating, sharing and using contact information).

Identify specific inefficiencies that could be addressed by a comprehensive Constituent Relationship Management solution.

Enumerate the resulting lost productivity. For example:

Incoherent view of our constituents. We are unable to see a holistic record of our constituents eg: who is a donor, volunteer and e-newsletter subscriber.

Inability to include all prospective donors in all outreach efforts. With fractured constituent lists we are unable to include all constituents in our efforts to raise funds, awareness and promote events.

Inefficient use of staff. Redundant staff time is spent re-keying information originally received digitally, importing, exporting and de-duping records.

Lack of communication. Inability to communicate across departments about our various interactions with the same constituent.

Data vulnerability. Inability to make reliable backups of all data and protect it against malicious or accidental loss.

Lastly, inventory current data sources that could be consolidated and shared across departments. For example:

Owner / Department / Count / Constituent / Description / filename

Kris / Comms / 245 / short-lead media contacts / comms campaigns / comms2010.doc

Katie /Dev / 79,000 / donors / donors active since 2005 / donors2005-2010.xls

Martha /Marketing / 233 / corporate partners / active partners / (Outlook)

Dan /Marketing / 134 / grassroots partners / all grassroots partners / grasspartners05-10 (Google docs)

Carole / Volunteers / 3450 / volunteers / all MLK day volunteers, skills / mlk_volunteers_10.xls

Benefits

Enumerate the specific benefits of investing in a holistic CRM solution. For example:

Accessible to the entire staff from inside and outside the office (with granular permissions from entry level to super-users)

Holistic record for each constituent showing all their contact information and interactions with our organization.

Dynamic creation of constituent groups allowing us to create groups of constituents based on criteria such as ‘all donors of over $100 in Massachusetts’ or ‘all donors whose gifts have amounted to major gifts this year’

Dynamic creation of top donor and other reports

Constituents' self-service creation and management of their contact/contribution/subscription/activity records

Recommendations

In recommending your CRM solution enumerate and compare its features and costs to other market solutions. Share case studies of other organizations who use the recommended solution.

Implementation costs - Include a budget for implementation that contemplates:

discovery and project management

data clean up, consolidation and migration

system configuration

post implementation training and documentation

Maintenance costs - Include a budget for ongoing maintenance that contemplates:

pro-active server maintenance

incremental data backups

operating system and software upgrades

ongoing training

Test it out

Demonstration sites

CiviCRM hosts several demo sites - there is at least one for each of the supported Content Management Systems (CMS) - Drupal, Joomla, and WordPress. 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 https://civicrm.org/go/demo.

The demo sites may be configured strangely, missing functionality or appear in different languages, as other people may be experimenting with them at the same time as you.

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

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, 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. 

Hosting

Before installing CiviCRM, careful consideration must be given to where it will be hosted. The main options with an outline of the situations in which you would want to choose them, and the advantages and disadvantages of doing so are outlined below: 

Internal hosting 

If you have an internal IT department or staff members with a technical background, you may wish to host CiviCRM internally. To do this, you will need:

Servers or dedicated PC hardware available to run as a web server, 24-7.

A space on premises to permanently store the hardware, possibly air conditioned.

An un-interrupted power supply (UPS) to ensure the server is still available during power outages.

Either a stable internet connection with a static IP address and an SLA (Service Level Agreement) for high availability, or a leased line. It is important to note that should the Internet connectivity to the building in which your server resides goes down, only users on internal network will be able to access it. External visitors will not be able to access your website, including logging into CiviCRM and accessing online contribution forms. Widgets posted on other sites will also become unavailable. The bandwidth is also an important factor, as it must be high enough to serve the amount of traffic your website receives.

There are other aspects to address too. If you have an internal network, the web server should be partitioned from the other computers and servers to enhance security (e.g. in a Virtual Private Network or DMZ). A web server could, potentially, introduce vulnerabilities that an external individual, script or bot could use as a gateway into your otherwise private, non-Internet facing systems. It is also a good idea to research the maintenance and daily running costs of having an internal server, and compare it to that of using an external host.

External hosting 

With internal expertise you could manage the install and configuration in-house, but host CiviCRM with an external provider. In this instance, we recommended you rent a VPS (Virtual Private Server) to ensure you have complete control of all packages and libraries (e.g. PHP, MySQL, etc), and are therefore able to configure it to your specific requirements.

Many shared hosts restrict the level of access you have, and may not support CiviCRM if you are unable to install the required pre-requisites. Shared hosts can also be prone to performance issues, as the hardware is shared between a group of customers with varying usage levels; if one customer's website suddenly receives a large spike in traffic, every website on that server could experience a lengthy outage.

Disadvantages aside, leasing space on a shared host is typically cheaper than a VPS, and both are subscription services on a monthly or annual basis (discounts may be available for longer leases.

We advise that you trial run any service for a short-term before committing to a longer period).

Existing hosting

If you are already using a website host, contact your provider to determine whether they support the packages and libraries required by CiviCRM. If they do not, there are two options available to you:

Migrate to another host.

Depending on the CMS you are using, the process of moving from one host to another may be fairly straightforward. You are in a good position to transfer to another host if you can: 

request that your users stop creating and updating content during the migration,

export and import all of the content from/to the chosen CMS,

edit your DNS records to switch the 'pointers' to your website from the old host to the new host

Run the website and CiviCRM in parallel, on different servers.

If you cannot move your website to a different host, you could purchase a second account on a host capable of running CiviCRM, and run the two systems alongside each other.

In this instance, you would use a CNAME DNS record to point to a second copy of the CMS and CiviCRM on the other host (e.g. civicrm.yourwebsite.com; the CNAME effectively adds a prefix to your website's address), and link to it from your website, perhaps in form of a log-in button.

Aside from paying a second bill, one of the limitations to this approach is the need to clone the style of your website on the second host to give the visitor the illusion that they are in the same place. If changes to the style are changed, the work must be duplicated.

Outsourcing to a CiviCRM implementer/host

There are implementers and experts in the CiviCRM community able to manage the hosting and/or installation for you. If requested, they may also be available to manage a local implementation and configuration on your premises.

For a list of experts recommended within the community, visit: https://civicrm.org/providers

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 such a 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:

the people who will be involved in the project

what the business goals of using CiviCRM are

how you will approach the initial development

what ongoing support you will need

the costs associated with hosting and your IT infrastructure

training and documentation

change management

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 front-line staff.

You'll be exploring new territory with your CiviCRM installation and this can sometimes be stressful. It might be helpful to share this project's management 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 underestimate 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 increase donations by 25% 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 wants 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, WordPress 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:

keeping your site up-to-date with security patches

upgrading to the latest version of CiviCRM (not necessary, but CiviCRM is improving all the time and your users will thank you for the improved usability and functionality each time you upgrade)

upgrading the CMS

hosting

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.

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

Before exploring the installation of CiviCRM, ensure you have read the chapter 'hosting' to confirm whether or not your host can support it.

CiviCRM must be installed on a computer that has been configured with a web server (such as Apache or ngnx), 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 prerequisites 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 which CMS (Content Management System; used for building and managing websites) you wish to integrate with, choosing between the open-source options: Drupal, Wordpress or Joomla!.

You can find full instructions on installing CiviCRM here:
http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

Internet vs. local installs

Most organisations access CiviCRM over the internet. However, some organizations who only want internal staff to have access to CiviCRM and are security conscious, choose to install CiviCRM on an internal network and have it only accessible internally.  The downside to an install that is not publicly available is that your contacts cannot 'self serve' to update their data.

Upgrades

New versions of CiviCRM are released approximately twice a year (once in the Spring and once in the Autumn).  You will need to apply upgrades to your CiviCRM site periodically if you want to take advantage of new features and improvements, and also to keep your site secure. 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.

Since upgrades are an important and technical process, many organisations employ the services of a CiviCRM expert service provider to carry them out.

Configuration

Once CiviCRM has been installed, you should review the initial configuration tasks which allow you to customize CiviCRM for your organization.

Log in to your CiviCRM site and navigate to Administer > Administration Console > Configuration Checklist. This section will cover the general tasks, while component-specific configuration will be covered in each component section. 

Use this checklist to review and complete configuration tasks for your site. You will be redirected back to this checklist after saving each setting. Settings which you have not yet reviewed will be displayed in red. After you have visited a page, the links will display in green (although you may still need to revisit the page to complete or update the settings).

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 and translations are available to download when you download CiviCRM. These translations are contributed by community members. If CiviCRM is not available in your language, you may wish to consider translating it.  You can find a translation guide on the wiki.

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.

For more info, have a look here:
http://wiki.civicrm.org/confluence/display/CRMDOC/i18n+Administrator%27s+Guide

Under Localization you will also find the Advanced Date Input Settings. By default, CiviCRM provides ranges for input on specific date fields. For instance, the default range for Activity Dates are 20 years prior to the current year all the way through to 10 years beyond the current year. If you would like to track activities that have occurred, say, 25 years ago then you would need to update this range to enable your end users to log these activities. To update these settings to the appropriate range go to Administer > Localization > Date Formats > Advanced Date Input Settings. If you were to leave these settings as the default you will see an error such as this:

Organization Address and Contact Info

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.

Enable components

This is where you can turn on or turn off the components for your CiviCRM system. 

When you first install CiviCRM the most frequently used components (CiviContribute, CiviEvent, CiviMail, CiviMember, CiviReport) are already enabled. If you do not need those components you can disable them. You can also enable any or all of CiviCampaign, CiviCase, CiviGrant and CiviPledge. You can revisit this page at any time to enable more components.

You can also disable a component you have already used. The information in the component is retained and will still be there if you re-enable it.  It would be unusual to disable a component you have already used.  If you want to simplify the administration menu and advanced search page then a better approach may be to use permissions (see the Permissions and access control chapter).

Display Preferences

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

Viewing Contacts - Controls the tabs displayed when viewing a contact record. EXAMPLE: If your organization does not keep track of Relationships, deselect this option to simplify the screen display. Tabs for Contributions, Pledges, Memberships, Events, Grants and Cases are also hidden if the corresponding component is not enabled.

Editing Contacts - Controls the sections included when adding or editing a contact record. EXAMPLE: If your organization does not record Gender and Birth Date for individuals, then simplify the form by deselecting Demographics.

Contact Search - Controls the sections included in the Advanced Search form. EXAMPLE: If you don't track Relationships, you will not search for that section. Simplify the form by deselecting this option.

Contact Dashboard - Allows your constituents to view the groups they are subscribed to, their contribution history, event registration information and more. You can control the sections that should be included in the dashboard here. EXAMPLE: If you don't want constituents to view their own contribution history, deselect that option.

WYSIWYG Editor - The editor provided to users to enter text in fields that allow HTML formatting (such as the introductory section for your online contribution pages). You can choose either CKEditor or TinyMCE. It's a good idea to try out both and see which is more comfortable for you and your users.

Individual Display Name - Display name format for individual contact display names.

Individual Sort Name - Sort Name format for individual contact sort names.

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.

Mailing Labels - Controls formatting of mailing labels here. The default format is:
{contact.addressee}
{contact.street_address}
{contact.supplemental_address_1}
{contact.supplemental_address_2}
{contact.city}{, }{contact.state_province}{ }{contact.postal_code}{contact.country}
You must include the {contact.addressee} token here in order to include the name of the addressee in your labels. Users will be able to select from a variety of label types corresponding to the label manufacturer code when they generate the labels from a list of contacts. It's a good idea to test your format with the type of label and printer you plan on using to verify spacing.

Address Display - Controls the layout of contact and event location addresses displayed on CiviCRM screens. The default format is:
{contact.address_name}
{contact.street_address}
{contact.supplemental_address_1}
{contact.supplemental_address_2}
{contact.city}{, }{contact.state_province}{ }{contact.postal_code}{contact.country}

This format applies to event locations, despite the use of the contact record type in the layout. The {contact.address_name} token is particularly useful for events where you need to include a location name (e.g. "Smithson Hall").

Address Editing Fields - Modify the available address editing fields here. You can hide fields that you don't plan on using in order to simplify the forms. EXAMPLE: If you don't plan on recording latitude and longitude for contacts, you can deselect those field.

Street Address Parsing - CiviCRM uses the US Postal Service's (USPS) Postal Addressing Standards to parse an address into fields to hold the address elements: Street Number, Street Name, and Apt/Unit/Suite. It's best \to enter address information that conforms to the Postal Addressing Standards, not only for consistency in your data, but also to best take advantage of the the Street Address Parsing function. You can edit and or view the parsed address by clicking on Edit Address Elements next to the Street Address field of the Address Area of the Summary tab when viewing a contact record.  You can learn more about USPS' Postal Addressing Standards at http://pe.usps.com/text/pub28/welcome.htm.

Address Standardization - CiviCRM includes an optional feature for interfacing to the United States Postal Services (USPS) Address Standardization web service. You must register to use the USPS service at https://www.usps.com/business/webtools-address-information.htm. If you are approved, they will provide you with a User ID and the URL for the service. The URL provided by USPS will not be prefixed with "http://". When entering this URL into the CiviCRM settings field, you must prefix it with "http://".

Mapping and Geocoding

CiviCRM includes support for both the Google and OpenStreetMap 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.

You can also select a Geocoding Provider. This can be that same or different form you mapping provider.  Once this service 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").

Automatic Wildcards - By default, when users search for contacts by Name, the Search interface treats the text as if it was surrounded by percent signes. EXAMPLE: Searching for 'ada' will return any contact whose name includes those letters - 'Adams, Janet', 'Nadal, Jorge', etc. Disabling this feature will speed up searches significantly for large databases, but will make users explicitly use wildcard characters ("%" or "_") for partial name searches.

Include Email - By default, when users search contacts by Name, the Search interface also searches for the text in email addresses. Disabling this feature will speed up searches significantly for large databases, but users will need to use the Email search fields (from Advanced Search, Search Builder, or Profiles) to find contacts by email address.

Include Nickname - By default, nicknames are automatically not included when users search by Name. Change this value to Yes if you want nicknames to be included.

Include Alphabetical Pager - If disabled, the alphabetical pager will not be displayed on the search screens. This will improve response time for search results on large datasets.

Include Order By Clause- If disabled, search results will not be ordered. This will improve response time for search results on large datasets significantly.

Default Contact Search Profile - You can select a Profile to override the columns displayed by default in Find Contacts search results.

Smart group cache timeout - Smart groups are basically saved searches. The list of contacts for each smart group is cached in the database in order to avoid running the saved search every time you access a smart group. This field determines the number of minutes to maintain the cache before refreshing it. The default value of 0 means the cache is emptied immediately when any contact is edited or a new one is added. If your contact data changes frequently, you may want to try setting this to a value of 5 minutes (or even longer) to reduce processing load on your server. The drawback of delaying the refreshing of the cache is that old data will still be served up to users for a few minutes after new data is added.

Autocomplete Contact Search - If enabled, selected fields will be displayed in auto-complete dropdown lists and the "Quick Search" box on the navigation menu. The contact name is always included.

Contact Reference Options - Selected fields will be displayed in autocomplete dropdown search results for 'Contact Reference' custom fields. Contact Name is always included. NOTE: You must assign 'access contact reference fields' permission to the anonymous role if you want to use custom contact reference fields in profiles on public pages. For most situations, you should use the 'Limit List to Group' setting when configuring a contact reference field which will be used in public forms to prevent exposing your entire contact list.

Autocomplete Results - This specifies the maximum number of contacts to show at a time when typing in an autocomplete field. The default is 10.

InnoDB Full Text Search - If you are using MySQL 5.6+ you can enable InnoDB full-text search optimizations.

Miscellaneous (Undelete, PDFs, Limts, Logging, reCAPTCHA, etc.)

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

Dashboard Cache Timeout - The number of minutes to cache dashlet content on the dashboard.

Checksum Lifespan - The number of days before a personalized (hashed) link will expire.

Contact Trash and Undelete - If enabled, deleted contacts will be moved to the trash (instead of being destroyed). Users with the proper permission are able to search for the deleted contacts and restore them (or delete them permanently).

Logging - If enabled, all actions performed on non-cache tables will be logged (in the respective log_* tables). By default, these tables will be created in the same database. However you can configure CiviCRM to write logging tables to a different database by editing your site's civicrm.settings.php file. Specify the separate logging database in the CIVICRM_LOGGING_DSN setting. After enabling this feature you can review changes to contact records using the Contact Logging Report. Go to Reports > Reports Listing > Contact Logging Report (Summary).

Attach PDF copy to receipts - If enabled, CiviCRM sends PDF receipt as an attachment during event signup or online contribution.

Path to wkhtmltopdf executable - wkhtmltopdf is an alternative utility for generating PDF's which may provide better performance especially if you are generating a large number of PDF letters or receipts. Your system administrator will need to download and install this utility, and enter the executable path here.

New Version Alerts - If enabled on-screen alerts will be displayed to users with "Administer CiviCRM" permissions when a new version of CiviCRM is available. This setting will only work if the "Version Check & Statistics Reporting" setting is enabled.

Version Checking and Statistics Reporting - This feature automatically checks the availability of a newer stable version of CiviCRM. New version alerts are displayed on the main CiviCRM Administration page. Statistics about your CiviCRM installation are also reported anonymously to the CiviCRM team to assist in prioritizing ongoing development efforts. The following information is gathered: CiviCRM version, versions of PHP, MySQL and framework (Drupal/Joomla!/Wordpress), and default language. Record counts (but no actual data) are also reported. You can set this field to No if you are not comfortable with having this information reported for your site.

Display "empowered by CiviCRM - When enabled, "empowered by CiviCRM" is displayed at the bottom of public forms. This will help increase awareness of CiviCRM.

Maximum Attachments - You can increase or decrease the maximum number of files (documents, images, etc.) that can be attached to emails, activities, and grant records. The default value is 3.

Maximum File Size (in MB) - Maximum size of a file (documents, images, etc.) which can attached to emails or activities. Note that your PHP configuration files, php.ini, should support at least as big a file size as the value specified here.

Allow second-degree relationship permissions - If enabled, contacts with the permission to edit a related contact will inherit that contact's permission to edit other related contacts. This can be used, for example, to let the teacher of a class edited the records for students in that class when they are both linked to the class (set up as an organisation sub-type) via relationships.

reCAPTCHA - reCAPTCHA is a free service that helps prevent automated abuse of your site by requiring users to read a random pair of words and type them into the form. To use reCAPTCHA on public-facing CiviCRM forms, sign up at recaptcha.net, enter the provided public and private reCAPTCHA keys here, then enable reCAPTCHA under the Advanced Settings section in a Profile where you want it used.

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

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

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.

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.

Redirect to Database - If this option is selected, all emails will be recorded as archived mailings instead of being sent out.

See Email System Configuration for more details.

From Email Addresses

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).

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.

Payment Processors

Payment processors are companies that handle credit card transactions for merchants and non-profit organizations and then 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/Payment+Processors

Permissions for anonymous users

This link is only present on Drupal sites.  On Joomla! and WordPress (and Drupal) Sites permissions for anonymous and other users are set after navigating to Administer > Users and Permissions > Permissions > Drupal  (or Joomla or WordPress) Access Control.  See the Permissions and Access Control chapter in this section for information on setting permissions.

System Workflow Templates

CiviCRM comes with a set of system-generated emails, including contribution receipts and event registration confirmations. These are known as system workflow templates, and it's a good idea to review them. They will be sent out with your organization's name on them. You can customize the style and wording of these messages here.

Workflow messages include text 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.

You should now have reviewed all the basic configuration tasks.  The remaining tasks on the checklist involve an understanding of the ways in which you can record and use contact data and are best left until you have read more in this book.

Scheduled jobs

CiviCRM relies on a number of scheduled jobs that are run on a regular basis to keep data up to date and to perform certain tasks.  These jobs must be triggered by a cron that runs regularly on your web hosting server.

Examples of scheduled jobs include:

the membership processing job, which updates membership statuses

the event waiting list job, which invites people on the waiting list to register for events when spaces become available

the CiviMail send and process script which handle the sending and processing of emails (to 

the CiviReport scripts which handle the emailing of reports on a regular basis.

Some jobs need to be run very frequently, for example the email send task tends to be run once every 5 or 10 minutes. Others need to be run less frequency, for example the membership update script may be run just once a day.

There are two ways of configuring scheduled jobs:

via the user interface, which you can configure at Administer > System Settings > Scheduled Jobs and a single consolidated cron job

by configuring multiple cron jobs for specific tasks

 These methods are discussed below.

What is cron?

Cron (think "cronology" or "cronograph") is a time-based automatic scheduler that triggers certain programs to run on your web server.  Generally speaking, cron (also known as 'a cronjob') can be setup in your web hosting control panel or configured by the server administrator in charge of your web hosting.  We recommend choosing web hosting that offers cron as a free service.

Before scheduled jobs configured via the user interface will actually work you will need to configure a web server CRON job.  There are CRON configuration examples found in the Running Command-line Scripts via URL wiki page.

Configuring Scheduled Jobs via the user interface

The user interface for scheduled tasks is designed to make it easy for people to set up scheduled jobs, and avoid having to create or edit a cron job each time you want to make a change to a scheduled job. Most smaller installations should be fine configuring and running scheduled jobs via the user interface. Larger sites should consider creating cron jobs in the normal way for each task. That requires some system administration skills.

The Scheduled Jobs page (Administer > System Settings > Scheduled Jobs) is designed to make it easy to set up scheduled jobs and to monitor when they were last run. It shows a list of all scheduled jobs and you can edit each one and set its frequency (hourly, daily or every time the scheduled job is run - typically this is set as every 5-10 minutes) and also any relevant parameters.

You can find an up to date list of all scheduled jobs and the parameters that can be sent to them on Managing Scheduled Jobs wiki page.

Some jobs perform special data update tasks and are not designed to be run automatically or repeatedly. These are: "Update Greetings and Addressees" and "Set Renewal Reminder Dates". Details about when to run them are provided on the Managing Scheduled Jobs wiki page.  

Manual execution of scheduled jobs

The scheduled jobs page can also be used to run scheduled jobs on a one off basis. This is useful for some of the scheduled jobs that are designed to be run on a less regular basis, including the geo-coding job and the greetings and addressees job. Execute a job manually by by clicking the More > Execute Now link for the given job at Administer > System Settings > Scheduled Jobs. 

Scheduling specific jobs via individual cron tasks

System administrators more commonly talk about scheduled jobs as cron jobs. If you run a lot of scheduled jobs on large data sets you may wish to consider getting an experienced system administrator to set these up using cron.  This will allow more granular control over when and how these jobs are executed, which may be useful if these processes put significant load on your server.

Note scheduled jobs that were run via an individual cron job directly do not automatically appear here. They need to be configured to do so. Details on triggering specific jobs via command-line, URL, Drush and other methods can be found in the Managing Scheduled Jobs wiki page.

Customizing the user interface

CiviCRM is highly flexible and customizable. This chapter gives information on the many ways you can change the interface to suit your needs and make it easier for your users.

How to customize your data itself—what you collect and track—is covered in Organising Your Data and in the What you need to know and Set-up chapters in the sections on the different CiviCRM components (e.g., learn about customizing event types in the Events section).

Changing dropdown options

The options included in the dropdown fields you see on contact entry/editing forms in CiviCRM can be modified (you can add, rename, disable or remove options) from Administer > Customize Data and Screens > Dropdown Options. These include:

Gender

Individual prefixes and suffixes (e.g., Ms., Mr. and Jr., Sr.)

Phone types (e.g. Phone, Mobile, Pager)

Mobile phone providers (e.g. Sprint, Verizon and Cingular)

Instant messenger services (e.g., Yahoo, MSN, AIM, GTalk, Jabber and Skype)

Website types (e.g., Work, Facebook, Twitter)

Location types (e.g., Home, Work, Billing, Main). Note that that Billing location is assigned to Billing Addresses entered when constituents contribute or pay for event and membership fees online. Location type names may not contain spaces (e.g., Summer Home is not permitted; use SummerHome).

The choices in Preferred Communication Methods (e.g., Phone, Email, Postal Mail, SMS) in the contact edit/entry form can also be modified; go to Administer > Communications > Preferred Communications Methods.

Modifying dropdown options that define data—such as Activity Type, Relationship, etc.—is outside the scope of this chapter; see Organising Your Data and the sections on the different CiviCRM components.

Changing display preferences

If there are types of activities you do not track or categories of data you do not collect, you can make it so these fields and tabs don't even show up when your users log into CiviCRM. This can make training and everyday use much easier.

To do this, go to Administer > Customize Data and Screens > Display Preferences.

You can change which tabs are available when you are viewing contact records by checking and un-checking the appropriate boxes next to Viewing Contacts.

For example, if your organization is not using Cases or Grants, you could uncheck those boxes and those tabs would no longer show up in the user interface. If you later decide start using them, simply re-display the tab by checking the box. Information stored in the tabs you hide remains in your database; you can hide tabs you have already used, and when you choose to display them again, all the information will display as it did before.

You can change which blocks of information appear when you are editing a contact by checking and unchecking the appropriate boxes next to Editing Contacts:

For example, if your organization doesn't collect information Demographics or Communication Preferences, you could uncheck those boxes to streamline the editing screen. As with the Viewing Contacts preferences, any information contained in fields you choose not to display remains in your database, and you can choose to display it again at any time by re-checking the boxes in this setting.

Disabling Popup Forms

The CiviCRM user-interface makes extensive use of popup dialog boxes to enable quick viewing and easy editing of data. You can disable this feature and limit the interface to traditional browsing by deselecting the checkbox Enable Popup Forms in administer > customize data and screens > display preferences. Note that CiviCRM will be slower with this feature disabled as every form will require a complete page load in the browser.

Customizing search preferences

You can change CiviCRM's default search behavior at Administer > Customize Data and Screens > Search Preferences. Available options are:

Automatic Wildcard (choose Yes or No): If you choose Yes, wildcards are automatically added to the beginning AND end of the search term when users search for contacts by Name. For example, searching for "ada" will return any contact whose name includes those letters: Adams, Janet; Nadal, Jorge; etc. If disabled, a wildcard is still added, but only to the end of the search term. In this case, searching for "ada" will return any contact whose last name begins with those letters: Adams, Janet' but not Nadal, Jorge.

Include Email (choose Yes or No): If you choose Yes, email addresses will be automatically included when users search by Name.

Include Nickname (choose Yes or No): If you choose Yes, contents of the Nickname field will be automatically included when users search by Name.

Include Alphabetical Pager (choose Yes or No): If you choose Yes, a bar will appear at the top of your search results allowing you to choose a letter of the alphabet. Clicking A, for example, will take you to a page displaying only contacts that begin with A.

 Include Order By Clause (choose Yes or No): If you choose No, your search results will not be ordered.

Autocomplete Contact Search: This is a series of checkboxes for basic contact fields (name, email, phone, etc). The fields that are checked will show up in the autocomplete results list that appears when you use the Quick Search bar at the top left of all screens.

The above Yes/No options are all defaulted to Yes when you first install CiviCRM, with the exception of Include Nickname, which defaults to No. If your database is large and your searches are slow, consider disabling some of these options to increase your speed.

There is one more place to customize search search settings: Administer > Customize Data and Screens > Display Preferences has a block of Contact Search settings:

These check boxes modify the Search > Find Contacts and Search > Advanced Search screens. Uncheck the boxes to remove the corresponding types of fields from your search screens.

Customizing the navigation menu

You can add, delete, rename, and move all items in the CiviCRM navigation bar to better meet the needs of your users. Some things you might want to do are:

Streamline the navigation by removing menu items you don't use

Add items to support specific workflows (e.g., data entry Profiles)

Add links to non-CiviCRM web pages or apps

Rename menu items to use terms for familiar to your users

Move menu items to better support the flow of your work

To customize menu items, go to Administer > Customize Data and Screens > Navigation Menu. You will see a file structure containing all of your menu items, with the items represented by folder icons. Expand folders by clicking the small triangles to the left of their names.

To delete an item, right-click it and select Delete.

To rename an item, right-click it and select Rename.

To move an item, drag and drop it to the desired location in the tree structure.

To add an item:

Click on the Add Menu Item button.

Enter the text you want to appear in the menu in the Title field.

Enter the link to your item in the Url field.

Select the location of your new item from the Parent dropdown menu. You can place the item anywhere in the navigation, at any level. If you want your new item to be in the top level of the navigation, do not select anything from this dropdown.

Check the Separator box if you want to add a line below your new item to separate it form the item below.

Making custom data entry forms

If you have staff or volunteers who are often entering batches of similar contacts manually, you can create a tool called a Profile with only the fields they need. This can speed up data entry considerably.

Go to Administer > Customize Data and Screens > Profiles and click Add Profile.

Give your Profile a clear name that relates to its purpose (e.g., Name and Address Data Entry Form)

Check the Standalone Form or Directory box in the Used For field. 

Use the Pre-form Help and Post-form Help fields to add any text you'd like to display to hose doing data entry.

Click Save; this takes you to the Add Fields screen so you can choose which fields to put in your Profile.

From the Field Name dropdown menu, select the contact record type where your desired field is found. This will be Contact, Individual, Organization, Household, or any custom contact subtypes you may have created. (The other record types available on this menu will not work with data entry forms, so do not choose them.) It's important to note that any field applying to more than one kind of contact record type (such as Phone or Email, which applies to both Individuals and Organizations) will be found on the Contacts menu.

Once you have chosen a contact type, another dropdown menu will appear listing the available fields. Choose your desired fields.

If the text that appears automatically in the Field Label field is not what you would like to appear on the form, edit it.

If every record entered through this form must have data in this field, check the Required? box.

Use the Field Pre Help and Field Post Help fields to add any text you'd like to display to those doing data entry.

You can use the Order field to change the order in which fields are displayed on the form. Lower numbers are displayed ahead of higher numbers.

Click on Save and New to add more fields, and Save when are finished.

You'll be taken to a screen listing all your fields and their settings. Click Preview (all fields) to make sure your form looks the way you want it to. Click Use (create mode) to go to the page containing your form. Copy the link and use it to create a navigation menu item (see the previous section for instructions).

Customizing search views

To do this:

Create or open a profile and mark it as used for Search Views (known as Search Results in 4.1 and previous):

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 (see image below).

Using Word Replacement to change terminology

CiviCRM has a Word Replacement setting that lets you replace existing text found in the system with your desired text. For example, if your organization does not typically refer to monetary transactions as "contributions," but prefers to use the term "donations," you can define a word replacement and have it automatically altered throughout your instance of CiviCRM.

To use Word Replacement:

Go to Administer > Customize Data and Screens > Word Replacements.

Enter the original text in the Original column on the left, and the replacement text in the Replacement column on the right.

Check the Exact Match box on the right to replace only instances of the word or phrase that match exactly. For example, if Exact Match is not checked checked, replacing "Contribution" with "Donation" would also replace "Contributions" with "Donations"; if it is checked, this would not happen.

Check the Enabled box to the left to replacement of the word or phrase. 

You can add additional rows using the Add row button.

Click Save when you are finished entering replacements.

When using this function, be sure to anticipate alternate forms of words and different ways your chosen word or phrase may appear in CiviCRM.

Permissions and access control

Permissions (and the related concept of access control lists, or ACLs) are collections of rules which define access to various areas of the system. In essence, you create roles for your site, give these roles permissions to do certain things, and assign the roles to certain people.

Permissions and ACLs allow you to grant access to:

Different areas of CiviCRM (e.g. CiviContribute, CiviCase and CiviMail) to reflect the tasks the user is responsible for

Entities within the system (like contacts, contributions, etc.), and how the user can interact or operate with them (e.g. view, edit, delete)

Since permissions define who can see and do what on your site, it is important, from a security perspective, that you understand them well. It is very easy to check a permissions box without fully understanding what it does. A site with badly configured permissions may inadvertently expose your contacts' data.

The difference between CMS permissions and CiviCRM ACLs

Permissions and ACLs are defined in two separate places: in the content management system (CMS) and in CiviCRM itself. Many organisations are able to do what they need to do with just CMS permissioning. Others need to use CiviCRM ACLs to provide more fine grained access control.

CMS permissions allow you to grant (or not grant) access to entire sections of CiviCRM to user roles, such as CiviMail, CiviEvent, etc. They also allow you to restrict the user's ability to view, edit, add and delete records such as contacts, events and contributions. However, this is an 'all or nothing' approach: you cannot differentiate between contacts who fall into different groups, for instance.

Native CiviCRM ACLs give more fine grained control, so, for example, you can limit access to view, edit, create, delete and search to :

groups of contacts

a profile (this is a collection of existing and/or custom fields, see "Profiles")

a set of custom fields

events (e.g. a user may access one event, but not others)

As a general rule, you should probably start with CMS permissions and if you can't do what you need to with these, look at using CiviCRM to enforce more granular access rights. 

To clarify, here are two of examples of times when CiviCRM ACLs should be used instead of those in Drupal, Joomla! or WordPress:

An organisation has a head office, and three regional offices spread across the country. The event director working from the central office must be able to view all events across every office, but the event coordinators reporting to the director and local to each regional office are only to have access to view and edit their own events. Since a CMS access control list would only be able to restrict access to view/edit/add/delete all or no events, a CiviCRM ACL must be used.

Two sets of custom fields have been built, one for a team of employees working in Paris managing a group of volunteers, and the other collecting donor information in London. Each team should only be able to access data held in their own set of custom fields, however, a CMS access control list could only give them access to all of the custom information, or none of it. In this case any CMS rule controlling access to custom fields should be disabled, and a CiviCRM ACL used instead.

CMS permissions

All CMS have the same set of CiviCRM permissions, but each are found in different places, and differ slightly in appearance.

Permissions in Drupal 

To access Drupal's permissions, go to the Drupal menu, choose the option People and click the Permissions tab in the top right corner of the pop-up window. Here you will find a long list of all possible operations/actions a user could perform in CiviCRM and Drupal, with columns for each existing role type. Checking an option in one of the columns will grant that role the ability to perform the action.

You may create new roles and edit all existing ones. To edit roles, while in the Permissions tab click the button Roles toward the top right of the page.

Roles can be assigned to users in the following ways:

Open a user's contact record (a contact in CiviCRM with a user account), hit the Actions button at the top and select User Record from the menu. When the next screen appears, click the Edit tab (top right) and then scroll down to the section titled Roles; here you may change their level of access.

As an administrator, go to the Drupal menu and select the option People. When the list of active users appears, click on the desired name to open their Drupal user profile, go to the Edit tab at the top-right of the page, and then scroll down to the Roles section.

Permissions in Joomla! 

Permissions in Joomla! can be found as follows:

Log into the Joomla! administrative portal

Go to the Components menu and select CiviCRM from the list

In CiviCRM's menu, navigate to Administer > User and Permissions > Permissions (Access Control)

Click the option Joomla Access Control at the top of the list

Joomla! has a different method of assigning permissions, in that each user group (role) is either a parent or child to another user group, where child user groups (those lower in the table) inherit the permissions set for those above them. Therefore, when editing the permissions assigned to a user group in the table, you may choose between:

Inherited: if the user group above was given this permission, it will also be able to perform the given action

Allowed: users in this user group are allowed to perform the operation

Denied: users in this user group cannot perform the action

Note that Joomla! has two additional permissions not used by Drupal or Wordpress: Configure Joomla! ACL (user can configure Joomla! ACLs and is assigned all CiviCRM permissions)  and Show CiviCRM Component (user can see CiviCRM in the Components list). 

Finally, to assign one of these user groups to a user, or change their existing user group, ensure you are logged in as an administrator then do one of the following:

Go to the user's contact record in CiviCRM, click the Action button and select the option User Record. A section called Assigned User Groups will be available to change roles.

Within the Joomla! administrative portal, under the User menu click User Manager. All available users will be listed, and clicking on a name will open a screen with the option to change their account settings, including user group.

Access Control (Permissions) in Wordpress

In CiviCRM go to Administer > User and Permissions > Permissions (Access Control). Select the Wordpress Access Control link. Here you can adjust the CiviCRM settings for each of the predefined User Roles from Wordpress.

Roles can be assigned to users in the following ways:

Open a user's contact record (a contact in CiviCRM with a user account), hit the Actions button at the top and select User Record from the menu. This will open the Edit User screen where you can change their Role to change their level of access.

Within the WordPress Site Admin area, select the Users menu item to see a list of all users. Clicking on a name will open the Edit User screen where you can change their Role to change their level of access.

Anonymous and Authenticated roles

You will encounter both these role types as you work with the access controls. Although they may be named differently on different CMSes, the basic principle is the same.

The anonymous role (public in Joomla!) applies to all visitors to the website who have not logged in. This role will have the lowest level of permissions.  The default CiviCRM permissions for this role are:

make online contributions/donations

view event information

register for events through online forms

vew event  participants

subscribe and unsubscribe from mailing lists 

access all custom data (ie see/enter information in custom data fields in forms)

access uploaded files ( ie view/print content of uploaded files)

view, create and edit profiles ( or profile listings and forms)

The authenticated role (registered in Joomla, subscriber in WordPress) is applied to all visitors to the site that have logged in . This is the default role for all new user accounts, and cannot be deleted.  By default CiviCRM permissions for this role are the same as those for the anonymous role. 

You can alter the permissions for anonymous and authenticated users if you need to as the following common scenarios show.

Taking online contributions

If you only want contributions from logged in  users you would remove the make online contributions permission from the "anonymous" or "public" role.

Viewing event info and registering for events

If "view event info" and "register for events" are enabled for the anonymous and authenticated roles then all visitors to your site will  be able to register for any event. If you wish to give only specific users the ability to view or register for some events, you must use a CiviCRM ACL, allowing a role "view" access to events if they should only be able to view event information, and the "edit" permission if they can register. However for this to function, the CMS "register for events" ACL must be disabled, as it will override these settings.

e.g. A charity holds occasional fundraising events for the public and separate evening dinners for some of its corporate donors. Any visitor to the website can register and participate in a fundraising event, however the dinners are private and must only be available to some of their donors. In this instance, CiviCRM ACLs should be used instead of the CMS rule "register for events" as they can specify the specific events each group of users can access.

Editing profile data in online forms

Profiles are collections of default and custom fields, and can be used in online forms to collect additional information from visitors, or build searchable directories (see "Profiles").

If you have a standalone profile in an online form used to search for and edit data in CiviCRM (e.g. not part of an event registration page), only authenticated users may edit. The permission "profile edit" can be given to the anonymous role, but visitors who are not logged in will still be unable to edit the data unless they have a checksum (a unique URL to one page where they may edit their own data; read "Everyday tasks" in the email section for more information). For checksum tokens to work, anonymous users must have the "profile edit" permission.

Collecting data from anonymous visitors using profiles 

If you have built profiles to collect data from anonymous visitors through online forms (e.g. event registration pages, contribution pages and standalone profile forms), the permission "profile create" will need to be given to the "anonymous" role. Furthermore, should the profile contain any custom fields, an additional permission will need to be given, depending on the circumstances. Read "Accessing custom data" below. 

Creating searchable directories for the public 

Profiles can be used to build searchable directories; a form of search criteria able to gather a list of results from the database (e.g. finding organisations held in the database by location). If you would like to give a group of users access to search pages published on the website, check the "profile listings" option for that role/user group.

Profile view

Where profiles have been embedded within online pages (e.g. to display an organisation's name, description and contact details from the database), the visitor must have the permission"profile view" to see it.

Using the "Profile listings and forms" permission

This access right should be assigned with care, and only to trusted roles. The permission grants access to:

Add data through profiles in online forms

Edit data displayed in standalone profiles on public pages, if the option is given (e.g. contact information)

Use public searchable directories

Where possible, each of these access rights should be assigned to a role separately, not through this 'allow all actions' permission. "Profile listings and forms" is not enabled for the "anonymous" and "authenticated" roles by default.

Note that if this role were given to anonymous users, in order to edit data, the visitor must either be logged in or using a checksum token (see "Everyday tasks" in the section on email).

Accessing custom data

If custom data fields have been used on an online form or within profiles, the user will not be able to interact with it unless they have been given permission to view and/or edit custom data. There are two ways of assigning this ability:

Enable the "access all custom data" permission against the roles you wish to give both view and edit access. If this were given to the "anonymous" role, for example, they would be able to view and edit all custom fields in online forms (e.g. custom data fields within a profile that has been incorporated into an event registration page). However, this is an 'all or nothing' approach.

Alternatively, CiviCRM ACLs can be created to give roles access to only specific sets of custom data fields. Use this option when you want to give groups of users access to different sets of data, e.g. a team in Amsterdam may only have access to custom volunteer fields, while the head office in Scotland has access access to both custom volunteer fields and custom donor fields. Note that these ACLs will not function if the "access all custom data" permission is used in the CMS; that permission in Drupal or Joomla! will override these settings in CiviCRM.

Accessing uploaded files

Enable the "access uploaded files" permission for any role that needs to view images, photos and files attached to CiviCRM records and pages. Be sure to assign this permission to the "anonymous" role if you want visitors to see photos attached to contact records, personal campaign pages, documents intended for public consumption, etc.

Giving users the ability to view their contact dashboard

You can provide authenticated (logged in) users with access to a screen where they can review the mailing groups they have subscribed to, their contributions, memberships and event registrations (where applicable). Assign the "access contact dashboard" permission to roles whose users are to be given access to this feature. Do not enable this for the "anonymous"  role.

Other CMS Roles

Each CMS also has other predefined roles giving varying amounts of access to CiviCRM.  Again you can change the permissions granted to these roles but you must make sure that there is always one role (Administrator/Super Users/Admin) that has the ability to administer CiviCRM including managing access control.

You may also want to add additional roles to to allow for very graduated access to CiviCRM functionality. 

More information on CiviCRM permissions (access control options) including permissions required to perform certain back office functions can be found at  http://wiki.civicrm.org/confluence/display/CRMDOC/Default+Permissions+and+Roles. 

Native CiviCRM ACLs

As discussed earlier, CiviCRM ACLs are a more advanced and granular way of managing user access to records through contact groups, assigned to ACL roles. While an access control in the CMS can 'turn off' visibility of entire sections of CiviCRM, and determine whether a user can view/edit/delete/create data in the different areas of the system, they cannot sub-divide these rules into access to different record types. For example:

A charity based in Chicago has three regional offices, and needs to give its fundraising staff the ability to create and edit contact records for prospective donors. They have decided that the fundraising department in each office can only have access to its local contacts. While the permission "add contacts" can be granted to authenticated users in the CMS (Drupal, Joomla! or WordPress), if "view all contacts" and "edit all contacts" were also assigned in this way, there would be no way to differentiate between the three groups of donors (locations). This could only be achieved with a CiviCRM ACL.

To begin, go to Administer > User and Permissions > Permissions (Access Control). This screen will link you to the CMS access control list, and the three steps to managing those native to CiviCRM.

Manage Roles

This is where you can create ACL roles. By default you will have "administrator" and "authenticated" (logged in), but only the administrator role may be edited; "authenticated" is a reserved role and core to the system.

Clicking "Add Acl Role" will present a screen for creating a new role with the following options:

Label: this is the name of the role, and will be visible to users

Description: create and format a description of the role

Weight: give the role a number to determine its place in the list (e.g. "1" places the role at the top, while "20" might send it to the bottom; lower numbers appear before higher ones)

Enabled?: is the role active or not? If you disable this option, functionality may cease to work for some users 

Assign Users to CiviCRM ACL Roles 

Once the roles are configured, you can begin to assign them to users. In CiviCRM this is done in two steps:

First create an access control group for a selection of users that are to have the same level of access. There are multiple ways to do this, outlined in the chapter "Groups and tags".

The ACL contact group can now be assigned to a role. Click the second step on the access control menu screen ("Assign Users to CiviCRM ACL Roles") and hit "Add Role Assignment". Complete the following:

ACL Role: select an available ACL role

Assigned To: choose a contact group to assign to the role

Enabled?: is this assignment active or not?

Manage ACLs 

The third step is where the ACLs are finally created. They can be broken down into the following questions:

Which role will have permission to perform this action?

What is the action/operation? Is it the ability to view/edit/delete/create, etc?

Which set of data can the action be carried out on?

To begin creating these ACLs, return to the Access Control screen (Administer > User and Permissions > Permissions...) and click "manage ACLs". A list of existing controls will be displayed, likely including one for administrators giving them permission to edit all contacts in the database. To add a new one, click "Add ACL" and fill in the following:

Description: write a clear description of what the ACL does

Role: choose a role to assign the ACL to from the drop-down list

Operation: select the action this role is allowed to perform (e.g. view, edit, create, delete...)

Type of Data: choose the data type the operation relates to:

A group of contacts

A profile

A set of custom fields

Events

Group/profile/custom data/event: this is where you select the specific group of contacts, profile, custom data set of event

Enabled?: is the ACL active?

Security  

CiviCRM is a web based solution, and as such, requires a web server to run. When web servers store sensitive data and are publicly available over the Internet - as CiviCRM is designed to be - security is an important aspect to consider. The recommended approach to securing CRM data is to use a VPN (Virtual Private Network) to encapsulate data transferred over public networks in encrypted packets. One of the simplest methods of implementing this is through forcing the use of encrypted tunnels when accessing the server through various data protocols (e.g. SSH, SSL and FTPS, explored below); this effectively wraps and the data in a protective shell, which can only be opened by the user's web browser, and the server. 

Encrypted data transfer

There are a number of different protocols (methods) for transferring data from one point to another.

FTPS: for uploading files to the server outside of the CiviCRM interface (admins only), you may wish to use a FTPS (Secure File Transfer Protocol) client. If possible, set up FTPS accounts with usernames and passwords.

SSH: the SSH (Secure Shell) is a method which can be used to authenticate a user - by password or a key - and tunnel them into the server to execute command-line instructions. 

SSL: this affects your everyday users accessing CiviCRM through a web browser. SSL (Secure Sockets Layer) encrypts the data submitted on a page by a user and sends it to the server - the only entity holding the 'key' to decrypt the data, and vice versa. SSL may be required for PCI compliance, or simply to prevent the interception of sensitive information during transit. By default, CiviCRM is not secured for browser access, please read the section 'Setting up SSL' for configuration instructions.

Note: ensure passwords used by one person across several protocols are different, as each carry with it varying levels of control.

Should I use SSL (Secure Sockets Layer)?   

PCI compliance

American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa Inc. work together to form standards for online payment processing (see https://www.pcisecuritystandards.org/organization_info/index.php).

Hosting for websites that accept payments using CiviContribute and CiviEvent should comply with their standards if the plug-in you are using does not route the user to external pages for payment processing (e.g. PayPal Standard redirects users to PayPal pages to make the transaction before returning to your website, and should therefore meet these standards). If credit card information is being processed or stored on your server, there are a number of PCI Payment Application Data Security Standards (PCI PA-DSS) which must be met, including the need to use SSL. Each CiviCRM installation must also be tested for PCI compliance every 4-12 months. Consider the payment processing method you intend to use carefully before implementing it, use SSL if you are using a credit card payment processor, and seek security consultation if you decide to store credit card information on your server (this is not recommended).

For further information, see: https://www.pcisecuritystandards.org/merchants/index.php.

Unauthorised data access

Aside from the potential need to meet PCI compliance, you should use SSL if you wish to ensure:

your data cannot be read by unauthorised users (e.g. through intercepting un-encrypted data during transit between the user and server).

a user's session is not hi-jacked through acquiring the cookie used to authenticate their access. If this occurs, an unauthorised individual could assume their identity and proceed to use the system through their account.

Setting up SSL

Before choosing a hosting company or web server provider, check that they support SSL certificates. As explained above, SSL encrypts the data transferred between a user's web browser and the server, but this is not enabled upon installation as it requires the purchase of an SSL certificate from a trusted vendor. To install SSL:

Determine what your server requirements or procedures are for enabling an SSL certificate. On shared servers this may require purchasing a static IP from your host. Important: your host must be willing to install the certificate on your domain, not one at a higher level. CiviCRM does not support shared SSL.

Purchase an SSL certificate from a security vendor.

Install the SSL on your server following the procedure you learned in step 1.

Enable 'HTTPS' redirection on your CiviCRM site so that the login, online contribution, member, event and administrator pages use SSL encryption. CiviCRM has an option in global settings to check the certificate and enable SSL for these pages (Administer > System Settings > Resource URLs). To use SSL for all CiviCRM pages, either edit the server's apache .htaccess file to force SSL and redirect HTTP requests to HTTPS, or enable the option in Drupal.

Backups and their security

All computer systems are prone to failures - both hardware and software. It is advisable to create periodic backups of all existing data (and possibly the software) to fulfil two important purposes: recovery and retention. In regards to recovery, the organisation can ensure that the data gathered and stored in its database is not lost in the event of failure. Backups can also aid in the strengthening of service continuity. In some situations it is essential that data gathering or analysis operations do not cease, and the ability to build a working tool from a backup (while the issue is being addressed) minimises downtime. Conversely, retention is useful when the organisation needs to check the state of data gathered at a given time in the past.

Once made, the backups themselves must also be secured from natural disasters, fire, vandalism and theft. It is good practice to encrypt backups and duplicate them, keeping one copy on premises, and sending the other to storage at another external location. 

Data storage jurisdiction

CiviCRM can be run on a web server managed by your organisation, or by an external hosting provider.  When working with issues related to human rights, or if your organisation is gathering sensitive information about a country's government or its officials, it may be important to know where your data is stored. Consider gathering detailed information about where the servers are physically located, and the country whose jurisdiction the data will fall under in case a governmental agency requests information.

Other security concerns

Data may be successfully accessed by unauthorised individuals through a variety of methods, many of which do not directly relate to the CRM's security. Amongst others, the following are areas that should be examined:

Physical access to the server: the building holding the servers should be adequately protected against break-in.

Passwords: an organisational policy should be implemented where passwords are of a sufficient complexity and length (e.g. minimum 8 characters, including letters and numbers), and must not be shared or divulged over insecure communications like email.

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. The correct configuration of your email system is crucial to keep your server off spam lists and black lists.

See the Email sections chapter on Set up for tasks necessary to set up the sending of messages once these email system configuration 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 CiviMAIL 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 but you can find community contributed instructions on the CiviCRM documentation ciki.(http://wiki.civicrm.org/confluence/display/CRMDOC/CiviMail+Installation).

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 we are going to use cron to trigger CiviCRM's Scheduled Jobs to ensure your scheduled mailings are sent.

Configuring outbound email service

Outbound email settings are configured at: Administer > System Settings > Outbound Email (SMTP/Sendmail). The choices here are:

mail().  This is the default option and if it works for you, you should use it.

SMTP.  If you have a dedicated external mail server, specify its details here. Bounce messages generated with SMTP are slightly more complete than the ones from mail(), but there is no practical benefit to using SMTP if you can use mail().

Sendmail.  This option is kept for compatibility with older CiviCRM versions.

Disable Outbound Email. Works as expected.

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:

The "Received: from" header should correspond to your mail server and be properly configured.  It might contain information about your hosting provider instead of your domain name. This is not a problem as long as the mail server is properly configured.  If you have a dedicated IP address for your server, you should try to configure a reverse DNS that represents your organization instead of the default name.

The "Received-SPF" header should list "pass" or "neutral".  Sender Policy Framework is described later in more detail.

Sending mass mailing is resource intensive.  We don't recommend sending email messages from budget hosting providers.  The time you will spend troubleshooting will often cost more than upgrading to a more professional host.  Check with your hosting provider to find out whether they limit the number of email messages you can send and whether they run PHP in safe mode.

Some of your recipients' mail servers use DNS based blacklisting services (DNSBL) which keep a blacklist of IP addresses likley to send spam.  Mail from these servers will be flagged as spam and not reach its intended destination.  If your server is blacklisted (for instance, because enough of your recipients flagged your email as spam, or because another website on your server has been flagged as spam), you will need to contact the organizations that have blacklisted you and convince them to remove you from their list.

They are several websites that help you testing whether you are in a DNSBL. A web search for "blacklisting email" will turn some up. Test regularly to find whether you are on a blacklist.

Configuring Sender Policy Framework (SPF)

By default, the Internet allows any mail server to send any email claiming to be from anyone. This makes it easy for spammers to forge addresses and send spam using your email address (or any other). SPF allows you to create a special DNS record listing the IP addresses of the mail servers that can legitimately send email from @yourdomain.org.

If your domain name already has an SPF record, make sure that it includes the IP address of your CiviCRM mail server (which might be a different from the host used for the web server or from your mail servers), and if it doesn't, add this IP address.

If you don't have an SPF record, consider adding one. You will need to add at least your mail server and CiviCRM server (if they are different) to the SPF record.

You can read more about SPF at http://www.openspf.org.

Configuring inbound email processing

This section explains configuration for bounce processing and auto filing incoming emails. Configuring Scheduled Jobs to do the actual bounce processing is discussed later in this chapter.

Bounce processing 

CiviCRM can automatically receive the bounced email notification and, based on the type of bounce reported by the recipient's server, flag your contacts accordingly. To accomplish this you will need to set up an email mailbox to receive bounced email messages and a schedule the Bounces Fetcher job that will periodically read this mailbox and update your contacts in civicrm.

The bounce email address is an "invisible" email address visible only in the email message's envelope (hidden fields that precede the headers and message added by the user). Choose any name you like that is meaningful to you. In this example we have chosen return, so the email address we need to set up on a mail server for example.org is return@example.org.

For each email sent via CiviMail's mass mailing feature, a new unique "invisible" sender address is created using the variable envelope return path or VERP. When CiviCRM receives a bounce, it looks at the invisible sender address to decide which email bounced. 

CiviCRM then looks a the bounce pattern and type to decide what action to take. Bounce types fall into two basic categories: permanent failures (hard bounce) and transient failure (soft bounce). A single permanent failure triggers CiviCRM to set the contact's email as on hold. For transient failures, CiviCRM waits for several bounces before setting the contact's email on hold.

The specific threshold for each bounce type can be found in the civcirm_mailing_bounce_pattern and civicrm_mailing_bounce_type. Multiple different bounce reply patterns are linked to a given type and threshold. 

Email-to-Activity processing

CiviCRM can automatically retrieve email from a specified inbox and file it as an email activity against contacts corresponding to sender and recipients of the email. New contacts are created for emails not already in the database.

There are two ways to do this (either or both ways can be setup at same time):

Special email address: Set up a special email address for your organization, e.g. civiemails@example.com. Users can then add this address in the Bcc field for your outbound emails; they will get auto filed in CiviCRM as described above. No one who receives the email will see this special address if the Bcc field is used. 

IMAP Folder: Set up a folder in your IMAP Inbox where you can drag emails that you want filed in CiviCRM.  This works with both inbound and outbound emails. (this requires that your email be set up using IMAP.) 

Special email address for incoming email

There are several ways of configuring your incoming mailbox:

Sub-addressing: Your mail service might allow you to append a +tag or  -tag qualifier to your e-mail address (e.g., return+test@example.org). Several mail servers, including Gmail, Yahoo! and Postfix provide this sub-addressing by default.

Try to send yourself an email, adding a +tag or -tag. If you received the mail you sent with a tag, it means that you can directly use the mailbox you created (return@example.org  in our example)  as the VERP.

"Catch-all" account: If sub-addressing doesn't work on your mail server, you need to define the mail account you created (return@example.org) as the "catch-all" account. Every mail sent to an address that isn't a real mail account will end up there, including all the bounced email messages.

External address: If neither of the preceding methods works, consider creating a new account on a service such as Gmail and use it to receive the bounced emails. You will have to set filters in this account so it doesn't discard as spam all the bounced email it will receive.

Adding an incoming email account for processing bounces and/or email-to-activities

Once you have created your email account to receive bounces or emails for auto filing, you need to set up CiviMail so it knows how to read it: Administer > CiviMail > Mail accounts as the default email address.

Specify the mail server, username, and password you used when creating the account.

The local part is optional and only relevant if you were able to set up an account using sub-addressing. It should be the account you created with '+' or '-' appended , e.g., "return+" or "return-".

The email domain is the domain of your email address (example.org).

You can leave the return path empty.

If your mail server supports it, specify IMAP protocol and check SLL, otherwise use POP.

You can specify an IMAP folder in the source field using the syntax INBOX.CiviMail. Note: Some exchange servers may not be configured in a compatible way. In that case, you can configure a script like fetchmail and use Maildir.

In the Used for? field you can choose whether you want to use the email account for Bounce Processing or Email-to-Activity Processing (or Auto filing). You can have multiple accounts specified for auto filing but only one for bounce processing. This will be marked as default.

Once the Bounce Processing mailbox is configured, you will need to configure CiviMail to empty it, read all these bounced messages and identify the related bounced contacts. This is performed by the Scheduled Jobs feature of CiviCRM .

We recommend testing the bounce process by running the process manually before setting up CiviCRM to process the bounced email messages automatically. This can be done in Administer > System Settings > Scheduled Jobs. Locate Fetch Bounces and select more > Execute Now. Check the Job Log for any error messages.

Once you have verified that CiviCRM can properly handle the bounce, you can set it up to automatically process the replies and bounces on a regular basis.

Scheduling inbound and outbound mail processing

As discussed in the earlier chapter, mail processing and other jobs may be automated through the Scheduled Jobs administrative page, cron or a combination of both. The full range of options is discussed in the Manage Scheduled Jobs wiki page, but below are specific examples for enabling CiviCRM mail processing. 

Scheduling using the Scheduled Jobs administrative page

Mass mailings are generated via the CiviMail web interface and are queued to be sent to their recipients. To schedule the regular processing of this queue and any bounces that are returned go to Administer > System Settings > Scheduled Jobs and find the Fetch Bounces and Send Scheduled Mailings jobs. Edit each in turn, setting their scheduled Frequency to "Hourly", "Daily" or "Every time cron is run". The defaults should be fine for small installations. Then select more > Enable for each.

In this example using the jobs' default frequency and cron configured to run at 15 minute intervals, scheduled mailings would be sent every 15 minutes and bounces would be fetched and processed hourly.

If you need to send some email from CiviCRM right away, without waiting for the cron job, you can trigger the sending process by visiting Administer > System Settings > Scheduled Jobs select more > Execute Now. Use this capability sparingly. It could utilize a lot of server resources and cause CiviCRM to slow down noticeably. The administrative settings for sending email are usually configured to minimize the load on the server, and the scheduling the job is a more efficient way to send mass email.

Scheduling only the mail jobs using the command-line interface

As an alternative on Linux and other Unix or Unix-like systems, individual cron jobs may be used to schedule inbound and outbound mail processing rather than the Scheduled Jobs page. This approach gives experienced system administrators more granular control over these processes by configuring specific cron jobs apart from other scheduled jobs.

The cron job needs to run using an account recognized by your CMS. Create an account dedicated to this task (e.g., mailprocess, civimail, etc), give it a long, secure password (e.g.,seol-lzprm42amv-psyc) and grant it access to CiviCRM, CiviMail, and view all contacts. Do not change the account password without changing the password in the configuration files of this cron job.

To set up your cron job, first, find out whether php-cli is installed. From the shell, type php -v. If you see (cli) in the result, as in:

PHP 5.2.3-1ubuntu6.5 (cli) (built: Feb 11 2009 19:55:53) Copyright (c) 1997-2007
The PHP Group Zend Engine v2.2.0, Copyright (c) 1998-2007
Zend Technologies with eAccelerator v0.9.5.3, Copyright (c) 2004-2006
eAccelerator, by eAccelerator

This means you have php-cli installed and you should use it, because it has several advantages:

You can run a PHP script at a lower priority than your web server, so that even if it takes a lot of CPU, it won't interfere with the regular users of your site.

You can set different memory limits for the php-cli process and the PHP process used by your web server.

You avoid the overhead of the web server and the HTTP layer.

You won't have any timeout problems.

The following is complete cron configuration to handle CiviCRM's mail requirements:

# This must be set to the directory where civicrm is installed.
CIVI_ROOT=/var/www/civicrm

# Comment: I believe these two lines are unnecessary.
# USER=www-data
# MAILTO="you@example.org"

# Location of the PHP Command Line Interface binary.
# nice -19 forces to run at a lower priority than the web server
PHP=nice -n19 /usr/bin/php

# line to be modified according to the informations below
# like this: PARAMS= -j -s<default or domain> -u<user> -p<password> -e Job -a process_mailing

PARAMS= -j -sdefault -umailprocess -pseol-lzprm42amv-psyc -e Job -a process_mailing
PARAMSBOUNCE= -j -sdefault -umailprocess -pseol-lzprm42amv-psyc -e Job -a fetch_bounces

# cronjob send
# m h dom mon dow command
*/5 * * * * cd $CIVI_ROOT; $PHP bin/cli.php $PARAMS
*/15 * * * * cd $CIVI_ROOT; $PHP bin/cli.php $PARAMSBOUNCE

The user that run the scripts (www-data in this example) needs to be able to write into the temporary folder. Your configuration might specify a different user.

You don't have to run both scripts at the same frequency. The preceding crontab file verifies every 5 minutes whether mail messages need to be sent, but only every 15 minutes whether bounced email needs to be processed.

PARAMS contains:

The site you used, which is -sdefault on Drupal. If you run multiple CiviCRM sites on a single server, you need to specify your site's domain, such as -sexample.org.

The user login account (-umailprocess).

The password you defined (-pseol-lzprm42amv-psyc).

Logging

CiviCRM keeps an eye on the various changes that you make to contacts, memberships and so on.  Each contact has a change log tab which is populated each time a contact is added or edited.  The change log shows who changed the record, and when the change was made.  This light-weight logging is turned on by default and many users find it detailed enough.

One key missing piece, however, is information about what was changed.  Detailed logging adds information on what has changed and provides many other features.

Detailed logging

When enabled, detailed logging tracks all changes made to data in CiviCRM.  Each time something is updated, CiviCRM keeps a note of

what the value was before

what the value is after

when the change was made

who made the change

When you turn on detailed logging, the screen will look something like the below.  Clicking on update on the left hand side will show details of the change.

This logging extends to almost all data that exists in CiviCRM, including your contact, membership, event, etc. data, and also all of the 'meta data' in your install, such as Activity Types, Case types, Contribution Types, etc. 

With detailed logging turned on, any changes made to your data can be reverted which means you can worry less about unwanted changes to the data, whether they are done by administrative staff or by contacts interacting via your website - either maliciously or accidentally.

As you can imagine, logging all changes to the database can result in the collection of quite a lot of data and will have a small performance impact on your database.  For this reason, we turn of logging by default in CiviCRM and let people turn it one if they require it. Before you decide whether you want to turn on logging, you might want to have a look at other ways in which time based logging happens in CiviCRM.

Activities vs. logging

The use of activities to record data in CiviCRM is often useful as an alternative to logging.  Since each activity happens at a specific point in time, you can view the activity tab on a contact record as a log of changes to that contact over time.  This isn't to suggest that each time you make a change to a contact in CiviCRM, you should record an activity.  Rather that, in some use cases, the data collected in the activity log provides a good enough log of changes to contacts over time, and supplementing that with a couple of manually recorded activities may cater adequately enough for your logging needs.

Membership logs

In a similar way to activities, over time a membership will grow into a historical record of the membership, with a record of any contributions that went toward that membership and any renewals, up-sells. etc.  It might be that this out-of-the-box logging meets your needs and means that you don't need to turn on detailed logging.

Reverting changes

One of the great benefits of turning on detailed logging is the ability to revert any changes that you make to you data.  For a lot of contact fields we make this easy by creating a revert button at the bottom of the screen that shows details of the change.

This screen isn't available for all contact changes, however, data is still being recorded behind the scenes. If you do need to revert data that cannot be reverted via the user interface, you should contact your system administrator or get help from someone that is familiar with CiviCRM's detailed logging functionality.

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.

...

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.

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.

To the left of the navigation menu is the Quick search field. See the chapter on Searching for more details.

The home dashboard & dashlets

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 report that you can display on your home dashboard. Many dashlets come with CiviCRM by default, and you or your administrator can create additional dashlets that are specific to your organization's needs. Some examples of dashlets that come with CiviCRM include:

Donor Report: a bar graph of the amount of total contributions per month for the last five months.

Activities: a list of recent activities that have been recorded by CiviCRM (this could include emails sent to constituents, donations that have been made, or meetings that have been scheduled in CiviCRM).

Membership Report: a table summarising information about Members tracked by CiviCRM and broken out by month. This includes the number of Members of each type total amounts of payments made and the number of contributions made, among other things.

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.

Click Done 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.

To create a dashlet, do the following:

Click Reports > Create Reports from Templates.

Select the report template that you want to use.

Choose the criteria you want to display in your dashlet. 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.

Click Preview Report.

Once there, click Create Report.

At the bottom of the Create Report section, select the box that says "Available for Dashboard?" Users with permissions to see that information will be able to add that dashlet. (See the section on permissions for more information).

Click Create Report. 

Now add the dashlet to your dashboard:

Click Home to get to your dashboard.

Click Configure Dashboard. Drag the dashlet from the "Available Dashlets" box to the column where you'd like it to appear.

Click Done.

(Refer to the Reporting section for more details on working with reports.)

Keyboard shortcuts

If you are on a PC, many common activities can be done with keyboard shortcuts (aka access keys rather than clicking through the navigation menus. (Unfortunately, there are no keyboard shortcuts for Macs.) In CiviCRM on-screen help, keyboard shortcuts are called Access Keys.

Access keys

Add a new Individual contact: <ALT>+<SHIFT>+I

Add a new Organisation contact: <ALT>+<SHIFT>+O

Add a new Household contact: <ALT>+<SHIFT>+H

Add a new Group: <ALT>+<SHIFT>+G

Add a new Activity: <ALT>+<SHIFT>+A

Save a page (when it edit mode) <ALT>+<SHIFT>+S 

Add a new record (e.g. add a new contribution when you are on the contribution tab):<ALT>+<SHIFT>+N

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 Quicksearch, 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:

To find a specific contact: the Quick search box can find contacts by name, email address or a variety of other characteristics.

To perform an action on a contact or contacts that meet certain criteria: a common workflow in CiviCRM, called a search-action, is to find contacts that meet certain criteria and then perform an action on them. For example, you might want to find all contacts in the advisory group in order to invite them to a meeting, find all those whose memberships have recently expired to send a renewal reminder, or find all contacts aged under 25 in a specific location to send them an email about an upcoming event nearby.

For ad-hoc reporting.

As a form of ad-hoc reporting, searching is often useful but does have limitations. For example, you can't group results by particular criteria, summarize, or easily produce graphs of the results. For more advanced reporting, see the CiviReport section.

Quick search

The easiest way to find a specific contact is to use the Quick search box that appears in the navigation menu at the top left of the screen. You may choose to search by one of several criteria. Contacts that match the phrase you enter will appear in a dropdown list below the box. For example, if you are searching with Name/Email and you have left automatic wildcard enabled (Administer > Customize Data and Screens > Search Preferences) , entering "peter" will find:

people who's first or last name is Peter

people who have Peter appearing as part of their name, e.g. Mary Peterson

people who have Peter as part of their email address, e.g. peter@gmail.com   

organisations with Peter in their name, e.g. Petersfield Community Centre.

You don't need to type the full name of the person - just the first few letters.

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.

The Date Range Filter

Most component searches include a date range filter. These can be configured in two ways:

by using an absolute date range, e.g. "1st Jan 2010" to "31 July 2010"

by using a relative date range, e.g. "Previous Year"

Relative date ranges are especially useful for searches that you would like to then save as Smart Groups (automatically populated groups that are configured to include contacts that share a certain set of characteristics or activities). For more information see the Groups and tags chapter.

For example you may want to use a relative date range search to find:

Contacts who have contributed in the last 7 days (Relative date range - "From 1 Week ago")

This (financial) years registered Event Participants (Relative date range - "This Year")

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.

You can change the default search operator from AND to OR in the Basic Criteria section of Advanced Search. 

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 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 search on the Membership renewal activity to find everyone who renewed their membership last week then display the results as Memberships so that you can export name, address and Membership expiry date to create and then post out membership cards to those contacts. In Advanced Search, simply select the record type you want from the Display Results As dropdown in the upper right corner of the form.

Modifying search columns (Search Views)

Advanced search allows you 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".

Read more about creating profiles in the Profiles section of the chapter on Organising Your Data. 

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

Search Builder

Advanced search lets you choose from a wide range of criteria in a user-friendly panel, but this has limitations. Search builder allows you to define your own search and arrange the criteria according to your specific needs.

Search Builder allows you to choose from a range of operators:

Search Builder Operators

Operator
Purpose
Example

=
Equals. Matches on the exact value you specify.

"First Name" = "Bob"
will find contacts who's first name is exactly "Bob" 

 ≠

Not equals. Matches on everything that is not the specified value.

"Gender" ≠ "Female"
will find contacts who are not female

> , ≥

Greater-than, greater-than-or-equal-to

"Birth Date" ≥ "Jan 1 2000"
will find contacts born on or after Jan 1 2000

< , ≤

Less-than, less-than-or-equal-to

"Last Name" < "J"
will find contacts whose name starts with a letter that comes before J in the alphabet

In

Value is one of those you specify

"Group" In "Board Members, Staff"
will find contacts who are in either of the specified groups

Like

Same as the = operator, but supports the % wildcard character

"Last Name" Like "Gree%"
will find contacts whose last name begins with "Gree" (Green, Greenberg, etc)

Regex

Same as the = operator, but supports all regular expression operators. See http://en.wikipedia.org/wiki/Regular_expressions 

"Middle Name" Regex "[a-c]"
will find contacts whose middle initial is A, B or C

Is Empty,
Not Empty

Empty means the field exists and is equal to the number zero or contains nothing.

"City" Is Empty
will find all contacts who do have an address but the city was left blank

Is Null,
Not Null

Null means the field does not exist or contains nothing.

"City" Is Null
will find all contacts who do not have an address at all

Search Builder also allows you to combine criteria with multiple AND and OR groups. 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. The following example will search for females born after Jan 1 2000 OR members of the Administrators or Advisory Board groups:

Your search results will contain each contact's name, plus a column for each search criteria you've defined. If you export search results, the export file will contain those same columns.

Just like other searches, you can choose from a list of actions to apply to the results of your search. If you export results, you can select fields for export. Note that the fields you searched on will get exported by default in addition to those you select.

You can also save your Search Builder search as a Smart Group. For more information on Smart Groups, see the Groups and Tags chapter.

Full-text Search

You can use this to search for text values all fields of the database.  This is particularly useful, for example, if you can remember specific words that you have used but can't remember where you have put them. For example, lets say that you recorded an activity with a contact and added specific words to the description but have now forgot the contact's name. You can use Full text search to find the contact and activity by words that you remember from the description.

Component searches

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.

Note that you can also use the Advanced search in conjunction with Display Results As to search for component objects based on criteria available in advanced search. For example, you could find all event attendances from contacts that are also members.

Custom searches

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 customized 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. Though some of these searches can be done in the Advanced Search (especially in later versions), custom searches are also set up to display results according to your search and my provide more useful columns in the results for your needs. Here's a short description of the custom searches available.

Finding contacts in one group but not in another

This is probably the most popular custom 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.

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 or volunteers, but exclude members of Advisory Board, perhaps to create a new mailing list to receive a message targeted at the most external circles of your constituents. 

Household Name and State

Search households in a state or province. 

Note: which states or provinces are available in the search depends on your localization settings. Add additional countries by going to Administer > Configure > Global Settings > Localization. Add to the column of "Available States and Provinces", but note this change will also affect profile forms which include country or state/province fields.

Contribution Aggregate

Find aggregate totals of contributions from contacts within a range of dates.

Postal Mailing

Search for contacts in a given group and display results 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.

Go to Search > Custom Searches > Proximity Search

Enter the distance in miles or kilometres.

Enter the country within which you want to search.

Enter any other parameters you wish to give your search.

Click Search.

TIP: You can also incorporate Proximity Searching in a profile which you've configured for use as a search form.

Event Aggregate

Search on event-related payments for a given event or event type in a given date range. You may also limit results to show credit card payments only or payees only.  See also event reports for more useful event search options.

Activity Search

Find activities using any or all of the activity-related criteria. This is also possible in Advanced Search by using Display results as.

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.

Find Contribution Amounts by Tag

Search on any tag for contributions within a range of dates.

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.

Go to Search > Custom Searches > Zip Code Range.

Enter the start and end range of the zip or postal codes.

Click Search.

Date Added to CiviCRM

Search for contacts that have been added within a particular time period. Including a group displays just those added within the specified time frame who are also in that group. Excluding a group removes those group members from the results.

Custom Group Multiple Values Listing

A search for multi-value custom data.

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.  See also the LYBUNT and SYBUNT reports.

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.

It is possible to write your own custom searches, but you'll need to be comfortable with MySQL and PHP. See the Developer wiki at http://wiki.civicrm.org/confluence/display/CRMDOC/Develop 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.

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.

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 contact summary 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 Data and Screens > Profiles).

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".  

Case sensitivity

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'.  Entering "mi%el" in lowercase will also find contacts with an upper case 'M' in their name.

Undelete

By default, deleted contacts are sent to the trash, and may be recovered at a later date by an administrator (or anyone holding the "access deleted contacts" permission"). To restore these contacts, go to Advanced Search, enter the contact’s details and check the Search in Trash check-box beneath in the Basic Criteria section.

From the list of results, you can either recover contacts individually using the Restore link at the end of the row, or by choosing Restore contacts from the action drop-down menu.

If you are sure that you no longer have a need for the particular contact, you can delete them permanently

Note that you can  disable the trash function if you like in Administer > System Settings > Misc (Undelete, PDFs, Limits, Logging, Captcha, etc.)

Overview

This chapter covers the main building blocks that CiviCRM uses to store data and offers advice on how to transfer and organize your existing data. Using CiviCRM successfully depends on storing data in the right place and in the right way, which can only happen with some thoughtful planning of mapping your data into CiviCRM.

Before thinking about CiviCRM structure, it is important to think about the systems you currently have in place to store and organise your data. Your data could be stored in a spreadsheets, another database or CRM (i.e. Constant Contact, Convio or The Raiser's Edge), paper files or in someone's memory. 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.

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 are some important questions to ask yourself about your current data:

Do you have an existing CRM?

Do you have spreadsheets with information about your contacts, donations or other valuable data?

Do you have any post-it notes or file cabinets with information about your community?

Does anyone at your organization know a lot about community members?

How does money come into your organization?

What are the day to day tasks your staff and volunteers carry out?

How do you currently communicate with your donors, members, volunteers and other community members? How would you like to communicate with them?

How do you track activities and communications (emails, meetings, webinars, other events) that you have with your community?

Do you have a list of donors interests and preferences?

How do you handle new contacts?

What classifications or labels are you using for your existing contacts (ie. alumni, students, parents, major donor, volunteer)?

Are there any reports you would like to create? What information will they contain?

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 practices 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.

Think about the move

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 data 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. You can read more about this in chapter "Mapping your data into CiviCRM".

Also, 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.  

The following chapters will help you understand what data CiviCRM can store and how the best to map your existing records into CiviCRM structure.

Mapping your data

Your existing data may be coming from multiple sources, some electronic, some paper based and some residing in people's memory. "Mapping" refers to the activity of taking existing data that was labeled in a certain way and "slotting" it into a CiviCRM structure. This is a very important step and skipping it may cause undesired consequences in the future. For example, you may not be able to control or report on data the way you expect. 

Everyone thinks about data differently, based on experience with another CRM or no CRM at all. For example, "Donation", "Opportunity", and "Contribution" all refer to money given to your organization. CiviCRM was designed to be flexible and adaptable, so you should have no problem finding the proper place for every piece of information relevant to your organization.

Resist the temptation to add custom fields right away. Instead of adding a new field for manually entering membership expiration dates, learn about CiviCRM's membership module that automates membership duration, expiration and renewal reminders. Having multiple fields to collect the same data will cause confusion later. Avoid data duplication by making informed choices up front. 

The following sections will introduce you to options CiviCRM provides out of the box with tips along the way for mapping your data. Instead of using  "flat" spreadsheets, relationships will tie your data together. Using relationships, you will be able to create a more complete picture of the community that supports your organization. 

Basic information about your constituents

CiviCRM comes with default fields to store constituent names, addresses, phone numbers, emails, notes and other contact information. Since CiviCRM was designed for non-profits, the mapping of your most basic constituent information should be very easy. 

CiviCRM divides constituents into 3 categories (Contact Types) based on who or what they are:

Individuals: any person your organisation wants to keep a record of

Organizations: this could be another non-profit, a company, a chapter of your organisation, or a committee. You will generally want to create at least one contact of the Organization type to represent your organization. This is particularly useful when you are configuring memberships

Households: a family or group of people who share a physical location

Each contact type comes with different fields, 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.

To read more on built-in CiviCRM basic constituents fields and how to use them, please see the Contacts chapter in Organising Your Data.  

Information about your constituents that is specific to your organization (basic introduction to Custom Fields)

Many organizations collect data specific to their mission or structure. Even though CiviCRM comes with fields to store basic data that all non-profits collect, similarities between non-profits end at a certain point. For example, your organisation may be interested in information about constituent allergies (for individuals) or service area (organizations).  

When mapping data into CiviCRM, decide if the information pertains to an individual, organization, or household. Additional information like "service area" only makes sense for Organizations. To find out how you can create custom fields, please see the Custom fields chapter in Organising Your Data.

Relationships between constituents

Relationships capture current and historical information about how two records connect to each other. 

You or your colleagues probably know more about your constituents than what has been written down. You may not have previously collected that information because there was no space in your "flat" spreadsheet or you may have collected it as a "mental note" about a given person or organization. The name of their family members, place of employment, and relationship to other constituents in your database can all be captured with a Relationship. 

CiviCRM comes with a predefined set of relationship Types including "employer--employee", "parent--child", and "employee--employer". You can create more relationships to describe your organization specific relationships, for example you might define a relationship type of "vicar--church". When you create a new Relationship, you can define when the Relationship began and, if relevant, ends. Previous relationships can still be accessed when they end. For example, you can see where someone used to work even after the relationship has been severed.

The term Household and relationship Types "household member of--head of the household" confuses many new CiviCRM users. It's useful to group individuals who share a common address in one household, so that they only receive one letter. The designation "head of the household" helps organizations know who the letter should address. For example, you want to address the parent and not the child.

To read more about configuring and using relationships, please see the the Relationships chapter in Organising Your Data.

Activities

It is important to know how and when constituents engage with your organization. Knowing that someone gives monthly or volunteers frequently and renews her membership yearly suggests that she may respond well to opportunities that strengthen her relationship with your organization. CiviCRM allows you to record interactions such as phone calls, emails, and meetings between staff and constituents. These features help an organization build a lasting memory of its relationships.

CiviCRM calls these kinds of exchanges Activities. They are tightly linked to other CiviCRM modules. When you record contributions, event attendance, membership subscriptions, and emails, CiviCRM will automatically create a related activity in the Contact record. Decide whether your organization needs different activity types in addition to those provide, such as training, review, exam, support etc.

To read more about configuring and using activities, please see the Activites chapter in Organising Your Data.   

Webinars, events, performances, and meetings (CiviEvents)

CiviCRM helps manage and track any occasion in which you bring community members together at a certain place and time. Webinars, events, performances, and meetings have specific start and end dates and times, meeting places (including online) and reasons for bringing people together. They can be ticketed, RSVP only, or no reservation required. CiviCRM comes with functionality to promote events and record registrations. If you have records of who has participated in past events, you can transfer these valuable records into CiviEvents.

The Event Types field helps you to distinguish between different types of events your organization hosts. This is helpful for evaluating how many people have participated in a similar series of events or whether someone prefers one kind of event over another.

To read more about configuring and using relationships, please see the Events section later in this book.  

Memberships

Many organizations offer a structured program in which community members can sign up to receive certain benefits for a pre-defined period of time. Members choose from a variety of dues levels that have associated benefits, generally the more you give the organization the more you get in return.  Organizations can also give membership at no price, perhaps as an award. For example, a long-time volunteer might receive a life-time membership to the organization. Common benefits include access to member directories, extra content, discounts, etc. Individuals, families or households, and organizations can all sign up for memberships.

The main difference between membership dues and a donation is that memberships redefine someone's relationship to the organization for a period of time. Organizations often expect that memberships will be renewed from year to year, while a donation is a one-time gift. Organizations need to send an acknowledgement letter, but they have not promised to serve the donor advertised benefits in response to a donation or Contribution in CiviCRM.

Analyze your current membership structure before importing membership records into CiviCRM. Take time to eliminate unused membership levels or simplify the benefits you promise. The only information you really need to transfer for each member is start date, duration, membership dues paid, and type of membership.

Generally speaking, having more than 10-15 membership types may be hard to manage. Sometimes organizations may have many membership types in order to preserve other information about constituents in the membership record. It's recommended to verify first whether or not CiviCRM already has existing data fields related to memberships to keep track of that information before extending membership records.

Some information that you may have recorded as static information before can now be calculated dynamically, and displayed in reports or other fields. For example, CiviCRM can dynamically calculate the number of years a given constituent has been a member based on the "Membership since" date.

To read more about configuring and managing memberships, please see the Memberships section later in this book.  

Contributions

Contribution in CiviCRM refers to money, goods, or services coming in to your organization. Money is still money whether someone buys an event ticket, signs up for a membership, or any other activity that requires payment. CiviCRM allows you to record all money coming into your organization as a Contribution with different Types to preserve information about where it came from. You will also be able to specify the date the contribution came in, it's status (you can record a contribution as pending before the money is deposited to your bank account) and the form it was delivered in (check, cash, etc.).

If you are planning to keep using an external donations system, you may leave transactions there. On the other hand, you may want to transfer to CiviCRM information about past event/webinar registrations because they tell you the history of constituent involvement in your organization. Also consider how far back you want to import the history of contributions. Large contributions should be preserved, but the fact that someone donated 5 dollars 10 years ago may no longer be relevant. 

To read more about configuring and using relationships, please see the Contributions section later in this book.  

Campaigns

Sometimes organizations host a fundraising gala, send an email appeal, and record contributions all to support one goal. E.g., raise $50,000 to support a kids camp. Campaigns are usually time limited and tie together a range of activities and give you a high-level view to compare how people responded to your initiatives.

You can start taking advantage of campaigns if your organization's fundraising initiatives fit well into a unique themes. Some examples of campaigns are year end pledge drives, or project specific fundraisers. Organizations often send several email appeals encouraging donors to support a particular project or fundraiser, such as a 'final notice' and one or more 'countdown' appeals.

Grouping and tagging constituents

Development directors, volunteer coordinators, and program managers store a wealth of information in their heads. They often make decisions about who to invite to an event, who should not receive an appeal, and/or who would be perfect for a volunteer opportunity.

Groups and tags can store that kind of information and act as the building blocks for creating email and invitation lists. Groups are useful to identify two or more contacts with something in common, as opposed to relationships which can only capture information about two contacts. Groups can also act as mailing lists. A group of people who subscribe to your newsletter(s) is a good start.

Organizations can have complex communication strategies, in which they send different letters to several subsets of their community. One Individual can be tagged member and volunteer, so that she receives member specific communications as well as volunteer specific communications. Groups are also useful to store issue or program specific communication preferences. For example, consider a group of people who have specifically requested not to receive fundraising appeals. When you go to create an email appeal mailing, you can exclude the group of Individuals who have requested not to receive fundraising appeals.

Try to avoid creating groups based on information that can be stored by other fields in CiviCRM. You don't need a group for individuals who have opted-out of bulk mailings, because that option will be selected on their Contact record. CiviCRM automatically excludes these constituents from any bulk mailing. Likewise, you don't need a group called "donors" because you can run an advanced search to find any Contact record that has a Contribution associated with it, even between any date ranges. Most functions available to groups are also available through the search results screen.

If you want new records that meet a particular criteria to be automatically added to a group, create a Smart Group from any advanced search. For example, you may want to have a Smart Group that calls the Contact record of all members who also donated more then $100 in the past year. When a member makes a new $100 donation after the group has been created, their record will be added to the Smart Group.

Tags are more like keywords that you want to associate with a record.  You can easily add or remove tags, but there is no easy way to see the history of changes. Relationships are a much better tool for seeing information history.

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.

Profiles are about how your data is edited or displayed to your staff or other groups of users, not how your data is stored. 

Read the Profiles chapter in this section for detailed information about how to make use of profiles. 

Where next?

In the sections above we've tried to describe how your existing data may be mapped into CiviCRM. We've only touched on basic CiviCRM functionality or "spaces" where your data may fit. To read more about how CiviCRM can work with your data, please see information in this book about specific CiviCRM components: CiviEvent, CiviMember, CiviMail, CiviContribute, CiviCase, CiviCampaign, and CiviGrant. 

Each of the above components will help you streamline administrative tasks related to event management, membership, sending communications, receiving contributions and donations, case management, conducting campaigns, administering grants programs, and more.

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.    

Contacts

This chapter introduces contacts: the basic building block of CiviCRM. We look at how to find, view, add, edit and delete contacts.  We also look at ways to extend and customise contacts, and to change the way that contacts appear in the user interface.

Out of the box, CiviCRM comes with three contact types:

Individuals - i.e. people

Organisations - for example companies or other non-profit organisations

Households - typically families that share a physical location

Each contact record comes with a set of core fields, including:

names (first and last name, etc. for individuals and organisation name, etc. for organisations)

greeting and addressee fields for different communication methods

contact methods, e.g. email addresses, phone numbers, website addresses, etc.

addresses (i.e. physical locations)

communication preferences: i.e. the methods that they prefer to be contacted by, and those that they do not want to be contacted by.

You can define new contact subtypes based on the out of the box contact types.  You can add custom fields that extend all contacts.  You can also add custom fields that extend particular contact types or sub types.

Think of contacts as the centre of your CiviCRM universe.  All of the other building blocks of CiviCRM, like relationships, actvities, groups and contributions connect to contacts in some way.

A quick look at contacts

Contacts are organised into tabs.  The first tab that you see when looking at a contact is the summary tab with some basic information about your contact.  Following the summary tab are a series of other tabs each showing information about different aspects of the contact.  Organising the contact into tabs helps manage the large amount of data it is possible to collect about contacts over time.

Tabs get turned on and off depending on what components are enabled and what permissions you have.  For example, you will only see the memberships tab if the CiviMember component is turned on and you have permission to see memberships, etc.  You can also define extra tabs that display any extra custom data that you want to collect about your contacts.

Below we look at the most important parts of the contact screen (including most of the contact  with pointers to other parts of the book where appropriate.

Contact actions

Above the tabs line, you will see a few buttons.  The first button is the Actions button which is a handy shortcut to carrying out actions with this contact. For example, you could add a note to this contact, or record a new contribution, meeting or other activity.

The summary tab

The summary tab shows overview information about your contact. Here you will find names, addresses and contact details as well as details of contact methods.

Some fields on this tab are just for individuals, for example, first name, last name, nick name, etc. Other fields are just for organisations, for example organisation name.

Individual fields

Individuals names are split into the following parts: prefix, first name, middle name, last name, suffix and nickname (you don't have to use all of them).  Prefixes and suffixes are selected from a drop down list.  If you can't find the value you want, you can add more options to the list from the following screen: Administer CiviCRM > Customize Data and Screens > Dropdown Options > Individual Prefixes (Ms., Mr...).

Addresses

You can record one or more addresses for a contact.  Each address needs to be at a different location type (e.g. work, home, etc). One of the addresses can be marked as primary and 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.

You can share addresses between contacts. For example, you may need to keep information about individual contacts and the organisations 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 organisation record on the fly by selecting "New Organisation" from the "create new contact" drop-down.

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.

If you have a mapping provider enabled you can click on the map icon next to an address to see the location of a contact on a map.

Phone numbers

You can store multiple phone numbers for each contact.  Phone numbers have locations (e.g. work, home, etc.) and types, e.g. landline, fax, mobile.  Note that any phone numbers that you add as of type mobile will be available for sending SMS.

Email addresses

You can store multiple email addresses for each contact. One of these email addresses can be explicitly marked as the address which receives all bulk mailings such as e-newsletters and announcements (e.g. these are emails your organisation would send using the CiviMail component).  Any bouncing emails are are automatically marked as being on hold when sending emails via CiviMail.  See the Mail section for more information.

Communication preferences and privacy options

Communications preferences (i.e. methods of communication that are preferred by contacts) and privacy options (e.g. do not contact me via email) can be defined.  Privacy options are respected when carrying out certain functions, e.g. mailing labels are not printed for contacts with the 'do not mail' privacy option, and emails are not sent to contacts with the 'do not email' privacy option.

Here is a brief explanation of each of the privacy options in the CiviCRM contact record:

Do not phone - The end user has elected to not be contacted via telephone.

Do not email - The end user has elected to not be contacted via email.

Do not mail - The end user has elected to not be contacted via postal delivery (snail mail)

Do not SMS - The end user has elected to not be contacted via text messaging service to their mobile device.

Do no trade - The user has elected not to share their info with other organizations. (ie. you may not share or sell user's information to other parties) 

Greetings and addressee fields

By default greetings and addressee fields are calculated based on the contacts name fields.  For example the postal greeting for an individual called 'Jenny Soper' is 'Dear Jenny'.

The default greetings can be configured at a global level here: Administer CiviCRM > Communications > Email Greeting Formats or Email Greeting Formats or Addressee formats.

Different formats can also be selected for each contact and can also be customised on a contact per contact basis. 

The 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.

You can read more about when it makes sense to use relationships in the relationships chapter of the organising your data section.

The activities tab

The Activities tab displays a list of all of your interactions with a contact, including all CiviCRM's built-in activities like event attendance, contributions, phone calls etc as well as any custom activities you may have added. It also 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 will also show any custom activities that you've defined.

To find out more about activities please refer to the Activities section in this chapter.

The contributions tab

The Contributions tab shows any financial contributions made by a contact, 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 offline 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 Financial Type in addition to the normal contribution information collected from public contribution pages.

Read more about Contributions, in the Contributions chapter of this book.

The memberships tab

This tab displays any memberships a contact has. 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.

Read more about Memberships, in the Membership chapter of this book.  

The events tab

The Events tab displays events related to this contact, for example events the contact has registered for, attended or volunteered at.

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 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."

Read more about Events, in the Events chapter of this book.  

The groups tab

The Groups tab shows the groups that the contact belongs to. 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. 

For more on this topic, please refer to the Tags and Groups section of the book.  

The 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. 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 (via your CMS) can view or edit it.

The 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.

For more on this topic, please refer to the Tags and Groups section of the book.  

The 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.

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

Adding contacts

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:

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

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).

For all contact types you can use the Check for Matching Contacts option to help avoid duplicate entries. After entering all of the information you have in this section, you can click on Check for Matching Contacts.

For adding an Individual record to the database, first name and last name OR email address are required. For adding an Organization or Household record to the database, just Organization/Household name is required. You can fill out as many of these fields as you like, and donâ€™t forget, you can always go back and make changes as needed by using the edit screen.

Useful things to know when adding contacts:

Address: You can add multiple addresses to a contact record. This allows you to store someone's home and work addresses, as well as a billing address if that's different.

You will see a checkbox here to allow you to share the address of either an existing contact, or create a new contact. If you select new contact, you will need to select which contact type you wish to create, and a pop up box will appear to add the new contact record. When a person uses another contact's address, that address can only be edited from the "master contact's" record.

The options available in the countries dropdown will depend on which ones you have made available at Administer > Localization > Languages, Currency, Locations under Available Countries.

There may be fields here that you do not need. Available address fields can be edited at Administer > Localization > Address settings. The "Address Name" field which can be used to label a particular address (for example "Summer Home") is hidden by default, but can be enabled from that screen.

Tags and Groups: Here you can specify which tags and groups to add your contact to. Please note that you may only add to existing groups and tags with existing tags. You can read more about creating tags and groups in the Groups and Tags chapter of this book.

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

Save will save the contact record and take you to the contact screen.

Save and New will save the contact and clear the form so that you can add another.

Cancel will discard the entered information and return you to your CiviCRM dashboard.

Editing contacts

Editing information on the summary screen is simple. Hovering in the upper right corner of the block that you wish to edit will bring up the Edit Info link.  You can then edit the information directly in the summary screen.

If you need to edit a lot information for one particular contact, an alternative is to open the entire contact for editing by clicking on the edit button above the tabs.

Note that on the rare occasions that two separate admin users edit a contact at the same time (specifically that they both open the edit screen, then both save the contact), the second admin user will be notified of the first admin user's edit and be given the chance to manually 'merge' the edits.

Deleting contacts

At the top right there is a button to Delete the contact.  When a contact is deleted, it does not disappear completely - instead it moves to the trash, where it can be recovered at a later date (using the search in trash feature of advanced search).  See  "searching" under the "working with your data" chapter for more information).

Deleted contacts are moved to the "trash" by default (and can be restored later if needed). There are a variety of ways to delete a contact:

Single contact: open the contact's record and click the 'delete contact' button at the top of the page. Alternatively, run a search for the contact and, from the results list, look toward the end of the contact's row, click 'More' and select 'Delete Contact'.

Multiple contacts: run an advanced search, check the boxes of each record you wish to delete (or select all with the checkbox in the header at the top) and in the 'actions' drop-down menu, choose 'Delete Contacts' to send the contacts to the trash (if enabled) or 'Delete Permanently'. A warning page will be displayed to verify your intention; simply click 'Delete' to continue or 'Cancel' to return to the previous screen.

Contact subtypes

In addition to the three default contact types (individuals, households and contacts), you can define additional contact types (sometimes referred to as contact subtypes) to suit your needs.

Each contact subtype that you define is based on one of the three core contact types. For example, 'Student' would based on the 'Individual' contact type, and 'Farm' could be based on the 'Organization' contact type, or perhaps 'Household' contact type, depending on your use case.

Contact types are very useful when you need to collect and display different sets of custom data for different types of contacts (e.g. you may wish to collect information on the subject area and qualifications of all teachers in your database but not be interested in collecting these for other individuals.  To do this, you would create a contact type called Teacher, based on Individual and then create a custom data set that only extends Individuals of the type Teacher (see custom data for more information).

Note that the core contact types are mutually exclusive, i.e. a contact cannot be an organisation and an individual.  However, contacts can be of more than one user defined contact subtype, i.e. the could be a Teacher and a Parent, for example.

To edit existing contact types and and create new contact types go to Administer > Customize Data and Screens > Contact Types. Note that you cannot delete the inbuilt contact types but you can change their names and the images associated with them

To add custom fields to specific contact subtypes, see the chapter on custom fields.

Customizing the view of contacts

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.  Using an account with Administer CiviCRM privileges.

Go to: Administer > Customize Data and Screens > Display Preferences.

Clear the Demographics box under Editing Contacts.

Click Save.

You can also use this screen to rearrange the order that the information is displayed in.  

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

Go to: Administer > Localization > Address Settings.

Check or uncheck fields under Address Editing.

Click Save.

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 > Customize Data and Screens > Display 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 disable.

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 of contacts, activities, and cases, while 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.

Regular Groups allows you to manually place contacts into a group. For example, you can manually assign your organisation's board members to a Board of Directors regular group. You can then easily send board-related emails to each person who is a member of the Board of Directors group without having to search through CiviCRM and select each member individually for the mailing.

Smart Groups are automatically populated groups that are configured to include contacts that share a certain set of characteristics or activities. As contacts are added or edited, CiviCRM automatically checks them and adds them to Smart Groups if they meet the characteristics that you have configured. For example, you can create a Smart Group for "2010 Contributors from California" that includes contacts who have made a contribution in the year 2010 (an activity) and have an address in California (a characteristic). When new contacts located in California make a contribution in 2010, they are automatically added to this group. Another example is 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.

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 standard types:

Mailing List is used if you plan to use this group as a mailing list in CiviMail. This group type is available for both Regular and Smart Groups.

Access Control (Drupal only) is used to assign CiviCRM access permissions to a set of contacts. Only Regular Groups can be assigned the Access Control group type.

It is possible to create additional group types to reflect your specific needs. This is particularly useful if your organisation has hundreds of groups as group type can be used as a filter on the Manage Groups screen. To create additional group types go to Administer>System Settings>Option Groups and select Group Type.

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: 

Groups are integrated into several other CiviCRM functions (most notably CiviMail).

Contacts can be added to smart groups automatically based on characteristics.

Groups can be associated to Drupal Organic Groups.

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

The following paragraphs outline the pros and cons of groups vs. tags

Benefits of tags

Easy to setup and use

Easy to search by tags (can use either Basic or Advanced Search)

Easy to combine with other properties (like residence state/province) to create Smart Groups

Limitations of tags

You can not create Tags for use with specific types of contacts (i.e. you can't create tags that are ONLY for use with Individual contacts)

When you export Tags, all Tags assigned to a record are exported in a single "cell" as a list (e.g. "Teacher, Volunteer")

Tags allow multiple selections - so they may not be appropriate for mutually exclusive characteristics (e.g. "Democrat", "Republican", "Green Party")

You cannot selectively hide or permission Tags on built-in or Profile create and edit forms (you get ALL Tags ALL THE TIME on edit forms)

Benefits of Groups

Groups are the most flexible way of segmenting your contacts for a wide variety of purposes.

Groups facilitate recurring tasks like sending an enewsletter, printing mailing labels, etc.

Groups allow you to restrict access to "special" sets of contacts

Groups support both administrative and end-user "subscribe" and "unsubscribe" actions - and a history of these actions is kept in the system

Visibility settings allow you to decide which Groups are shown to end-users on Profile forms (i.e. some Groups can be "private")

You can create Smart Groups that combine members of Group A + Group B

Limitations of Groups

All existing Groups are listed under Manage Groups and in the search forms. This may cause group "overload" if your organization winds up with "too many" Groups. 

Groups used for short-term projects should be "purged" when they're no longer needed

When exporting contact records, all the Groups a contact belongs to are exported as a single comma-separate list (e.g. "Administrators,Newsletter Subscribers")

You can add contacts to groups in multiple ways:

through the Tags and Groups section of the Contact Details edit screen

through a contact's Groups tab

by using the "Add Contacts to Group/Tag contacts" batch action after conducting a search

by clicking a group's Contacts link in Navigation Menu > Contacts > Manage Groups.

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.

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:

add contacts to a group by clicking the Contacts link in the group's row

edit the group by clicking the Settings link

disable or delete a group using the links in the "more" pop-up menu. 

see how many contacts are currently in each group.

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 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. 

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.

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:

while creating or editing the record

from the Contact Summary Tags tab

by using the Tag Contacts batch action after conducting a search.

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

Tag sets

Tag sets are a free-form way of tagging contacts and are similar to regular tags, but they differ from regular tags in a few key ways: 

they act as a "bucket" to allow you to group tags (i.e. an Issues People Care About tag set might contain the tags "affordable housing", "racial justice", or "water quality")

they allow tags to be created on the fly without you having to access the Manage Tags page 

adding them creates an additional search field in the Basic Criteria section of the Advanced Search

Tag sets are created by going to: Contacts > Manage Tags (Categories) in the navigation menu and clicking the Add Tag Set button. Give the tag set a name, a description, and indicate whether the tag set will apply to contacts, activities, or cases.

Clicking the Reserved checkbox makes a tag set more permanent - this will prevent a tag set from being deleted by someone without Administrator permission. (Read more about permissions, in the Permissions and Access Control chapter of Initial Set Up section.)

Now you can use the tag set to freely tag a contact, activity, or case record.

When you create a new tag set, a new field shows up on the edit pages of the entity's activities or cases as well as in the Tags tab for contacts. For example, if you create a tag set called "Issues Folks Care About" an associate it with Contacts, you will see the tag set next time you go to the Tags tab of a contact's record.

This is an 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 record that you are editing (contact, case or activity).

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

A Note About Searching on Tags and Tag Sets

For each tag set you create, a new field will appear in the Basic Criteria section of Advanced Search. You can only search on tags that already exist in this tag set.

Searching in the All Tags field will allow you to find records with tags (regular or tagset tag) which contain a complete or partial word or phrase. EXAMPLE: If you have several tags that contain the word 'Donor', you can find contacts tagged with any of them by entering 'Donor' in this field.

Read extensively on using Advanced Search in the Searching section.

Smart groups

Smart groups are 'saved searches'. They are useful for keeping track of groups of contacts meeting certain criteria, for example 'all members based in Europe'.  Creating a smart group is easy: you search based on your desired criteria and then choose 'Create smart group'.  Once the smart group is created, each time you ask to see the contacts in a group, CiviCRM will carry out a search and show you contacts that meet the criteria you specified.

Smart groups are a really powerful and useful part of CiviCRM.  They come in handy in many different situations.  Spend some time making sure you understand smart groups and how you might be able to use them.

When might I use a smart group?

Smart groups come in handy in many different situations. Here are a couple of examples.

Smart groups and profiles: a membership directory

A smart group could be used in conjunction with a profile to display a directory of members on your website. To do this, you would create a smart group that includes members of your organization and create a profile that includes the fields that you would want to display in your directory.  You would then configure the profile to only show contacts that were in that smart group. When a contact becomes a member - for example, when they fill in your membership form and pay online - they will automatically be added to the smart group and therefore be published in your members directory.

Smart groups as mailing lists: an events newsletter

Lets assume that anyone who has registered for or attended an event will want to receive our events newsletter. We can create a smart group with that includes all people who have registered or attended an event, and specify that this smart group is a mailing list.  It will then be available for use in CiviMail and we can use it to send the events newsletter.  As people register to attend an event - or are marked as having attended an event - they will be added automatically to the smart group and hence subscribed to the newsletter.  Smart groups respect people's subscription preferences.  If people unsubscribe from the newsletter, they will be removed from the smart group.

Creating smart groups

Smart groups can be created from the search results generated by many of CiviCRM's search forms.  Lets say we wanted to create a smart group of all donors who have not yet been sent a thank-you letter to help us manage our work-flow for thanking donors. As we send letters, the donors receiving them will automatically leave the smart group, allowing us to have an always accurate list of people to send letters to.

We can use the advanced search to create this smart group (you could try this on the demo site - http://demo.civicrm.org if you don't have contributions in your CiviCRM installation).

Go to Search > Find Contacts > Advanced Search.

Scroll down to the Contributions section. 

Check Thank-you date not set? and choose Donation from the financial type drop-down menu.

Click Search at the bottom of the page. 

Select all records

From the Actions drop-down menu select New Smart Group, then click Go.

Give the smart group a name and click Save Smart Group.

Your smart group will now appear in all the usual places where you see groups.

Try editing the a contact in the smart group so that they no longer match the criteria.  You'll see that they are removed from the smart group.

If the contact is not removed immediately, it may be that you have smart group caching turned on (see Smart group caching below).

Changing criteria for smart groups

You may want to refine the criteria that your smart group uses to select contacts.  For example, you may want to edit a smart group consisting of all current members to include new members as well. You can do this from the Manage groups screen.

Click Manage Groups. To edit the search criteria of a particular smart group, click Settings next to that group.

On the group settings screen, click Edit Smart Group Criteria at bottom left.

This will bring up the a screen similar to the one that you originally used to create the smart group with the search results displayed.  Clicking on the bar at the top of the screen will bring up the criteria that you used to define the smart group.  You can then update the criteria and once you're happy with the results, select all records and choose Update Smart Group from the Actions list.

Your smart group is now based on the new criteria.

Smart group caching

For performance reasons, smart groups are often cached, i.e. the contacts that meet the smart group criteria are saved in memory for a certain amount of time.

This speed things up because CiviCRM doesn't need to run the search each time you want to use the smart group.  If you query is simple and involves a small number of contacts, the speed up may not be significant.  If it is complex and involves a lot of contacts, it may be very significant and even necessary.

The down side of caching is that you need to wait up to 5 minutes for the query to be updated.  Depending on how you use smart groups this may not be an issue.

The default expiry time for a smart group in newer versions of CiviCRM is 5 minutes. You can adjust the smart group query cache 'timeout', i.e. the amount of time the cache is considered a valid reflection of the smart group in Administer > Customize Data and Screens > Search Preferences.

Activities

Activities are a key concept in CiviCRM, providing a unified place to record and view the history of interactions between your organization and you constituents, clients and partners.  You can you them use them to track meetings, phone calls and other activities that you set up.  Activities are also used by all of CiviCRM's components to record things like when contributions are made, when people come to events, sign petitions, etc.

All activities happen at a specific point in time. All activities involve at least one contact, and many involve more than one. Activities can be assigned to staff or volunteers, and an email is automatically sent to the assignee.

If it is important for you to know who at your organisation carried out a task, then record it as an activity

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.

Several types of activities are included by default, but you can create additional types to define specific things that your organisation does. You can define these at Administer > Customize Data and Screens > Activity Types. You can also add custom fields to activity types to allow specific data to be collected. For example you might create 2 new activity types called: Training and Interview. You can then set up a custom field set which is associated with activities which includes information such as funder and project. 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 which is used for a specific activity type. For example, you could classify meetings as a 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:

date and time: activities always happen at a certain point in time

duration: so you can collect all the time spent on a series of activities

status: is the activity scheduled, completed, cancelled, etc.

added by: the person who added this activity, or the contact if they carried out the activity themselves via the website

assigned to: the person (usually within your organisation) that will carry out (or has carried out) the activity

with contact(s): the contacts in your database that are the subject of the activity.

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". However, it would probably be better to record this as an activity. 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 date to a future day and time and setting the status to "scheduled".

Activities and events This is an important distinction to understand. An event is something that a contact attends, such as a meet-up, a training, a dinner or fundraising event. As discussed, an activity can be any type of interaction a contact has with your organisation, from a meeting or a phone call to a donation. 

Creating new Activity Types

Go to the Activity Type Options page Administer > Customize Data and Screens > Activity Types and click Add Activity Type. 

Assign your new activity type to the "Contact" component if you want it to be available from the Actions button when viewing a contact record. Assign it to "CiviCase" if these activities are only for use inside a case.

Setting up Custom Field Sets for Activities

When setting up custom data sets, you will need to specify what the custom data will be used for. One of the options here is Activity and if you wish, you can further specify which type of activity. This means that these custom data fields will be available when recording activities.    

Activity Status Options

The default set of status options is

Scheduled

Completed

Cancelled

Left Message

Unreachable

Not Required

If you need to add more options, you can do so from Administer > System Settings > Option Groups.

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.

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

Navigate to one of the records that you want to relate.

Click on Add Relationship from the Actions button on the contact summary, or from the Relationships tab

Select the Relationship Type. In this case it would be either "Child of" or "Parent of".

Begin to type the last name of the related person(s). If you discover that a contact you want to connect is not yet in the database, you can create a new contact from this screen.

Optionally 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 to indicate that the relationship is active, which is checked by default.

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.

Navigate to the record of the individual who you want to connect to an organisation.

Click the Edit button to edit the individual's record.

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. 

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

Select the desired contacts from your search results as described above.

Select Add Contacts to Organization from the dropdown " - more actions - " menu, then click Go.

On the Add Contacts to Organization screen, select the Relationship Type from the dropdown menu.

Enter part of the desired organisation name in the Find Target Organization field, then click Search.

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.

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.

Click Done to return to your search results. 

Adding contacts to households

Select the desired contacts from your search results as described above.

Select Add Contacts to Household from the dropdown " - more actions - " menu, then click Go.

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.

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.

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.

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.

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.

In the navigation menu, go to: Administer > Customize Data and Screens > Relationship Types.

Review the list of existing relationship types to ensure that you are not creating a duplicate.

If the relationship type you need does not already exist, click the New Relationship Type button.

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.

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.

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.

Leave the Enabled box checked unless you intend to create this relationship type but not allow users to utilise it until a future date.

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. 

In the navigation menu, go to: Administer > Option Lists > Relationship Types.

Click the "more" link in the row of the relationship type that you'd like to disable or delete. 

Select either Disable or Delete from the pop-up menu.

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.

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.

Creating Custom Fields

This chapter explains how you can collect information beyond that which CiviCRM allows by default through adding custom fields to hold the data 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:

Create a custom field set, which is simply like a container to hold these custom fields together.

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:

How will the fields in this set be used?

What types of contacts or records will these fields be appropriate for?

Will the fields have broad applicability, or are they relevant to a specific Contact Type, Event, Financial Type, etc.? For example, a field which stores a person's entree choice at a dinner event should be assigned to the Participant record, and not to the Individual Contact record; this data describes the person as a participant in an event (they might not have or make the same choices for another dinner).

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 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 > Customize Data and Screens > Custom Data. This screen 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.

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:

Activity: fields that may be assigned to all activities or to a specific activity type, such as Meeting or Phone Call.

Addresses: creates an address block, which allows the administrator to create additional fields related to an address.

Contacts: fields that may be assigned to all contacts.

Contributions: fields that may be assigned to all contributions or to a specific Financial Type, such as Donations or Event Fees.

Events: fields that may be assigned to all events or a specific event type (e.g., Conference or Fundraiser). These fields are applied to an actual event, not the participant registration record.

Grants: fields specific to grants.

Groups: displayed in the Group settings (note that these fields are not searchable).

Household: fields specific to the Household contact type.

Individual: fields specific to the Individual contact type.

Memberships: fields that may be assigned to all membership records or to a specific membership type.

Organization: fields specific to the Organization contact type.

Participants: fields that appear on the participant registration record. There are three options for  these: general fields applied to all registration records, role-type fields assigned to a specific participant role, and event participant fields assigned to a specific event.

Pledges: fields specific to pledges.

Relationships: fields that may be assigned to all relationship records or to a specific relationship type, such as "Spouse of" or "Employee of".

Order

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

Multiple record fieldsets

By default custom data sets have a 'one-to-one' relationship to the entity they are attached to. For example, one field set for a person's physical attributes which contains one field for their height and one for their eye colour will be attached to one individual record. This makes sense because we only ever need to record one eye colour and one height for each person.  However, in certain circumstances, we want to record multiple custom field sets for a single contact, for example, when recording a person's educational history. In this case, a single person may have multiple educational degrees, so a custom field set about educational history, which contains fields for subject, institution, and grade, should allow multiple records, and this is what multiple record fieldsets allow.

You can only add multiple record field sets to contacts - you can't add them to other entities. To use this option, select the "Does this Custom Field Set allow multiple records?" option. A few things to bear in mind when creating mutiple record custom field sets:

Multiple data applies to the whole field set, not to individual fields.

Multiple data be can only be added to Contacts. It cannot be added to Activities, or Contributions, etc.

Mutiple data cannot currently be exported

Before deciding to model something as a multiple value custom field set, you may wish to consider whether it could or should be modelled as an activity. For example, an educational degree could be an activity with custom data added.

Display options

The display style tab is only visible for custom data fields attached to contacts. We can choose to display contact field sets either inline, i.e. on the summary screen, or in their own tab. Whether you use a tab or inline depends on a number of factors. For example, how frequently do you need to access the data, how large is the data set, etc.  You can switch between display styles at a later date if you so wish.

You can also 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 amount of space taken up by the data when the page opens. A similar "collapsed" property is available for the display of custom data in Advanced Search.

There are two options for displaying in a tab. Tab and Tab with table.

Tab with table provides a concise overview of the data in the set. New records can be added and existing records can be edited in pop-up windows. Under more there is the option to "copy a record".  For consecutive records that have the same value in many fields this lets you edit just one or two fields and save the copy as a new record.

Tab displays data in a similar format to the inline style.

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 the field (keep the Activate option unchecked), 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.

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.

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.

Field label

The text next to the field when displayed to the user. Text entered 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 filling out forms on websites. When you create a custom field, CiviCRM presents a dropdown list of data types from which you can select that which best represents the data you plan to store. The menu on the left (shown open in the following figure) indicates the format of data you wish to store, whereas the menu on the right indicates the way you want to interact with the user.

The types of fields are:

Alphanumeric (i.e. text and number fields), which can be of the following types:

Text: a simple area in which users can enter text.

Select: a dropdown box which limits choice to one selection.

Radio: a list of options where you can make one selection. Unlike a Select box, all the options are visible on the screen at the same time.

Yes and No: a special kind of radio list with two contrasting options.

Check-box: a list of options that allows multiple selections.

Multi-select: a list of options in a single box. You can select multiple selections using control+click.

Advanced Multi-select: two lists side by side in which items can be moved from one to the other.

Autocomplete select: an autocomplete widget. The user can start typing, and when the text entered uniquely identifies a selection, the field automatically fills in the complete selection.

Note: a longer text box which allows multiple lines. Notes come in two flavours:

plain, and

rich text, which displays a WYSIWYG editor that allows HTML.

Integer, i.e. a whole number. This can be displayed as a:  

text box

select box

radio list.

Number: i.e. any number that includes decimals, such as 3.175. This can be displayed as a:

text box

select box

radio list.

Money: similar to a number, but treated according to the local currency as configured in CiviCRM's administrative pages. This can be displayed as a:

text box

select box

radio list

Date: a way of entering a date (and optionally time) value using a calendar widget. You can set a range of years which can be selected prior to and after the current date.

State/Province: a list of available geographical locations as configured in CiviCRM's Localization settings (Administer > Configure > Global Settings >> Localization). Can be offered as either a select box or a multi-select box.

Country: a list of geographical locations. Can be offered as either a select box or a multi-select box.

File: offered as a browser where the user can select and upload a file.

Link: an active internet hyperlink.

Contact Reference: an autocomplete widget for an existing CiviCRM contact.

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.

Display in Table?

This check box only appears when you are creating a field in a multi-record field set that you have elected to display as tab with table.  It is checked by default. If you unselect this then the field will not be displayed in the table. You might want to do this for less important fields if you have a large dataset that is too wide for your screen.

Fields hidden in the table view will still be available when adding a new record or viewing, editing or copying a particular row.

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 will not make a 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.

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.

The help text 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 (see 'profiles'). The person creating the profile can remove or change the help text there without impact on the original custom field definition.

Required

When selected, 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 and check the Required field later within the profile.

Is this Field Searchable?

Makes the 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 do not 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 displays 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:

To store data imported from another system that you want available for reference to the user, but do not want them to be able to modify.

To store data that is not entered directly through the user interface but rather through a method set up by your developer. 

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 create a new set. You can enter these values while creating the field, or enter the values later. The option's label is displayed on the form, while the option's value is stored in the contact record.

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 may go to this screen at a later date to modify the label, order and active status of any multiple choice option, or add more choices. 

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

Inactive options are hidden when the field is presented.

Managing custom field sets.

You can view a listing of all the custom fields in a custom field set at any time by navigating to Administer > Customize Data and Screens > Custom Data and clicking 'View and Edit Custom Fields' for the relevant field set.

As well as the expected options of edit field settings, edit multiple choice options (if applicable), preview, disable or delete, you also have the option to Move a custom field to another data set.  You can move custom fields between sets used for all contacts or for contact sub-types but otherwise you can only move fields between data sets of the same type.

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 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 where they could be 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:

Data that can take a wide range of values, such as a person's address or biography, should be stored in an alphanumeric custom data field.

Custom data fields can be grouped and displayed on their own tab on the contact's record.

As the name implies, Groups are used to group contacts. For instance, you'll probably assign board members to one group, staff to another, volunteers to a third, and so on. If you use Drupal, you can assign permissions based on group membership. You can also define a group that CiviCRM automatically adds contacts to and deletes contacts from, based on some characteristic. This feature is called a Smart Group.

If you plan to use CiviMail for mass mailings and you want certain contacts to get a particular mailing, those contacts must be assigned to a Group. For instance, you may want a press release to go only to certain contacts; those contacts should be assigned to a particular group. This group could be a Smart Group.

Both Tags and Groups can be structured hierarchically. For instance, a group or tag labeled 'Regions' can have a subgroup or subtag for each geographic region your organisation covers (see "Case study in hierarchical tags" later in this section).

Tags support more powerful search options than data fields or groups. For instance, visitors can search through multiple tags with both AND and OR operators. Data fields support only lists of words (which is effectively the same as an AND operator), except for fields represented as check-boxes, which support OR operators.

Tags have a more sophisticated user interface than data fields or groups. The interface allows the visitor to add and remove tags without reloading the page in edit mode.

Custom data fields can be assigned to a specific record type (e.g., only households), whereas tags will be assigned to all types once the tags are defined.

Custom field set storage limitations

A large number of custom field sets or custom field sets with a larger number of fields may cause problems when searching, exporting data or running reports. It is hard to give specific limits on the number of data sets you should create or the number of fields that you should add to field sets because a lot depends on the type of data you are collecting, and the server that your installation is hosted on, but if in doubt, you should discuss with your system administrator or CiviCRM service provider

Profiles

A Profile is a collection of fields from your database. Profiles are a powerful tool that have many different uses across all components of CiviCRM. Profiles are used to collect data (e.g., on a sign-up form), and to display data to the user (e.g., as a member directory). They can be used both internally (e.g., to create simplified data entry screens for  staff) and externally (to display up-to-date information in from database).

You can add any core and custom fields to a profile, including multi-value custom fields.  There are also a couple of other special fields you can add to profiles, namely, Groups, which will include all set of checkboxes - one for each of your public groups, and tags, which includes all public tags.

By creating a Profile, you are able to pick and choose only those fields that are relevant for a specific purpose. The diagram below provides a visual explanation of how existing fields become part of a Profile.

This section will outline how to use Profiles for both collecting and sharing data, and share several ways of using profiles that can save time for anyone managing data in your organization.

Different uses for Profiles

This section briefly discusses many different ways that Profiles can be used. You can find step-by-step instructions for creating and using Profiles later in this chapter.

Collecting information on public pages

A Profile can be used to collect information from your constituents. Profiles can be displayed on standalone pages, or embedded into contribution, membership sign-up, and/or event registration pages. You can add more than one Profile to a page. You can also choose required fields and add text in the Profile that will help users fill out the form.

Some examples:

A volunteer sign-up form containing the predefined fields for first name, last name, mailing address, and a custom field for volunteer interests

A Profile containing custom fields about food preferences that can be added to the registration pages for any event where food will be served

For example, this profile is being used to collect address information on a donation page.

Displaying information on public pages

A Profile can display information, from the database, on public pages. This saves time, because you only have to enter information in your database, rather than in your database and on your website.

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. Also, an organization that wants to thank its donors publicly can list their names on a web page as soon as contributions are made.

A mini case study: Native Americans in Philanthropy (NAP) wanted to create a membership directory that their members could use to search and connect with each other. 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. Using a searchable Profile on their website instead meant significant resource savings and, because their website became a portal for their members to connect, it helped to advance their mission.

Details on using Profiles this way are included later in this chapter.

Customising your user interface

Profile forms may also be used as simplified data entry forms. 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 that shows only the fields they need to input. This greatly simplifies data entry and reduces the chance of data being entered incorrectly.

You can also use a Profile to display selected fields in the results of an advanced search. For instance, you could create a Profile that includes the phone number field and a custom field for volunteer interests; when used to display search results, it would provide an on-screen call list for your volunteer coordinator.

Details on using Profiles this way are available in the Customizing the User Interface chapter in Initial Set-up.

Updating information in batches

There is often a need to update a large number of records all at once. For example, after an event, you may have an attendance list, and you want to mark everyone who registered as Attended or No-show accordingly. Or, you may want to update the Thank-You Sent field for a week's worth of donations all at once.

CiviCRM has a function called Batch Update via Profile, which is available from the -actions- dropdown menu for most kinds of search results (Search, Advanced Search, Find Contributions, Find Memberships, Find Participants, and Find Activities) and from the event participant lists generated from the Manage Events screen. 

The Batch Update via Profile function pulls up a view of your search results containing the fields in your profile and allows you to change the contents of the fields on a single screen and save them all at once. Details on using profiles this way are included later in this chapter.

Managing email lists

Another use of Profiles is to present a form where people can sign up to receive emails from your organisation. Groups that you use to track different email lists can be added as check boxes, and when visitors to your website submit the form, they are automatically added to the email lists they have checked.

Details about using Profiles to manage email lists are found in the Set-up chapter of the Email section of this book.

Planning your Profiles

Because Profiles can be used for so many different purposes, there are a lot of choices to make and settings to configure when setting them up. There are settings for the Profile as a whole and settings for each field you add—and the choice of what those fields are. Choices you make about one aspect will affect choices you can make about others. For example, some types of Profiles limit the kinds of fields you can include, and some combinations of fields are not allowed in any type of profile. Because of this complexity, it's important to understand the consequences of certain settings and carefully plan what you will use your profile for, and what you need in it, before you create it. You may also need to use some trial and error before you hit on the right solution for your purpose.

Here are some guidelines on which fields can be added to a Profile:

Profiles that are used for Search Views (known as Search Results in 4.1 and previous) can contain only fields from Contact records (and the different Contact types, e.g., Individual).

Contact fields are available in all Profiles; however, you cannot mix fields from different Contact types (e.g., Individual and Organization).

To add fields (like Street Address or Email) that apply to more than one Contact type, choose fields from Contacts rather than the specific type. The Organization field menu, for example, contains only those fields that do not also apply to other Contact types.

Except in Search Results Profiles, you can combine Contact fields with fields from one—and only one—of the other record types: Activity, Participants, Contributions, and Membership.

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.

Creating and managing Profiles

Creating a Profile is a multi-step process. First, you create the Profile and choose its settings. There are basic settings and Advanced Settings. Next, you add the fields and choose settings for those as well.

Creating a Profile and understanding Profile settings

This section walks you through all the Profile settings and explains how they affect how your Profiles work. As you look over it, you may notice that the list of settings is quite long. It's important to understand that most settings apply only to one type of Profile use. Each time you create a Profile you will be able to ignore many settings, as they will not apply to your intended use.

Go to: Administer > Customize Data and Screens > Profiles and click on Add  Profile.

Profile Name: Give the profile a meaningful name.

Used For: Your choices are Standalone Form or Directory; Search Views (known as Search Results in 4.1 and previous); Drupal User Registration; and View/Edit Drupal User Account. You can check more than one box in the Used For field, to make your Profile available for more than one use; just remember that checking Search Views will limit your field choices to Contact and Contact type records only.

Order: This field determines controls the order in which Profiles are presented when more than one Profile is included in a page. Lower numbers are displayed ahead of higher numbers. The field is filled in automatically when a Profile in created; change the number if you wish.

Pre-form Help and Post-form Help: These fields allow you to write text that appears either before or after your Profile to guide people in filling out forms.

Is this CiviCRM Profile Active?: This box is checked automatically; it is what allows the Profile to appear as options for insertion into forms and use by the Batch Update function. When creating Profiles, you obviously want to leave it checked; later on, if you want to take a Profile out of use in your organization, you can edit the Profile and un-check the box.

Advanced settings 

Profiles have a number of advanced settings which are applicable in various different contexts. Not everything listed under Advanced Settings applies to every Profile; some apply only to specific Profile uses. You can skip over any settings that do not apply to the way you will use your Profile. To access advanced settings click on the gray advanced settings bar and a set of fields will appear

Limit listings to a specific group

This is important only for Profiles that will be used to display information on your website (e.g., if you will be allowing web visitors to search your data, as in a membership directory).

Select the Group whose information you want to make publicly viewable/searchable from this field's dropdown menu. For example, if you want to display a directory of active members, create a Smart Group of all members that have a status of New, Current, and Grace.

Choose the Smart Group in this field. (Remember, smart groups are dynamic lists of records; when new memberships are added, the corresponding contact will automatically be included in the directory.) 

If you do not choose a Group from the dropdown menu in this field, by default CiviCRM will allow a search to expose every record in your database. In most cases this is a bad idea, as you probably don't want anyone who comes to your website to know who is in your whole database.

Add new contacts to a group

Any new contacts that fill out this Profile will be added to the Group. You can use this, for example, to add anyone who fills out your volunteer sign-up form to a Volunteers Group. Note that contacts will not receive any confirmation that they have been added to this group or be asked to validate their email address. Also note that if you want to offer more than one group, you might be better off using the groups profile field. 

Notify when profile form is submitted

This setting, which is is also applicable only when using a Profile as a sign-up form, allows you to send an email automatically whenever the form is submitted. For example, maybe your volunteer coordinator wants to get an email whenever anyone fills out the volunteer sign-up form. Simply enter the email address in the field; if you want to send email to multiple addresses, separate them with a comma. 

Redirect URL

This applies only to Profiles that are being used as standalone forms; it will not apply when the Profile is embedded in an event sign-up or contribution form. The Redirect URL field allows you to send people to a specific web page after they submit their form. For example, you may want to create a web page that thanks people for submitting their information.  If this field is left blank, people will be directed to a page which displays the information they've just entered. 

Cancel Redirect URL

Performs exactly the same way as Redirect URL, except that it applies when people cancel their form submission.

Include reCAPTCHA?

This applies when profiles are being filled in by anonymous users. CAPTCHA is a type of spam-blocking software that requires the visitor to fill in text displayed in a graphic file. This prevents automated web-crawling spiders (robots) from completing the form. It is highly recommended that you include it. 

You must set up a free reCAPTCHA account and enter some configuration information in CiviCRM to use this feature. Go to Administer > System Settings > Undelete, Logging and ReCAPTCHA to configure your account; instructions for signing up are included on that page.

Drupal user account registration option

This setting applies to Profiles that are used in public pages and determines whether people can or must use your form to sign up for an account with your website in addition to submitting the information on the form. This can be useful for ensuring people have to sign up for a user account as part of becoming a member or registering for an event.

WordPress user account registration option

Like Drupal, Wordpress allows CiviCRM Profiles to create accounts as described above.  Within WordPress Settings > General "Membership [ ] Anyone can register" must be clicked.

What to do upon duplicate match

This setting applies to Profiles that are used in public pages. It controls what happens when the contact data submitted from the Profile matches an existing contact record. You must choose one of these options. "Issue warning and do not save" is chosen by default. Matching in Profiles uses on the Unsupervised deduplication rule (see the Deduping and Merging chapter in the Working with Your Data section for more information about deduplication rules). Note that if there are multiple matching contacts, the first matching record is used. 

Here are the options and their effects how your form works: 

"Issue warning and do not save" This option is ignored if the Profile is embedded in an online contribution, membership sign-up or event registration form. In these cases, a contact match results in the transaction being linked to the matching contact.  In other cases, the user will receive a message that a record already exists in the database, and they will be unable to submit the form. 

"Update the matching contact" adds new information from the form to the contact record and, if there are any form fields that are already filled-out in the record, overwrites the existing record fields. For example, if the form includes address fields, the text that the user enters in the form will replace what was already in the database address fields. 

"Allow duplicate contact to be created" ignores any potential matches and creates a new contact record for all submitted forms. This means that all form submissions will be saved and no data will be overwritten; however, it may produce a lot of duplicate records that will need to be deduped later (see the Deduping and Merging chapter in the Working with Your Data section). 

Proximity search

This applies if you are using the Profile for a searchable directory; it adds a proximity search block to the search criteria. This block contains a field for start address, and another that allows the user to set a search radius (how far from the start address they want to search). Choose None if proximity search is not relevant to your directory, Optional if you want to offer proximity search to your users, and Required if you want to force the user to enter a start address and a search radius.

Enable mapping for this profile?

This applies only if you are using the Profile for a searchable directory; it adds a map to the search results.

Include profile edit links in search results?

This applies only if you are using the Profile for a searchable directory; it adds a link in the results listings to edit the Profile fields in the returned contact records. Only users with permission to edit the result contacts will see this link.

Include Drupal user account information links in search results?

This applies only if you are using the Profile for a searchable directory; it includes a link in the results to the resulting contacts' Drupal user account information (i.e., their My Account page). This link will be included for only result contacts who have a user account on your website.

Once you've 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.

Adding fields and choosing field settings in Profiles

This section walks you through all the field settings and explains how they affect how your Profiles work. As with the overall Profile settings, not all of them are necessary to consider for each use.

Click Add Field.

Field Name: Choose the record type where your desired field appears from the - select - dropdown menu. This will bring up a secondary dropdown menu listing all available fields for that record type. Choose the field you want to add to your Profile. 

Field Label: This is the field label that will display on all uses of your Profile. It is prefilled with the default field label. However, the default field labels are often confusing for users of your forms, so you can rewrite them here. For example, the Postal Code field can be renamed Zip Code if your audience is more familiar with that term.

Required?: Check this box to make this required anytime the Profile is used. This is most useful when you want to make sure that certain information (e.g., First Name, Last Name, Email) is always included in a form submission. (This is not relevant to Search Views usages [known as Search Results in 4.1 and previous].)

View Only?: Check this box to allow users to view but not edit this field. If your Profile is used to expose search results, fields marked View Only will not be included. This setting is not relevant when a Profile is being used only to collect information.

Visibility: If the Profile is being used for a searchable directory, set the Visibility of any fields you want to include on the search form to Public Pages or Public Pages and Listings. For fields that will be used on sign-up forms, set Visibility to User and User Admin only. This ensures that other visitors to the form can't view any data from the database. To use fields for Search Views, you must set Visibility to Public Pages or Public Pages and Listings. Choosing either of the Public Page options pops up two additional settings:

Searchable?: This applies only to searchable directory uses. Check the box if you want to include the field in the search form.

Results Column?: This applies only to Search Views (known as Search Results in 4.1 and previous). Check it or the field will not appear in your Search View.

Field Pre Help and Field Post Help: These fields allow you to write text that appears in the user interface to guide people in filling out forms. Field pre help appears inline. Field post help will create a small speech bubble which when clicked appear in a yello

Order: You can use this field to control the order in which fields display in the Profile. Lower numbers are displayed ahead of higher numbers. 

Active?: Leave this box checks to ensure that the field appears when the Profile is used. 

Click Save and New to add more fields to the Profile, or Save if you have no more fields to add.

Managing Profiles

All your profiles are available for viewing and editing at Administer > Customize Data and Screens > Profiles. You can add fields and edit field settings (at the Fields link) and change Profile settings (at Settings). You can also look at how your Profiles will appear, get links and embed code for your Profiles, and copy Profiles to use as a basis for building other Profiles (at more).

Using Profiles

This section contains specific instructions for  the different profile uses discussed above.

Standalone forms with Profiles

There are two ways in Drupal and Joomla! to use standalone forms once you have created your Profile according to the instructions above:

Use the page created automatically by CiviCRM to hold the Profile. Get the link to this page at Administer > Customize Data and Screens > Profiles. Click the more link  next to your Profile and choose Use Profile-Create Mode from the pop-up menu. You can then publish this link wherever you want: in an email, on a blog, etc.

Paste the HTML code for the form in a page you've built on your website. Get the code at Administer > Customize Data and Screens > Profiles. Click the more link next to your Profile and choose HTML Form Snippet from the pop-up menu. Copy the code that appears on the next screen and paste it wherever you want. 

In WordPress, there is an additional third way. When creating or editing a post, click on the CiviCRM button to insert a CiviCRM shortcode into the post.

On the popup form, select Profile as the desired frontend element.

Use the second select widget to specify the profile you would like to use. Finally, select the purpose of the form — create, edit or view — and click Insert Form.

Multi-value fields in profiles

Multi-value custom field sets allow you to have more than one set of custom data per contact. They are handy for modelling data that repeats, for example, work experience data. You can expose these multiple value custom fields via profiles.  In the screen shot below, we have created a profile that is used to collect name and work experience data.  Notice that the multi-value custom data appears slightly differently in the profile to facilitate adding, editing and deleting multiple instances of these records.

Making directories with Profiles

To put a directory onto your website:

Create your Profile as described above.  Be sure to consider these Advanced Settings, as they are especially helpful when using profiles for directories.

Enable mapping: a really cool feature available in CiviCRM is giving visitors the ability 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 > System Settings > Mapping and Geocoding.

Include profile edit links: check this box if you want to include a link in the directory listings to allow people to edit data in 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.

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:

are searchable in the directory

appear in the results columns of your search

appear in the record detail View page.

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

Visibility for all fields in your directory must be set to Public Pages or Public Pages and Listings. The difference between these two options is that those configured as Public Pages and Listings will have the field in detail view hot-linked, enabling the user to generate a follow-up search for other records which also have that same field value. For example, you might set City to Public Pages and Listings. After the user conducts a search and views the details for a record they can click on the city value and run an immediate search. The search will run as if they had selected that city in the profile search screen.

The Searchable option determines if visitors to your directory can search the directory by this field. In common directory uses, almost every field is set to searchable. The more fields you set to searchable, the more power you provide to your visitors to find the information they need.

The Results Column check-box determines if the the field is displayed as a column in the list of results. For example, your directory may have a field for website, and if you set the website field to appear in the results column, it will appear in the results table. If you do not check the results column the field will still appear in the view mode for a record. In other words, checking Results Column? will allow the field to appear in the results column AND in detail view mode.

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

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

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:

Drupal: link to the directory search page using this path: http://www.myorganization.org/civicrm/profile?reset=1&gid=N where N is the ID of the profile directory.

If you add &force=1 to the above URL it will directly show a result set.

If you add &force=1&search=0 it will hide the search criteria and directly show the result set.

Joomla!: use the Menu Manager to create a front-end menu item. After creating a new menu item, select CiviCRM and choose the profile search option. In the parameters pane, choose the specific profile to use.

Wordpress: this feature is not yet implemented.

You can also prepopulate any search criteria in the URL. These options are described here: http://wiki.civicrm.org/confluence/display/CRMDOC/Linking+Profiles

Batch update via Profiles

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. You can edit up to 100 Contacts at one time using the Batch Update via Profile function.

From the search results, go to the dropdown menu -more actions- .

Select Batch Update via Profile from the list.

You will go to the Batch Profile Update screen.

From the drop-down list, choose the the Profile you want to use and click Continue.

You will go to the Batch Update screen. You will see a grid with the fields in your profile. Batch Update via Profile

Update field values for each contact as needed.

To set a field to the same value for all rows, enter that value for the first contact and then click the Copy icon (the image of two documents that is next to each column title). The value will automatically be copied into all the records displayed.

Click Update Contacts to save all your changes or Cancel to cancel the changes.

Batch update limitations

You cannot perform batch updates for different types of contacts (individuals and organisations, for example) at the same time.

If you wish to update participant fields, you must do the update from a Find Participants search (and only include participant fields in your profile).

You may perform a batch update for no more than 100 records at a time.

View/edit user account /new user registration with Profiles

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:

Create a profile that is used for User Registration:

addprofile_usedfor_reg 

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:

Create a new profile, or navigate to an existing profile and click Settings.

Select View/Edit User Account in Used For.

Click Save.

Add the fields you want people to be able to edit from their Drupal My Account page.

 Note: the profile must include only fields related to the Individual contact type.

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 Customize Data and Screens > Profiles > click Settings against a profile. 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.

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.

Including Profiles in forms in CiviCRM components

Often you will want to define certain fields for inclusion in event registration and contribution pages. 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 about including Profiles in contribution pages, event registration pages, and membership sign-up pages in the Set-up chapter of Contributions, Events, and Memberships.

Other sources of information about Profiles

Read more about Profiles in the following chapters:

In the Customizing the user interface chapter of Intitial Set-up

In the Set-up chapter of Email

In the Set-up chapter of Contributions

In the Set-up chapter of Events

In the Set-up chapter of Memberships

Alternatives to Profiles

As you have seen, profiles can be put to a lot of different uses.  It is worth bearing in mind that there are alternative approaches for many of these use cases.  The alternatives available to you depend on the CMS that you are using and your skill set, and have advantages and disadvantages  We've listed a few of the common ones below for you to investigate.

Drupal specific alternatives

The Drupal Views module can be used to make sophisticated displays of CiviCRM data. For example you might want to display a list of members on your public website using Views.

Drupal Webform-Integration is the most powerful form-builder for CiviCRM and includes many features missing from profiles, such as the ability to work with multiple contacts, events, memberships, and relationships, and offers greater flexibility in how forms are displayed, offering pagination, draft-saving, advanced spam-control, and conditional fields. For more information see the Drupal Integration chapter or https://drupal.org/project/webform_civicrm.

You can add fields directly to Drupal user accounts without using an embedded profile. These fields won't be available in CiviCRM but they will be more available in Drupal, so depending on why you are collecting this information, that may be appropriate for you.

The API

With some basic coding skills (which if you are keen and reasonably technically minded you might be able to pick up in a day or so) you could use the API to flexibly display data on your website. See the Developer Documentation wiki (http://wiki.civicrm.org/confluence/display/CRMDOC/Develop)  for an introduction to using the API. 

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.

Imports can also be used to update existing data. This will be covered in the final section of this chapter.

Considerations before importing

For more details on how to think about your data before importing into CiviCRM, please read the section on "Organizing your data", especially "Mapping your data into CiviCRM". 

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 will focus on the import process for contacts. The processes for other data are similar.

There are two ways to import data:

from CSV files. Most database and spreadsheet applications (e.g. OpenOffice.org Calc, Google Spreadsheets, Microsoft Excel) can create and manipulate files in this format. It is often easier to view and clean your data when it's in a CSV file than while it's still inside your old database.

Each column in your CSV file will map to a field in CiviCRM, so make sure you use a different column for every distinct bit of information.

Depending on your country or region, fields in your CSV files might be separated by semicolons (;) instead of commas. If so, you'll need to change the Import/Export Field Separator value in the CiviCRM Localization settings by going to the navigation menu and choosing Administer > Configure > Global Settings > Localization.

from another SQL or MySQL database stored on the same server, using an SQL query. (This option is only for advanced users who have a clear understanding of server and database administration.)

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:

Always test your data import with a small subset of your records. After importing the test set, visit the records within CiviCRM and ensure that the data was imported and functions as you expected.

It can be helpful to create a test contact that has every attribute you've defined in your existing data set. Then import the contact and check results to ensure that CiviCRM correctly represents all the data.

When you map the columns or fields from your source data to CiviCRM fields during the import, CiviCRM can save this field mapping as an import map for future use. This is helpful if you will be importing multiple files with the same structure. To save an import map for future use, click the "Save this field mapping" check-box at the bottom of the Match Fields screen of the import wizard and enter an appropriate name and description. To reuse a saved import map, select it from the Load Saved Field Mapping dropdown menu on the Choose Data Source screen (step 1) of the import wizard.

If your imports are timing out or taking too long, try splitting up the imports into smaller batches. If you have the appropriate permissions on your web server, you can also increase the memory_limit and max_execution_time values in the file php.ini.

You can add all of the contacts imported in an import to new or existing groups or tags. All of the contacts in a single import will be given the same groups and tags. This limitation has a couple effects on your import:

Make sure that you assign groups and tags that are applicable to every contact in the imported set. If you need to assign groups or tags on a contact-by-contact basis, import contacts in small, discrete batches in which all contacts share the same tags and groups. Alternatively, you can create searchable custom data fields in CiviCRM that contain the groups and tags that you want to assign to imported contacts. After the import you can run searches on those fields and use the "Add Contacts to Group" or "Tag Contacts" batch actions on the search results.

You can use this feature to manage the import. Consider adding contacts to a new group or tag that indicates what batch of imports the contacts were a part of, thereby allowing you to easily identify when a contact was imported and undo an entire import if necessary.

CiviCRM stores first names and last names in separate fields, so these should appear as separate columns in your CSV file. The same goes for city and postal code/zip code. Most spreadsheet programs contain tools that automate the process of splitting text across fields.

Ensure that your country names are expressed in the same way as they are in CiviCRM, i.e., 'United States', not 'United States of America', and 'United Kingdom', not 'Britain'.

If you are importing multiple locations, the first location will be set as the primary location address. You may want to move your columns around to ensure that the desired location becomes the Primary Location. You may also need to split your import so that some records have one type of record as their Primary Location, while others have a different one.

If you are importing data into multi-choice (e.g. check-box or radio button) custom fields, your data source can use either the label (what's visible to the user in the CiviCRM front end) or the value (what's actually stored in the database for that choice). CiviCRM will recognise it and import it appropriately. When importing into multi-choice core data fields, you can specify only the value(s) in your data source, not the label.

If you are updating multiple choice options, new values will replace the entire field. For example, if you update the value of the Colors field to be "orange" for a contact that currently has Colors set to "blue", the result will be that Colors is set to orange, not orange and blue.

Make sure your data source uses an accepted date format and that you select the same date format on the Choose Data Source screen of the import wizard.

Make sure any name prefixes and suffixes you use have been set up in the administration interface (go to: Administer > Option Lists in the navigation menu).

If you plan to do additional imports of related data that's associated with your contact data, e.g. contribution data, event participation data, membership data, you can make things easier by ensuring that your contact records have unique IDs that are also associated with the related data. When you do the initial import of your contact data, import these unique IDs and map them to CiviCRM's External ID field, so that you can then use your original (or legacy data) IDs to match to the contact records records for later imports of the related data.

Required Fields for Contact Imports

When preparing your data import it is helpful to know what fields are required for Import. You'll want to be sure that these fields are included in your CSV import file. Below is a list of the required fields. Please note that the field with the identifier (Match to Contact) is required for deduplication purposes.

Email (Match to Contact)

External Identifier

First Name

Last Name 

Setting up a CSV file for importing

Example of spreadsheet .csv format

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.

Note that imports use the default unsupervised 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:

Skip: skip the duplicate contact, i.e. leave the original record as it is.

Update: update the original record with the database fields from the import data. Fields that are not included in the import data will be left as they are.

Fill: fill in the additional contact data, if it contains fields that are missing or blank in the original records, and leave fields which currently have values as they are.

No Duplicate Checking: this inserts all valid records without comparing them to existing contact records for possible duplicates.

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.

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.

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. 

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.

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.

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 separate 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.

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.

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.

Import Activities

When preparing your data import it is helpful to know what fields are required for Import. You'll want to be sure that these fields are included in your CSV import file. Below is a list of the required fields. The Contact ID field is used to cross reference and attach the activity to the contact so it must match the contact ID of the contact in the system exactly.

Activity Date

Activity Type ID

Activity Type Label

Contact ID (Match to Contact)

Subject

The import tool for Activities is similar to that of contacts, but there are some pre-requisites which must be met before running the import. Firstly, Activities cannot be imported unless the contacts and Activity Types already exist in the database. If you need to import Activities for contacts that are not yet available, run a contact import first, preferably including a unique external identifier (most often an ID assigned by the database or application you are importing records from).

Remember, CSV files must be less than 2MB in size. If the file size exceeds this, create multiple CSV files and distribute the data between them.

Import Contributions

You can insert new contributions or update existing ones.

If you insert new contributions, your CSV file must include at least the following fields:

Contact Id or External Identifier or all the fields used in your Unsupervised Duplicate Matching rule (to match to an existing contact)

Financial Type

Total Amount

If you want to update existing contributions, your CSV file must include at least the following fields:

Transaction ID or Invoice ID or Payment ID (to match to an existing contribution)

Financial Type

Total Amount

You can use also use update existing contributions to import new or change existing data in other core or custom contribution fields. When doing this you will still need to include an ID to match to an existing contribution and the Financial Type and Total Amount fields in you CSV file, even if the values you import for those fields are no different from the values already in your database.

Import Memberships

You can insert new memberships or update existing memberships.

If you insert new memberships, your CSV file must include at least the following fields:

Contact Id or External Identifier or all the fields used in your Unsupervised Duplicate Matching rule (to match to an existing contact)

Membership Type

Membership Start Date

If you want to update existing memberships, your CSV file must include at least the following fields:

Membership Id (to match to an existing membership)

Membership Type

Membership Start Date

You can use also use update existing memberships to import new or change existing data in other core or custom membership fields. When doing this you will still need to include Membership ID to match to an existing membership, and the Membership Type and Membership Start Date fields in you CSV file, even if the values you import for those fields are no different from the values already in your database.

Import Participants

In each import session you can either insert new registrations or update existing participant records.

If you insert new registrations you need to decide whether to restrict registrations for each event to just one per person (set On duplicate entries to Skip) or to allow duplicate registrations for the same event from a given contact (set On duplicate entries to No Duplicate Checking).  In either case your CSV file must include at least the following fields:

Contact Id or External Identifier or all the fields used in your Unsupervised Duplicate Matching rule (to match to an existing contact)

Event ID

Participant Status

If you want to update existing registrations, you should set On duplicate entries to Update. Your CSV file must include at least the following fields:

Participant ID (to match to an existing registration)

Event ID or Event Title

Participant Status

You can use also use update existing registrations to import new or change existing data in custom participant fields. When doing this you will still need to include Participant ID to match to an existing registration, and the Event ID or Event Title and Participant Status fields in you CSV file, even if the values you import for those fields are no different from the values already in your database.

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:

in any of the search tools

when viewing contacts in a group

in component-based search results, where the resulting records reflect the component specific data rather than simply core contact data. For example, from the Contributions > Find Contributions search, you could export your donors and their contact information for use in a thank-you letter in which the total amount donated is included.

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.

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 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

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

Deduping and Merging

What is deduping?

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 on your site without realising they're already in your list of contacts (maybe with their names spelled differently or with a different email address).

Some examples of scenario's where duplicate contacts can enter your database:

When an administrator or user creates a new contact through the admin interface and this contact already exists.

When a contact is created by self serving or signing up online and the user has done this with another email address or name.

When contacts are imported to the database.

CiviCRM Features for deduplicating contacts

CiviCRM is equipped with several features for dealing with duplicate contacts. Some attempt to avoid the duplicate contact from being created, others help you to search, identify and "merge" duplicate contacts found in your database.

These features are split between those that act "automatically" (known as "unsupervised" from v4.3 on), and those that act manually (known as "supervised" from v4.3 on).

These features include:

Scanning your database for duplicates using a selected dedupe rule (see below) and merge duplicate contact data as needed.

Manually selecting two contacts using the search and then choosing to merge these contacts.

Automatically scanning your database and suggesting duplicates when contacts are added or edited via the user interface.

Automatically merging a person's details to an existing contact when a person signs up online for items such as Events, Membership, Contributions and Profile pages.

Automatically merging a person's details when importing contacts.

Dedupe rules

Dedupe rules are a way of specifying to these features whether CiviCRM should consider contacts to be duplicated. For example a rule could state that when the email address and first name between two contacts match CiviCRM should consider these contacts to be duplicates.

Using the default rules to find and merge duplicate contacts

If you do not want to configure the dedupe rules at this stage you can simply use the default rules to find duplicates from your database.

Firstly view the dedupe rules. Go to Contacts > Find and Merge Duplicate Contacts in the navigation menu. This displays the following screen:

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

Start by looking for dupes using the "Individual unsupervised" rule: click the Use Rule link (contact type "Individual" at the usage "unsupervised").

Select All Contacts or a particular group.

Click Continue.

If duplicates are found, merge or delete the duplicate contacts.

Now look for duplicates using a "supervised" or "general" rule to find those that were missed with the stricter rule: click the Use Rule link for "Individual supervised" (contact type "Individual" at the usage "supervised").

Select All Contacts or a particular group.

Click Continue.

If duplicates are found, merge or delete the duplicate contacts.

Different rules are configured for each contact type (individuals, organizations, and households.)  A default supervised rule and a default unsupervised 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.

Understanding dedupe rules: Supervised, Unsupervised and General

CiviCRM now includes three categories of dedupe rules:

Unsupervised: The 'Unsupervised' rule for each contact type is automatically used when new contacts are created through online registrations including Events, Membership, Contributions and Profile pages. They are also selected by default when you Import contacts. They are generally configured with a narrow definition of what constitutes a duplicate so as to avoid a false match being merged accidentally.

Supervised: The 'Supervised' rule for each contact type is automatically used to check for possible duplicates when contacts are added or edited via the user interface. The UI will alert the user if a contact they are creating matches another contact using the rule. The user can then decide whether to edit the existing contact or to continue to create a new contact. Supervised Rules should be configured with a broader definition of what constitutes a duplicate as the user can decide whether to act on the rule or not.

General: You can only configure one 'Unsupervised' and one 'Supervised' rule for each contact type, but you can configure any number of additional 'General' rules to provide other criteria to scan for possible duplicates.

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. 

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 limit the search to a particular group. If you choose to limit the search to a specific group, CiviCRM looks for duplicates where at least one of the contacts in any identified duplicate pair is in your selected group. Contacts of the type to which the rule is assigned will be scanned and compared. If the match between two contacts meets or exceeds the rule's threshold score, 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 at the top of the page.

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.

Click Merge... to complete the merge, or Mark this pair as not a duplicate if you believe the two contacts are not the same.

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.

Select the duplicate contacts from your search results by clicking the check box at the left side of each record.  

Select Merge Contacts from the - more actions - menu.

Click Go.

Follow the normal steps for merging duplicate contacts. 

Merging multiple contacts simultaneously

Once a dedupe rule has been used, the option to "Batch Merge Duplicates" will be available beneath the list of duplicates discovered. This feature will merge all contacts under the given rule together, provided their are no data conflicts. For instance, two individuals named "Michael Blake" may have been matched based on identical first and last name, with neither having an email address on record. If the data held on both contacts is either exactly the same, or one contact contains information the other does not (e.g. a work phone number, where the other has a mobile), the two will be merged. However, if both contacts have different home telephone numbers, the records will be skipped; the two contacts will not be merged.

Once a batch merge has been completed, you will be returned to the original list. If any of the records were skipped due to a data conflict like the example above, the message shown below will be displayed. To view an updated list of duplicate contacts (those that were not merged by the duplicate process) you must click Refresh Duplicates; the page will not refresh automatically, just in case your database is very large, and searching for duplicates would cause a significant delay. You may then continue to assess and merge the remaining duplicates manually.

WARNING: before you begin to consider using batch dedupe, please take note of the following:

This feature is intended for use with large data sets that have strictly managed field structures. If you have a small database with only a few duplicates, we recommend you merge them manually using your own judgement.

Once merged, the links between the duplicate contact and records elsewhere in the system will be transferred to the original contact (e.g. event participant records, groups, tags, contributions, activities, cases and memberships). You will NOT be able to reverse this change.

Duplicate records, once merged, will be deleted and are not recoverable. We strongly recommend backing up your data before running a batch merge.

Mail merge functions (a.k.a. using Tokens)

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 is further addressed in the Email section of this book.

Tokens

Tokens are the equivalent of mail merge fields 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. For example, use the Postal Greeting token to include a customized greeting for each recipient in your PDF letters. Most contact fields, including custom fields you've created, are available as mail merge tokens. You can view available tokens by clicking 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 in emails, such as a link to an opt-out 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.

Checksum token

A particularly useful token is the checksum. The checksum allows you to give people links to  contribution forms, profiles, petitions, and event registration forms that are prefilled with information that is already in their contact record.   The image above shows an example of this.

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), or you could use a checksum token to allow access to a profile through which they can modify their information without having to log in.

Go to this page for further details on using the checksum token: http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens.

Custom tokens 

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/Tokens.

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 postal 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.

What types of mailing do you send out to your constituents?

Are mailings always sent to everyone in the database or are they frequently targeted to a select group of contacts?

How do you want to greet recipients (e.g. "Dear Jane" or "Dear Jane Doe")?

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

Generate labels: print out standard address labels when you don't need to personalise the content, for instance to send a printed brochure.

Export contacts and do a mail merge to an external tool (such as OpenOffice or Microsoft Word). Refer to the chapter on Exporting earlier in this section for detailed exporting instructions.

Use CiviCRM's Print PDF Letters function to do the merge directly in CiviCRM (see below for details).

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 chapter on Scheduled Jobs in this section, and to the documentation on the wiki at:

http://wiki.civicrm.org/confluence/display/CRMDOC/Update+Greetings+and+Address+Data+for+Contacts

Print PDF letters

The workflow is to first select the contacts you want to target, then choose to print letter as a batch action. The letters will then be outputted as a PDF, allowing you to easily print them.

To create the letter:

Go to Search > Find Contacts or Find Contacts > Advanced Search; if you want to print letters for members of a Group, go to Contacts > Manage Groups and click "Contacts" next to the Group you want.

Enter your search criteria and click Search (not applicable if using a Group).

Select the contacts who will receive the letter.

From the Actions dropdown menu, choose "Print PDF Letter for Contacts" and click Go.

Review the selections under Page Format and make any desired adjustments. This is where you set your paper size, margins, and page orientation. 

Enter your text and make formatting adjustments in the WYSIWYG editor. You can also insert image files such as your organisation's logo, or a signature. Click in the body of the letter where you want the image to appear and click the Image icon. 

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.

Before you move to the next screen, decide whether the format of this letter could be used again. If so, check the Save As New Template box and enter a name in the Template Title field.

When your letter is finished, scroll to the bottom and click Make PDF Letters.

A pop-up window will offer the option of opening or saving the PDF (this is the same notification your browser will give you for any download). Open the file, review your letters, and then print them, or save the PDF and review it at your leisure.

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.

Perform the search to select the contacts you want to target.

Choose Mailing Labels from the Actions dropdown menu and click Go.

Select the mailing label style

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. 

Automating tasks

If you find yourself making the same set of decisions regularly, more often than not, CiviCRM can free you from having to make them again. Automating administrative or routine tasks, more commonly referred to as workflows, take quite a bit of work to set up, but save a tremendous amount of time in the long run. To get started, realize that every decision, no matter how arbitrary it may feel, can be made based on a set of criteria and information that satisfies that criteria. We'll help you think through what criteria you might be using to make decisions that CiviCRM could easily make for you. The second step will be to find places for information that corresponds with your criteria in CiviCRM and then teach CiviCRM which action to take in response. Here is an example: 

Goal: Automatically personalize acknowledgment letters

Focus Questions: What letters do I edit and what information do I add? Where do I find information that needs to be added? What CiviCRM features can help accomplish this task? 

Strategy: Create custom tokens and print to PDF function in CiviCRM

Custom Fields: Fund Name, Tag “Works with Organization,” Tax Receipt Pull-Down (No Tax Receipt, Extra Tax Receipt to Soft Credit, Tax Receipt to Hard Credit), Relationship “Known by Organization Staff”

Existing Fields: Thank You Letter Sent, Soft Credit

Custom Tokens: First Gift Date, Financial Type, Soft Credit Address and Main Contact

Variations in Template Language:

Include/Exclude Fund Name - based on the fact that the money was donated to the fund or as a generic donation

Include/Exclude Tax Receipt - based on information if this contribution is eligible for tax receipt

Include/Exclude Invitation for Sponsorship - based on the fact that the organization receiving this email was a sponsor in the past

Include/Exclude Invitation to Visit Office - based on the address of the recipient; if constituent is located close by, include the invitation. 

The goal refers to which routine task you would like to automate. It can be: email me a report of major donations the organization receives each day, send a reminder email to anyone who has registered for an upcoming event, remind me when it's time to follow up with a donor about an outstanding invitation to meet for lunch, send a renewal notice to anyone whose membership is about to expire, or send a reminder email to anyone who has promised to make 4 more donations to your organization. CiviCRM has the capability of doing all these things out-of-the box. To learn more about how you can set these tasks up, visit the chapters that discuss functionality of CiviCRM components (chapters like Events, Membership, Contributions, Scheduled Jobs, Reporting etc.).

But there are probably a number of other, more complicated tasks, that with a little customization, CiviCRM could do for you as well. These might include sending personalized acknowledgment letters to certain donors or giving members access to member-only content, discounts, mailings and other benefits on your site.

Answering focus questions will require reflection and research. As an expert in what you do, try to articulate what piece of information helps you realize that this person, donation or organization deserves different treatment. Maybe this individual is personally known by someone at your organization, maybe this donation requests a unique language in their acknowledgment letter, maybe this volunteer only wants to hear about opportunities to support a particular program.

When you make the decision to give someone or something different treatment, do you have to hunt down any additional information? For example, do you have to find a spouse's name or the address of someone's company? Write out what pieces of information you add or what language you change. If you are familiar with writing conditional statements, try explaining your decision making process in the following format:

If the Spouse Name field is not empty, include spouse name in the line address

If last contribution amount is greater than $10,000 and City is within the Zip Code Range 94110 to 94114, include as the last line in the opening paragraph: "It looks like you're in the neighborhood. Would you enjoy stopping by the office to speak more about our work and meet the staff?"

CiviCRM has myriad features that can be used to help you automate simple tasks. Sometimes the hardest part is finding them. The case studies available on civicrm.org can introduce you to how other organizations are using CiviCRM and subsequent chapters in this book describe what features are available and how you can start using them. If you are poking around the CiviCRM interface, the small speech bubbles can also be a great source for more information on the capabilities each field offers. To create a complicated workflow, you will ultimately want to tie several of these features together.

You will most likely have to create custom fields and custom tokens in order to accomplish your goal.  Once you have planned what task you want to automate and how, create custom fields from the Administrator Console. Create custom fields carefully. It's always easy to choose a text field, but they can be impossible to use later in reports or searches because everyone enters information differently. It's better to create fields that have pre-defined answers so spelling mistakes are not an issue. CiviCRM along with any computer program is great at executing on the basis of well defined facts. They aren't as good at comparing two facts that look the same, even if the difference is only one letter in a differently spelled word. You might also be tempted to create several Yes/No radio buttons to capture a set of facts that might work better as a drop down menu. 

To be a good database manager, you don't have to understand everything about relational databases. It can, however, be helpful to understand your system's underlying structure in order to understand some of the consequences related to that structure. 

For example, you might wonder why you can't create a friend relationship between two organizations. The organizations might be partners, but if the database was told to only recognize the relationship type "friend" between two individuals, that constraint on the database will not let you freely use relationship "friend" for organizations. A fix to that relationship definition will fix the problem but people are often tempted to find a workaround for a problem rather then actually fix the problem. We strongly recommend looking into the reasons why something doesn't work for you and addressing the problem at its root instead of applying a "patch".

CiviCRM comes with multiple pre-defined reports that should cover most of your needs, but more complicated searches may require creating custom reports. You may hesitate to hire a professional to create a proper report to search your specific criteria, but if you are currently copying/pasting information to spreadsheets, you may consider this one time expense worthwhile in the long run.

In general, our advice is to have high expectations of your CiviCRM (and other software) and automate as much of your manual work into the system as you can to free yourself from daunting administrative activities that computers can do faster and more accurately.

What is CiviContribute?

CiviContribute supports fundraising and related money management. It has two main uses:

to facilitate fundraising campaigns and collection of donations, and

to support activities by other CiviCRM components that have financial elements, such as collecting and recording payments in the Events and Member components.

CiviContribute offers a number of tools for raising money through your web site. For example, you can create contribution pages with fundraising targets, and configure a thermometer-style widget for each contribution page which can be embedded on other web sites and blogs. Personal campaign pages (e.g. sponsor my 10K run for... the name of your organisation) and the "tell-a-friend" functionality engage your supporters in raising money for your organization 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 for collection and tracking of associated payments or fees. To use CiviContribute you will need to configure a payment processor.

Scenario: Contributing to Leadership

A community arts group, Arts in Action, conducts leadership workshops for youth under 25 throughout the year. They use CiviCRM extensively in the planning and execution of these workshops, combining the CiviEvent and CiviContribute components to make the administration of the workshops as efficient as possible.

The workshops are funded in three ways: participant fees, local arts funding, and donations. Most of the donations are from previous workshop participants who have continued as Arts in Action constituents. Twice a year a call for donations towards the workshops is sent out using CiviMail, providing a link to a donations page on the site. Some donors make recurring donations, while others make one-off donations. A thank-you email and receipt is automatically sent to every donor when a payment is successfully processed. All donations are tagged for the workshops, so that Arts in Action staff can run reports showing total workshop donations and look at individual contact records to see who has donated.

Participants register and pay for the workshops via an online form. There is a flat fee for registration, with additional fees for optional workshops, food and lodging preferences. The participants make these choices in the form and pay with a credit card. If they are not already a contact within the database, a new record is created at the time of registration, and the payment is recorded in that contact's contribution record which is also linked to the workshop event.

Arts in Action allows participants to pay later, as many of the participants do not have a credit card and need to pay in cash at the workshop. CiviContribute distinguishes between an actual payment and a commitment to pay, and this information is included in the registrants report that is printed out and used on the day to check participant attendance and payment. A computer at the registration desk at the workshop is used to manually input cash and cheque payments to the participant's contribution record.

Because Arts in Action has assessed that the most effective publicity for the workshop is by word of mouth and participants bringing friends, they also enable participants to forward the registration link to friends via the "tell-a-friend" mechanism. After completing the registration form, participants can easily forward it via email or social networking platforms to their friends and colleagues who may also be interested in attending.

After every workshop, the Arts in Action accountant generates a report that shows the total income from each of the three sources for the workshop, using a report template. She also tracks trends in donations and ensures that the Board are aware of who the larger donors are. Key statistics are displayed graphically on staff members' CiviCRM dashboard.

What You Need To Know

This chapter provides information that you need to think about before configuring and using CiviContribute. CiviContribute allows you to:

accept donations and other financial contributions

process membership signups and renewals

run specific fundraising campaigns

batch enter contribution and membership payments using "batches"

report and evaluate fundraising results and trends 

Throughout CiviCRM, the term contribution refers to any financial transaction or payment taking place in the system such as a donation, event fee payment or membership fee payment. 

It is helpful to list out the types of contributions your organisation receives (or wants to receive), and identify which of those you want to track using CiviCRM. Then consider the following concepts and answer the key questions listed below before you begin to work with CiviContribute.

Key Concepts 

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 do this by defining new custom data fields. Custom data might be useful to further categorize your contributions or track additional information.

Write down all the information you want to track about your contributions, including reports (described later in this chapter), then compare your data needs to CiviCRM's predefined fields. An easy way to do this is is to look at the screen for adding a new contribution. A lot of useful functionality is built in to the core contribution fields so there's no point in duplicating them with custom fields, but your organisation may have specific needs that require custom fields.

If you do need to create custom fields to meet your needs, see the chapter Creating Custom Fields in the Understanding Your Data section.

Types and accounting codes

CiviContribute categorises contributions by Financial Type. Examples of Financial Types include event fees, membership fees, donations and grants.

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

Financial Accounts and Financial Types

New to the CiviContribute module in 4.3 is CiviAccounts which allows wider integration with accepted accounting principles and workflows typical to most organizations.

"Contribution Type Accounts" are now called "Financial Type Accounts". New to this administration page is a column named "Accounts" (see screen capture) which reflects the new Financial Account object associated with each type. Now, an organization may better manage and report in relation to both the income and expenses on a Financial Type.

For example, a fund raising dinner that charges $100/person may now allocate the true costs toward the relevant accounts i.e. $75 donation posted to the Income account named "Donations" and the $25 Cost of Sales account to "Event Fees".

As with the types, the list of associated preconfigured accounts will suit the needs of most organizations and may also be customized if your organization requires changes or additions.

You will want to check the list of Accounting Codes that are assigned to each account to ensure that they correspond with those used in your organization's chart of accounts.

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 recording and managing contributions.

Financial Types and Accounting Codes

If you need to add Financial Types or accounting codes, do this first. 

Navigate to Administer > CiviContribute > Financial Types, where you can edit one of the existing Financial Types or create a new one by clicking Add Financial Type. 

Once you edit or add a Financial 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 Financial Types or adding new types, because CiviCRM has useful built-in functionality that depends on the core Financial Types.

Premiums

Configure premiums, such as T-shirts or subscriptions, that you want to offer on your contribution pages:

Navigate to Administer > CiviContribute > Premiums (Thank-You Gifts). 

You can edit an existing premium or click Add Premium to add a new one.

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). 

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: 

Navigate to Contributions > Manage Contribution Pages and click on Add Contribution Page.

Give the page title, select the Financial 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.

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.

Select the Currency

Select one or more Payment Processors for this page (which you have previously configured). Some organizations find it advantageous to give their constituents a choice of processors. You can do this by setting up multiple processors, and checking the corresponding boxes on this form.

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.).

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. 

Select a pre-defined Price Set (for more complex payment options), OR enter up to 10 fixed contribution amounts in the table.

Check the Pledges box to give users the opportunity to pledge future payments. To learn more about configuring pledges, refer to the Pledges chapter.

Check Allow other amounts to give users the option to pay any amount they choose.

Click Save and Done.

Include Profiles

If you want to collect information from contributors beyond what is required to make a contribution only, such as volunteer age and skills, you can include existing CiviCRM Profiles at the beginning or end of a contribution page. You can also create new profiles.

Profiles used in a contribution page can ONLY contain fields which belong to:

contact records

contribution records

Profiles which include fields associated with any other record types will not be available for this purpose.

Contribution pages will always include a required email address field, regardless of whether you include any other fields in your profile(s).

Navigate to Manage Contribution Pages then for the page you wish to configure, click on Configure > Include Profiles.

Select a CiviCRM profile from the dropdown menu to be included at the top of the contribution page and/or at the bottom of the page. You can then preview your selection(s), edit an existing profile, copy an existing profile or create a new profile.
When you edit or create a new profile you will use the profile drag and drop interface pictured here.

WARNING: If you modify an existing profile whilst configuring your Contribution  page, the changes you make will apply everywhere that profile is being used. So unless an existing profile exactly matches your requirements you should copy the profile, then rename and edit the copy as required.

Click Save or Save and Done or Save and Next.

Read more about profiles in the Profiles chapter of Organizing your Data.

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.

Navigate to Administer > CiviContribute > Manage Contribution Pages.

Use the Configure link at the right-hand side of a contribution page in the list to access and edit the page.

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.

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. 

Navigate to a menu and create a new CiviCRM item. 

From the list of menu options, choose Contributions. 

In the basic parameters section, select the contribution page you would like exposed from the dropdown menu. 

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. 

Page or Post in WordPress

You can easily embed your contribution page in a post or page on your WordPress front-end site.

Login to the administration dashboard of your WordPress site.

Click on Pages or Posts > Add New

Click on the CiviCRM icon next to Upload / Insert

Select Contribution Page as your Frontend Element

Select the desired contribution page

Save the page or post, and your contribution page will automatically be embedded within your site's theme on that page.

"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/Tokens

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.

Go to Search > Find Contacts to create a list of records to receive your offline postal mail appeal (it could be your entire database).

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.

If you want to create letters for postal mailings you can do this using CiviCRM's internal Print PDF letter feature, or you export the list as a CSV file and use mail merge to a word processor. 

To export a list:

Select all records or a subset using the checkboxes, and from the "- actions -" dropdown menu choose Export Contacts and click Go.

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.

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. 

Click Export to generate the CSV file.

Click Done when you have finished to return to the contact list.

Creating postal 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:

From the "- actions -" dropdown menu, select Mailing Labels. 

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. 

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.

Batch Entry of Contributions or Membership Payments

The Batches feature allows you to enter multiple membership or contribution payments as well as add new contacts on the fly in a grid-style input screen. The fields of information that you see and want to collect in the batch entry input grid for Batches are determined by several CiviCRM reserved profiles.  If you want to collect other kinds of information that are not currently included in these profiles, you will need to alter these profiles to reflect the fields you want to display.

Configuring Profiles for Batch Entry of Contributions & Membership Payments

To alter the profile used when you want to create a new contact for an Individual, Household, or Organization while recording the contribution, update the reserved profiles called New Individual, New Household, or New Organization accordingly.  To change the fields of information you want to collect for these contacts:

Go to the  menu and click Administer > Customize Data and Screens > Profiles, then  click on Reserved Profiles tab.  Click on Fields next to called New Individual, New Household, or New Organization.

You can then add, edit,  or rearrange the fields as you want to see them in the batch entry input grid.  To find out more about how to use profiles, see the chapter called “Profiles” in the “User Interface” section.

TIP:  Reserved profiles for New Individual, New Organization, and New Household, are used in other areas of CiviCRM.  Be aware that if you alter these profiles for use with Batches, these same changes you’ve made will also appear on other screens where you have the option to create a new contact inline. 

Above is CiviCRM’s default configuration of the New Individual profile, which is used when you select to create a new contact for an individual during batch entry of contributions or membership payments.

To alter the profile of fields of information you want to collect for contributions or membership payments, you will need to update the reserved profiles called Contribution Batch Entry or Membership Batch Entry:

Go to the menu and click Administer > Customize Data and Screens > Profiles, then click on Reserved Profiles tab.  Click on Fields next to Contribution Batch Entry profile or the Membership Batch Entry profile.

You can then add, edit , or rearrange the fields in this profile, e.g. you may have other custom contribution fields you would like to display and collect information,  and display in the batch entry input grid.  To find out more about how to use profiles, see the chapter called “Profiles” in the “User Interface” section.

Above is CiviCRM’s default configuration for the Contribution Batch Entry profile, which is used when you record information about a contact’s contribution payment.

Above is CiviCRM’s default configuration for the Membership Batch Entry profile, which is used when you record information about a contact’s membership payment.

Importing contributions

If you have not imported data before, please refer to the chapter 'importing data' first.

When preparing your data import it is helpful to know what fields are required for Import. You'll want to be sure that these fields are included in your CSV import file. Below is a list of the required fields. Please note that the fields marked (Match to Contact) indicated that only one of those options must be included for import. You do not need all of those fields to be included.

Contact ID (Match to Contact)

Email (Match to Contact)

External Identifier (Match to Contact)

Financial Type

Total Amount 

The import tool for contributions is similar to that of contacts, but there are some pre-requisites which must be met before running the import. Firstly, contributions cannot be imported unless the contributors already exist in the database as contacts. If you need to import contributions for contacts that are not yet available, run a contact import first, preferably including a unique external identifier (most often an ID assigned by the database or application you are importing records from). There are two ways to match a contribution to a contact:

Use the external ID of the contact by including the ID in a column of the CSV file (if this ID was not imported with contacts, but you have them on record, a second contact import could be run to update this field, after which you may import contributions).

Alternatively, you can match contributions to contacts based on your contact de-dupe rules, e.g. through including the first name, last name and email address of the donor against each contribution in the file. If a contact matches these three fields, the contribution will be assigned to it.

Remember, CSV files must be less than 2MB in size. If the file size exceeds this, create multiple CSV files and distribute the data between them.

Everyday Tasks

This chapter explains how to perform some common CiviContribute tasks.

Viewing the CiviContribute dashboard

The CiviContribute main page or dashboard summarises the contributions made, including lists of contributions received in the current month to date, year to date, and cumulatively since inception (i.e. all contribution records in your CiviCRM installation). This allows you to easily browse contributions that have been recorded automatically or added manually. The dashboard also provides buttons to manage and add contribution pages.

Different layouts are available for viewing summaries. The following screenshot shows the most recent contribution to a campaign using the Table Layout tab:

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.

Finally, you can add any number of contribution report instances to your personal CiviCRM Dashboard. These might include a bar chart summary of year-to-date contributions by Financial Type or month, a list of the top 10 donors, etc. Refer to the Reports section for details on adding reports ("dashlets") to your personal dashboard

Adding contributions manually

When your organisation receives a contribution from a contact, you can add it to their record. This will be done automatically if the payment is made through CiviCRM (for example, a membership or event fee made with an online registration) but offline payments will need to be manually recorded to ensure that reports generated from CiviCRM are accurate.

If the donor does not already exist in the database, you need to first create a new contact record for them; see the chapter on Contacts in the Basic Concepts section of this book for information on how to do this. Once the record is created, you can then enter the contribution.

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

Find the contact's record using one of the contact search tools, for example Search > Find Contacts.

Select the contact's Contributions tab.

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.

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 Financial 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. 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. There is more information about PCPs and campaign fundraising pages in the Set-up chapter of the CiviContribute section.

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).

Click Save, or Save and New if you are entering further contributions.

If you find that you are entering more than a few contributions at the same time, consider using the Bulk Data Entry method described later in this chapter.

Finding contributions

To View the Find Contributions screen, go to Contributions > Find Contributions

You can search based on a number of criteria, such as 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 Financial Type "donation" and the date range "January 1st to May 31st" will return contributions that meet both criteria. Relative date ranges such as "Last Month" or "Last Year" are often quite useful.

The search criteria shown above are also available from Advanced Search, which means you can get results as a list of contacts OR contributions. Advanced Search allows you to save a query as a smart group - and you can also filter your results with additional contact criteria including donor addresses and demographics ("Show me all contacts who have contributed more than $100 last year AND who live in California"). 

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:

You can select an action to perform from the - actions - menu once you select all or a subset of records. The "actions" menu allows you to:

Batch Update Contributions Via Profile: this is useful if you want to update a large number of contributions' thank-you date at once, for example. You need to create the profile you want to use before you perform the search and batch update (see the the chapter Profiles in the Configuration section for more information about creating profiles).

Delete Contributions: this removes contributions entirely from the system, as if they had never been entered in the first place. Editing contribtions and updating their status to canceled provides a better audit trail, but there may be situations where you do want to delete, such as a contribution entered on the wrong contact's record.

Export Contributions: because this search is contribution-centric, it does not recognise if contributions come from the same contact. Therefore, if one contact has multiple contributions that fit the search criteria, that contact will appear as multiple rows when you export your spreadsheet. If you want to do searches that return one result per contact, use the contact advanced search.

Print or Email Contribution Receipts: this allows you to create a PDF file of all the receipts in the search, or email the receipts to the associated donors. See "Sending thank you letters" below for more information.

Send Email to Contacts: send an email to all or selected contacts found in the search.

Send Thank-you Letters for Contributions: create a custom PDF letter for each of the contributions selected, with the option to update the receipt or thank you date for each.

Update Pending Contribution Status: update the contribution status of all or selected contacts who have contributed online. This action only works with online contributions, and the same contribution status will be applied to all the contributions selected for updating.

Batch Entry of Contribution or Membership Payments

The Batch Data Entry feature is very useful if you have a workflow where you want to enter multiple contributions or membership payments for new and existing contacts in CiviCRM at one time into a single batch and then want to verify the total amount and count of items against the payments you’ve recorded on your deposit slip(s). 

You may also find it helpful to use the batch entry feature if you just want to enter multiple contributions and memberships into a batch, and save the batch to continue entering later.  In both cases, the batch entry feature allows you to use a batch entry grid input screen where you can use the ‘autocopy’ icons to copy values down a column as well as add new contacts on the fly to ease data entry when you have a lot of payments to record at one time.

Here’s a simple workflow on how to use bulk data entry:

1. Create a New Batch Data Entry Batch

Create a new batch to hold the multiple contributions or membership payments you want to record:

From the menu, click on Contributions >  Batch Data Entry or Membership > Batch Data Entry.

Enter the following information: 

Batch Name: CiviCRM will create a default batch name ("Batch N" + open date), which you can edit (required field)

Type:  select the type of contribution, e.g. Contribution or Membership; this essential selects the appropriate reserved profile to view in the batch entry grid screen (Contribution Batch Entry profile or Membership Batch Entry profile)

Status: the default will be “Open” (note: once a batch has a “closed status”, the batch will no longer be editable)

Number of items: total of payment items in the batch (required field)

Total amount: total amount of all the payment items in the batch (required field)

You can later edit or delete Batch information, by going back to the Bulk Data Entry screen, then clicking on Edit or Delete next the batch you want. 

2. Enter Contribution or Membership Payments (check, cash, EFT, etc.)

Once you enter information about the batch, you can begin entering contribution or membership payments on each line. Note that the information you see will depend on whether you created your batch with type Contribution or Membership:

Under the Contact column (will be seen on both Contribution or Membership batches):

you can start entering the name of an existing contact and CiviCRM will return a list of potential contact names for you to select, OR 

you can create a new contact by clicking the drop-down box for “-create new contact-“ and selecting the type of contact you want to create: New Individual, New Organization, or New Household and enter the information about the contact here.

Note:  If contact information such as phone number or email address are included in the grid profile - those values will be populated for an existing contact and can be updated as needed.

For Contribution payment Batches you will see fields that pertain to contribution payments and then enter information as appropriate (Note at the top of each column is a ‘autocopy’ icon, so if you have a value in field of the first record of a column, you can copy and paste the value of that field down the column):

Amount: amount of the payment

Status: status of the payment

Received – Date and Time: date and time payment was received

Source : enter text that describes the source of the payment

Paid by: enter the type of payment vehicle, e.g. cash, check, EFT, etc.

Check Number: if paid by check

Send Receipt: check the box if you want to send a receipt via email

Invoice ID

For Membership payment Batches you will see fields that pertain to membership  payments and then enter information as appropriate (Note at the top of each column is a ‘autocopy’ icon, so if you have a value in field of the first record of a column, you can copy and paste the value of that field down the column):

Under the Type column, select the name of the membership and the type of membership, e.g. General, Student, Lifetime

Member Since: if the existing contact had a membership, this field with be populated with a date, otherwise you can add or edit this field

Start Date: date the membership starts

End Date: if you leave the date empty, CiviCRM will use the membership status rules to calculate the end date of membership

Source: enter text that describes the source of the payment

Send Receipt: check the box if you want to send a receipt via email

Financial Type: by default the following options are: Campaign Contribution, Donation, Event Fee, Member Dues

Amount: amount of the payment

Received – Date and Time: date and time payment was received

Paid by: enter the type of payment vehicle, e.g. cash, check, EFT, etc.

Check Number: if paid by check

Payment Status: status of the payment

Note:  If an existing contact has membership information, those values for the displayed membership fields will be populated and can be updated as needed.

3. Validate and Process the Batch Totals or Save the Batch

You can enter all transactions for the batch in one session, or simply save the batch and complete the data entry at a later time.

If you want to continue entering information into this batch at a later time, click Save & Continue Later.

To find and add/edit more transactions into the batch later:

From the menu, click on Contributions > Batch Data Entry or click on Membership > Batch Data Entry, then click on Enter Records next to the batch you want

Then continue entering more transactions in the batch

Once you are finished entering payments into a batch, click Validate & Process the Batch.  The status of the batch will be set to “Closed” and will available for searches and reporting later.

If the total amount or count of items do not match the values you entered when you created the Batch, you will be alerted when closing if the count or total don't match.  In this case, you either:

You can override the entered count and total by clicking Ignore Mismatch & Process the Batch? button, in which case the batch values are updated to match the transactions in the batch, and then the status of the batch will be set to “Closed”, OR

You can continue entering or editing the payments for the batch, then Validate & Process the Batch again.

4.  Search for contribution or membership payments in verified and processed batches

You can search for contribution or membership payments in verified and processed batches in a several ways:

From the menu, click on Searches > Find Contributions , enter criteria for the contributions, and under Batch Name, select the batch you want;

From the menu, click on Searches > Advanced Search, enter criteria about the contact, then open the Contributions area and enter any contribution criteria, and under Batch Name, select the batch you want; 

From the menu, click on Contributions > Batches , then select  Closed in the Status field; 

From the menu, click on Memberships > Batches , then select  Closed in the Status field; 

From the menu, click Reports > Create Reports from Templates, then click Contribution Report Detail, enter your report criteria and under Set Filters area, next to Batch Name, select “is one of” or “is not one of” and select the name(s) of the batch(es) you want.

Sending receipts and thank you letters

Receipts 

Donors making contributions through an online form will automatically receive an email receipt for their payment, provided the option to send them was selected during the configuration of the contribution page. If you wish to manually send or re-send a receipt at a later date, you can do so by either editing the contribution record against a contact and ticking the option “Send Receipt?” (an email will be sent after you click “Save”), or sending one to multiple contacts through the contributions search. Simply run a search, as above, and after selecting the contacts you wish to send a receipt to, choose "Print or Email Contribution Receipts" from the actions drop-down menu. You will be given the option to print a PDF letter or send an email. Either way, the receipt date and time will change for each of the contributions accordingly.

To find out how you can change the format of receipts, see the chapter "Contributions" > "Set-Up".

Thank you letters 

Later, your organisation may wish to send custom thank-you letters to a group of donors. The first step would be to search and filter your contributions until you have a target list of recipients. Go to Contributions > Find Contributions and enter your search criteria, which we recommend includes:

Thank-you date not set? (a thank you letter has not been sent)

Financial Type

Contribution Status ("completed" if payment has been confirmed)

In your new results list, select the contributions requiring letters, choose "Thank-you Letters for Contributions" from the actions drop-down menu and click "Go". You are now ready to customise your letter. Decide whether to use a pre-existing template, if the letters should update the receipt or thank you date against each of the selected contribution records (under "Record Update Options"), and check the page format settings. When satisfied, begin to edit the content of your letter. Remember that you can use tokens to include information relevant to each contact, ranging from first and last name to the total amount contributed (see "Tokens and mail merge" for more information). Some of the key tokens you might want to use for thank you letters are:

Postal Greeting or First name/Last name

Total amount (the total contributed/donated)

Net amount (total contributed minus fee)

Receive date (when the donation was received)

Campaign (the campaign the contact donated under)

Source (what the donor contributed to)

Once your letter is composed, choose whether to add it as a new template (or update an existing template). Then click "Make PDF Letters".

Soft credits

Soft credits are a familiar concept to many fundraisers, and are useful for a better understanding of the sources of contributions received by your organisation.  They allow you to assign credit for a donation to one or more people who are not the donor.

Soft Credit Types

CiviCRM's soft crediting allows users to assign soft credit types to contributions. Assigning an appropriate reserved or custom soft credit type enables administrators to properly attribute contributions received through one or more charitable contribution types (such as Donor Advised Funds, Scholarships, Family Bequests, etc) whether solicited (P2P) or not.

CiviCRM uses the following reserved soft credit types:

In Honor of

In Memory of

Solicited

Personal Campaign Page

Gift 

Lets say that a very active member of your organization was responsible for getting 10 other people to make a contribution.  Soft credits provide a way for you to credit this person and the actual donor, without counting the contribution twice.

You can use CiviCRM's soft crediting to credit parts of a donation to multiple people.

In the screenshot below, you can see that we have credited Magan Cooper's contribution of $1,500.00 to three different people. 

CiviCRM can also handle more complicated scenarios. For instance, Joe is an active member of a community foundation that regularly contributes to your organization. Joe solicited a contribution from Jane on behalf of the community foundation. Your organization would therefore receive a check from the community foundation. Using soft credit types, users can properly attribute the credit without duplicating contributions. In this case:

The community foundation is the donor.

Joe would receive the solicited soft credit.

Jane would receive the donor advised soft credit

This scenario is illustrated in the screenshot below.

As well as recording soft credits, we can also report on them.  The contribution detail report has optional columns which show soft credit details.

 [screenshot of soft credit filters here]

When checked, these will show four extra columns in CiviReport, which can be used to view soft credit information.

Honoree information and profiles 

When creating a contribution page you will have the option to allow your end users to make a contribution on behalf of an honoree. To do so you must select the Honoree Section Enabled checkbox. 

This will reveal additional fields that will allow you to specify the Honor Types and Profile to be included in this section.

Once configured your end users will be able to enter honoree info for online contributions. CiviCRM will check to see if the honoree exists within CiviCRM already using the default duplicate checking rules on your site, if a duplicate is not found a new contact record will be created. A soft credit will be added to the contact record of the honoree.

Soft credits and personal campaign pages

The concept of soft credits is closely related to personal campaign page (which are covered in more detail elsewhere). When someone donates by a personal campaign page, their donation is soft credited to the owner of the personal campaign page.

Personal Campaign Pages

CiviCRM's features include allowing your constituents to create their own fundraising pages - and then ask others to fund their cause.  These pages are called Personal Campaign Pages or "PCPs".

A personal campaign page allows your constituents to personalize the fundraiser, event, organization, etc., by offering their personal reasons and/or experiences with the organization on their own personal page. Also, your contributors may in turn send the personal campaign pages to their circle of friends.  You can enable the "tell a friend" feature to help someone share their page even more.

Examples of this feature in action are typically called "Sponsor My 5k Walk", "Help Fund Our Trip" or "Let's Raise Money to Build A School".

Administrator Features

Administrators managing fundraising pages may use the following features via the contribution page configuration:

Requiring approval before a newly-created fundraising page becomes active

Turning on or off 'tell a friend' so fundraisers can email others

Setting a notification email when a new page is created

Choosing a profile of fields to collect from PCP supporters

Customizing the text in the create button

Once PCP pages are active, administrators can:

Disable or deny Personal Contribution Pages

Edit PCP content

View the amount of money collected by each PCP

Run reports (using CiviReport) showing a summary of PCP fundraising

Enter 'offline' contributions (i.e. checks) and credit the money to a PCP

Fundraiser Features

Those creating their PCPs enjoy the following ways to personalize their page:

A title of their choice

Descriptive text

Selecting a monetary goal amount they hope to raise

A single image they can upload that will appear on their page

Choosing whether or not an 'honor roll' of supporter names will be shown on their page

Option to display a 'thermometer' showing progress towards their goal

Create a username (or login using a username they already have) so they can edit their PCP later

Limitations

CiviCRM's PCP functionality doesn't allow for team management.  For instance, a fundraising leader recruiting members to a team, managing membership and then keeping track of which member brought in how much money is not supported by CiviCRM at this time.

There is a limit of a single image uploaded to a PCP by the fundraiser.  The image is not automatically re-sized.

The thermometer and honor roll appearance can be modified, but changes are applied to all pages.  These customizations cannot be done without the expertise of a coder.  

Set-up

All Personal Campaign Pages must be linked to an existing online contribution page or event, created in CiviCRM by navigating to either: Contributions > New Contribution Page or Events > New Event. Once a contribution page or event has been generated, while editing the settings go to the Personal Campaigns tab and click 'enable personal campaign pages'. A number of other options may then be configured, including:

Approval Required: check this option to moderate all PCP creation requests. An administrator must approve the page before it becomes active, at which point the user will be notified via email, and may proceed to promote it (ensure "notify email" is also used to notify an administrator when PCP pages are awaiting review).

Notify Email: a receipt for each new PCP will be sent to the named administrators (separate multiple email addresses with commas).

Supporter Profile: select a profile of fields to be collected from the user creating the PCP.

Allow 'tell a friend' functionality: the PCP owner may send emails to their contacts, persuading them to visit their page and contribute.

Campaign Type: when enabling PCPs for an event, you may give the event registrant the option to either create a fundraising event of their own, or a contribution page (e.g. to raise money in support of their attendance).

After PCP creation has been enabled, there are two ways to create a PCP:

An individual donating to a contribution page or registering for an event are given the option to build their own PCP via a button on the 'thank you' page.

If the individual forgets to click the link upon donation, or you wish to give all visitors the opportunity to create a PCP without the prerequisite of donating or registering themselves, you can give your constituents a direct link. This link could be emailed to the constituent, embedded in a page or added as a menu item. Note that 

The invitation button: 

The invitation link:

http://YOUR-SITE.ORG/civicrm/contribute/campaign?action=add&reset=1&pageId=CONTRIBUTION_OR_EVENT_ID&component=EVENT_OR_CONTRIBUTE

To use this link, replace the following:

YOUR-SITE.ORG: enter your domain's address

CONTRIBUTION_OR_EVENT_ID: give the ID number of the event or contribution page. This can be obtained through navigating to 'Manage Events' or 'Manage Contribution Pages' and looking for the ID against the item in question.

EVENT_OR_CONTRIBUTE: If the invitation is for a Personal Campaign Page in support of a contribution page, use component=contribute. If the invitation is in support of an event, use component=event.

Managing Personal Campaign Pages 

When an individual has clicked the 'create your own fundraising page' button or a direct link, they will be presented with a form to fill out their information, including: a title, message, monetary goal amount and text for the donate button. They may also attach a photo, enable a progress - thermometer style - bar, include an honor role of their donors who have not elected to be anonymous, and whether the campaign is active (they may choose to activate it at a later time).

If PCP moderation has been enabled (the 'approval required' option), an administrator must log into the CiviCRM back-end and enable the page at Contributions > Personal Campaign Pages before the individual is able to use it. Simply seek the PCP in the list, look toward the end of the row and click 'Approve', 'Reject' or 'Delete' (at a later date, you may also enable/disable the PCP by clicking the 'More' link). The individual will be sent a confirmation email, and may proceed to use it. Ensure administrators are always alerted to this step by entering a notification email address in the contribution page settings (see 'Set-up' above).

Finally, following approval the PCP owner will be sent an email outlining how they may begin promoting their page and editing it, providing they have been given user access. The user and administrator can edit the PCP settings at any time through the menu item: Contributions > Personal Campaign Pages > click 'Edit', 'Delete' or 'Disable/Enable'.

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 Display Results As 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.

Accounting Integration

The accounting integration feature provides the capability to assign financial transactions to a batch, or to use batches created from batch data entry, then export the batch to be imported into accounting software.

Financial Accounts Set-Up

Accounting software such as Quickbooks requires specific fields to be included in the import file in order to process external data correctly. From Administer > CiviContribute > Financial Accounts, you can set up specifics of your financial accounts, and how CiviCRM transactions relate to them, in order to ensure your export from CiviCRM will correctly record into your accounting database.

Many accounting software options require the accounting code to match exactly, because of that financial types and financial accounts should be added in coordination with your bookkeeper.

Financial Types Set-Up

Financial Types need to be set-up before you begin using CiviCRM for financial transactions. Previously financial types were known as contribution types. Each financial type will have financial accounts associated with it. From Administer>CiviContribute>Financial Types, you can set up the different financial accounts that are associated with each type.

Accounting Batches

From the Accounting Batches main page, you may search for existing batches or create a new batch.

Batches can be created through the batch data entry tool or by grouping existing transactions.

Create a New Batch Through Batch Data Entry

Select Contributions > Batch Data Entry or Memberships > Batch Data Entry. Give the Batch a name, choose either contribution or membership as the type and and enter the number of transactions that will appear in the batch and the total amount of all the contributions. You can later return to edit these parameters as long as the batch remains open.

On the next screen you can begin entering your contribution data, if membership was chosen as the type during batch set-up you will be able to add membership information as well. If the contact is new, you can add them during the batch.

After entering your batch through the batch data entry tool, then validate and close, it will appear in the accounting batch listing with a status of Closed.

Create a New Batch from Existing Transactions

Select "New Accounting Batch." This opens the batch creation screen. Before you assign transactions to a batch, you will first define the parameters.

Enter the batch name (required). CiviCRM will create a default batch name ("Batch N" + open date), which you can edit. You may optionally enter a description of the batch.

You may also set several Optional Constraint parameters:

If you want this batch to contain only transactions paid by a specific Payment Instrument, select it from the drop down: Credit Card, Debit Card, Check, Cash, or EFT, or any custom Payment Instruments you may have set up.

If you know in advance the number of transactions that will be in the batch, enter it in Number of Transactions. When you close the batch, CiviCRM will verify that you have entered the correct number (you will have the opportunity to override the warning if they do not match).

If you know in advance the total amount of the transactions that will be in the batch, enter it in Total Amount. When you close your batch, CiviCRM will verify the totals entered match this number (you will have the opportunity to override the warning if they do not match).

You can later return to edit these parameters as long as the batch remains open.

Assign Transactions to a Batch

From the Accounting Batches screen, select an open batch. Click "Transactions." This opens the transaction assignment screen.

At the top of the screen is displayed the parameters of the batch:

created by

status (open, closed, or exported)

the description entered when the batch was created

the specified payment instrument (if one was selected when the batch was created)

the number of entered transactions (if a number of transactions was specified when the batch was created)

the number of assigned transactions (which will update as you assign transactions to the batch)

the entered total amount of the transactions (if a total amount was specified when the batch was created)

the assigned total amount (which will update as you assign transactions to the batch)

the date the batch was opened.

Below that is a list of transactions assigned to the batch. This will be empty until you assign transactions to the batch. There is also an action dropdown selection that will not be available until transactions are assigned to the batch.

Find and Assign Transactions

At the bottom of the page is search pane to find transactions to assign to the batch. Click "Edit Search Criteria" to open a search pane. If a Payment Instrument was selected when the batch was created, this option will be selected by default. Search for the contributions you want to add to the batch.

From the search results list, you may assign a single transaction to the batch by clicking "Assign" at the end of the result row. Or you may select multiple transactions and use the action menu above the results to select "Assign to Batch." The transactions will be added to the assigned transaction list, and will be removed from the search results list.

View and Remove Assigned Transactions

Once you have assigned transactions to the batch, they will appear in the assigned transactions list in the middle of the page. If you need to remove transactions from the batch, select "Remove" at the end of a row of an individual transaction, or select multiple transactions and use the action menu above the list to select "Remove from Batch."

You will also see changes to the parameters table at the top of the page, reflecting the new number and total amount of assigned transactions.

If you want to return and edit the batch later, simply return to the Accounting Batch main page. The batch status will remain "Open."

Close and Export a Completed Batch

Once you have completed assigning the transactions, you may close the batch, or close and export it.

If you attempt to close the batch and your assigned number of transactions does not match the entered number of transactions, or if the assigned total transaction amount does not match the entered total amount, a "Mismatch" error message will appear. You may close the error message and return to the batch to correct the mismatch, or you may click "OK" to override the error; the entered transaction number and total amount will update to match the assigned transaction number and total amount, and the batch will be closed.

If you close the batch without exporting it, the batch status will change to Closed. You may re-open the batch later, before exporting it, or you may export the transactions later.

If you close and export the batch, you may choose your export format. CSV will produce a spreadsheet of comma-separated values. IIF will produce a file in Intuit Interchange Format, which is used by Intuit products such as Quickbooks to import transactions. Once the transactions are exported, the batch status changes to Exported. An exported batch cannot be re-opened.

Searching and Acting on Batches

From the Accounting Batch main page, you may filter the list of displayed batches by status (Open, Closed, or Exported); batch name; the user who created it; the Payment Instrument; the entered number of transactions; and the entered total amount.

If a batch has the status Open, select "Transactions" to assign or remove transactions, or select "Edit" to edit the batch parameters. Under "more" you can choose to close, export, or delete the batch.

If a batch has the status Closed, select "Transactions" to view the assigned transactions, or select "Export" to export the assigned transactions to a CSV or IFF export file. Under "more" you can choose to re-open or delete the batch.

If a batch has the status Exported, select "Transactions" to view the transactions assigned to the batch; select "Download" to export the CSV or IIF file of assigned transactions; or select "Delete" to delete the batch. Once a batch is exported it cannot be re-opened.

From the search results page, you may also take action on more than one batch. Select all the batches to be updated, and choose an option from the action dropdown menu: Re-open, Close, Export, or Delete.

Finding Transactions by Batch

From the Advanced Search Contribution pane, or from Find Contributions, you can search by Batch Name. Select a batch and the results will return all transactions stored in the batch.

Payment processors

CiviCRM provides you with the ability to take payments online on your website.  You can take payments for a variety of reasons including fundraising campaigns, membership dues and event attendance.

To start taking payments online you need to configure a payment processor which will connect your website to the credit card and banking infrastructure that actually processes the payment.

CiviCRM connects to a variety of different payment processors. Out-of-the-box, it comes with support for approximately 15 payment processors. Many other community contributed processors are available to download from the CiviCRM.org Extensions Directory:

http://civicrm.org/extensions

Additional payment processors may also be available from third party sites.

Community contributed processors are not supported by CiviCRM but there is no reason why they should not be just as reliable as the out-of-the-box processors.  If you do use a community contributed processor, be sure that you have access to adequate technical support for that processor, either in house, from the author of the payment processor, or from a trusted third party.

You can browse an up-to-date comparison of many of the available payment processors at

http://wiki.civicrm.org/confluence/display/CRMDOC/Payment+Processors

Selecting a payment processor

Below is a list various things to think about when choosing a payment processor. Not all payment providers are created equal and there are significant differences between them in terms of cost, suitability for your use case, and availability. This is a quick guide to selecting a payment processor.  If possible, you should talk to other similar and nearby organisations that use CiviCRM about their experiences with payment processors. You can also configure more than one payment processor, and give constituents the option to choose the one they prefer.

Onsite vs offsite processors

Payment processors can be split into those in which the user enters credit card details directly on your site, and those that transfer the user to another site to make the payment, and then return them to your site once the payment is made. You can typically brand the payment site to a limited extent – for example you might be able to add your organisation name, logo and colours – but the workflow is less seamless and a percentage of people tend to get lost along the way and not complete the payment.

As well as providing a more seamless experience for end users, onsite payment processors allow site admins to process card payments (contributions, membership fees, event payments, etc.) from CiviCRM admin pages. 

The disadvantage of processing payments directly on your site is that you will need to have an SSL certificate to ensure the security of the users card details as they are transmitted over the internet. SSL certificates cost money (typically an annual fee) and they are not straight forward to set up. Your hosting provider or system administrator can help you here.  You may also want to read the 'security' chapter in the initial set up section of this book.

It is worth noting at this point that CiviCRM never stores credit card details on your server. It only transmits them to the payment processor. 

Regional Availability

For many countries there are no payment processors written that support their currencies. If you do not have payment processor support for the payment processor you want to use, consider writing your own processor or asking a third party to do so.

Merchant account vs built-in

Most organizations that accept credit card payments will have their own merchant account through a bank, however these usually have monthly charges which may not suit smaller organizations (though they generally have lower percentage payments). You can expect to pay a fee for the merchant account and to the payment processor, though these may be bundled together. Some, like World Pay & Paypal, do not require separate merchant accounts.

Support for recurring contributions

Support for recurring contributions and auto-renewing memberships is an important feature for many organizations. However not all of the payment processors available for CiviCRM support this feature, and a few like Moneris have "incomplete" support. Check the wiki for the latest information.

Cost

Determining which payment processor is least expensive depends on the number and average size of the transaction you process. So the question is not which processor is the cheapest, but which is the cheapest for you. Commission percentages, per-transaction charges, and fixed monthly charges vary along with set-up costs. In general, if you process many transactions, an account with a monthly fee but low commission might be a good option. On the other hand, if you expect infrequent transactions, it is best to avoid monthly fees and accept paying a higher commission.

Usability

If you do not collect the credit card information yourself on your own site, you need to consider whether the payment workflow is intuitive and easy to use. Paypal Standard is often confusing to end users because they are not sure whether or not they need to create a PayPal account. Such a barrier can result in decreased contributions.

Support

CiviCRM supports the processors that are incorporated into the core codebase, to the extent that they ensure they do not break in upgrade - support and enhancements of community contributed processors are generally expected to come from the community.

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 Administer > System Settings > Payment Processors and click on New Payment Processor

Choose Payment Processor Type from the dropdown list. 

Assign a descriptive name to this processor configuration and an optional description. The name will show up when you want to select a payment processor for a Contribution Page or Event. A description can be useful if you are configuring multiple merchant accounts for different chapters or sub-organizations within your site with the same payment processor type.

Select a Financial Account. You probably want to have a separate Financial Account for each payment processor, but your bookkeeper or accountant will be able to advise you best on this. The financial account you select records where the money gets deposited, not the sort of revenue you anticipate it receiving. The contribution, membership and event money you receive will also get recorded into different revenue financial accounts as well, based on the configuration of contribution pages and events. For a partial explanation of how this works, see Double Entry Accounting in Wikipedia.

Fill in the appropriate details for your payment processor. Note that this set-up screen varies according to the payment processor selected.

Make the processor active so that it is available for use with paid events and online contribution pages. If the processor allows you to collect credit card information on your website, your staff will also be able to use it to submit credit card contributions and payment for memberships and events.

Finally fill in the details of your test and live accounts so that you can use it in both test and live environments. You will need to do some further set up on the actual payment gateway but that is beyond the scope of this book and should be documented by your gateway.

Once done, the processor will be available in your paid events and contribution pages.

Test payments and dummy payment processors

For the purposed of testing, you can configure dummy payment processors.

If you do use a dummy payment processor, or are using any payment pages in test mode, the following card details should work:

Card type: Visa
Card number 4111 1111 1111 1111
CVV: any three digits
Expiry: any date in the future

Writing a new payment processor 

If you cannot find a suitable payment processor, or want to use a specific payment provider that is not currently supported by CiviCRM, you can write a new payment processor integration, or pay someone else to do so.

What is CiviPledge?

A pledge is the promise to give a donation at a pre-arranged time in the future, either in full, or at regular intervals until a total goal is reached. For example, Sally pledges to give $3000 over five years, at regular monthly intervals of $50 each.

In CiviCRM, donors can make a pledge themselves through an online contribution form (see the 'Contributions' section), or internal users may do so on their behalf. Payments are handled separately, either manually (e.g. cheque) or automatically through a payment processor, and the pledge itself is the 'umbrella' that links all of the individual contributions together.

If a donor has missed a payment, the status of the pledge can be updated accordingly, and email reminders may be set for delivery automatically at specified intervals before the payments are due, to remind donors of their commitment.

What you need to know

Before using CiviPledge, you must enable it for your installation, if you have not done so already. Go to Administer > System Settings > Enable CiviCRM Components, and move CiviPledge into the box on the right to enable it.

New Pledges

To create a new pledge on behalf of a constituent, navigate to Contributions > Pledges > New Pledge (note that an individual may do this themselves through an online contribution form; see the 'contributions' section).

The options available are as follows:

Select contact: type the name of an existing contact, or create a new one before setting up the pledge (a new window will open)

Total pledge amount: enter the total amount to be donated

To be paid in: specify the number of instalments and time period for payment, if greater than one

Payments are due on the: choose the day on which a payment is due during that instalment cycle (e.g. the second day of the week/month/year)

Pledge made: select the date on which the pledge was promised

Payments start: set the date the scheduled payments will start

Send Acknowledgment?: if outgoing mail is configured, and an email address is available for that contact, check this box to send a notification email

Acknowledgement date: the date the individual was notified of the pledge's creation (automatically populated if an email was sent)

Financial Type: choose the Financial Type of the contribution (e.g. donation or event fee) to denote what the pledged money is meant for

Campaign: if available, you may assign the pledge to a campaign if the money is intended to go towards that fundraising effort

Self-service payments page: give donors the ability to make a payment online by selecting an online contribution form to collect the money through

Honoree information: you may also enter honoree information if the individual elects to dedicate the pledge to someone, and set payment reminders

Payment reminders

One or more payment reminders can be emailed to the donor prior to the scheduled payment date. If a 'Self-service Payments Page' has been selected (see below), the reminder will include a link for the contributor to make their payment online.

In order for reminders to be sent:

The Process Pledges (process_pledge) scheduled job must be enabled to updates pledge payment statuses and sends the payment reminders. Alternatively a cron job can be scheduled to run this specific task apart from other scheduled jobs. Refer to the Scheduled Jobs chapter for more information.

The donor must have a valid email address (and must not have the "Do Not Email" flag checked). 

Once these pre-requisites have been met, you can choose the payment reminder schedule for an individual when creating a new pledge. The settings are:

Send initial reminder: enter the number of days, prior to the payment date, that a reminder will be sent

Send up to: specify the maximum number of reminders an individual will receive for one scheduled payment

Send additional reminders: set the interval period between reminders, by the number of days, e.g. 5 days before the next reminder is sent.

Self service payments

A donor can be given the option to make a scheduled payment online if a contribution page (with payment processor) has been created. To do this, select a contribution page from the drop-down menu 'self-service payments page' when creating a new pledge. If reminders have been enabled for the pledge, a link to this page will be included in the body of the emails.

Finding Pledges

To search for existing pledges, go to: Contributions > Pledges > Find Pledges. You may search by name, email address, or any discrete feature of the pledges themselves (e.g. payment start date, pledge status and honoree information). The search results page will display a summary of the pledges found, and view, edit and delete options are available for each record at the end of the rows. If the status of a pledge is 'in progress', there is also an option to cancel the pledge.

Dashboard

You can view a list of recent pledges and a summary table of pledges recorded over the current month and past year on the pledges dashboard. This can be reached through the Contributions menu: Contributions > Pledges > Dashboard.

Set-up

Within your online CiviContribute donation form, you may let your constituents make pledges for future donations. By allowing pledges, donors have the flexibility to choose the frequency with which they will donate, e.g. twice a year, twice a month for five months, etc. Some payment processors will not allow this kind of automation and the payments themselves may arrive in a non-electronic form like cheques. However, you can record future income against a current source such as an event or email campaign, and change the status from 'pledged' to 'complete/paid' manually when the payment arrives (should the payment method not support this). Pledges also provide an automated mechanism to remind donors of their commitment.

For further information on pledges, and creating pledges internally on behalf of constituents (i.e. not through an online form), see the chapter 'Pledges'.

Enabling pledges

Setting up pledges for online forms is a simple check-box affair. Once a contribution page has been created (see the chapter 'Setup'), while editing the page's settings go to the 'Amounts' tab and tick the option 'Pledges'. Several options will appear, as below.

Supported pledge frequencies: choose whether the donor can pledge a daily, weekly, monthly or annual donation.

Allow frequency intervals: if checked, donors will be able to specify a gap in payments (e.g. once every 5 days, 5 weeks, 5 months, or five years).

Send payment reminder: if you wish to send the donor a reminder before their scheduled payment is due, enter the number of days prior to the payment that they will be reminded (e.g. via email)

Send up to: specify the maximum number of reminders an individual will receive for one scheduled payment.

Send additional reminders: set the interval period between reminders, by the number of days, e.g. 5 days before the next reminder is sent.

Allow other amounts: check this box if you wish to give individuals the option to pledge an amount of their choosing. You can also specify the minimum and maximum payment they can make.

Once enabled, the option to make a pledge will appear on the online form. To check and monitor the current pledges, several reports and a dashboard are available. To access the dashboard, go to: Contributions > Pledges > Dashboard.

Everyday tasks

Recording payments 

If a donor has chosen to use an offline payment method like cash or cheque, you will need to manually record the receipt of payment within the pledge. To do this:

Look up the contact in CiviCRM

Go to the 'Pledges' tab within their contact record

Click the small arrow next to the pledge to open up the scheduled pledge payments

Find the next scheduled pledge payment and record the payment as paid

Cancelling pledges

Sadly, some pledges will not come to fruition. To cancel a pledge, find it through a contact or the 'find pledges' search tool, use the 'more' link to the right side of the pledge and click 'Cancel'.

Pledges Reports and Analysis

Pledge reports

CiviCRM comes with two pledge reports that are useful when analysing pledges.  ThePledge 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. 

What is CiviEvent?

CiviEvent provides a set of tools for running events that minimizes the amount of administration required.

CiviCRM helps you manage both simple and complicated registration processes.  Some key features include:

self-registration for participants, including online credit card payments

tracking sign-ups, cancellations, and attendance

Promotion of your events on your website

Streamline event set-up for similar, recurring events with event templates and event copy functionality.

Participants check in on-site at the event from any computer with an internet connection

CiviEvent is designed to work together with other parts of CiviCRM.  For example, you can promote the event to a targeted list and communicate with event participants via email before and after the event using CiviMail (see the Email section, particularly the Set-up and Scheduled Reminders chapters, for more information). It works with CiviContributer to allow you to accept event payments online. To do this, you must enable CiviContribute and set up a payment processor; see the Contributions section for more information.

Scenario: Youth leadership workshop

A community arts group, Arts in Action, conducts leadership workshops for people under age 25 throughout the year. Their goals include attracting new youth to attend their workshops and enlisting past 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 workshop from the beginning of its planning to the end of its evaluation. First, a staff member creates an event page that includes an online registration form. Because this is a regular event, a staff member has previously created an event template, which fills in much of the information needed in the event set-up process. There is a flat fee for registration, with additional fees for optional workshops; attendees can select what they are registering for and pay for it online. The registration form also gathers information about participants' food and lodging preferences using a CiviCRM feature called a profile.

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 participants can arrive at the online registration with a single click. The event is also announced publicly by posting it on the Arts in Action 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 questions.

On the day of the event, organisers can check in each attendee on-site to keep track in real time of who is attending and whether there are any no-shows. Participants with outstanding fees can also be asked to pay at this time. The database is updated immediately, freeing up spaces for those on the wait list and recording payments.

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 can be updated if necessary and saved for the next event.

What You Need to Know

Before you use CiviEvent to support your event management, we recommend you read this chapter to understand the concepts and address key questions. 

Key Concepts

Below are the key concepts that you need to understand, followed by a list of concrete questions that will help you to use CiviEvent effectively. You'll also find mentions of other CiviCRM components that are needed to use CiviEvent. At the end of this chapter, Other Considerations gives suggestions for promoting, managing, and following up after your event.  

Review the following concepts before you begin to set up your event. You will put these concepts into practical use when following the step-by-step tasks in the next chapters of this section.

Take time to assess the kind of information you need to run your events effectively, as well as what information it would be useful to collect during events and from event participants.  If you run recurring events that are very similar, think about using event templates or the event copy features to make the set-up processes easier.

Managing different kinds of events with Event Types

CiviCRM allows you to define different types of events, such as conferences, meetings and fundraisers. Which event types to create is entirely up to you, according to the needs of your organization. Event types are useful for things like searching for event participants or generating an event listing feed. For example, Arts in Action may find it useful to search for everyone who has attended a youth leadership workshop, generate a list of meetings for volunteers.

You can create custom fields to store and display additional data about an event by its event type. See the chapter Custom Fields in the section Data in CiviCRM for more information about this.

Participant roles

Every individual is assigned a participant role, such as attendee, volunteer or speaker, at the time of registration. Participant roles are fully customizable to match the types of events your organization conducts. This allows you to segment participants into meaningful categories based on their involvement in the event, for the purpose of things like sending an email to volunteers only or generating a list of past table captains for fundraisers.

You can also create custom fields that apply only to specific roles, for example, to collect information about availability from volunteers only.

Participant statuses

Participant status—for example, registered, waitlisted, cancelled—tracks individuals' registration before, during and after the event. Participant statuses are fully customizable to match the way your organization does event registration. This allows you to segment participants into meaningful categories based on their behavior with respect to the event,for the purpose of things like generating sign-in sheets, tracking how many people are likely to come to an event, and tailoring email communications to registrants.

Custom data

CiviCRM provides a lot of flexibility for you to collect and store exactly the information you need to manage your events. This is done using custom fields. Custom fields can be created for all events or all participants, or only specific Event Types or Participant Roles. You'll be able to view custom data fields automatically when you access the information on your events and participants through CiviCRM. See the chapter Custom Fields in the section Data in CiviCRM for more information.

Profiles

Profiles provide a way of collecting information from participants during the registration process. Participants must provide at least an email address when registering online, but many organisations find it useful to collect first and last name, as well as event-specific information such as meal preference. For example, Arts in Action asks participants to select which workshops they want to register for.

Creating a profile groups these fields together for use on the registration form and associates the collected information with the event. You can use custom fields in profiles. You can also let participants fill them out in the online event registration via profiles. See the Profiles chapter in the Data in CiviCRM section for more information.

Event fees and payments

CiviEvent, along with CiviContribute, allows you to collect and track payments for event fees. There are two ways of setting fees in CiviCRM. When setting up your event, Event Fees provide a set of price levels from which the registrant must select a single level (e.g., an individual registration for $50 and a family registration for $100). This approach works well for many events and is easy to set up. For more complex pricing needs, there is a feature called Price Sets. Price Sets allow you to break event fees into smaller pieces, and set a fee for each piece. Using a price set, you can offer optional programmes and features (e.g., an optional post-conference dinner or a book) at extra cost. CiviEvent also lets you offer discounts for paid events either with a discount code or by early sign-up date. Examples and steps are described in the Set-up chapter of this section.

Fees coming in via events are tracked as contributions using CiviContribute. You will need to decide Financial Type of your event fees.  

If you plan to accept credit card payments through the online registration form, you need to configure a payment processor prior to creating your event. Find more information about this, see Payment Processors in the Contributions section.

Scheduled Reminders

CiviMail has a feature called Scheduled Reminders, which allows you to set up emails to be sent automatically to event participants both before and after events. This is extremely useful for many aspects of event management, such as recruiting volunteers, collecting evaluations, and following up with attendees. Complete information about Scheduled Reminders is in the Scheduled Reminders chapter of the Email section of this book.

Key Questions

Thinking about the structure of your events and how you want a person to experience the event registration will help to inform how you set up and configure your events. Here are some important questions to consider.

What different types of events does your organisation hold? And what in type of event is this?

What different roles will participants have at the event? 

What kinds of information you want to collect about participants, e.g., food and lodging preferences?

Will you allow online registrations to the event?

Is there a limit on the number of participants that can attend?

Do you want to approve registration, or leave it open to anyone?

Will there be a waitlist if the maximum number of registrations is exceeded?

Should one person to be able to register multiple people?

Do you want to give registrants confirmation of registering?

Do you want to make the listing of the participants public? 

Is this an event that repeats regularly with roughly the same details?

Will this be a paid event? If so..

What Financial Type will you consider the event fees to be? 

What kind of fee structure will you need to hold your event?

Will you charge multiple fees, such as fees for additional sessions or meals? 

Will you offer discounts or early registration?

Other Considerations

You may wish to consider some of the following depending on your needs.

Promoting the Event

Think about who you want at your event and where they tend to get their information. This will help you determine which tools can help you promote it:

What strategy will you use to promote your event, and through what channels?

Will you be posting your event on your website and allow people to register online?

Is email a good way to reach your constituents to market the event? 

Is your event "by invitation only"? Who are you are inviting?

Have you planned a schedule to announce your event from the initial invitation to sending out event reminders?  

Managing the Event

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

Consider how those managing the event will keep track of participant registration and participants' needs. Read about how to do this using the event dashboard in Everyday Tasks.

Following up after the Event

Updating the status of each participant during the event or soon after will help to ensure that you have the most accurate information to evaluate your event.

It is good practice to send an email after the event to all the attendees to thank them and provide links to any documentation you have online. You may want to send a different email to those who registered but did not attend. You might also 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. You can learn more about how to do this in Scheduled Reminders in the Email section.

Set-up

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 set up CiviEvent and start 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 enable CiviEvent.

General CiviEvent Configuration

A number of general settings lay the foundations for your events such as Event Type, Participant Role, and Participant Status. These have been described in the "What you need to know" chapter, and you should modify them as appropriate before you begin creating events.

Event Types

Here is where you define the types of events your organisation holds. You can return at any time to add to the list of types or modify an event type label. However, you cannot 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.

Modify event type labels by clicking Edit on any row.

Click Add Event Type to create a new category for your events.

Participant Roles

Navigate to Administer > CiviEvent > Participant Roles to review the default list, shown in the following screenshot.

Modify participant role labels by clicking Edit on any row.

Click Add Participant Role if you need additional roles that are not in the default list (e.g. audio-visual coordinator, catering manager, etc.).

Participant Statuses

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.

For each of these statuses, you can specify if they are for administrative use only or for public use in the visibility column. Public statuses can be exposed on the registration screen via a profile on your registration form.  For example, you could create a new status 'Maybe' and allow people to select it when regsitering.

Waiting lists and staff approval

There are five statuses that are disabled by default (displayed in red). They are used for optional event registration features:

online event registration with an automatically managed waiting list

events which require staff to approve participants before they can complete their registration (moderated event registration).

Enable "On waitlist" and "Pending from waitlist" statuses if you want to use the Waitlist feature.

Enable "Awaiting approval", "Pending" and "Rejected" statuses if you want to use "moderated" event registration.  Once you enable the associated statuses, you can use that feature for any of your events.

Importing Participants

If you have not imported data before, please refer to the chapter 'importing data' first.

When preparing your data import it is helpful to know what fields are required for Import. You'll want to be sure that these fields are included in your CSV import file. Below is a list of the required fields. Please note that the fields marked (Match to Contact) indicated that only one of those options must be included for import. You do not need all of those fields to be included.

Contact ID (Match to Contact)

Email (Match to Contact)

Event ID 

External Identifier (Match to Contact)

Participant Status

The import tool for participants is similar to that of contacts, but there are some pre-requisites which must be met before running the import. Firstly, participants cannot be imported unless the Individuals already exist in the database as contacts. If you need to import participants for contacts that are not yet available, run a contact import first, preferably including a unique external identifier (most often an ID assigned by the database or application you are importing records from). There are two ways to match a participant to a contact:

Use the external ID of the contact by including the ID in a column of the CSV file (if this ID was not imported with contacts, but you have them on record, a second contact import could be run to update this field, after which you may import participants).

Alternatively, you can match participants to contacts based on your contact de-dupe rules, e.g. through including the first name, last name and email address of the individual against each contact in the file. If a contact matches these three fields, the event participation will be assigned to it.

Remember, CSV files must be less than 2MB in size. If the file size exceeds this, create multiple CSV files and distribute the data between them.

Custom Data

To collect custom data from participants, add new custom fields through Administer > Customize Data and Screens > Custom Data. Give a name to the set of custom fields, such as Participant Info, by clicking Add a set of custom fields.  

You must then choose what the set of custom fields is to be used for. For example, a set of fields might be used for events, participants, participants at certain events, or participants who take on certain roles (such as speakers).  Here's additional explanation of what custom fields might be used for in CiviEvent:

Events (Event Type): This type applies to fields that are connected to the event itself, or to a specific event type. For example, Arts in Action from the scenario in What is CiviEvent? hosts a series of training workshops throughout the year and wants to create a custom field to track six common topics covered in workshops. You could create a checkbox style field with the list of topic options, such as XXXX. When creating an event of type Workshop, this field will be available. Note that you are not required to select a specific event type. Leaving the dropdown set to Any indicates the field is available to all events, regardless of the type.

TIP: Do not select Used For - Event if you want to collect information about people coming to an event (such as whether they need childcare). Use Participant custom fields for this purpose.

Participants: The Participant use type attaches to the actual registrant record. For example, you may want to know whether a registrant has any dietary restrictions and collect that information when they register.

Participants (Event Name): This use type is identical to the Participants type, with the exception that it allows you to assign a group of custom fields to a specific event. Returning to the previous example, you may find that the dietary restrictions field is relevant only to an upcoming full-day workshop where lunch will be served, but not to an afternoon workshop series you are planning for the coming month. You could create the field set and assign it to a single event.

Participants (Role): Additionally, you may create a participants type field and assign it to a single participant role. This is valuable, for example, if you need to collect biographical profile details from your speakers and wish to record it with their event registration. Because that field is applicable to only the Speakers role, you would limit it using this interface.

After creating your set of custom fields, add the actual fields within each set, such as Lodging Preferences (Single or Shared Room) or Dietary Needs (Vegetarian, Vegan, Allergies). Refer to Custom Data in Understanding Your Data before creating your actual fields.

Using Profiles for online event registration

Navigate to Administer > Customize > Profile to set up and edit profiles; a collection of custom fields for inclusion in a form. The following screenshot offers a typical example of a profile used for a conference where there is an option to provide childcare. The profile contains fields belonging to Individuals and a Participant custom field.

If you are not familiar with setting up Profiles, refer to the the section on profiles in the chapter: "The User Interface". Otherwise, see the section "Including profiles in an event registration page" below to start embedding them in your online registration forms.

Paid Events

You will assign a Financial Type to funds that comes in through events. This makes it possible to track fees that come in via events separately from funds that come in otherwise, or even distinguish between fees that come in for different event types.  

Registration confirmation and receipting

You can send automated confirmation and receipt emails to participants who register online, as well as participants who are registered by your staff or volunteers. The content and layout of these emails are controlled by message templates. Both HTML and Text formats are provided. You can modify or add text to these emails, or add branding such as a logo to the HTML versions. To set up a from email address from which to send the confirmation and receipts, see Set-Up in the Email section.

Navigate to Administer > Communications > 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.

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. 

Creating an Event

This chapter covers the options available in the event creation screen.  To get started, create a new event by choosing Events > New Event from the menu.

Event Information and Settings

The first page you see when creating an event requests basic information about the event.  You can click on any of the blue question marks to show help for each of the fields. When you see a pencil, clicking on it will take you to a screen where you can edit the options available. Note, depending on your permissions, you may not be able to edit these options and therefore will not see the pencil.

From template allows you to create an event from a template (covered below) rather than creating one from scratch.

Event type allows you to categorise the event.

If you have CiviCampaign enabled, you can select a campaign for this to be a part of (see CiviCampaign for more details).

Roles distinguish different types of event participants, such as attendees, speakers and staff. What role should participants be assigned when they register online for this event? The value placed in this field will be assigned by default when users register online or when you import registrations unless you include the field Participant Role with other values in your CSV import file. The most common value is Attendee.

Do you want users to see a list of participants, and how much information about the participants do you want to reveal? Participant listings demonstrate support for an event and can help to generate interest within your constituent community. Note that the options you define in this section only enable participant listings — to display one, you will need to create a menu item or link to the listing somewhere on your website. Once you've created the event, the participant listing link is displayed on the event configuration page. Refer to the chapter on Everyday Tasks for information on participant listings and other ways to promote your events. 

What is your event called? The title will appear on event information pages, registration pages, event listings, and in the Manage Events administrative page. Be sure to choose a meaningful, well-crafted title to represent your event.

The next two fields (event summary and complete description) let you describe your event. Both the summary and complete description will be included on event information pages. Use the rich-text editor provided for the description field to include photo, images, and formatted text.

Enter the start date/time and end date/time for your event. These will be included on the event information page and event listings.

You can set a maximum number of participants for each event and define a message to be displayed when that number is reached.

If you want to display a map showing the event location you can do so using either Google Maps or Open Street Maps (you will need to configure your mapping solution through Administer > System Settings > Mapping and Geocoding).

Select the Public Event box to include the event in promotional listings such as RSS feeds, iCal files or feeds, and event listing pages.

Select Allow sharing through social media to include social media links for sharing this event on the Event Info page, Thank-you page, Tell-a-Friend page (if enabled), and in event confirmation emails. 

Lastly, you have the option of making this event active or inactive. If you anticipate that it will take some time to complete the configuration of your event, consider making it inactive until it is complete to ensure it is not inadvertently listed on the event listing feeds. You can easily activate the event when you are ready to begin publicizing it. 

After reviewing the details on this page, click Continue >> to create your event and advance to the next step. You can interrupt configuration on any subsequent page by clicking Save and Done and return later to review and modify any of the settings. 

To return to a saved event, navigate to Events > Manage Events and click Configure to continue working on the event. 

Event Location

The next step is to complete the location and contact details for the event.

Once you have entered an event location, you can reuse it for subsequent events by clicking Use existing location and selecting it from the dropdown list. Note that if you choose an existing location and edit it, it will update that location for all events that use it.

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.

Fees

If the event is free, set the Paid Event radio button to No, then click Save and skip to Online Registration.

If this is a paid event, click Yes. The screen will show the options available (see the following set of screenshots).

What Financial Type will be assigned to paid registrations for this event? Although the most common value for this field is simply Event Fee, CiviCRM provides the flexibility to define multiple Financial Types and assign them to different events as needed. See Set-Up in the Contributions section for details.

Do you want to allow registrants to pay later by mailing in a check, paying on-site with cash or credit card, or arranging some other payment method? If so, you can enable the Pay Later option and define a label and payment instructions. If you keep this unchecked, registrants will be required to pay by credit card.

Can you use Regular Fees for this event, or do you need to use a Price Set? Regular fees are easy to set up: each fee amount has a label assigned and you can set a default fee. Here's a simple example:

Complex event fees with price sets

The standard fees layout form is a very simple structure that 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.

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:

To create and manage price sets:

navigate to Manage Price Sets and choosing the Events link OR 

navigating to CiviEvent > Manage Price Sets and choose Administer.

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, and check "Used For" > "Event". It's helpful to also add a description since Price Sets can be used by more than one event.

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.

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

Text/Numeric Quantity: allows you to set a unit price. When the form is presented to the registrant to fill it, it displays a text box where the registrant enters a quantity. The quantity entered is multiplied by the unit value to calculate the fee.

Select: displays a dropdown box where the registrant selects one option from the list.

Radio: displays multiple options in a list, allowing the registrant to select one fee choice.

Checkbox: displays fields in a list where the registrant can select or unselect any number of options.

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 whether the event item is Active. These fields are described in the Custom fields chapter in Organising your data.

In addition you can choose the dates when this price field is active. This means you can have a series of price fields offering, for example, discounted rates for people who register very early for your event, the standard rates for people who register up to two weeks before the event and premium rates for people who register in the last two weeks before the event.

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 add it to your event on the Fees tab. Select the name of your price set in the Price Set field as shown in the following screenshot.

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.

Discounts

We have already explained that you can use price sets to offer different event prices at different times of you registration period.  You can also configure early bird discounts (discounts determined by sign-up date), if you use a simple fee structure. These will override regular event fees during the period you specify.
CDiscount
Discounts are structured in parallel with the base event fees. After creating your list of fee options and enabling the discounts feature, you must create the discount set and add it to the fee table. To help you create a discount set, a new fee table will appear toward the bottom of your page, duplicating the original fee table shown in the previous screenshot. You can now edit the labels and fees to correspond to the discounts offered for each of the original fee options. 
You can create multiple date-based discount sets for an event. This may be useful if you have a series of early bird dates that progressively increase the cost of registration as the date of the event gets closer.

Discount sets and discounts via price sets are out-of-the-box CiviCRM that allow you to do offer discounts based on sign up dates.  If you want to get more sophisticated, you can install the CiviDiscount extension. This allows you to give a variety of discounts, using things like Discount codes, discounts based on membership status, and so on.  See CiviDiscount documentation for more detailed information. 

Online Registration

Allowing people to register online (self-service) through your web site offers many benefits. Online registration is convenient for your constituents and can save staff time and resources.

To offer online registration, check Allow Online Registration and use the options on this form to configure this feature. 

Define the text to be used as the link from the event information page to the registration form, and set the starting and ending dates for registration. The link text is used in the event information page, and is most commonly "Register Now" or similar. The start and end dates define when web site visitors may register for the event. The registration end date may be different from the start date of the event, as you may want to close registration in advance of the event in order to prepare name tags or perform other administrative functions.

Enabling Register multiple participants lets individuals register as many people as they choose for the event and pay the fees with a single transaction. For example, an organisation may be sending multiple people to a conference, or an individual may bring their partner and wish to register and pay for both in a single process. By default, this option requires a different name and email address for each person registered.

Checking same email address provides the same capabilities, but without requiring distinct email addresses for each registrant. In either case, CiviCRM uses a separate contact record (an existing one if the contact is already in the system, otherwise a new one is created) for each individual registered.

Information on the Duplicate matching rule is provided in the Contact matching and duplicate management sub-section of this chapter.

Pending participant expiration (hours) is the time for confirming/finishing registration by participants with any of the statuses classed as Pending. It works in conjunction with the scheduled job Update Participant Statuses (see Administer > System Setting > Scheduled jobs).  If these are both set, pending registration must be finalized within the set time or the registration will be cancelled and the would-be registrant notified by email of the cancellation. This feature is very useful when combined with scheduled reminders  for automatically managing Pending from pay later registrations if you have allowed that payment option on your online registration page. (See the Email section for more details on scheduled reminders)

The next step is to define the text and the fields for collecting information that will be displayed on your online registration page.

The introductory text comes at the top of the page and the footer text at the bottom.  In between will come some, or all, of: profile, fee selection, credit card details, additional profile(s) in that order.

Collecting participant information with profiles

The best way to collect information during online registration is to include one or more profiles in your event configuration.You can include one profile immediately after the introductory message and one or more profiles under any fees and payment details you need to collect.  (If you are not sure what a profile is and why you would use them see the Profiles chapter of Organising you data.)

By default, when creating an online registration form the profile "Your Registration Info" will be selected as the 'top' profile. This consists of three fields: first name, last name and email address. However, CiviCRM only requires either first name and last name or email address for each contact. So you can modify 'Your Registration Info' or create a new profile with fewer fields. If you choose not to collect email addresses, be sure to uncheck the option "Send confirmation email?" at the bottom!

WARNING: If you modify an existing profile whilst configuring your Online Registration page, the changes you make will apply everywhere that profile is being used. So unless an existing profile exactly matches your requirements you should copy the profile, then rename and edit the copy as required.

If the profile you require does not already exist, you can create it without leaving the Online Registration configuration page. The drag and drop profile interface also allows you to create custom fields to include in the profile if you have not already done so.

Once you registration page is configured you need to enter the text to be displayed on the Confirmation page, Thank-you page, and emailed confirmations/receipts (if enabled). The standard page flow is:

For free events, the Confirmation step is skipped. For paid events the payment is processed between the Confirmation and Thank you pages.

For most events you'll want to enable the Send Confirmation Email feature (see following screenshot). For paid events, the confirmation email also acts as a receipt. Make sure that the Confirm From Email address entered is a valid email account on your mail server. Add one or more staff emails (separating multiple email addresses with commas) to the CC Confirmation To field if you want real-time updates on who is registering for your event.

Please note that the contents of the Text field will be included in both TEXT and HTML versions of receipt emails so we do not recommend including HTML tags / formatting here.

Contact matching and duplicate management

Whenever we allow people to interact with our database from 'the outside' we run the risk of creating duplicate contacts.  There are various ways to deal with this. For example, some websites require you to be logged in at all times when doing important things and we can do the same for CiviCRM using permissions (just take away the register for events permission from anonymous users and give it to logged in users, or a specific role.  Depending on the type of event that you are running, this might not be a good idea. Lets say you are running a conference, or AGM and you want as many people as possible to register.  Requiring them to log in wil decrease the amount of registrations.

Lets say, we don't require people to log in to register for an event. Consider the following situation. James Martin registers for an event. James Martin is already in our database.  How do we match up the James who is registering with the one that is in the database. What about if there are two James Martins in our database. One that lives in London, and one that lives in Paris. How do we know that we have found the right one?  The answer is duplicate rules.

You can read more general and more detailed information about duplicates and merging in the Deduping and merging chapter and we recommend that you get familiar with that chapter at some point. This section just covers contact matching and duplicate management in the context of CiviEvent.

By default, CiviEvent uses the Unsupervised rule to do matching.  When you configure an event for online registration, you can override the default by selecting a different duplicate matching rule for matching participants for this particular event. The rule you select takes effect for the primary participant and any additional participants.

The Online Registration tab checks for whether the included profiles have enough fields to have a chance at matching participants to existing contacts. It reviews the possible combinations of matching fields that would satisfy the matching rule in effect for the event, and it checks to see if any of those combinations is present among the fields in the included profiles. The warning "Duplicate Matching Impossible" appears if there's no way to match duplicate contacts using the rule, while the warning "Duplicate Contacts Possible" appears if enough fields are there but not all of them are required.

Waiting lists

If you'd like to enable the Waitlist feature, you must first enable the related participant statuses On waitlist and Pending from waitlist.  You can do this in Administer > CiviEvent > Participant statuses. You can then check the Offer Waitlist checkbox on the Info and settings tab, and set the message you want displayed on the event information page when the event is full.

The waiting list works in the following way:

As space becomes available on your event, for example, if one or more people cancels, then On waitlist participants will be moved to 'Pending from waitlist' status and will be sent an email with a link to complete their registration (including paying event fees - if any).

People will remain pending for a certain amount of time defined in Pending participant expiration (hours). This gives them a window of opportunity to register.
You can set the amount of time, measured in hours, that you set on the Online registration tab under Pending participant expiration hours.  If you want, you can set this to 0 for no limit.

After this period of time, they will be moved to expired and other people on the waitlist will be given the opportunity to register.

Note that in order for the status processing to happen, you need to have the Update Participant Statuses scheduled job running (see Administer > System Setting > Scheduled jobs).

Participant approval

If you'd like to enable the 'Participant approval' feature, you must first enable the related participant statuses Awaiting approval and pending from approval. This is similar to what you do for waiting lists and you can do it in Administer > CiviEvent > Participant statuses. You can then check the 'Require participant approval' checkbox on the Online registration tab, and set the message you want displayed in the approval message.

Prior to being able to complete the registration process. Participants will be placed in 'Awaiting Approval' status. You can review and approve participants from 'Find Participants' - select the 'Change Participant Status' task. Approved participants will move to 'Pending from approval' status, and will be sent an email with a link to complete their registration (including paying event fees - if any)

Note that in order for the status processing to happen, you need to have the Update Participant Statuses scheduled job running (see Administer > System Setting > Scheduled jobs).

Scheduled reminders

Scheduled reminders can be used to send automatically send event registrants emails at certain time before or after events, for example

a week before: remind them that they should check out the conference schedule

a day after: ask them to fill in the feedback form

Two days before payment is due for a Pending from Pay Later registration: warn them that their registration will be cancelled if they don't provide payment details in the next 48 hours.

To set up a scheduled reminder for a specific event, click on the scheduled reminders tab, which will show you already existing scheduled reminders for this event (if any) and click on Add Reminder.

Fill in the details on this form to send, for example, an email to all registered speakers 3 days before the event start date.  Note that you can limit recipients by status (registered, attended, etc.) and also by role (speaker, attendee, volunteer, etc.).  You can either use a template or compose your own message in the HTML format box.

As well as setting up reminders on an event by event basis, you can also set them up for specific event types. and add them to specific event templates.  The idea is basically the same as above, but you can access this functionality from Administer > Communications > Scheduled reminders.

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).

A "Tell a friend" activity record will be added to a participant's Activities tab each time she sends mail to her 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.

Personal Campaign Pages

If you enable Personal Campaign Pages (PCPs), you offer completed event registrants the ability to create and customize a page of their own to either:

promote the event for which they registered

promote an online contribution page

For more information see Contributions > Personal Campaign Pages in this book.  This is the last step in creating an event. Click Save and Done.

Testing the registration process

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

Navigate to Events > Manage Events.

From Event Links, 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. 

Fill out the registration form and complete the registration process.

In order to find the new test participant record, navigate to Events > Find Participants.

In the search criteria, check the box Find Test Participants.

If you need to adjust the event settings, navigate to Events > Manage Events and click the Configure link for this event.

If you discover elements that you need to edit and adjust, select Configure to return to the list of event setting pages.

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.

Once you are satisfied with the event information and registration form, it's time to display it on your website. The Everyday Tasks chapter includes detailed information on adding the event to your web site and promoting it. 

Using event templates to streamline event creation

If you need to set up a number of events with similar configurations, you can streamline the process using event templates.

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

Assign a descriptive template title that clearly identifies the type of event this template is used for (e.g., Monthly community meetup with online registration).

There are no starting and ending dates in the template form. That information will always be specific to an actual event instance.

Click Events > Event Templates.

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

Select campaign if all events created from this template should be associated with a campaign. 

Continue the normal event set-up process using the settings that will be constant for all events to be created using this 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 pre-filled with the saved configuration properties.

Registration permissions

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 Administer > 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, you must assign the following CiviCRM module permissions for the anonymous user role:  

access all custom data - required if you are collecting information in custom fields from registrants

profile create - required if you've included any profiles in your online registration forms

register for events

view event info

view event participants - required if you want to display a listing of registered participants.  

If you want to exclude anonymous visitors from viewing or registering online for events, assign these permissions to an authenticated user role.

CiviCRM has an additional permissioning system known as Access Control Lists (ACLs) ACLs allow you control access to CiviCRM data. Note that a CiviCRM ACL Role is not related to the Drupal Role. Refer to the Access Control List chapter for more information. 

If you need to limit access control for specific events, you can use the Manage Access Control feature to assign access to specific groups of contacts.  

CiviEvent Everyday Tasks

This chapter outlines a variety of tasks related to managing an event that you have set up in CiviEvent.

Dashboard

The CiviEvent Dashboard displays an Event Summary table, providing a summary of up to ten scheduled and recent Events. Click the Event name to view the event as it will be displayed to site visitors. Click the Participants count to see a list of participants.

To run your own customized searches, click Find more event participants at the end of the page. Here you can search by Participant Name, Event, Date Range and Status.

From the Dashboard you can also:

click on Manage Events to find and manage specific events

click on New Event to create a new event page

use the icons for RSS feeds and calendars to use the data in external applications.

Finding and Reporting on Participants

This section describes some common event searches. 

Overview of participants for all upcoming events

Navigate to Events > Dashboard

Click the Counted: link to see all the contacts for an 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 clean-up duty. 

Find participants for any event with a variety of criteria

Navigate to Events > Find Participants.

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. 

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:

Batch update participants via profile: this feature is useful if you wish to edit multiple fields for multiple participants in a table grid layout. Note that you must create the profile set you wish to use before implementing this action. If you are not familiar with how Profiles work, please read the chapter on that topic before using this feature.

Cancel Event Registrations for the selected participants.

Change Participant Status for the selected participants.

Delete Participants: deleting participants does not delete the contact record; it will delete all transactions and activities associated with the participant for this event. Note that this action cannot be undone.

Export Participants: this allows you to export a predefined set of fields or create your own custom set of fields (which can be saved for reuse). The software exports to CSV format, which can be easily opened in standard spreadsheet software or directly used for mail merges.

New Smart Group: smart groups are saved search results based on defined criteria, similar to a query. The advantage of a smart group is that the system will rerun the query using the criteria you have defined each time you open the smart group. This is particularly helpful for complex search criteria that you need to view on a regular basis.

Print Event Name Badges: select the type of badge you require and a printable PDF will be generated with the names of the selected participants.

Send an Email to Contacts: CiviCRM also lets you generate an email on the fly to your search result list. For example, you may want to let recipients know details about the event in advance, such as parking options or changes to the programme.

List participant's individual fees 

Navigate to Search > Custom Searches.

Click on Event Aggregate.

Choose your search criteria, and click Search. 

Create an event report from a template

 Click Reports > Create reports from templates.

Scroll to see the templates in the Event Report Templates section.

Click the name of the report template to create a new report. 

Choose the desired report criteria, then click Preview Report. 

Expand the area labeled Create Report.

Choose a report title, and other choices as desired. 

Click Create Report. Typical results appear in the following screenshot. 

Mass Registrations

CiviEvent offers the time-saving feature of registering multiple contacts for an event at one time (or as a "batch"). Returning to the youth leadership workshop scenario, Arts in Action anticipate a high rate of attendance from participants at the previous workshop. The staff perform a search to find previous participants and mass register them, setting each individual's participate status to "pending". The list of pending contacts is then used to call or email 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".

Steps for Mass registration:

Search for the set of contacts you are interested in (Arts in Action would navigate to Search > Find Participants to search for all participants at the previous workshop).

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

From the actions list just above the search results, choose Add Contacts to Event then click Go.

Choose the event you would like to register participants for. Note that you cannot currently register participants en masse for past events.

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.

Click Save.

Limitations of mass registrations

The action choices you make (in Step 3) are applied uniformly to the entire set of selected 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 do mass registration of participants for events in the past.

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 can always add payment details for individual contacts later on.  

Importing Registrations

Arts in Action is collaborating with a local school for its youth leadership workshop; the school is handling their students' registrations and sending a spreadsheet after the event which Arts in Action will then import into CiviCRM. It is important to record the event registration inside CiviCRM to enable Arts in Action to consolidate accurate information and enhance interactions and reporting for future event participants. 

Importing registration information is a quick way to add a bunch of registrations to the event. The data 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.

Steps for importing registrations

Prepare the data in the CSV file: make sure date fields (if used) are valid dates, and 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. 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.

From the navigation menu, go to Events > Import Participants.

Browse to the data file on your local computer.

Select the appropriate contact type, date format and other options, and click Continue.

Match the fields of your CSV file to the CiviCRM fields. 

If this is something you may repeat in the future, check the Save this field mapping box.

Preview and Save.

Promoting your events

Getting the word out and building excitement about your event can take many forms, but most important is to ensure that the event is prominently listed on your organization's website and your public calendar. Then you can use various strategies to let people and organizations know about it, and encourage participants 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.

Display an event description or registration on the website

Drupal:

Navigate to Events > Manage Events and then click  more > Live Page for the event.

Copy the URL for the event page.

Create a Drupal menu item for this URL or paste the URL into any Drupal page.

Additionally, you can 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

Joomla!:

Go into the Joomla! control panel.

Choose Menu Manager > Your menu name.

Click New.

Expand CiviCRM > CiviCRM Events and click the Event Info item.

Choose the event from the Select an Event list on the right side of the page.

Click Save.

WordPress:

Navigate to Events > Manage Events and then click  more > Live Page for the event.

Copy the URL for the event page.

Place the URL in a page or menu

or

Navigate to a Page or Post

Use the CiviCRM icon 'shortcode' to insert the event registration form into the Page or Post

Add the participant list to the event information page

Some organizations may wish to publicise their guest list as part of the event description to encouraging others to register.   

Navigate to Events > Manage Events, then click the Configure link for the event.

Expand the section labeled Public Participant Listing and copy the URL in the description area. 

Click the link Event Information and Settings.

Paste the URL from step 2 into the event summary or event description, then click Save and Done.

Optionally, you can share the URL via other communication vehicles such as within an email message, associated web sites and any other places you are promoting the event. 

List of upcoming events

Sometimes you may want to give an external organization or web site a link to a list of your upcoming events, that they can place anywhere on their website. For example, the school that is collaborating with Arts in Action might want to make information about future workshops easily accessible to their students' parents by including it in the school web site. 

To get the URL: 

Navigate to Events > Manage Events.

Click on the globe icon on the top right of the page.

Copy the URL.

Send the URL to the other organisation for inclusion in their site.

The only drawback is that the page will appear visually like your own website. 

RSS feed for all upcoming events

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

Navigate to Events > Manage Events. 

Click on the orange and white square icon on the top right of the page.

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 then capture the friend's email and create a Tell A Friend activity for the email, and create a corresponding activity in the participant's record.

Navigate to Events > Manage Events and click the Configure link for this event.

Click on the Tell a Friend link.

Click the checkbox to enable Tell a Friend for this event.

Provide an appropriate message to include for this event.

The Tell A Friend option will now appear in the event registration page.

Showing events in a calendar

Many web sites include a graphical calendar that can display upcoming events by the month, week or day. It is very useful to get your events on relevant calendar pages. Often individuals maintain personal digital 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

Navigate to Events > Manage Events.

Click on the square icon displaying  "31" on the top right of the page.

Save the iCal file on your local computer.

Go into the other calendar system and find the import iCal file tool.

Within the import wizard of the other calendar system, browse to and upload the iCal file from your local computer.

New CiviEvents created later 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

Navigate to Events > Manage Events.

Click on the square green icon displaying the letters "ICAL" on the top right of the page.

Copy the URL of the page that opens.

Go into the other calendar system and find the import iCal feed tool.

Within the import wizard of the other calendar system, paste the URL from step 3. 

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

Displaying an event report on CiviCRM 's home dashboard

If you haven't already created any Event Reports, see the following chapter Reports and Analysis for instructions on how to create reports. You must then ensure that the report you want to display is available for the dashboard:

From the navigation menu, click Reports and select the report you wish to display.

In the Report Settings area, check the Available for Dashboard? box.

Click Update Report.

Once the report is available for the dashboard, you can then:

Navigate to Home to view the dashboard.

Click Configure Your Dashboard.

Drag the desired report from the Available Dashlets area into either the Left Column or Right Column of the dashboard area, and click Done.

You should now see your report on your home dashboard. 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:

Navigate to Events > Manage Events.

Click the Configure link next to your event.

Click the Event Information and Settings link.

On the Info and Settings form, check the Offer a Waitlist? box.

Click Save.

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 invite volunteers who have donated 100 or more volunteer hours to an appreciation dinner. The people invited may talk about the event to their friends, and possibly forward the information. With CiviEvent, you can check who has registered and approve only the people invited.

To create an event that requires approval:

Navigate to Events > Manage Events.

Click the Configure link for your event.

Click the Online Registration link. 

On the Online Registration form, check the Requires Participant Approval box.

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.

Click Save or Save and Done.

Now, 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. 

Managing Participants

After creating your event and providing the registration form to web site visitors, you can manage your participants through the CiviEvent administrative tools. In this section we will discuss how these administrative tools are used. 

CiviEvent lets you:

register participants manually (including partial payments at time of registration)

modify price field selection for an existing participant

search through participants based on a variety of criteria

export participant lists

perform a number of other functions on your event records. 

The Events dashboard brings all your events and participant information together in one place (see screenshot). 
  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 may continue to register by mail, phone, or in person on-site. Your staff will then need to 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.

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:

Add Event Registration: for people who pay later, such as by sending a check or paying when they arrive at the event. 

Submit Credit Card Event Registration: for people paying immediately with a credit card. This option is available only if you've configured a payment processor that allows direct payments through your web site. If you are taking a registration over the phone you can ask them for their credit card information and enter it manually.

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 choices you have made. For example, when you choose the event you are registering the contact for and select a 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 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.  

Registering a participant paying only a deposit (partial payment)

If you are registering a participant manually, you can enter a payment amount less than the event fees, then make one or more additional payments later on until the fee is paid in full.  

During the manual registration you enter the the amount actually being paid at this time in the Total Amount field in the Payment Information region.  This sets both the Event status and the status for the linked contribution to Partially paid. 

The expectation is that additional payment(s) will be made until the full event fee has been paid, so a Partially paid registration is included in the participant total in the same way as a Pending from pay later registration.

To make an additional payment on this registration:

Go to the registrant's contact record.

Click on the Events tab on that record.

Click on more on the far right of the partially paid event record.

Select Record Payment.

For a payment using a credit card select submit credit card payment, otherwise complete the payment details as required.

You can make more than one additional payment.  When the event fee has been paid in full the Event status will automatically change to Registered (although you can override this by choosing a different status option when you make the last payment) and the status of the linked contribution will automatically change to Completed.

Looking at this from an accounting perspective, when the registration is created, the event fee is added to accounts receivable. Each partial payment is then added as a separate line item until the fee is paid in full.

Note that on the event registration and the linked contribution the displayed amount will always be the full event fee. You can see how much is owing by choosing to view the event registration.  Selecting ›› view payments  (under the Total Paid amount) will display a summary of each payment.

Changing event registration selections for an existing participant

Sometimes the details of an existing registration needs to be changed.  Some examples are:

A volunteer for an event has been asked to register online selecting a pay later option for the event fees.  Back-office staff want to change the person's role from attendee to volunteer and select a zero fee option from an admin-only price field.

A conference participant decides they no longer want to attend the conference dinner and requests a refund of the dinner fee.

A participant decides after registering online that they do want to attend the pre-conference workshop and contacts the registration office with that request giving their credit card details for the extra charge.

A child registered for a holiday program decides she want to do archery rather than pottery one afternoon.  Although there is no difference in fees, back-office staff need to change her event registration so that they know where the child should be for that session.

All of these situations can be managed by back-office staff editing the participant's event registration as follows:

Navigate to the participant"s event registration (One way to do this is via Events > Find Participants)

Select View or Edit (towards the right of the event record)

Click on Change Selections.

Make the required adjustments.  The event fee will be adjusted appropriately and the event status will be set to partially paid, registered or pending refund based on the difference between the new event fee and the contribution(s) already processed. 

Additional payments (credit card or offline methods) or a refund (offline methods only) will need to be entered via the record payment link associated with the event registration record as described in the section on partial payments.

Event Badges

You can create custom name badges for your event.

Set-Up

Navigate to Administer>CiviEvent>Event Badge Layout>New Badge Layout and you will see the following set-up screen.

Points to consider are:

Label format: Four options are available

Avery 5395 - 2-1/3" x 3-3/8"

A6 Badge Portrait 150x106

Fattorini Name Badge 100x65

Hanging Badge 3-3/4''x4-3/4''

Image (top left) and/or Image (top right): You can select an existing image or upload a new one.  Images can be positioned on the right and the left so that your logo and that of you major sponsor could be included.

Elements - Rows:  Most standard or custom contact, event and participant fields can be selected to provide up to 6 rows on the labels or you can select spacer to improve the layout. Typical fields to include would be display name, current employer, country and/or participant role. If you have set up the appropriate custom fields you could also include which sessions the participant has registered for and which meal option they selected.

Barcode?: A linear barcode or QR code can be added at the bottom of the badge.

Enabled?: This needs to be ticked for people to use this badge layout.  If you want to keep a special layout for your annual conference you could untick this box for most of the year to prevent accidental usage.

Reserved?: Select this option if you want to ensure that admin users do not accidentally delete the badge layout.

Note: You will not be able to preview the badge layout unless at least one event has been created and at least one participant has been registered.

Printing Name Badges

Once your list of event particpants is finalised you can print the name badges for the event as follows: 

To print name badges, do the following: 

Go to Events>Find Participants.

Select the relevant participants.

Choose Print Event Name Badges from the drop-down list of actions and Click Go.

Select the name badge layout for this event.

Click Make Name Badges

A PDF file will be created that you can print on the appropriate-sized labels.

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.

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 Display Results As 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.

What is CiviMember

CiviMember is the CiviCRM component that provides functionality to support and automate the management of memberships. CiviMember allows you to:

define membership types and pricing schemes that meet your needs

create self-service options for online membership sign-up and renewal, utilising CiviContribute

manage memberships manually through the administrative interface

create and schedule automated messages to welcome new members, remind about upcoming renewal, etc.

track and report on your contacts through the membership cycle  

grant additional website privileges for members.

The chapters in this section take you through everything you need to know in order to get the most from CiviMember.

If you are new to CiviMember and planning to use it for your membership management it is a good idea to review this entire section whilst you are considering your organisation's membership scheme and working out how best to model it within CiviCRM. CiviMember provides a high degree of flexibility, enabling you to configure it to meet most requirements.

Adopting a system like CiviCRM will normally require some changes in working practices, so it is important to work closely with the people within your organisation who will have day-to-day responsibility for managing memberships using CiviCRM as you develop your plans.

Memberships can run from a day to a lifetime, they be free or paid, and have simple or complex pricing structures. They can be set up to auto-renew where a compatible payment processor is enabled.

Memberships for any given contact are visible on the contact's summary screen and on the membership dashboard. They can be searched for through the Membership Search or Advanced Search, and CiviMember provides four membership reports, each of which can be customised to better meet your specific needs.

Conceptually, members are simply contacts in your CiviCRM database with one or more memberships. The contact may be an individual, a household, an organisation, or some other contact sub-type, but it is always a contact to which a membership is applied.

Scenario: Driving membership forward

The Atlantic Region Public Transit Association (ARPTA) has a complex requirement with four membership categories:

Regular Members: Public transit systems. There are three tiered levels within this category, based on the size of the system. Membership is organization-based, and all employees of the member organization receive access to member benefits, such as discounted rates at Association events.

Affiliate Members: Businesses providing goods and services to the transit industry. Membership fees are the same for all Affiliate Members. Membership is organization-based, and up to 10 employees of the member organization receive access to member benefits, such as discounted rates at Association events.

Associate Members: Students, government representatives, public interest groups, research institutions, and other interested parties. Membership fees are the same for all Associate Members. Membership is individual-based.

Honorary Members: Retired transit system executives and others who have made a notable contribution to the industry and Association. Membership is individual-based and free for life.

When the ARPTA membership administrator, Sue, initially configured CiviMember she created a separate membership type for each of the four member categories described above. This was 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 board agreed that they needed to boost membership income by improving their membership recruitment and renewal rates, whilst keeping tight control, and if possible reducing, the amount of time spent on membership administration.

To help achieve this they used CiviContribute and CiviMember to set up online sign-up and renewal pages for Regular and Affiliate Members. They were then able to run targeted membership recruitment campaigns linking to the online sign-up pages so that potential members could quickly join online. At the same time, existing members were encouraged to renew online, by logging in to the member section on the ARPTA website.

These steps streamlined ARPTA's sign-up process, eliminated a lot of admin work and gave Sue a clear view of new sign-ups, recent renewals and expired members that need to be chased. Through CiviContribute, she can produce a monthly spreadsheet for her 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 much more involved in the annual conference, which ARPTA manages using CiviEvent.

ARPTA's board were also pleased with the results of the move to online sign-up and renewal, which, in conjunction with their marketing campaign, led to a 30% jump in new members over a year. Their analysis also showed a 40% improvement in membership retention (in part because Sue was able to devote more time to contacting lapsed and expired members, and in part because members reported that they found it easy and convenient to renew online, and were prompted to do so by the reminder emails that Sue had set up using the Schedule Reminders feature. Their market research also showed that members appreciated the fact that they were being contacted more regularly by Sue, and felt more engaged with ARPTA as a result.

Defining memberships

This chapter describes how to set up one or more membership types that you can use to manage your organisation's members.  It also explains the concept of membership statuses and how your organisation can use them to define a membership life-cycle.

Membership types

Membership types are a basic building block for membership management in CiviCRM. Typically an organisation will set up a membership type for each of the different memberships that they offer. For the simplest membership structures, one membership type may be enough. For more complex membership structures, more membership types may be required. For example, an organisation may define three membership types for 'regular', 'student', and 'honorary' members.

There are a number of options that can be configured for a membership type, and these are best discussed by working through the membership type form. A solid understanding of the options will help you decide on how many membership types your organisation needs and how they should be configured.

In this chapter we will cover the most common set-up for membership types. Some organisations, with more complex membership structures, have requirements that go beyond what is available with membership types alone.  These organisations may find that membership price sets give them the extra flexibility they need.  Since membership price sets are an advanced topic, they are covered in their own chapter Membership price sets. 

If you are having trouble modelling your membership structure in CiviCRM, ask in the forums about the problems you are having. There may be other ways to model your data, or simple changes you can make to CiviCRM's behaviour to better fit your needs. 

To start learning about membership types:

Go to Administer > CiviMember > Membership Types

Select Add Membership Type

Name

The name is displayed throughout the system, on both public and backend pages so spend some time thinking about a name that is appropriate to both audiences. It can be changed at a later date (though this may result in extra work in updating membership receipts if they have been customised based on membership names)

Description

This is not required but you may wish to fill it in with a description of the membership, what type of contacts it is aimed at, etc.

Membership organisation

CiviCRM is able to manage the memberships of more than one organisation, i.e. a local sports centre could use a single CiviCRM instance to manage the memberships of a tennis club, a football club, and a hockey club. For this reason, when defining a membership type, you specify the organisation that the contact will become a member of.  Each organisation must already exist as a CiviCRM organisation contact. Many organisations are only interested in modelling the memberships of one organisation (their own organisation). In this instance you can just choose the default organisation.

If you wish to enable online sign ups or renewals, the CiviCRM data model requires that a contact can only have one active membership with a single organisation at any given time.  However, some organisations may want people to have two or more memberships of the same organisation that run concurrently.  For example, an organisation focused on child health might want to offer a membership for parents that includes a parenting magazine and a membership for health professionals that includes a peer-reviewed journal and discounts at training events. Parents who are health professionals may want both memberships. A 'workaround' for this is to create 'dummy' organisations for each of the possible concurrent memberships .  For the situation just described, we would need to create an extra organisation for health professionals.  Note that you don't have to expose the dummy organisation to your members on the website, it is only for administrative purposes.

Minimum fee

If your memberships are free you should enter 0 (zero) in this field.  Otherwise you should enter the minimum amount that must be paid for this membership type. The reason we call this field the minimum amount is that we have an option to encourage people pay more than the minimum for a membership if they want to.

Financial type 

The default financial type for a membership type is Member Dues.  This is appropriate for  many organisations. However, if you have more complex accounting needs, you can specify different financial types that will allow you to account for different membership payments in different ways. For more details see the Accounting Integration chapter in the Contributions section. If you need more fine grained control over financial types you may want to look at using membership price sets.

Note that the financial type can be overridden for specific public membership sign up pages, and also when recording a membership in the back end.

CiviCRM handles paid memberships by linking membership records to contribution records. A membership record documents a contact's relationship with the organisation, while the corresponding financial transaction indicates the monetary value associated with that membership.

CiviCRM respects this distinction by storing the membership record under the membership tab, storing the financial record under the Contributions tab, and then creating a link between the two records.

Auto-renew

CiviCRM offers an auto-renew functionality that will automatically submit a repeat transaction to the payment processor when the current membership expires. This can be a good way to increase membership retention. This functionality is not available for all payment processor so you will need to check if yours is configured for recurring payments before selecting one of the auto-renew options here.  For information on payment processors see http://wiki.civicrm.org/confluence/display/CRMDOC/Payment+Processors.

You can offer or require auto-renewal for a membership type. However auto-renew memberships can only be offered for memberships that have a duration (discussed below) of one year or less. 

Duration

In the Duration field you should enter the number of days, months or years that your membership lasts for each time someone signs up or renews.

Period type

The options for Period type are rolling and fixed.  Rolling memberships start on the day the member signs up. Fixed memberships start on the particular calendar date you specify. 

When you set the Period type to fixed, extra fields will appear depending on the duration you have specified.

If the Duration is specified in years two extra fields will be displayed:

The Fixed Period Start Date is the calendar date that all memberships start on (eg January 1st or April 15th).

The Fixed Period Rollover Date determines the end date for the membership when a person signs up part way through your membership year. Its use is best illustrated through an example.  Consider a membership type with a Duration of one year, a Fixed Period Start Date of January 1 and a Fixed Period Rollover Date of September 1

Anyone signing up between 1 January 2014 and 31 August 2014 will have a membership end date of 31 December 2014. 

Anyone signing up on or after 1 September 2014 will have a membership end date of 31 December 2015.( ie they will receive up to 15 months membership for the 1 year price.)

If the Duration is specified in months one extra field will be displayed:

The Fixed Period Rollover Date determines if the membership duration starts at the beginning of the current calendar month or the beginning of the next calendar month. Consider a 6 month membership type with Fixed Period Rollover Date set to 15:

Someone signing up on days 1-14 January will have a membership end date of 30 June.

Someone signing up on days 15-31 January would have a membership end date of 31 July.

Example: If Duration = 12 months, Period type = Fixed, and Fixed Period Rollover Date = 1, then anyone joining during August 2014 will have an expiry date of 31 August 2015.

Relationship Type

Memberships can be inherited from one contact to another.  An example of this would be a professional trade organisation that signs up a company as the (primary) member and wants employees of the company receive the benefits of membership.

In order to support this feature we define a relationship type along which the membership inherits.

The pop-up help screen gives examples of the relationship types to select for this feature. Once you have selected a relationship type, you enter a number in Max related to set a maximum for the number of inherited memberships linked to each primary member. This would be useful, in the example above, to limit the number of employees that can become a member by virtue of their employment to 10 maximum.

With inherited memberships, we distinguish between the primary member and the members that inherit their membership from the primary member. 

Visibility

Choosing Public means that this membership type will be able to be selected for inclusion on online membership sign up forms. If certain membership types are only to be handled by an administrator manually (e.g., honorary and lifetime memberships) you should choose Admin here.

Order

This determines where this membership type appears in a drop down options list of membership types, and on membership sign up pages.

Enabled

If you have membership types that are no longer offered or not yet available you may wish to untick this box. This will remove these memberships from the user interface. It will not delete the membership data, however, and the membership can be re-enabled at a later date.

Membership status rules

Membership status rules allow you to define a journey that contacts take through their membership.  These rules are defined in terms of the join, start or end date of the membership. So let's first have a look at what these dates mean.

Memberships have three primary dates, the join date, start date and end date. The join date is the date the contact first signed up for a membership with your organisation.  Unless it is altered manually it will never change from that first value.  The start date is the date the current continuous period of membership began.  The end date is the last day of the current membership.

By default the journey through membership statuses is as follows: 

Pending: someone who has requested membership but has not paid. This status cannot be amended manually meaning that you can not change the status from pending to new unless you update the associated contribution record. For example, if you have the pay later option enabled for membership and Joe Smith signs up for your membership and chooses the pay later option, the status of his membership will not be changed to new until you change the contribution status of his related payment to Completed.

New: member has just signed up for a membership or a pending payment has arrived. By default this lasts until 3 months after the membership start date.

Current: new members move to this status after the new period has finished. As might be expected, the current status lasts until the membership end date.

Grace: when the end of the membership period is reached, someone who has not renewed membership enters this status for a period of time. They are still counted as a member.

Expired: when the grace period expires, the member moves to this status and is no longer counted as a member.

Deceased: this status keeps a deceased contact's record in the system but removes the contact from all further communications. This status is set automatically based on a contact's deceased flag).

You can force a membership to have its status overridden by selecting membership override on a membership record and choosing a status. As might be expected, a membership with status override will remain at that status, and not be updated according to the membership status rules described above.

At Administer > CiviMember > Membership Status Rules you will find a summary of the existing status rules.

To decide on which status should be applied, CiviCRM looks to see if the membership has a status override. If it does, it applies that status. If not, it looks at each status in turn starting at the top of the Status Rules page until it finds one that is valid. That is to say, it looks to see if today's date is between the start and end date for the membership status at the top of the list.  If it is, it applies that status, if not it moves to the next status and repeats this process until it finds a status that matches.

When you edit or add a new membership status the following form appears.

You can add new statuses and edit existing statuses (except for Pending and Deceased) using this form.  To create a new status, you need to specify when the status should start and stop. This is done in relation to a membership event (i.e. the join date, start date, or end date).  e.g. 'one month after the membership start date would be configured with 'start date' and '1 month' or 'five days before the membership end date' would be configured with 'end date' and '-5 days'. 

You also specify whether contacts with this membership status should be considered members or non-members by checking or unchecking the 'Current membership' tick box. (This results in a Yes or No in the Member column on the status rules summary page.) Renewing contacts with a status that defines them as members will have their existing membership end date extended by the duration of the renewal.  Renewing contacts with a status that defines them as non-members get a new start date for their membership and an end date based on that new start date.

Keeping membership statuses updated

When a membership is added or renewed the membership status is automatically set based on your status rules. For example, a newly created membership will be assigned the status "New" by default. If your membership statuses are not updating automatically, make sure that the Update Membership Statuses scheduled job is enabled and runs at least once a day. Refer to the Scheduled Jobs chapter for configuration details and consult your system administrator if appropriate.

Collecting additional information about your members

Sometimes you want to collect additional information about your members.  You can create one or more custom field sets for this purpose.  Custom field sets can be created for either all memberships or specific membership types.  If the information you want to collect varies according to the membership type then you should set up more than one custom field set linking it to the specific membership type(s).   (Refer to Custom Fields chapter in the Organising Your Data section for more details.)

Online membership sign up

This chapter explains how to allow visitors to your website to sign up as members of your organisation. It looks at the steps necessary to create membership sign up pages, some things to consider when doing so (including testing your membership pages), and the ways in which you can integrate membership sign up pages into your website.

Before reading this chapter, you may wish to read the chapter Defining memberships which gives useful background to many concepts (like membership types, membership statuses, and so on).

About membership sign up pages

Membership sign up pages are created in the same way as online contribution pages. In essence, you create an online contribution page and then add to this page the ability to sign up for a membership. The reason we do this is because the actual work flow for becoming a member of an organisation is normally quite similar to the work flow for contributing money to an organisation, and tying them together allows membership pages to take advantage of a lot of the functionality that contribution pages have, for example, we can offer premiums as part of the membership sign up.

Note that even if your membership is free, you should still use a contribution page for online sign up (see free memberships below for instructions on how to do this).

Contribution pages are very powerful and have a lot of options that are grouped together into tabs. Once you have given your contribution page a name, these tabs are displayed at the top of the page as you work through the rest of the set up process.

In this chapter, we concentrate on the tabs and options of contribution pages that are most useful for memberships.  A couple of tabs that are worth highlighting include the Memberships tab, which contains the bulk of the membership configuration, and the Profiles tab, which allows you to collect information about the people or organisations that are filling out your membership form.

We recommend you also review the chapters on creating online contribution pages which will give you a better understanding of all the tools you have at your disposal when creating membership pages.

The Title tab

The title tab (which is also the first page that you see when you create a new membership page) allows you to set the title for the membership page and set some basic information like the Financial Type etc. that will be recorded for memberships that are made through this page.

This tab also has space for you to include an introductory message to be displayed on your membership page. You can include images and other simple HTML in this introductory text.

Organisational memberships

The title tab contains a check box to allow people to become members on behalf of an organisation, which is the recommended way to offer organisational memberships. When enabled, you are prompted to select a profile (see the profiles chapter for more information) that will be used to collect organisational information. Organisational sign up can either be optional or required.

The Amounts tab

The amounts tab allows you to set various financial options, including the payment processor that is used on the page. Note that you can select more than one payment processor which will give people who are signing up a choice. For more information on setting up payment processors, and things to consider when choosing a payment processor see the chapter Payment processors.

Note that the amounts tab is not the place where membership fees are configured - they are configured on the Memberships tab. If you want to use this page for collecting membership amounts and do not want to solicit extra contributions, leave the Contribution Amounts section enabled checkbox unticked. If you do want to solicit contributions on top of membership fees, then tick the box and either add some suggested contribution options or configure a contribution price set.

Free memberships

If you are offering free memberships, you should leave the 'Execute real-time monetary transactions' box unticked and choose a membership type with a zero value minimum fee.

The Memberships tab

Since we are using this contribution page for membership sign up and renewal, we need to check the Membership Section Enabled to use this contribution page for memberships.

The first few boxes allow you add text that will be displayed when this page is used for initial membership sign up and for renewals. When a logged in user with a current or expired membership views the membership sign up page, CiviCRM automatically replaces the membership sign up page with a membership renewal page which contains the text from the renewals box.

After the text boxes, are a few options that you can use to configure the membership types available on the membership form.

Looking at the simple use cases first, you select which membership types should be available on the page, which should be the default, and which can be auto-renewed (you'll need to have set up your membership types as auto-renew and have a payment processor that supports automatic recurring payments).

If you enable auto-renew for a membership then on the web page users will see "Please renew my membership automatically. (Your initial membership fee will be processed once you complete the confirmation step. You will be able to cancel automatic renewals at any time by logging in to your account or contacting us.)"  Membership payment receipt emails will include a link for the member to cancel the auto-renewal.

If you want, you can make membership signup optional. This is often useful if you have a contribution page on which you want to offer the ability to become a member, but not require it (you will need to check the box for "Contribution Amounts section enabled" on the Amounts tab).  You can decide whether such payments are recorded separately from membership fee payments.

If you cannot accomplish what you need using the Membership Types table (for example if you want to offer sign up to two memberships at the same time, or offer sign ups with multiple membership terms), then you should use a membership price set (which is covered in its own chapter Membership price sets).

Some of the things you can do with price sets include:

allow users to sign up for multiple classes of membership (e.g. "national" and "local" memberships) at the same time

let people sign up for multiple membership terms at the same time

offer other options such as a paid subscription in addition to membership signup.

The Receipt tab 

After the site visitor completes the membership signup or renewal form, they will be redirected to a thank-you page and can have an email receipt generated and sent to them. This fourth step in the wizard allows you to configure those options. You can customise the message that gets added to the membership receipt on this page, and the email address that the receipt will come from. If you want to further customise the receipt email template you can do so using the Mailings > Message templates screen.

You may also want to CC or BCC every membership receipt to a staff member so they are alerted immediately every time someone becomes a member.

The Tell-A-Friend tab

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. Those friends that are told about the membership sign up will also be added to CiviCRM if they do not already exist and their source field will show that they were added via tell-a-friend.

Collecting information as part of membership sign up (the Profiles tab)

You can use profiles to collect information about your members as they fill in the sign up form. By default, contribution pages will include only an email field. Adding a profile to the contribution form will add a collection of fields that CiviCRM will display as part of the membership sign up form.  You can use profiles to collect extra information about the contact, for example their address, their interests, etc. If the person signing up to become a member is logged in, their profile fields will be populated with data from CiviCRM where available. Don't add a membership profile. Collection of that information occurs automatically during the online membership sign up process. 

The profiles tab allows you to select an already existing profile to include on your membership page, and if you have permission, to edit an existing profile or create a new profile to be included on this page. WARNING: If you edit an existing profile here, it will be changed in all places where that profile is used. 

Premiums tab

Premiums are thank you gifts and incentives offered to people that donate to your organisation. They are most commonly associated with tiered donation levels (e.g. donate $50 to receive a T-shirt) but can also be used in conjunction with your membership pages.  Before including premiums on a contribution page, you must configure them through Contributions > Premiums (Thank-you Gifts).

The Premiums tab of the contribution page wizard controls the introductory text, contact information, and other premium-related details.

Testing membership sign up pages

Once you finish configuring and setting up your membership page, you are advised to test drive the process to make sure everything is working according to your expectations. Test functionality is available on Contributions > Manage Contribution Pages, click Links next to your membership sign-up/renewal page and click Test-drive. Any membership data you send through the form in test mode will be added to CiviCRM as test data and not be included in any membership stats or when searching for members, etc.  If you want to find and delete test memberships, you can do so by clicking the 'is test' check box in Find Memberships.

Try and put yourself in the eyes of someone who wants to become a member of your organisation and go through the process a number of times, with different combinations of fields each time.  Make sure that the data all appears as you would expect in CiviCRM. Once you've tested the process and have made any necessary changes, get other members of staff or friends from outside your organisation to test 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 (see Payment processors for more information on dummy processors and card details you can use for test transactions).

It is worthwhile periodically testing and reviewing your membership process to make sure that it is as smooth as possible. You will receive indirect feedback from your members as they use the form. If they are not entering data in the way you intended then you will need to make some changes.  From time to time, you may want to solicit direct feedback from people who have recently become members to see how easy it was for them to become a member and ask their opinions on ways in which you could improve your form.

Adding membership sign up pages to your website

Once you've made your contribution page, you need to make it visible on your website. The method for this depends on the CMS. Instructions for each CMS are below.

Membership sign up pages are built to inherit your website theme and should look reasonably nice out of the box. You can include images on the HTML text areas in the page to make them look more attractive. Many organisations want to spend time improving the look and feel of their membership pages in order to increase membership sign up rates. The methods for changing the design of these pages are outside the scope of this book but a website designer who is familiar with your CMS and CiviCRM will be able to help.

In Drupal

Go to Contributions > Manage Contribution Pages > click Links next to your membership sign-up/renewal page > click 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.

In Wordpress

Go to Contributions > Manage Contribution Pages > click Links next to your membership sign-up/renewal page > click Live Page.  Copy the URL and insert it into an HTML link or menu.

Or use a plugin such as Page Links To create a URL 'slug'.

Or click the Wordpress shortcode icon to insert a form into any page or post. 

In Joomla!

The most direct way to expose your membership signup/renewal page to the front of your website in Joomla is by creating a menu item.

Navigate to a menu and create a new CiviCRM item.

From the list of menu options, choose Contributions.

In the basic parameters section, select the contribution page you would like exposed from the dropdown menu.

Save the menu item and view the website to confirm the page's functionality.

Permissions needed for online membership sign up/renewal.

Anonymous and Authenticated roles need the following CMS permissions to be able to join or renew online:

Profile listings and forms: This will let you collect core contact information ( name, address etc.) when people sign up.

Access all custom data: You must enable this permission to collect custom data.

Make online contributions: This permission must be granted unless your memberships are free and you have no interest in accepting donations when people sign up or renew.

Manual entry of memberships

Although CiviCRM provides a tool set allowing website contacts to self-serve and become members without intervention required on the part of office staff (which can be very powerful and save organisations a lot of administration time), there are many situations when memberships need to be processed manually. This chapter describes the various ways in which office staff (or any appropriately permissioned users) can manually create and process memberships, including:

Creating new membership records one by one (including gift memberships where the payment comes from a different contact) 

Batch data entry of members

Importing Memberships

CiviMember Access Control

As with other CiviCRM functions, Administer > User & Permissions > Permissions allows you to control access to various CiviMember features.

For users who need to find and view memberships - assign the access CiviMember permission, the view contributions permission if payments are involved and make sure the user has view contact permissions for the associated record.

For users who need to create and/or edit membership records - assign the edit memberships permission, the edit contributions permission if payments are involved and make sure the user has edit contact permission for the associated contact record.

MOre details on permissions can be found at http://wiki.civicrm.org/confluence/display/CRMDOC/Default+Permissions+and+Roles .

Creating a New Membership Record

You can create a new membership record in a couple ways, by looking at an existing contact's record, or through the Memberships menu.  Using the membership menu is useful because you can create a new contact at the same time as adding the new membership record.

An advantage of creating a new membership record directly from an existing contact's record is that if you have set up a payment processor that allows credit card transactions directly on your site, you may select the Submit Credit Card Membership option and process the membership payment immediately.  

When you use the Memberships menu to create a new membership, you do not have the option to submit credit card information, but can still have the option to record other types of payments like checks and cash. 

Via an existing contact record

From a contact's record, click the Memberships tab then click Add Membership. If you have set up a payment processor that allows credit card transactions directly on your site, you can select the Submit Credit Card Membership option and process the payment immediately. 

Many of the fields on "New Membership" form will be auto-completed if left blank. Fields include:

Membership Organization and Type: select the name of the organization that the contact has a membership with and the type of membership  OR

Choose Price Set: select Choose Price Set rather than Membership Organization and Type if you have various fee structures for different classes of memberships. (see the chapter membership price sets for more details)

Number of Terms: enter the number of membership periods or terms associated with this membership record. The membership end date will then be set to an end date for this number of terms (this option is hidden when using membership price sets)

Source: if left blank the system will complete details regarding the record, including whether it was an offline or online transaction and who completed the record.

Campaign: if the membership is connected with a larger campaign, select the name of the campaign. To learn more, see the Campaign section.

Member Since: the date the membership record was created will be auto-filled, but can be overridden if necessary.

Start Date: if the membership type is a rolling membership, the current date will be auto-filled. If the membership type is a fixed period, CiviCRM will determine the appropriate start date based on the membership type configuration. This can be overridden if necessary.

End Date: this field is automatically calculated from the start date and filled in based on the membership type settings. This can be overridden if necessary.

Auto-renew: this field is only shown if you have chosen a Membership Type that has auto-renew functionality set in the Membership Type and are using the Submit Credit Card Membership option to create the Membership.

Status Override?: check this box to manually define a status for the membership record. As indicated by the title, it overrides the status automatically provided. You should use caution with this field as setting it will stop the status from automatically updating based on the membership status rules you have set up (see the chapter Defining memberships).

Record Membership Payment?: by checking the box and completing the transaction fields displayed, you will record the money paid for the membership. This creates a contribution record in addition to your membership record. After recording the membership, you will be able to view the membership record and see the related contribution record at the bottom.

Record Payment from a Different Contact?: this is often used for Gift memberships. 

Financial Type: select the appropriate financial type for this payment.

Amount: enter the amount of the membership payment.

Received Date and Time: enter the date and time the payment was received.

Paid By: select the payment instrument in which this payment was received, such as cash or check.  You can learn more about configuring Payment Instruments in the Contributions section. 

Check Number: if the payment was received by check, enter the check number.

Transaction ID: if you have a payment processor, CiviCRM will store an auto-generated transaction id.  For manual transactions, you can enter a bank transfer ID or other identifier as applicable.

Payment Status: select the status of the membership payment received. You can learn more about configuring Payment Instruments in the Contributions section.

Send Confirmation and Receipt?: check this box to send an email to the contact that their membership is confirmed

Receipt From: select the email address the confirmation receipt is from.  If the email address you want to use is not listed, you can add it by going to Mailings > From Emails.  

Receipt Message: you can enter text here to send a special message to the member. If you don't enter text, the default confirmation and receipt message will be used. 

Auto-renew Memberships via Back end

To manually create a membership that will auto-renew go to the contact's summary screen, select the Memberships tab and click on Submit Credit Card Membership. If you select a Membership Type that is set up for recurring, a checkbox labelled Membership renewed automatically will be exposed.

If you check Auto-renew, a recurring payment (subscription) request will be submitted to the selected payment processor. If the request is successful, this membership will be automatically renewed on the last day of the membership period until the recurring payment is cancelled. Membership payment receipt emails will include a link for the member to cancel the auto-renewal.

Via the Memberships menu

Navigate to Memberships > New Membership, then select the contact or create a new contact.

Fill out the New Member form with the appropriate membership and payment information as in Via an existing contact record above.

Gift Memberships

When you enter a membership manually you can select Record Payment from a Different Contact? to record the membership as a gift from someone else. The person paying for the membership (gifter) can be an existing or a new contact created during the process.  The payment will be recorded on the gifter's record with a soft credit for the membership on the gift recipient's record. The receipt will be sent to the gifter.  You will need to send a separate email or letter to tell the gift recipient about their membership.

Entering batches of membership payments

CiviCRM offers a Batch Data Entry feature (found in the Memberships menu) that can be used for entering batches of membership payments that have been received into the office on paper forms, or similar. It can be used for new and existing contacts and includes verification of the total amount and count of items against the payments you’ve recorded on your deposit slip(s). 

This feature has a batch entry grid input screen, which has a couple of tools that you can use to speed up processing when you have a lot of memberships to process at the same time. It includes a copy feature to set all fields to the same value, and allows you to create new contacts without leaving the batch entry screen.

The fields of information that you want to collect in the batch entry input grid for Batches are determined by several CiviCRM reserved profiles.  If you want to collect other kinds of information that are not currently included in these profiles, you will need to alter these profiles to reflect the fields you want to display. 

You can read more details about the Batch Entry of Contributions or Membership Payments feature in the Set-Up chapter of the Contributions section. 

Importing Memberships  

The Importing Memberships feature is very useful if you have a large set of membership records that comes from a source outside of CiviCRM. This feature can also be used to update large numbers of existing memberships with new information. 

You should read the Importing Data chapter in the Common Workflows section, before you begin importing memberships since this gives lots of relevant general information. Here are a few details specific to membership importing that you should be familiar with.

Contact records must exist before you import membership data.  If you want to import membership data for contacts that do not yet exist in CiviCRM, you will first need to import the Contact data.  Make sure the contact data has an External ID so you can include this External ID with your membership data to associate these records with the related contacts. If you are importing membership data for contacts that already exist, then you will need the Internal Contact ID or the fields from your Unsupervised Duplicate Matching Rule to associate the related membership data with the correct contact. 

Your import membership data file MUST contain both Membership Type and Start Date. The membership types listed must exactly match the membership types set up by your CiviCRM Administrator. The start date should use the date format specified for your CiviCRM installation. If your import file does not contain these fields then you will not be able to import it.

You must import membership data for different contact types separately. Importing files with more than one contact type will not work. (You must import new memberships and renewals separately also.)

Now you are ready to import your membership data:

Navigate to Memberships > Import Memberships.

On the Upload Data screen:

Select your import data file. It must be a CSV file.

Select the checkbox if your source data contains column headers.

Specify the contact type you are importing.

Indicate what date format you are using.

Click Continue >>.

On the Match Fields screen, map your membership data with the appropriate CiviCRM fields under the Matching CiviCRM Field column.   Note that you can Save this field mapping so you can re-use this mapping for future imports.

On the Preview screen, you will see the preview of the results of your import. There is a table that lists the Total Rows in the uploaded file, the number if rows with errors and the number of valid rows. If you continue with the import, the rows with errors will be skipped. You can download a file with just these problem records and continue with the import. You can then edit the errors and do another import with them.  Alternatively, you can fix the errors in your original CSV file and start the import again.

If there are no errors or you don't want to correct the found errors, click Import Now>>. You will be shown the progress of the import until it is complete. When the import is complete, you will see a summary of the import activity and its results.

Membership price sets

This chapter describes how to configure membership price sets so that your contacts can:

Sign up for multiple membership terms at the same time.

Sign up for more than one membership in a single transaction ( e.g. National and local memberships).

Select non-membership options such as information booklets when they sign up for a membership.

Here's an example of how a membership price set that offers all these options could look:

The Donwell Swim Club price set consists of five price fields: National Association Fees, Annual Club membership, Club Gear, raffle tickets and donation.

It offers two membership types: 

These membership types must be defined before you create the price set. (Refer to Defining Memberships chapter.)

You must also have defined all the financial types you will need before you can create the price set. (Refer to the Contributions section for information on financial types)

Membership price sets can be used in online join up or renewal pages or for new member sign ups processed manually through the CiviCRM back office system. However, they cannot be used for renewals that are processed manually. Each membership must be renewed individually (see the Renewals chapter) and in addition you may need to create a contribution price set consisting of the non-membership items you offer. Also, you cannot combine memberships that can be auto-renewed with memberships that do not offer auto-renewal or with non-membership items.

Price sets can be configured in many ways and you should always test a price set thoroughly before using it on your live site to make sure that you have configured it in the way that fits your situation best.

Creating a New Price Set

Navigate to Memberships > New Price Set or Administer > CiviMember > New Price Set.

Enter the price set name. This name will be displayed both to the public as part of the price set and to admin staff when they need to choose between price sets, so make sure it is descriptive enough for both purposes.

Tick Membership

Set the Default Financial Type. The choice you make has accounting implications and you should refer to the Contributions section for more information.

Add pre- or post-form help text if you want to.

Make sure the price set is active and Save.

You will be taken to a form to create the first price field for your price set.

Creating a New Price Field

Enter a name in the Field Label. This name will be displayed to the public.

Select the Input Field Type. There are 4 input types available for price sets:

Text/Numeric Quantity: allows you to set a unit Price. When the price set is displayed it shows a text box where a quantity can be entered. The quantity entered is multiplied by the unit price to calculate the amount.

Select: displays a dropdown box where one option can be selected.

Radio: displays multiple options in a list; up to one option can be selected.

Checkbox: displays multiple options in a list; multiple selections are allowed.

Each of the input types will be used in an example in this chapter. 

Financial Type will be set to the Default Financial Type chosen when this price set was created. You can override this value if required.

Display Amount? This displays the price of the option next to the label. If your field label includes the option price then this can be unticked. Otherwise it should stay ticked.

Order, Field Help, Required and Active are either self-explanatory or have adequate help provided on the form.

Active On and Expire On can be set so that the price field is not visible until the Active On date, not visible after the Expire On date or is only visible between the Active On and Expire On dates. For example you could use these fields to bring in a price rise at 12:00am on 1 January 2015 by setting the price field with the old prices to Expire On 1/12/2015 12:00am and the price field with the new prices to be Active On 1/12/2015 12:00am.

Visibility can be set to Public (visible on your website to those who can see the membership sign up page) or Admin (visible only through the back end and then only to users with appropriate permissions). 

Multiple membership terms

The configuration for the National Membership price field illustrates how you can allow contacts to sign up for multiple membership terms at the same time and shows the Radio input field type.

In the Membership Type field you select the option you want from a dropdown list of all the membership types you have configured. When you select a specific membership type the Number of terms auto-fills with 1 and the Label, Amount and Financial Type are auto-filled based on the definition of that membership type. All those values can be changed as needed. The National Association Fees membership type has a duration of 1 year with a minimum fee of $100. Setting the number of terms to 2 will give 2 years of membership. The Label will need to be changed if you have more than one option as each option must have a different Label. The Amount can be can be increased to any value you want. This lets you offer a concession and standard fee for for the same number of terms.

As we have not included the price of each option in its Label we would need to have Display Amount? ticked.

Defining a price field in this way will reduce the number of membership types you need to create. You only need a 1 year National Association membership type with a minimum fee of $100 for this price field instead of three membership types. However you need to be aware that your members will not be able to auto-renew if you use this type of multi-term configuration. 

Membership of more than one organisation

In addition to the National Association Fees, contacts are required to sign up for a membership with the swim club. The Select input field type has been chosen for this field.

Again, when you select a specific membership type from the drop down list the Number of terms auto-fills with 1 and the Label, Amount and Financial Type are auto-filled based on the definition of that membership type. You can change any of these values as desired.

As we have not included the price of each option in its Label we would need to have Display Amount? ticked.

The combination of the two price fields described so far will let someone sign up for a minimum of 1 and a maximum of 2 memberships. Remember the two memberships will need to be linked to two different organisations as a contact can only have one active membership with a specific organisation. (See the Defining memberships chapter for more information.) 

Non-membership Price fields

You can also configure price set fields to offer additional services, subscriptions or other non-membership options.

There are three non-membership price fields in our example. The first offers a selection of club branded swimming gear. The checkbox field type lets people choose more than one item from the options offered.

As these are products rather than memberships the Membership Type and Number of Terms fields are left empty. You set the Label, Amount and Financial Type for each option. 

As we have not included the price of each option in its Label we would need to have Display Amount? ticked.

If you look back at the screen shots of the three price fields discussed so far you should notice that they all contain the same fields even though are for three different input field types. Radio and Select input types are interchangeable, both allow you to choose just one option and can be used for membership or non-membership options. Checkboxes must be used if your contacts are allowed to choose more than one option from a single price field. They also can be used for either membership or non-membership options.

The fourth input field type is Text/Numeric Quantity and it can only be used for non-membership options. With this field type you usually include the unit price of the item on offer in the field label as shown in the following example or in the field help. This means that Display Amount? should not be ticked.

This will display as:

This price field will only be visible between the Active On and Expire On dates and lets us make sure that the raffle tickets can only be purchased during the selling period authorised by the relevant licensing authority.

The final price field is configured to allow people to give a donation. Notice that the unit price is 1 and it is not included in in the field label although the currency symbol is. The Display Amount? is not ticked. This is the best configuration to allow "any amount" donations.

For review, here again is how all of these fields look on the final screen:

Finding and viewing memberships

This chapter describes how to view and search your membership records. 

Viewing Your Memberships

To see a summary of the status of your memberships over recent months, as well as details  about these memberships, you can use the membership dashboard or view the membership in an individual's contact record.

The Membership Dashboard

To see  a quick snapshot of your recent memberships, use the membership dashboard:  Memberships > Dashboard. This screen contains two blocks of information that display a summary or your recent memberships, categorised by type and date range, and a list of recent member activity.

All of the summary numbers are hot-linked. Simply click on a number 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. From this list of members, you can perform additional actions with the memberships, such as Delete, Edit, Export, Send Email to Contacts.

Viewing A Contact's Membership Records

Another way to view membership records is by viewing a specific contact's record and looking at the Membership tab:

After finding the contact you wish to manage, click the "Membership" tab to view a summary of the contact's membership records.

Membership records appear in a list with active memberships (those with a current status) first and followed by expired or canceled memberships.

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), which can also be used to set up auto-renew if the processor supports this. The interface for each process is very similar, except that the credit card option includes payment processing and recording options.

If  you are looking at the primary member contact record for a membership type that has inherited membership you will see a list of the contacta who have inherited the membership.

In this case a maximum of two inherited memberships are allowed for people who are employees of the primary membership organisation.  If one of the available inherited memberships is not assigned to the correct employee then you can click on Delete for that contact.  This will free up an inherited membership for you to assign appropriately by selecting Create.

 Sending email to members

After searching your records, you may want to send an email to selected contacts and include data field tokens to personalize the email message. To learn more about emailing and tokens in CiviCRM, see the section called "Email".

To send email to members:

Click on Memberships > Find Members > enter your criteria,

then on the "Find Members" search results screen, select the records you want to import and in -actions- drop down, select Send Email to Contacts.

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 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.

Click on Memberships > Find Members > enter your criteria > Click the Search button

The Advanced search allows you to search based on some limited membership information (combined with other contact information) and return contacts.  You can also choose membership from the Display Results As column to show members rather than contacts. To find out more about using Advanced Search, refer to the "Searching" chapter.

Click on Search > Advanced Search > from Display Results As drop-down, select Memberships > enter your criteria > Click the Search button 

Once you've found the membership information based on your criteria, via Finding Memberships or Advanced search, your search results will allow you to view some membership details. You then can perform further actions on your search results or a smaller subset of selected records, such as Sending email to contacts or Export Members by clicking on the -actions- drop down menu.  

Membership Reports

There are a number of techniques for reporting on and analysing your memberships. 

The membership dashboard gives a quick summary of your current memberships, displaying information for each membership type such as current totals of members, and then a break down for last month, this month and current year to date totals.  You can also search for specific membership details using Advanced Search or Find Memberships. To learn more about the membership dashboard and using the search features to find your memberships, refer to the "Finding Memberships" chapter.

This chapter will show you how to view and create membership reports as well as export membership information so you can do further analysis.  

Viewing Membership Reports

Out-of-the-box, CiviCRM comes with several membership reports designed to tell you something specific about your membership:

The Membership Summary report shows information about members grouped by a date frequency you specify, such as month, week, quarter, year.  For example, you can look at the number of members that have joined each month over a date range, membership types, or any other custom data that you collect about them.  If you click on any highlighted row, based on your selected frequency in the summary report, you will then see the corresponding Membership Detail report for that row.

The Membership Detail report shows information for each membership record based on your selected criteria.  

The Lapsed Memberships report provides a list of memberships that lapsed or will lapse before the date you specify.

The Contribution and Membership Details report will display information details of a contributions and those contributions connected to a membership records based on your report criteria. 

Creating New Membership Reports

If you find that you want to create and save new membership reports with different criteria other than the out-of-the-box membership reports offer , you can do so by using the membership templates.

Click on Reports > Membership Reports > click the New Member Report button

On the Create New Report Template screen, click on one of the membership report templates, and begin entering your criteria

Once you've entered your criteria, click the Preview Report button to check your results

If you like what you see, you can then save this report as a new membership report by clicking Create Report, then enter the information you want to save this as a new membership report.

To learn more about working with reports, see the "Reporting" section.

Exporting membership records

You may decide to export membership records so that you can do more analysis, perform document mail merges, or create a specific type of reports outside of CiviCRM. Exporting membership records allows you to select a default set of primary fields or choose fields that are specific to the membership record for export.

You will need to first search for the specific membership records you would like to export. To learn more about how to search for membership records, refer to the "Finding Memberships" chapter.

To export membership records:

Click on Memberships > Find Members > enter your search criteria

Then on the "Find Members" search results screen, select the records you want to import and in -actions- drop down, select Export Members.

You can select Export PRIMARY fields or Select fields for import and click the CONTINUE button

If you selected Export PRIMARY fields, a file called CiviCRM_Member_Search.csv will be created containing the membership records based on your search criteria

If you selected Select fields for import, then include the fields you would like to export, check the box for Save this field mapping if you want to re-use this field mapping for a future export, then click the EXPORT button. A file called CiviCRM_Member_Search.csv will be created containing the membership records based on your search criteria and the fields you selected to export.

Renewals

This chapter will discuss the various ways your contacts can renew their memberships. These include automatic renewals, online renewals and manual renewals entered by office staff either on an individual basis or in bulk via Batch Update of Memberships Via Profile. First though we will discuss the ways of letting your members know that their membership is due to be renewed.

Renewal Concepts

There is an important distinction between adding a new membership and renewing an existing membership. If someone is approaching their membership end date and wants to continue being a member, in most cases you will want to renew the existing membership using CiviMember's renewal workflow rather than creating a new membership. 

Memberships have three primary dates.  Member Since is not altered when a membership is renewed.  Start date and End date may change depending what membership status is in effect when the renewal is processed.

If the renewal is processed when the membership status is one that has a Yes in the member column on Administer > CiviMember > Membership Status Rules then the Start date does not change and the end date is extended by the duration of the renewal.

If the renewal is processed when the membership status is one that has a No in the member column on Administer > CiviMember > Membership Status Rules then the Start date is changed to the current date and the End date is calculated from the new start date.

If applicable for the membership type, a contribution (financial) is recorded as part of the renewal process. This will create a contribution record that is linked to the membership record. Over time, and after a few renewals, the membership record will be a single membership record whose end date is extended, with multiple related financial transactions representing each renewal purchase.

Membership Up-Sell

Membership up-sell allows contacts to change membership type as part of the renewal process. If a contact with a membership linked to an organisation renews under a different membership type belonging to the same organisation, the existing membership will be changed to that type and the associated membership history, including join date and contributions, will be preserved. The existing end date will be extended by the duration of the new membership type. If this is not what you want then you will need to link your membership types to different organisations. (One can be a dummy organisation created purely for this purpose and invisible to the user. See Defining Memberships chapter for a more detailed explanation.) 

If you are using CiviCRM to manage memberships for more than one organisation, note that a contact's membership type cannot be changed or up-sold to a type from another membership organization.

Renewal reminders

Letting a member know that their membership is about to end is the first step in the process of getting them to renew. CiviCRM facilitates communications with your members via email or via postal mail.  

Email reminders

One or more renewal reminder emails can be sent automatically using the Schedule Reminders feature (Administer > Communications > Schedule Reminders). This is particularly helpful for rolling membership types, where memberships could be ending at any time during the year. Refer to the Schedule Reminders chapter in the Email section of this book for the steps involved in sending out a scheduled reminder once you have composed your message.

Exactly what you want to say in your reminder email(s) will depend on what type of membership it is and when it is being sent in relation to the membership end date. For example, renewal reminders sent three months in advance to individuals who signed up on behalf of organisations (to give them enough time to arrange for a purchase order and payment through their accounts department)) would be different from those sent one week after an individual 's membership has ended.

However, if members are able to renew online, all renewal email reminders should contain a checksum token link.  This is a "special" link ( in this  case to the membership renewal page) in the CiviMail message that includes the checksum token {contact.checksum}. When a person clicks on the special link, it will look them up in the database and prefill the renewal form with any data that exists in their record. The special link lasts for seven days from the time it was sent out (although this can be changed at Administer > System Settings > Misc (Undelete, PDFs, Limits, Logging, Captcha, etc.) As membership pages are a type of contribution pages, the checksum link to use in renewal emails where N is the ID of your renewal page is:

Drupal: http://www.myorganization.org/civicrm/contribute/transact?reset=1&id=N&{contact.checksum}&cid={contact.contact_id}

Joomla!: http://www.myorganization.org/index.php?option=com_civicrm&task=civicrm/contribute/transact&reset=1&id=N&{contact.checksum}&cid={contact.contact_id}

WordPress: http:/www.myorganization.org/?page=CiviCRM&q=civicrm/contribute/transact&reset=1&id=N&{contact.checksum}&cid={contact.contact_id}

As with all emails you send out you need to allow time to test renewal reminder templates, especially if you have complex membership structures and want to customise messages based on member types or other factors. 

Remember that by default scheduled reminders will be sent to people who have opted out of bulk or all emails unless you specifically exclude those people. If people can elect to auto-renew their memberships then you should exclude members who have chosen that option from the scheduled reminders.

Postal reminders

You may also want to post out letters to all your members who are due to renew or just post letters to those without an email address and those who have opted out of bulk or all emails. Refer to Postal mail communications in the Common workflows section for ways to generate those letters.

Automatically renewed memberships

For members who have chosen this option when they first joined, on their renewal date the payment will be taken automatically from their pre-authorised credit card, their membership end date will be updated and they will receive appropriate thank-you and receipts from CiviCRM. (See Defining memberships, Online memberships sign up and Manual entry of memberships chapters on details of how to set up auto-renewing memberships.)

Online renewals

CiviCRM uses the same page for new memberships as it does for renewals. The only difference is that the page title and introductory message will the text you entered into the renewal fields on the memberships tab  when you were configuring your online membership page. The renewal page is automatically displayed at the same URL as the membership join page when viewed by a logged in website visitor that has a valid current or expired membership.

When you are setting up membership sign up pages, it is worth remembering that current members will only see the renewal page if they are logged in.  If they are not logged in, they will see the sign up page. If they fill that page in and, based on their contact information, CiviCRM can find their existing contact record then their membership will be renewed.  If CiviCRM can't find their existing contact record (perhaps they have changed their email address) then a new contact record and membership will be created.  This is one source of duplicates in your database and you need to minimise the chances that this will happen.  Two ways to do this are to always include a checksum token in renewal reminder emails and add text to the new member introductory message to remind people that they should log in before they renew.

Default Online Membership Renewal Page

When a membership is purchased using the online membership signup page (self-service), that user's Contact Dashboard will contain a "renew" link pointing to that page.  However this link will not appear for members whose initial membership was entered manually unless you configure a Default Online Membership Renewal Page as follows:

If it does not already exist, create a membership page that includes all currently available memberships. (You may need to use a price set for this if the membership fees need to be allocated to more than on financial type.  Refer to Membership price sets for more details.)

Navigate to Administer > CiviMember > CiviMember Component Settings.

For Default Online Membership Renewal Page choose the membership page containing all your membership types

A "renew" link pointing to that page will then be displayed on the Contact Dashboard for any memberships which were manually entered.

Manually renewing a membership for a single contact

Go to the contact's summary page.

Click on the Memberships tab

Click MORE next to the membership record

Select Renew to enter cash, cheque or EFT payment or Renew-Credit Card to process the renewal through your online payment processor.

Batch Update Members Via Profile

You can use the Batch Update Members Via Profile feature to update multiple existing membership records (don't confuse this with the Batch Data Entry feature that is used for adding new memberships and member payments).

To use the Batch Update Members Via Profile, you can either use the CiviCRM default reserved profiles, Membership Batch Entry and Contribution Batch Entry, or you can create and configure a profile that contains fields pertaining to membership information that you want to display and update. You can read more about how to configure profiles in the Profiles chapter of the Organising Your Data section. 

To use the Batch Update Members Via Profile feature:

Find the memberships you would like to update by selecting Memberships > Find Members. Enter your search criteria and click Search.

From the Find Members results screen, select the membership records and select Batch Update Members Via Profile from the -actions- dropdown box and click Go.

From the Batch Profile Update for Membership screen, in Select Profile, select the profile you want to use from the dropdown box and click Continue >>. You can read more about setting up a membership profile for batch update in the Set-Up chapter of the Memberships section.

From the Batch Update for Members screen, you can update the information that is displayed based on the profile you selected.  You can use the "auto-copy" icon at the top of a column to copy and paste the value from the field of the first record of that column to the rest of the fields below in the column.  Once you are done updating, click Update Memberships. 

Below is an example of a Batch Update for Members screen that is using a membership profile configured to display the Membership Type and the Membership Start Date fields for use with the Batch Update Members Via Profile.

Cancelling and expiring memberships

Cancelling and manually expiring memberships

If a contact wants to resign or cancel their membership, rather than deleting their membership, you should change the status to cancelled or another status that is not considered current.  This ensures that you keep a historical record on the contact's interaction with your organization and all contribution records attached to that membership. Similarly, if a contact's membership was in grace period and you knew that they were not going to be continuing their membership for another period, you could manually change their membership status to expired as opposed to cancelled since they went through the entire period of their membership.

You can cancel or manually expire a membership record by:

 Search for a particular contact whose membership status you would like to change, click on the Membership tab then click Edit next to the membership record.

One you are in the edit screen of the membership record you will need to check the Status Override box and then select the appropriate Membership Status you wish to change to. i.e. Cancelled or Expired

Keep in mind that manually Expiring memberships may not be needed. Dependent upon how you have your Membership status rules setup within Administer > CiviMember > Membership Status Rules memberships will automatically expire based on a certain timeline criteria. 

Deleting memberships 

The only time you would want to delete a membership is if you entered it error, for example if you made Jo Smith a member instead of Joe Smith, you would want to remove the incorrect membership and any linked contribution record for Jo Smith.  When a membership is deleted it is completely removed from the database and so are any linked contributions.   This action cannot be undone so you should only give permission to delete memberships to trusted staff.

You can delete membership records by: 

Searching for a particular contact, then click on the "Membership" tab > click More next to the membership record > click Delete, OR

Click on Memberships > Find Members > enter your criteria and from the "Find Members" results screen, select the membership records and click Delete.

Members area on your website

CiviMember can be used in conjunction with your CMS to create a members-only section of your website.  Each CMS has it's own integration module(s) that can be used to do this.  A typical workflow would be that a contact creates an account on your site and becomes a member of your organisation using a CiviMember membership sign up page.  When they log in to you site they get access to member-only content on your site.  This extra content could be from your CMS or it could come from your CRM, for example a detailed members directory, or a list of private events that are only available to members.  You can refer to the section on your CMS in Website Integration for more information or ask questions on http://forum.civicrm.org/.

What is CiviMail?

The CiviMail component is a sophisticated tool 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.

CiviMail (like all of CiviCRM's mail features) interacts with your mail server. Configuring the mail server and properly setting up CiviMail are system administrator tasks and you may require professional assistance. You will also need to check with your web hosting provider to ensure that they meet the configuration requirements, and find out about any limits they may have on how many emails you can send per day. A misconfigured mail server is a liability and if you don't know what you are doing you could easily end up on a spam black list.  Getting off a spam black list is much harder that getting on it.  For more information about configuring your mail server, see the "Email system configuration" chapter in the Initial Setup section. 

Scenario: managing email lists 

St Ethelburga's Centre for Peace and Reconciliation uses 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 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 Ethelburga's also automatically subscribes 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. Ethelburga's sends out other emails to a mailing list that includes nearly all contacts in 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, and 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 You Need To Know

This chapter outlines some key concepts and questions that are useful for planning the use of CiviCRM's email capabilities. This chapter should be read before you start sending emails to contacts. Detailed information on how to carry out the activities mentioned can be found in the Everyday Tasks section.

Key Concepts 

As you might expect for a web-based CRM, email plays a central role in CiviCRM. Broadly speaking, there are three situations in which email is sent from CiviCRM:

to individuals and small groups of people via the Send Email action

to a large group of people as a mass mailing via CiviMail

to individuals who trigger an email as part of workflows in other components, for example, an event registration confirmation email 

The advantage of sending email through CiviCRM (rather than through your email client or through a bulk email tool other than CiviMail) is that every email sent, via the Send Email action or using CiviMail, is treated as an activity and stored in the activity history of each recipient. This allows you to see, for example, that John Doe made a donation three days after he received your April newsletter, or that your volunteer coordinator emailed Jane Smith and asked her to staff the information table at an upcoming event. 

Send Email versus CiviMail

CiviCRM offers two options for sending email to contacts:

Send an email as an activity for a contact: this is suitable for sending emails to individuals and small groups.

Send a mailing to a group using CiviMail: this is ideal for mass mailings or scheduled emails to small groups.

In order to send mass emails, the CiviMail component must be enabled and set up (see the Set-up chapter in this section for details). The Send Email action is available even when the CiviMail component is disabled.

There are crucial differences between the Send Email action and the CiviMail component:

Emails sent via the Send Email action are limited to a maximum of 50 email addresses, and there is no reporting other than an activity record for each recipient.

CiviMail emails have sophisticated bounce processing and reporting.

CiviMail allows recipients to manage their own subscriptions.

CiviMail can be configured to automatically track replies.

CiviMail requires more work to configure, and there are more steps involved; however, once you have enabled and configured CiviMail, you will have greatly enhanced mass email capabilities.

Working out which method to use for each email might not be immediately apparent. Over time, the best practices and the right tool for each situation will become more obvious and can be shared among your users. 

When to use the Send Email action

As long as you are contacting fewer than 50 recipients and you don't need to track whether recipients opened the email or clicked on any links, the Send Email action is quicker and easier than sending a mass mailing in CiviMail.

The Send Email activity offers all the functionality of sending through an email client: you can attach files, CC and BCC contacts, and use message templates.

Note that CiviCRM records only the messages you send; replies from the recipient come to your email address and are not recorded in the database. For this reason, you should not rely on the Send Email action for conducting extended email exchanges. If you want to record the fact that you had an email exchange with somebody, you could create an activity called Email Exchange and copy and paste your email conversation in the body as you would a record of a telephone call. 

You can also record emails sent through your email client using the autofiling outbound email option described below.

When to use CiviMail  

If you want to send mail to 50 or more contacts at once, you must use CiviMail. 

You also should use CiviMail whenever you want to capture statistics about the success of your mailing, including bounce statistics and click-throughs. For more information on this, see Reporting and Analysis.

CiviMail also enables people to sign up for your mailing lists on your website, and automatically keeps track of their unsubscription or opt-out requests. It also lets you file any emails that your recipients send as replies to the mailing, and send them an autoresponse to their replies.

Choosing recipients 

Send Email allows you to choose recipients in two ways: from a contact record and from search results.

CiviMail also allows you to choose recipients in two ways: with Groups marked as Mailing Lists, which must be created prior to setting up your mailing, and from search results. However, there is one complication with using search results: All mail sent from CiviMail must have an unsubscribe link. If recipients are included in a Group, any unsubscribe requests simply remove them from the mailing list for that Group. But if they are not in a Group, they must be added to one when they unsubscribe so the unsubscription request can be recorded in CiviCRM.

Personalisation with tokens

Emails sent with both Send Email and CiviMail can include personalised text, such as a person's name. This is done with tokens, which are placeholders that CiviCRM recognizes and replaces with an appropriate value when sending each message. You can include tokens for standard fields and also custom data fields that you have created. Note that there are some tokens available in CiviMail that are not available in the Send Email activity.

A particularly useful token is the checksum. The checksum allows you to give people links to  contribution forms, profiles, petitions, and event registration forms that are prefilled with information that is already in their contact record.

This saves your constituents the hassle of filling out forms and increases the chances they will take action (e.g., donate, sign up for an event, sign the petition). It can also be a simple way to keep your data current by asking people to review and update their contact information.

Detailed instructions for using tokens, including custom tokens and using checksums, are available in the Everyday Tasks section, under the heading "Using tokens in emails."

From Email Addresses

Both mass and regular email can be sent from your personal address, from a general email address associated with your organisation, or from another person's address. For example, an assistant can send official email messages under the name of his manager.

Headers and Footers

In mass mailings only, you can include customised headers and footers. You can configure custom headers and footers under Administer > CiviMail > Headers, Footers, and Automated Messages.

Templates

Templates for emails or parts of emails help to streamline your communications by reusing entire emails or parts of emails such as headers and footers. Email templates can be created either beforehand or when you send an email, and edited at any time.

Reporting

CiviMail can track mass mailings, providing useful information to help you understand the areas your recipients are interested in and gauge the effectiveness of your communications. You can track how many recipients opened the email and which links in the email were popular.

Mailing List Sign-Up and Unsubscribing

CiviCRM allows you to publish a sign-up page or form (called a profile) where people can sign up for your mailing list on your website. It requires that you allow recipients to unsubscribe from any mailing list and opt out of ever getting email from you, and CiviCRM will automatically keep track of these requests. For more information, see the Set-Up chapter.

Autofiling external emails in CiviCRM

CiviCRM lets you automatically record email sent via your email client in contact records in your database. To do this, you need to set up a special email address that you include in the BCC field of an email you are sending. This 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. See the Email System Configuration chapter of the Intial Setup section for details.

Key Questions

When planning your use of CiviCRM's email capabilities, it may be helpful to answer these questions to guide your setup and use:

Are there any types of emails that you send again and again and thus want to create templates for?

Is there content you'd like to include in the header and/or footer in every mailing? 

Do you want a web page where people can sign up for your emails?

What kinds of emails are important to you to store in recipients' contact records?

When planning to send a specific email through CiviCRM, it is helpful to consider the following:

How many people are you sending your email to?

Do you want to know who is opening your email and clicking on links in it?

Have you created a list (a Group or Smart Group) to which to send your email?

Do you want recipients to be able to view your mailing in a browser window if they have trouble viewing it from their email browser?

Who should be the sender of the email? This could be a generic organisation address, or personalised with someone's name.

Other considerations

Many CiviCRM components interact with email functionality and with CiviMail, for example to send confirmation, thank-you and receipt emails. The sections of this book relating to each component will include some information about customising these emails, and should be read in conjunction with this section in order to give you a full understanding of how email works in the broader context of CiviCRM.

Privacy issues

We encourage you to consider privacy issues. Different countries have different laws relating to email privacy, including opt out/unsubscribe options. There may also be issues related to CiviMail's tracking tools; for instance, you may wish to avoid tracking who has clicked on the "how to deal with drug issues" link on a specific mailing. 

Spam and email deliverability

When sending mass emails, there is always a risk that your emails will be marked as spam. This affects both the delivery of your current email and also the future delivery of all emails sent from your server. Managing these issues is complex and outside the scope of this book. If your organisation does not have a system administrator, consultant, or email hosting service that is knowledgeable about these issues, you may want to seek the advice of an expert.

Set-up

This chapter describes how to set up information such as From email addresses, Mailing List Groups and email templates. It assumes that the basic functionality necessary for your server to send and process emails in the first place has already been configured. See Email System Configuration in Initial Set-Up for details. 

Configuring your organisation's contact information

In order to send mass emails you must fill in some basic information: your organisation's name, a short description, your email address, and your postal address. CiviMail requires that you include the sender's postal address along with unsubscribe/opt-out links in any mass mailing 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 this information, go to: Administer > Communications > Organization Address and Contact Info.

Mailing groups

CiviMail uses Groups to organise recipients of mass mailings. 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 under Group Type so that it is available as a Mailing List in CiviMail. You can then do a search and add contacts to the Group.

You can also create Smart Groups based on search results, which will update the Group with any contacts that fit the search criteria. For example, based on the results of Advanced Search you can create a Smart Group of contacts who have active memberships, or a Smart Group of contacts in a given city. As people become members or move to the city you've searched on, they will be automatically added to the Smart Group. This makes it possible to to send mailings without having to first update the contacts in a group.

To create a Smart Group:

Go to Advanced Search or Find Contact and run a search query based on the criteria for your group.

On the search results page, click the radio button that selects all the records.

From the - more actions - drop-down menu, select New Smart Group and then click Go.

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.

Click Save Smart Group.

Note: You can also create a Smart Group based on a Participant search. However, the Smart Group save page will not offer you the option to make this group a Mailing List. To make this Smart Group available to CiviMail, you must change its settings through Contacts > Manage Groups. This same thing happens if you use the Advanced Search and choose Event Participants under "Display results as." 

You cannot create smart groups based on Membership, Contributions or Pledge searches, or based on results of an Advanced Search if the "Display results as" option is set to anything but Contacts. 

Allow people to sign up for your mailing lists online

CiviCRM makes it possible for people to sign themselves up for your mailing lists online.

To allow this, you must designate the group as a mailing list. If you didn't do this when you created the Group, go to Contacts > Manage Groups. Click Settings on the group that holds your mailing list recipients and check the Mailing List next to Group Type. You must also change the Visibility to Public Pages.   

For this to work for users who don't have a log-in to your CiviCRM, you must ensure that anonymous users in Drupal have the following permission checked: "Access CiviMail subscribe/unsubscribe pages."

Using the subscribe link

One way to allow users to subscribe to an email list online is by directing them to www.yourdomain.org/civicrm/mailing/subscribe. You and anyone who accesses this link can subscribe to the available mailing list groups.

Using a profile

Alternatively, you can collect more information when people sign up to your mailing lists with the use of a profile that is then displayed on a public page. Guidelines on what is you need to think about when using profiles for mailing list sign-ups are below; for more complete information about profiles, how they work, and how to set them up, see the Profiles chapter in the Data in CiviCRM section. 

For example, you could create a new Profile called Newsletter Sign-up. Add to this profile the fields that you'd like website visitors who want to join your mailing list to fill out. Each of the fields in the profile must have its Visibility set to Public Pages.

For each field you include, you can choose whether it is required or optional for people filling out the public form. The one exception is that the profile must include an email field that is required. This is so that an email can be sent to the person to confirm that they wanted to sign up for the mailing list. Until they confirm, they will have a status of "Pending" in the mailing list group. 

You must also add a field for the mailing lists groups that you want them to be able to sign up for. Click Add Field. For Field Name, select Contacts. When the possible selections load in the second field, select Group(s). In Field Label, you can leave "Group(s)" or you may want to change it to something more intuitive to your website visitors such as "Newsletter Sign-up." Visibility for this field must also be set to Public Pages. When the profile displays publicly, this field will show check boxes for all Mailing List Groups that have their Visibility set to Public Pages.

There are two ways to display the profile publicly:

Share a link directly. Return to the listing of profiles (at Administer > Custom Data and Screens > Profiles) and click More to the far right of your profile. Click Use Profile-Create Mode. Your browser will open up the public page; you can publish this link to allow users to sign up for your mailing lists.

Embed this set of fields as a form in your website.  Return to the listing of profiles (at Administer > Custom Data and Screens > Profiles) and click More to the far right of your profile. Select HTML Form Snippet. This will open a window in your browser that has a box with HTML code in it. Copy and paste the contents of the box into a page on your website. Website visitors will be able to sign up to your mailing lists on this page.

Using a Webform (Drupal)

Many Drupal site administrators prefer to use a webform instead of a profile to create their newsletter sign-up, because it provides additional features such as advanced spam control and flexible theming. For more information see:

http://wiki.civicrm.org/confluence/display/CRMDOC/Webform+CiviCRM+Integration

Mailing list confirmation workflow

After people subscribe to mailing list groups—via the subscribe link or a profile—CiviCRM will automatically send them an email asking them to confirm their subscription. Until they click the confirmation link in the email, their contact information will appear in CiviCRM with their group subscription set to Pending. When they confirm, CiviCRM will automatically change their group subscription status to Added and they will be sent a welcome message. (Note: When users subscribe to multiple groups at once, a confirmation email is sent for each group separately.) 

Automated Messages and mailing list management

CiviCRM sends emails automatically when your participants take certain actions:

When someone signs up for a mailing list, they get a confirmation email with a link that that they must click.

When they confirm, they get a welcome email.

When they unsubscribe, opt-out of all emails from your domain, or resubscribe to a list they have previously unsubscribed from, they get a confirmation email that does not require any action.

When they reply to a message you have sent through CiviMail, you can set up an autoresponse to their reply.

In CiviCRM, these are called Automated Messages, and you can edit them and add new ones at Mailings > Headers, Footers, and Automated Messages. 

For more information on email list management see the chapter entitled Maintaining Healthy Email Lists which explores how CiviCRM handles unsubscribes, bounces and email holds.

Creating and maintaining message templates

Message templates help to streamline your communications by allowing you to reuse entire emails or parts of emails in both mass mailings and when using the Send Email activity.

The easiest way to create a new message template is to check the Save as New Template box on the message creation screen. This is available both when using the Send Email activity and when sending a mass mailing.

You can also create message templates from scratch or edit existing templates by going to Mailings > Message Templates OR Administer > Communications > Message Templates.

Click on Add Message Template.

Enter a Message Title and a Message Subject. You can choose to use tokens to personalize your subject line.

Scroll down to the HTML Format section and create your template. There are online resources, not specific to CiviCRM, that offer instructions on creating an HTML email templates. One suggestion is to find and copy an email template from a website that offers samples.

In the WYSIWYG editor toolbar, there is an icon called "Source" (the appearance and labelling of this icon changes depending on whether you are using Drupal, Joomla, or WordPress). When you click on it, the template changes the view to show the HTML code that is being used. If you want to paste in HTML from a template you found externally, or if you want to write HTML directly into your template or modify the HTML that you've created with the WYSIWYG editor, you need to switch to this view. 

Message templates are available even when CiviMail is disabled.

Tips for creating templates

HTML code allowed in emails is more restricted than HTML used for web pages. For instance, it needs to use tables for layout, inline CSS, and must not include background images. Here are some tips for creating a template that will look good in all mail clients:

Table border: The HTML <table> element includes an optional border attribute. Since the default value is 0, it doesn't appear unless you choose to use it. Adding it (or editing it if it is available) and setting it to 1 (e.g., <table border="1">) allows you to see the edges of your table and helps identify potential places to fix problems. Please note that HTML email templates usually have multiple tables and nested tables (tables inside tables). Make changes one at a time and switch to the HTML view to see the results. A table usually has more than one parameter, so make sure to place spaces between parameters.

Table cellpadding and cellspacing: these table parameters are very useful when trying to improve the readability of your email. Play with these settings in different tables and see what works for you.

Width: Do not send an email that is wider than 600 pixels, to ensure maximum compatibility across email clients. Make sure your outermost table does not exceed 600 pixels. Do the same for any other tables inside your main table. Also make sure that the total width of each image does not exceed 600 pixels. Images have a width parameter, but they can also have a horizontal padding parameter that, if set, can increase the width of the image.

Images: these need to be online and accessible in order for you to use them. First edit your image so that its width and height is appropriate for your email template. Next, save it so that its file size is as small as possible. If you do not have image editing software, or do not know how to use it, there are free online resources that can help you resize your image.

HTML editor: CiviCRM comes with two WYSIWYG editors (CKEditor and TinyMCE) and Textarea, a plain text editor. If you have another editor configured as part of your Drupal, Joomla, or WordPress installation, you can choose to use that instead. go to: Administer > Customize Data and Screens > Display Preferences > and select a different WYSIWYG Editor.

To see examples of message templates, see http://wiki.civicrm.org/confluence/display/CRMDOC/Sample+CiviMail+Messages  .

Plain text and HTML formats

All messages can be sent either in plain text or in HTML. Today the vast majority of people use email clients that can read messages received in HTML. However, the best practice is to offer the option to send a plain text email version to ensure all recipients can view the message. Plain text email readers may display HTML email as blank. HTML email may also present accessibility issues to people using screen readers.

However, there is a risk that if users modify an email based on a template that contains both plain text and HTML, they will forget to modify the plain text version of this message. This will mean that people using plain text-only email clients will receive an incorrect or incomplete message.

One solution to this problem is to either use plain text emails only or to set templates without the plain text option and ask users to create a plain text version before sending their mailings.

To create a plain text version of a message from HTML:

Copy and paste the text from HTML Format field into the Plain Text Format field. When you do this, make sure you are not in the Source view; you don't want all the code, just the text. When you copy from the WYSIWYG view, the plain text field will automatically strip out the formatting and any other elements that do not work in plain text.

Copy the URLs of all links to the appropriate places in the Plain Text Format field.

If the HTML version contained tables, modify the layout of your text manually to ensure the text version is readable.

Creating headers and footers

Headers and footers can be used only in mass mailings using CiviMail. They are not available unless CiviMail is enabled. 

The header is the area at the top of the email; it should include elements that you want to be displayed before the main content body, such as the logo of your organization and the title of the newsletter.

The footer is always the last thing in the email. The footer is an ideal place for the compulsory unsubscribe tokens (see What You Need to Know for more information).

You can manage the content of headers and footers in Mailings > Headers, Footers, and Automated Messages. You can create different headers and footers for different purposes; for example, you might want to create a set of headers with different images and titles that can be used for different campaigns or programs. It is recommended to style them similarly, to present a coherent visual identity across all your messages.

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.

Like the Message Templates, headers and footers have both a text and an HTML version. Unlike Message Templates, however, the header and footer creation pages do not offer a WYGIWYG editor. You will need to write header and footer HTML directly or use another HTML editor to produce the HTML code.

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. An easy way to do this is to 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 very differently from each other, 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, since the template will have already been tested.

Auto-filing email conversations in CiviCRM

It is possible to have emails sent to and from your regular email client automatically filed in CiviCRM. This is done by including a designated email address in the To, Cc, or Bcc field (Bcc is recommended, as it is invisible to the recipient.) Emails that include this designated email get filed as an activity for the contact(s) that match the other email addresses in the From, To, and Cc fields. If any of these email addresses are not already in the system, a new contact record will be created. (Technically, this can work for inbound emails as well; however, it does depend on the person sending the mail to you including the auto-filing address in the To, Cc, or Bcc field.)

For this, your administrator should have configured IMAP or other mail accounts and set them up in CiviMail (see Email System Configuration, especially Adding an incoming email account for handling bounces or auto filing to CiviMail, in Initial Set-Up for more details).

Maintaining Healthy Email Lists

In the setup chapter we discussed setting up and configuring Email lists. In this chapter we are going to delve a bit further into list management and discuss compliance. It is important that you keep you email lists healthy with low rates of bounced emails and unsubscribes. 

There is always fear of the dreaded 'blacklist' if you have very high bounce rate, or the fear of being scolded by your SMTP provider for the same. However, the reality is high bounce rates and unsubscribes typically represent a deeper organization issue... and that's really scary.

Understanding Email Bounces

Each time you send a bulk email from CiviMail it's possible that some of the emails will bounce. Hopefully, only a few. Bounces happen for many reasons; some may be temporary, others permanent. 

So why do emails bounce?

If the email bounces, it means it never reached that recipient. It can happen for a number of reasons, including the following:

the email address was input incorrectly

the email address is out of commission

the email inbox is full and temporarily cannot accept any more messages

the recipient has an automatic away reply message because they are on vacation and out of the office

CiviCRM handles different bounce types differently. Whereas temporary bounces will have no affect on a contact record and CiviCRM will attempt to send future mailings to this address, permanent bounces may put a contact email on Hold. When an email is on Hold, no future emails will be sent to it unless someone fixes it and removes the hold.

A detailed table of each type of bounce and the number of bounces allowed before an address is put on hold is available on the wiki at: http://wiki.civicrm.org/confluence/display/CRMDOC/Bounce+Handling

What do I do if an address is put on hold? 

Basically you have two options if an email address gets put on hold. You can either unhold them or fix/delete them.

To release a hold:

Go to Advanced Search 

In the Basic Search Criteria check the box to search for Emails On Hold 

Once you have the list of contacts with held email addresses, select them and choose the action Unhold Emails from the dropdown list and click Go.

To correct/update held emails you'll first need to create a group(s) for bad emails, then:

In the top menu, go to Reports

Select Mail Bounce Report

The report will show contacts whose emails have bounced.

You can then open Report Criteria at the top of the mailing to limit the report to a specific bounce type.

From here you add the contacts in your search results to the group you first created.

Pull up the group via Advanced Search. It is also recommended that you select Email on Hold to avoid querying records that have previously bounced but may have been already updated.

Select Batch Update via Profile for all the results whose email addresses you can correct/update. This will require a profile in place that contains just Primary Email.

Select this profile and click Update.

The difference between on hold emails and unsubscribes

Emails that have been held are different from emails that have been unsubscribed. Unsubscribers have clicked the linked text in an email that said “unsubscribe from this mailing”. This link is created by one of these tokens in an email: {action.unsubscribe} or {action.unsubscribeUrl}

Email recipients who unsubscribe from a single mailing list will simply be removed from the group you used as a mailing list to send to.

What is the difference between opting out and unsubscribing?

Email recipients also have the option of not receiving any bulk emails from you by clicking a link you provide in every mass email. This is called "opting out". You can still send individual or small volume emails to someone who has opted out using the Send Email action which is accessible via the contact's record or after a search. Scheduled reminders will also still be sent to contacts who have opted out. You should be very careful about the emails you send to someone who has opted out if you do not want to be accused of sending spam.

To opt out, an email recipient can click the linked text in an email created by one of these opt-out tokens: {action.optOut} {action.optOutUrl}

You can include these tokens directly in the body of your mailing or in a footer message. (For more on tokens, see here: http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens. For more on footers, see the previous section in this chapter, Set up > Creating headers and footers.)

What does the privacy option 'Do not email' mean?

If a contact has this option selected then you will not be able to send them individual or small volume emails using the Send Email action reached via the contact's record or after a search. They will not receive bulk emails sent through CiviMail, either. However they will still be sent scheduled reminders unless you specifically exclude them from those reminders. If the Do not email option is set manually after someone has contacted you in person, it is probably a good idea to exclude them from scheduled reminders. The Schedule Reminders chapter outlines how to do that.

How can I make sure a contact doesn't receive any emails?

Due to user error, there is always a chance that someone could change CiviCRM settings incorrectly or manually misuse an email address. The only way to fully guarantee that a contact doesn't receive any emails is to remove all email addresses from the contact's record.  However, in this case the contact would not be able to log in to your website. 

Everyday tasks

This chapter contains step-by-step instructions for performing important everyday tasks with email.

Send an email to one person (with CC and BCC)

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.

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.

From the contact summary page, click Actions > Send an email or click the Activities tab and choose Send an Email from the dropdown menu.

You can add additional recipients using the CC and BCC fields.

If you have templates defined, you can choose one from the Use Template dropdown menu. 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. 

Enter your content or add content to your template. If you just wish to send a Plain Text version of your email, ignore the HTML Format section and click on the Plain Text Format section. Enter your message in the box.

Note: Choosing a template overwrites any text you have in the message text area and on the subject line. If you would like to use a template, you should select it before adding any text. If you have already typed some text in the message area, copy it into a separate document before applying a template. 

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 Email to Contacts" 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 it 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.

Click Search > Find Contacts  (or Advanced Search).  Choose your search criteria and click Search (or use any other search to find the contacts that you wish to email).

From the search results screen, choose some or all of the contacts and click - actions -  > Send Email to Contacts.

Follow the same steps as in sending an email to one person.

Each of the recipient contacts will have this email recorded as an Activity in their record. An activity will also be recorded for the sender. The activity record will also list all the other message recipients. Unlike with mass mailing (see below) there is no one place where all emails sent via the Send Email function are listed.

Note: If a message is sent to multiple recipients, each recipient will see only their own email address in the To field. 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")

Inserting an image in an email

Click the image button in the WYSIWYG editor. 

The Image Properties window will appear. Click Browse Server to look for image files on your server.

In the left sidebar, you will see a directory of files. If the image you need is already uploaded to your server, navigate to it in the directory and select it. If not, Click Upload to choose a file from your computer.

Your computer's file-browsing window will open. Find the image file you want,
click to select it and click Open. You can repeat this process to upload multiple files to CiviCRM at once.

To insert, double click on the image you want. You'll return to the Image Properties window of your email.

Here you can add adjust the size and alignment of the image and the border around it. You can also fill in the Alternative Text field, which is text that appears when the image is not available to the reader (if they choose not to load images in their email client, or are using a screen reader due to a visual impairment). The alternative text ensures no information is lost; it's a best practice to always include alt text for images to make email accessible to all user communities.

Click OK to insert the image.

Sending a mass mailing through CiviMail

Using the Mailings functionality offered by CiviMail provides many benefits over the Send Email activity, allowing you to track respondents to your mailing, process bounces, and allow people to unsubscribe from your mailings.

Choosing recipients: Groups versus search results

There are two ways to select the recipients for your mailing—sending to existing Groups and sending to search results—and although the workflow to create the mailings is mostly the same, there are two important differences.

The first and most important is that when you're setting up Mailings to send to Groups, you can save your work at any point and continue it later. Mailings to search results cannot be saved for later editing; when you start to prepare your mailing to search results, make sure you have time to finish it.

The other difference is that for mailings to search results, you are required to choose a Group from the Unsubscription Group dropdown menu. Here's why: Every mass mailing needs a way to track unsubscribe requests. Mailings sent to Groups have this capacity built-in—the next time a mass email is sent to that Group, anyone who has unsubscribed will not be included. However, mailings sent to search results do not have this built-in way to track who has unsubscribed, so you need to provide one.

Here's how it works: If a contact who matches your search results is already unsubscribed from the Unsubscription Group that you designate, that contact will not be sent the mailing. If a contact unsubscribes via the unsubscription link in this mailing, they will be unsubscribed from this Group and therefore not receive any more emails sent to this group. This is true whether they were originally a member of the Group or not.

The Unsubscription Group you designate collects unsubscribe information only; it does not supply any contacts to the mailing. In other words, contacts who are in the Unsubscription Group but do not match your search criteria will not be included in the mailing. (If you wish to include these contacts you should include the relevant Group.)

For example: Your organization is having a big event next week. Several emails have already gone out about it, but you have added many new people to your database in the last week and you want to send them an event announcement. You do a search for new contacts via Search > Custom Search > Date Added to CiviCRM. This is the search that is the basis of the mailing. Your organisation stores its event email list in a Group called Event Alerts, so for this mailing, you would probably want to choose that as your Unsubscription Group.

If you do not already have a Group that would be appropriate for the Unsubscribe Group for a mailing you're planning, you may want to create one and call it something like Miscellaneous Mail Unsubscribes. You could then add that Group to other future mailings to ensure that the people who have unsubscribed are excluded from those future mailings.

The Mailing set-up screens

If you are sending mail to an existing Group, go to Mailings > New Mailing. 

If you're using search, perform your search (for example, using the Search > Advanced Search) and then choose Schedule/Send a Mass Mailing from the - actions - drop down.

The process for sending the mailing then proceeds via the following screens. You can move between these screens by using the Next/Previous buttons. For mailings sent to Groups, you can also save your mailing at any stage by clicking on the Save & Continue Later button.

Step 1: Select recipients

Fill out the following fields:

Name Your Mailing: Enter a name for this mailing. Select a name that will allow you and others in your organization to clearly identify the purpose of this mailing. It is recommended that you start each name with a date (e.g., "08/15/10 monthly newsletter"). This will make it easier to include or exclude recipients of this mailing in future mailings. This name is for internal use only and will not be shown to recipients. You will be asked to enter the Subject of the email later. 

Remove duplicate emails: CiviCRM will always dedupe your mailing based on unique contact records. For example, if a contact is in three of the groups you are including in your mailing, they will only be sent one copy of the email. However, if the same email is used by multiple contacts, that email address will receive multiple copies of the email—one for each contact using that address. Checking this box will ensure only one email is sent to each address

(Additional) Mailing Recipients: This is where you can choose who will receive the mailing (if mailing to Groups) or further refine your mailing (if mailing to search results). You can choose Groups to include and exclude. You can also refine your recipient list by including and excluding recipients of previous mailings.

For instance, you may want to resend an email only to contacts that have been added to a Group since the last time you sent them email, to avoid sending the same email twice to some people. In that case, choose the original mailing in the EXCLUDE Recipients of These Mailing(s) area. This will then send the message only to those members of the group who did not receive the original mailing.

You will see the final number of recipients on the next screen after you click on the Next button.

Step 2: Track and Respond

This step of the process offers options for Tracking and Responding. You can set the following options; section headers here match the onscreen sections.

Tracking

Track Click-throughs: This option will keep track of how many users and which users clicked on all the links in your message. This is accomplished by redirecting all links through your server. This means that all links will be overwritten with custom links containing your domain name.

Note for HTML mail: Some phishing filters may mark links that are displayed differently in HTML code and in the text as unsafe. It is therefore best not to use something like <a href="http://google.com">http://Google.com</a> but rather <a href="http://google.com">click here to go to Google</a>.

Note for Plain Text email: If you use short, user-friendly URLs in your email, they will all be overwritten with long links containing the name of your site and a long code looking like this http://yoursite.com/sites/all/modules/civicrm/extern/url.php?u=529&qid=29011.

Track Opens: This option allows you to track how many people opened the email you received. However, there are limitations to the effectiveness of this method. If the recipient does not show images in their email client (often referred to as "blocking remote content"), their email will not be marked as opened even if they do open it. Blocking remote content is a very common practice.

Responding

Track Replies: Checking this option will send replies from the mailing's recipients to CiviCRM rather than the person specified as sender. Checking this box will open the two options described next.

Forward Replies: This option is only visible if Track Replies is checked. You will need to check this option if you want the From address to also receive the replies sent by recipients.

Auto-respond to Replies: This option allows you to send a specific automatic reply to anybody who replies to your mailing. You need to set up an autoresponder ahead of time in Mailings > Headers, Footers, and Automated Messages.

Online Publication

There is only one field in this section: Mailing Visibility; its dropdown menu offers two options, "User and User Admin Only" and "Public Pages." Choosing Public Pages makes this content viewable as a web page by everyone who has the permission of "view public CiviMail content."

User and User Admin Only means that only users that received the mailing or administrators can view the content of this email as a web page; the recipients will have to log in to be able to view the message.

To link to the web version in your email, insert the Mailing permalink token in your message in the next step. This token generates a URL on which the message can be viewed; in order to display it properly in HTML messages, you'll need to add the proper link tags using the Source icon in the editor. 

Step 3: Mailing Content

This section will allow you to compose content for your mailing. If you have made any templates, you can choose one to use for this email. Selecting a template populates the HTML Format and Plain-Text Format fields with the message content from the template. You can then edit that content. You can also update the template, either changing the original template or saving it as a new template.

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.

If you just wish to send a text version of your email, ignore the HTML section and click on the Plain 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.

Choose a Mailing Header and Mailing Footer. You can have additional Headers and Footers defined via Mailings > Headers, Footers, and Automated Messages (See Set-up for details).

Note: The message editing text area displays all text as Arial. However, the actual default is Times New Roman. You should change all text to your target font at the very end because future text edits often revert to Times New Roman.

Step 4: Test

You can test your message in one of two ways:

Test Mailing: You can specify an individual email address or a test group for your test mailing. The test mailing will fill in all the Tokens and include any attachments you are planning to send.

It is a good idea to test your email by sending it to 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 (see Testing templates in the Set-up section for more tips on this). It is preferable to have more than one person receive your test email and give you feedback.

Preview Mailing: The preview will show you all the HTML formatting and converted tokens with your data. It will not include the attachment. There is no guarantee that all email clients will display the email exactly as it is shown in this preview, but it is useful to ensure things like font consistency, basic layout and color.

Step 5:  Schedule or Send

This section will allow you to either send the email immediately or schedule a date 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.

Mailings sent to large numbers of recipients are sent in batches of about 400 to avoid the emails being caught in spam filters. Therefore, the actual sending of your mass mailing can take several hours depending on your server configuration.

Tracking sent mass mailings

To review key statistics about mailings sent in the past, go to Mailings > Scheduled and Sent Mailings. Once you have found your mailing in the list, or searched for it using the filters above, click Report in the "action" column. This will display basic information on all of the tracked actions, including the number of opens, link click-throughs or the percentage of bounces (see "Managing bounces" below).

To expand on this information, click the name of one of the statistics to display a list of the contacts to whom it applies, and various other details such as the time the email was opened (tracked opens). Where a mass mailing has been sent to a contact, you also view the "Bulk Email" record of the mailing in the Activities tab of their profile.

Now you might want to filter this information further. For example, of all the recipients who opened the mass email, you might only be interested in those who are between the ages of 21 and 30, or registered for a given event. Click "Advanced Search" next to a statistic to start an advanced search with the email attributes pre-filled; e.g. if the link next to "Tracked Opens" is clicked, the search fields will be set to look for all contacts who opened the email, ready for you to add extra criteria. For more information on advanced searches, see "Searching". 

Managing mass mailings

Mass mailings can be found in one of three areas accessible via the Mailings menu:

Draft and Unscheduled Mailings: As soon as you name your message in Step 1 and click Next, it is placed in this area. If you click Save & Continue Later or simply abandon a message after some steps, you can continue working on it by clicking on the Continue link next to the message listed here. (Note: Mailings started based on search results will not have the Continue link listed.)

You can also Delete draft messages here.

Scheduled and Sent Mailings: When you send or schedule a mailing, it will be placed in this area and remain there until it is archived or deleted.

You can track the success of delivery by clicking on the Report link next to the message.

You can also start another mailing based on a previous mailing by clicking on the Re-Use link. (Note, the Re-Use link is not available for mailings based on search results.)

The Archive and Delete links are available under the more link. For mailings that are scheduled but not yet sent, a Cancel link is available instead of Archive.

Archived Mailings: This area lists all messages that were archived from the Scheduled and Sent mailings area. Mailings listed here are not available to be included or excluded from the recipient list.

It provides exactly same functionality as Scheduled and Sent Mailings, including the possibility to view Reports and Re-Use.

Using tokens in emails

You can use tokens to insert personalized text (such as a person's name), to add action links (such as an unsubscribe option), or display standard organization information (such as domain address) into a mass mailing sent with CiviCRM. Tokens are replaced by the appropriate value at the time the email is sent out.

To view the list of available contact tokens, click on Insert Tokens. For more information about tokens in general, see Mail merge functions (a.k.a. using Tokens) in the Working with Your Data section of this book.

Contact data tokens

If you want each email to address the person by first name after "Dear," you would type a space and then click on Insert Tokens at the top right of the HTML Format field. The popup that appears enables you to find the appropriate token by 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. Browse the Inset Tokens pop-up for a complete list of contact data tokens, including any of the custom fields that have been created for your site. You can also refer to: http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens for more details.

Action and Organizational Tokens

You can also insert action tokens, such as opt-out, unsubscribe and forwarding tokens. These tokens insert links to take the specified action; in order to display the links properly in HTML messages, you'll need to add the proper link tags using the Source icon in the editor.

You can also insert standard organization information, such as "Domain (organizational) address," which displays the address of your organization as defined at Administer > Communications > Organization Address and Contact Info. For a complete list of action and organizational tokens, see: http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens.

NOTE: You are required to include a token for either opt-out OR unsubscribe, as well as the organizational (domain) address token in every CiviMail mailing. These can be placed directly in the body of your mailing body, or you can put them in the mailing header or footer. If your organization has developed a standard mailing footer, just include these tokens in the footer so that folks don't have to think about them each time they create a new mailing.

In general, including click-able unsubscribe and opt-out links are a bit friendlier for recipients (as opposed to the reply-to via email method). You can also provide both options. More details at: http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens

Custom and Checksum Tokens

Only contact fields, action links and organizational information 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 can provide a link to the person's contact dashboard so that they can review their registration details for themselves (once logged in).

You can create and use a token for custom data fields that you have created to store data about your contacts. You can also create a checksum token that generates a unique URL for each contact so they can modify their information without having to log in. See more information about custom and checksum tokens, including how to construct URLs you need, at http://wiki.civicrm.org/confluence/display/CRMDOC/Tokens.

Note: In the HTML format editing area, tokens that generate URLs (links) need to be placed in the URL field of the Link creation screen. Otherwise, they will display as text and not a clickable link in the email client of the recipient.

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 Mailings > Scheduled and Sent Mailings. These reports are based on live information about your data; you can track your emails in real time by refreshing the page.  Each mailing report is broken down into a few sections. The availability of data is dependent on you enabling tracking of the items when you set up your mailing.

Delivery summary

The delivery summary shows some high-level statistics about the mailing. Clicking on the links in the Delivery Summary will show a list of the contacts that took the action.

Intended Recipients shows the number of people that the mailing was intended to be sent to.

Tracked Opens shows the number of people that CiviCRM thinks have opened the email if you have chosen to track opens.

Note: 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 your report really tells you the number of people who downloaded the images; the actual number of readers is higher than the number reported. Tracked opens statistics should be taken as indicative, rather than accurate. In our experience, 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.

Click-throughs shows the total number of times that people have clicked links in your email if you have enabled click tracking.

Forwards show the number 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.

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.

You should review a list of bounces by clicking on the Bounces link in the Delivery Summary. You can see the reasons for individual bounces such as incorrect email addresses (e.g., contact@gooogle.com), fix them and remove their On Hold status. You can then re-use the mailing and simply add it to the EXCLUDE Recipients of These Mailing(s) list on the Select Recipients screen of the re-used mailing setup.

In the Mailings area of Search>Advanced search you can search by bounce type.

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, Mail Bounce Report, Mail Summary Report, Mail Clickthrough Report and Mail Opened Report, which offer similar functionality to what is described above.  The major advantages of looking at the reports via CiviReport (available from the Reports menu) are:

You can run the reports for multiple mailings.

You have access to all the other cool features of CiviReport, including the ability to add reports to dashboards, get reports emailed, etc.

Read the Reporting section of this book for more information.

Scheduled reminders

Scheduled reminders allow you to automatically send messages (through email or SMS) to contacts when certain criteria are met. For example: you can set up a reminder SMS to be automatically sent to participants the day before they attend a training course; or you can send a series of emails to contacts asking them to renew their membership as they approach their membership end date.

There are several components of CiviCRM that support scheduled reminders:

activities

contacts

events

memberships

You can create scheduled reminders for all these components at Administer > Communications > Schedule Reminders.

Scheduled reminders for events can also be set up on the event configuration pages.

Tokens available to scheduled reminders

In addition to the standard tokens (see Tokens and mail merge in Common workflows for a full explanation of tokens) that are available in CiviMail, messages sent via scheduled reminders can also contain tokens representing information about events, activities, and memberships that the scheduled reminder pertains to.  This allows you to use one scheduled reminder template for various events, membership types, or activity types.

In event messages, tokens such as event location will be replaced with the specific location of the event.  In membership messages, you have access to each individuals expiry date, and so on.  Membership and event ID tokens are also available and can be used to create links to specific pages (such as the membership renewal page).

Note that you also have access to the checksum token which allows you to authenticate people to specific pages without them needing to log in, and show forms with details already filled in.

Creating and managing scheduled reminders

Scheduled reminders can be created from the administration page at Administer > Communications > Schedule Reminders or during the creation of an event.

From the administration page:

Click on Add Reminder.

Give your reminder a name that will help you identify it if you need to edit it in the future.

Select an entity for your scheduled reminder. This will bring up a further set of options relevant to that entity: activities have activity types and statuses; membership gives membership types and statuses, and so on. These secondary options are (usually) multi-select fields, so you can choose to include more than one option in each field.

Choose when to send the reminder. This can be a set date or an amount of time before or after the start or end of your chosen entity. 

If you want to send more than one reminder, check the Repeat box. This gives you choices about the interval of repetition and when the repetition should end.

Check Record activity for automated email if you want a record of the  contacts who received this reminder.

Fill in From Name and/or From Email if you don't want this reminder to come from the default name and email address for your site.

Refine or add to your recipient list. For more about your choices, see Limiting or adding to your recipient list in this chapter. 

Choose to send your reminder as an email, an SMS or either depending on the preferred method(s) of communications for the contact.

Compose your message. You can use Message Templates or write the message from scratch. Note that you cannot save your message as a new template or modify an existing template from this screen, so if you are writing a reminder for the first time and you think you will want to re-use it, consider creating it as a Message Template instead.

Click Save when you are are done.

Reminders can be edited, disabled, or deleted from Administer > Communications > Schedule Reminders.

IMPORTANT: Your system administrator will need to ensure that the Send Scheduled Reminders scheduled job is enabled and runs at least once a day. Refer to the Scheduled Jobs chapter for configuration details.  

Using scheduled reminders for Contacts

Contact reminders are ideal for sending greetings for dates that may be significant to a contact such as Birthdays or dates when qualifications expire.

By default, reminders created from this screen apply to all contacts with dates set for the specified field.  If you don't want everyone to receive the reminder (eg. send birthday greetings to children but not to adults), you will need to limit the recipients. (See Limiting or adding to your recipient list in this chapter.)

Configuration options for Contact reminders:

 Send a reminder ever year on the same date (anniversary - particularly suitable for celebration dates such as birthdays) or only once in relation to the actual date (appropriate for non-repeating events such as expiring qualifications).

Using scheduled reminders for Events

Event reminders can be set up via the Scheduled Reminders administration screen (as detailed above) or from the Schedule Reminders screen in the event configuration workflow. (To get there, either click the Schedule Reminders tab when setting up an Event, or Configure > Schedule Reminders next to your event on the Manage Events screen.) The steps to configure the reminder are the same as from the administration screen (see above).

Any reminder set up from the event configuration screen applies only to that specific event. If you would like to send out reminders for all events of a certain type (for example, evaluation forms after workshops), you should use the Scheduled Reminders administration screen.

The configuration options specifically for Event reminders consist of:

Sending only to participants in specific event(s) or sending to participants in all events of a given type(s) (conference, meeting etc.)

Sending to all participants in the chosen events or only to participants with specified participant statuses (e.g. registered and attended, or cancelled and no-show)

Sending to all participant roles with the appropriate statuses or only to specified participant roles (e.g., volunteer and host, or attendee or speaker)

Since you have so many configuration options, you could set up an event reminder for almost any purpose you can think of. Here are a few examples:

Send an email to the volunteers for your annual fundraising dinner the day before the event reminding them what time to arrive.

Send fundraising emails to the attendees of all your training courses the day after the courses are held. 

Ask for feedback from event attendees.

Send a thank-you email to your event speakers and hosts.

Email people who registered but didn't show up for your event to gather information about why.

Using scheduled reminders for Activities

All scheduled reminders for Activities must be set up at Administer > Communications > Schedule Reminders.

The configuration options specifically for Activity reminders consist of:

sending to contacts associated with any combination of core and custom activity types.

sending to the specified activity types with any combination of activity statuses. (e.g., scheduled and/or  completed and/or cancelled)

sending only to the Activity Assignees (those in the Assigned To field) or only to the Activity Targets (those in the With Contact field) or only to Activity Sources (the logged-in user who added the Activity) for the specified activity type(s) and statuses.

Here are some ways you might want to use reminders for Activities:

Log calls with major donors via the Phone Call activity and automatically send emails to your executive director containing the Activity Details.

Send reminders to your staff about the interviews they are assigned to conduct.

Send notifications to the person who scheduled an activity that it has been completed.

Send thank-you notes to people who met with you.

Using scheduled reminders for memberships

You can set up messages to be sent out to members based on various characteristics of their membership, including the membership type and status.  For example, you can send an renewal reminder emails based on membership expiry date for current members 1 month before their membership end date or 'sorry you are leaving' emails 1 week after their membership end date.  You could also send membership engagement letters 2 weeks after the membership start date to remind them of the benefits of their membership.  Note that as well as sending emails based on membership, you can also send emails based on the membership related activities like Membership Signup (which is what we use in the 'Chasing members who have not sent membership payments' example below).

Below are a couple of examples of ways you can use scheduled reminders for memberships.

Renewal reminders

To send a renewal reminder email to members 5 days before their membership expires:

Select Entity Type = Membership

Select one or more Membership Types

If the selected membership types allow auto-renewal, you may want to only send this reminder to memberships that do NOT renew automatically.

Set 'When' to be 5 days before Membership End Date 

Check 'Send Email' and choose the Template (or create and save one).

What information you should include in a renewal email will be discussed in Renewals in the CiviMember section.

Chasing members who have not sent membership payments

To send scheduled reminders to contacts who have memberships that are pending because payment has not been received:

Create a smart group for contacts with a membership status of pending.

In scheduled reminders set Entity Type = Activity, Membership Signup, Completed. Note that we are using the Activity entity, not the membership entity.

Restrict Recipients to the membership pending smart group. This is important as if we don't set this, all members (even those that have already paid) will receive the message.

Limiting or adding to your recipient list.

As already outlined you can limit the recipients of your scheduled reminders based on entity specific characteristics such as event type and participant status, membership type and auto-renew options, activity type and status.  In addition, for all scheduled reminders you can limit recipient to members of a group or a list of contacts you have manually selected.  This is done by setting Recipients to Limit to and choosing either Select a group or Choose recipient(s) from the adjacent option list.  You could use this feature to, say, only send birthday greetings to your members who are less than 12 years old.

It is important to remember that groups or manual recipients selected with the Limit to option will only receive the scheduled reminder if they meet the all other criteria for that reminder.

If you want to send a scheduled reminder to contact(s) who do not meet the general criteria for that reminder you should set Recipients to Also include. You can then select a group of contacts or an individual who will receive the reminder even if they don't meet the other criteria.

For example if you send an event reminder to registrants 2 days before an event, you can also send it to Bob Adams, your office manager, so that he will remember to check that the event room is set up in the appropriate configuration with any equipment required.

Scheduled reminders and privacy options

Scheduled reminders are still sent to contacts who have opted out of bulk emails and those who have selected the privacy option Do not email. In some cases this is appropriate as these contacts will still want to be reminded when an event they have registered for is approaching or when their membership is due to be renewed. In other situations it is not appropriate. 

If you want to exclude contacts who have opted out of bulk emails from a scheduled reminder you should:

Find all contacts who have not selected the privacy options Do not email or NO BULK EMAIL. (You can do this using the Search Builder found at Search > Search Builder and updating the settings as indicated in the example below)

Create a smart group from the search results.

Select this smart group as the Recipients of the scheduled reminder.

What is SMS?

SMS stands for Short Message, or Short Messaging Service, and is simply the text messages your mobile phone may send and receive on a daily basis. CiviCRM can handle the sending and receiving of these messages from within the system, providing you with an extra means of making and tracking communication with your constituents, other than email.

Some of the use-cases for this include:

Disseminating information to areas where mobile and landline internet access is either unavailable or unstable.

Collecting information/responses from remote areas

Rolling out an SMS marketing campaign

Distributing alerts and reminders

Sending a note to event participants (e.g. a meeting) that the location or time has changed at the last minute

Set-up

In this chapter, the steps required to set up an SMS gateway will be explored. Once configured, you will be able to send text messages to individual contacts and mass mailing lists within CiviCRM. For more information, see "What is SMS?"

Configuring a Clickatell SMS Gateway

Registering for a Clickatell account 

The Clickatell service is an online SMS gateway designed for the sending of text messages via the Internet. They offer several products, but here we are only interested in the "Developer's Central" SMS gateway, as it offers more advanced tools needed to link it to CiviCRM (this is achieved through APIs; see the CiviCRM developer guide for more information). Registering for a Clickatell account is free, and they supply 10 complimentary credits to try the service. To sign up, visit:

http://www.clickatell.com/register/

Once you have registered for a Developer's Central account, please sign-in and follow the steps below (when logging in you must select "Central API" as the product and enter your Client ID):

In the Central Home dashboard, click "Create a new Connection" under "Connection Status"

Select "HTTP/S" as the connection type

Four optional settings will appear, including:

Description: change the name of the connection (e.g. "CiviCRM HTTP")

Replace leading zero: enable this option if phone numbers against your contacts begin with "0". For delivery to be successful, all numbers must begin with the country code if this is not enabled.

Enable IP Address Restriction: if you know the IP address of your CiviCRM server, you can enter it here to ensure that text messages cannot be sent using your account elsewhere (your username and password would be needed to do this)

Click "Submit and Get API ID" to generate an API ID, and on the next page, make a note of it. 

Completing the SMS Provider settings in CiviCRM

You now have all of the information needed to configure SMS in CiviCRM. To continue, return to CiviCRM and go to: Administer > System Settings > SMS Providers. Click "Add New Provider". 

Complete the following settings:

Name: select "Clickatell"

Title: give the SMS provider a title user's will see (e.g. "Clickatell SMS")

Username: enter your Clickatell username

Password: and your Clickatell password

API type: select "http"

API URL: type the URL as follows: https://api.clickatell.com

API Parameters: this is where you should provide your API ID. The format required is:

api_id=8473658

Is this provider active?: tick to enable the SMS gateway

Is this a default provider?: check this option to make it the default, where multiple SMS providers are available

CiviCRM will now be configured to send text messages to your contacts. 

Testing the SMS gateway

You can begin testing the gateway using the methods laid out in the chapter "Everyday tasks". However, please note that if you are using the 10 complimentary SMS credits which came with the account, until you have purchased credits Clickatell will replace the content with thank you text like the message below:

"Thanks for testing Clickatell's gateway coverage. You will be able to change the content of your message after your initial purchase of message credits."

Everyday tasks

Here we assume that you have already configured an SMS provider in CiviCRM, and are now ready to either test sending an SMS, or engage with your contacts. If you have yet to set up an SMS gateway, please read "Set-up" first.

Sending text messages 

SMS messages can be sent to mailing lists or the results of an advanced search for bulk SMS blasting, or a selection of individuals chosen manually.

Messages to a few individuals

If you wish to send a text message to an existing individual, open the contact's profile, click the "Actions" button and select the option "Send SMS". You can also create an SMS in the activities tab of a contact from the "- new activity -" drop-down menu.

A new page will now appear in which to write your message:

From: choose the SMS provider you would like to send a message from.

To: this field will automatically populate with the mobile number of the contacts you selected on the previous screen, however, you can add further recipients by typing their name after the first number, and selecting a name from the suggestion list. Note that contacts without mobile numbers will not appear in the list (the phone number type must be "Mobile").

Name the SMS: this will appear as the SMS activity against the recipient's profiles, so giving it a name appropriate to the subject will help differentiate it from others later (e.g. "Change of email address request").

Use Template: if an SMS template has been created in the past, you may insert it here to save time (for more information, see "Set-up" in the "Email" chapter).

Plain-Text Format: here you may enter up to 160 characters of text for the message content. As with emails, tokens can also be inserted to pull information about the contact into the message (e.g. first and last name, or contribution amount; see "Tokens and mail merge").

Save as New Template: message written, if you wish to re-use the text regularly at a later date, you can save it as a template to save time later.

Finally, once the SMS has been sent, a confirmation message will appear and an SMS activity will be posted against the recipient's contact profile. To view this, open the contact, go to the "Activity" tab and browse the list for an activity of the type "Text Message (SMS)". Click "View" in the last column to see more details, including the message content and campaign.

Mass SMS messaging

Alternatively, you might want to send a personalised SMS to many people at once. Before you start to write your message however, you will need to have a list of recipients. If the message is a one-time affair, you can run an advanced search for the criteria your participants must fall into, select some or all of the contacts in the results list and choose "Send SMS to Contacts" in the "Actions" drop-down menu. Please note that the activity type this method creates will be "Text Message (SMS).

Otherwise should you wish to send bulk text messages to the same group of contacts on a regular basis, you can use a mailing list. If you haven't built one before, or would like to refresh your memory, read the chapter "Setup" in the email section.

To begin writing a bulk SMS, go to: Mailings > New SMS. There will three steps to complete:

Naming your SMS and selecting recipients: first give the text message a name. This will appear as the SMS activity against every recipient's contact profile, so giving it a clear subject will help identify the content later. You will then need to select your recipients, so move the mailing lists you wish to include from the "include groups" box on the left, to the right using the "Add" button. You can also specify groups you do not want to include; contacts who fall into both groups will be not be sent a message (e.g. they may have already received a similar SMS under the group you have chosen not to include). Click Next.

SMS Content: before writing the message, select an available SMS Provider and decide whether to use an existing mailing template for the content of your SMS (see "Setup in the Email chapter).

The message content can either be written manually in the "Compose On-Screen" section, or uploaded from a text file, however, bear in mind that the character limit for both is 160 (this is the length of one text message). You may also insert tokens to personalise the SMS by 'pulling' information about each contact into the message (see "Tokens and mail merge" to learn more). Once written, if you think you would like to reuse the message later, tick the check box "Save as New Template" before going to the next screen.

Schedule or Send: you now have the option to send the message immediately, or schedule it to be sent automatically at a future date and time. If you do not wish to do either at the moment, you can click "Continue Later" to save your progress and make the decision later. To return to the message, go to Mailings > Draft and Unschedule Mailings, tick the option "Is SMS" and click "Search". A list of unsent text messages will appear - simply click "continue" against the message you wish to complete.

Finally, you can click on the "Preview SMS" banner at the bottom to check the content, or hit "Submit Mass SMS" to send your message.

Reports and Analysis (SMS)

Reporting on all text message activity

To report on all SMS messages sent in CiviCRM, you can run an activity report, available here: Reports > Activity Report.

First, you will need to filter the activity type to either "BULK SMS" or "Text Message (SMS)"; select "BULK SMS if you sent the message to a mailing list, and "Text Message (SMS)" if you created it within a contact or advanced search (you may also select both by holding CTRL or CMD while you click). You can then filter further by:

message status (e.g. completed/scheduled)

date and time

which group or tag the recipient is in

and characteristics of the recipients themselves, such as their name and location.

All of these settings can be found by clicking the "Report Criteria" banner at the top of the report page.

Finally, to update the results click "Preview Report" at the bottom of the criteria section. 

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 You Need To Know

This chapter explains 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.

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. 

The number of questions an organisation might want to ask about their data is pretty much unlimited. The CiviCRM approach to solving this problem 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%. 

Key Concepts

Report templates

A report template is the base for creating any number of reports. CiviCRM comes with a number of predefined report templates that can be used to create specific reports. For example, the Membership Report(Detail) template can be used to create a report that shows all student members that have joined your organisation within the past quarter or another that shows all cancelled memberships this year.

These templates are built to satisfy the basic needs of non-profits and organisations and future versions of CiviCRM are likely to include further report templates. You can create new templates to meet the specific requirements of your organisation and contribute these reports back to the CiviCRM community for others who have the same reporting needs. Writing a new report template requires some PHP and SQL skills. See the Developer Guide for details of how to do this.  

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. CiviReport gives users the ability 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. 

The current report interface does not support most common batch actions such as Update via Batch Profile, Smart Group creation and so on. This means that if you want to perform any action against a result set, it is better to use search rather than report. 

However, in some cases reports are more flexible than searches, and each has its own set of features. For example, reports allow you to change the columns displayed and in summary reports you can order by whichever display results you choose.

Report options

Run the report: you can Print Report so it is viewable in browser or you can generate a PDF or Export to CSV. All of these run the report once when you hit the button and allow you work with it.

Dashlet: if you make a report Available for Dashboard users with appropriate permissions can add this report to their dashboard. This is useful for information that you want to see on a regular basis, such as a list of new members, or donations this month, etc. In this case the report is run every time the dashboard is loaded.

Email: schedule a regular email of the report so that your finance office can receive a monthly email of all event fees received or your membership administrator gets a weekly email of overdue renewals.

Detail vs summary reports

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.

Key Questions

Should you use CiviReport for a particular task, or could it be better achieved with a search?

What reports are available? 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).

What questions do you want to ask about your data? For example, you may want to know how many new members you have in a certain period, or how much money was collected during a fundraising campaign.

What fields do you need to include?

Does the report provide enough options or will you need to analyse further in a spreadsheet?

Is it a one off report or will you need to run it regularly? Could you make a report template to streamline future reports?

Who needs to see this report? Will it provide sensitive information that should only be available to privileged users or does it give useful daily updates to all?

Details of available report templates and comparison with searches are provided for each component throughout the rest of this book; refer to the relevant section for more details about component-specific reports.

Set-up

This section explains how to set up CiviReports. It assumes a basic understanding of why you would want to use CiviReport, and describes the workflow for creating a report from a template through to making these reports available for users. It also assumes that the report you require can be achieved using the report templates supplied with CiviCRM.

If the report template you need does not exist you (or your developer) should refer to the Custom Reports chapter in the Extensions section of the Developer Guide for information about creating new templates.

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.

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 your report criteria: decide what information will be displayed in the report.

Define the report settings: choose a title, set permissions and add it to a menu. 

Select report criteria

There are three types of report criteria:

Display Columns

Group by Columns

Filters

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 shown below compares donations per quarter in 2009.

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.

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:

by using an absolute date range, e.g. "1st Jan 2010" to "31 July 2010"

by using a relative date range, e.g. "Previous Year".

Relative date ranges are very useful for reports that you want to run on an ongoing basis.

This year gives all records from the start of the current year.

Previous year gives all records from the previous year.

Earlier year gives all records excluding this year.

Ending year gives all records between one year from today's date, and today (really useful!).

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.

In the Create Report section of the template, 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

If you wish to have the report emailed to yourself or someone else on a regular basis, 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. See the information below about email settings.

If you want to make this report available to other users through a menu item, check Include Report in Navigation Menu? and specify the parent menu and permissions. 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

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. 

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; users without this permission will be able to view reports but not edit the criteria. 

Checking the box Available for Dashboard? to make the report available for users with appropriate permissions to add this report to their dashboard (this is done by clicking the Configure Your Dashboard button on the individual's dashboard).
ConfigureDashboardBtn

Click Create Report. It will now appear in the drop down list of reports under the Reports navigation menu. 

Email settings

As well as entering the email delivery settings described above, the Mail Reports (mail_report) scheduled job must be enabled to send report emails. Alternatively a cron job can be scheduled to run this specific task apart from other scheduled jobs. The specific report instance and, optionally, format are specified as part of the scheduled job configuration. Refer to the Scheduled Jobs chapter for more information.

Everyday Tasks

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 setting up CiviReport.

Viewing reports

To view a report:

Go to Reports > Report listing. 

All reports are listed on this page, grouped by the component they report on. 

Click on the name of the report you wish to view.

Reports can also be configured to be directly accessible from navigation menus. For example, an event report can be configured to 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.

The appropriate report should then be displayed.

As well as viewing reports on screen you can create a PDF version of either tables or graphs, suitable for printing or emailing.

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.

To display specific reports on your dashboard:

From your dashboard, click on Configure Your Dashboard.

Select a report from the list of available reports.

Drag the report onto your dashboard.

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.

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:

track a specific workflow or set of procedures that must be followed and that involves a number of different organisational staff

allow staff to manage and track interactions while avoiding duplication 

automate the task of remembering and scheduling follow-up activities. 

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 couple of examples of different types of organisations that use 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 an issue, the staffer taking the call can look at the activities in the case related to the issue and see that another staffer is already working on the issue and relay that information to the caller). 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:

A legislative staffer received a phone call about illegal dumping near the caller's home. The staffer created a case recording the details and location of the reported issue. She then assigned the task of following up with the Health Department to another member of the legislator's staff. Upon logging-in to CiviCRM, the other staff member saw that the task was assigned to them. He then contacted the Health Department on behalf of the constituent, and contacted the constituent to confirm that the Health Department was informed of the situation.

The legislator's office received a phone call from a constituent requesting support from an agency. A staffer logged the call in CiviCase and then set up a follow-up call for the next week to make sure that action was taken on the agency's behalf. 

The legislator's staff records event invitations on an ongoing basis that a legislator's scheduler must respond to. 

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:

passed basic checks

failed basic checks

technically feasible

technically infeasible

suppliers approved

suppliers disallowed

deferred to next round

accepted.

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 review the summary details of all applications with an accepted status to make a final determination. 

CiviCase in use

Here's a simple example of a Housing Support case.  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.

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.

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.

Key Concepts

Activities : CiviCRM tracks most interactions with activities. These are particularly useful for 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 date/time, a duration, a status, a priority. They have a creator and a subject/target and can be assigned to someone for action.

Cases are used to track more complex interactions or communication processes than can be handled by a single activity. CiviCase provides additional structure around activities:

Multiple activities can be grouped together into a case

Activities can be optionally structured using a Timeline or a Sequence

The set of possible activities to track interactions can be optionally restricted

CiviCase also identifies the people involved and their role(s) in the case:

Case Coordinator is a pre-defined role

Additional roles can be added as required

 CiviCase also provides additional options for managing activities:

The Case Dashboard allows users to see the cases they are involved in

Cases provide an extra layer of access control 

Using these features, a case can define a workflow with specific steps 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.

Case Types

One or more Case Types are defined that describe a specific group of related tasks, interactions, or processes. 

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:

In-patient Treatment

Referral to Counsellor

For a community services organisation, examples of case types might include:

Housing Assistance

Job Training

Prenatal Counseling

Think about the multi-step 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 they may involve the case client (a.k.a. the constituent), 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:

Open Case: created at the same time the case is created. 

Follow up: you can use this type when it isn't necessary to define a more specific one (see Activity Data below). 

Change Case Type: created every time the type is modified. 

Change Case Status: created every time the status is updated. 

For a community services organisation, additional activity types might include:

Client Intake

Skills Evaluation

Review

Consultant Referral

For each of the case types you identified, create a list of the specific activities involved. Creating new activity 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 an activity is recorded in CiviCase:

who recorded the activity and who reported the activity

when and where the activity will (or did) occur

free-form subject and detailed description

time spent on the activity.

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 and the standard timeline

CiviCase allows you to define one or more expected sets of activities for each type of case and when they should occur. These are called timelines.

For really simple cases, the timeline might include only two items:

Open Case

Follow up - scheduled for two days after the case is opened

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 time-frame. When a timeline is added to a case the activity dates are pre-computed and do not update automatically. Any changes to dates must be made manually.

Each case type must have a standard timeline. The standard timeline is created automatically when a new case is opened. At its simplest it consists of just one completed "Open Case" activity. You can leave it at that or add more activities as required. In a standard timeline you define the expected number of days between the beginning of the case and each of the subsequent activities in the timeline.

You can create mulitple (non-standard) timelines for a case and add them if/when it is appropriate to do so. For these timelines you can use any activity as the reference for subsequent activities. So, for example, if one of the activities in your standard timeline is a medical evaluation, you could have 2 or more timelines that outline different schedules of medical treatment and add one of these to the case depending on the outcome of the original medical evaluation. For this example the timelines would typically use "medical evaluation" as the reference activity.

You might also want to define a (non-standard) timeline based on the end date for a case. When a case has to be completed by a specific date (e.g. by the start of the school year), each activity can be defined as needing to happen a number of days before this end date, i.e. you would define negative offsets in the timeline. You would open the case, add the final activity with the scheduled end date, then add the timeline. This would create a series of activities with the scheduled date for each being the latest it could be completed if the entire case is to be completed by the end date.

Sequences

CiviCase lets you define one sequence instead of, or as well as, timeline(s). A sequence is a set of activities that should follow one after the other, but no time-offsets are defined for the activities.  Instead the activities are created one at a time, with the first activity in the sequence created when the case is opened, and the second activity in the sequence being created as soon as the first activity is completed and so on. The scheduled date is always the date the activity is created.

Defining a sequence rather than a timeline may be useful if the completion of activities in your case are outside your control. However, as the activities are created progressively it will not provide the same at-a-glance overview of the case that a timeline does.

NOTE: If you want to use both a timeline and a sequence in the same case you must make sure that there is no overlap in activity types between the two. For example, you cannot include the activity type of "Meeting" in both a timeline and the sequence within the same case as this will create problems.

Case Roles and Relationships

CiviCase provides three mechanisms for relating people to cases and clients:

Case Roles: people directly involved in this case. Examples include Intake Specialist, Case Coordinator, Addiction Counselor, Employment Counselor, etc. You can identify one of these roles as the case manager for a particular case type.

Other Relationships: people related to the client, with relationships that exist beyond the context of a particular case. Examples include Spouse, Sibling, Family Doctor, etc. Generally, use relationships when you want someone to appear on ALL cases for the same client, otherwise use a case role.

Case Resources: people and organisations that have involvement with many or all cases in your case management setting. Examples include: regulatory agency contact(s), service provider, frequent referral contacts, etc.

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:

Case Coordinator

Addiction Specialist

Job Counsellor

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:

What case types do you have? 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.

What activity types do you need to have in those cases?

Who should activities be assigned to? By default everything might be assigned to a case coordinator who will then reassign to whoever has capacity, or certain activities might require the intervention of a particular individual.

Do you have a default timeline and what does it look like?

Do activities need to be offset from the start, each other or from the end?

What roles are involved? Are existing relationships adequate, or do you need to create some case specific ones?

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.

Activities are single tasks or interactions between your organisation and a client or constituent, or between people within your organisation.

Cases involve a succession of interactions (activities). The record of these activities forms the case story and almost all information about a case should be stored as an activity.

Classifying cases by case type allows you to define work-flows and evaluate results.

Cases often have a predictable succession of activities (a standard timeline). Creating a schedule with the expected timeline helps people working on the case to manage their work, and is a useful way to measure progress.

Cases often involve a predictable set of people involved (staff, professionals, etc.). These are case roles. Knowing who is playing what role in a case is helpful, and provides an easy way to communicate case activities to other people who are also working on that case.

Organisations may have additional people and/or outside organisations (case resources) who are frequently contacted or involved with most or all cases.

Set-up

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.

Enable the CiviCase component

The CiviCase component is included in CiviCRM downloads, but it is NOT enabled by default. To enable the component:

Go to Administer > System Settings > Enable Components.

Select CiviCase in the left-hand box and click Enable (this should move it to the right side).

Click Save.

You will now see Cases in the navigation menu.

Define Case Types

You can create one or more new case types.

To add a case type:

1.  Go to Administer > CiviCase > Case Types.
2.  Click New Case Type. Enter a "Title" and an optional "Description" of the case type.

The case type has both a "Title" and a "Name". The title will be displayed to users, and the name is used internally by CiviCRM. CiviCRM will autofill the name field. (The default name is usually fine, but advanced user may unlock and change the name. Once the case type is created, the name should not be changed.) 

3.  Include Case Roles
This section lists the types of people who are involved in the case in some way. Roles listed here will be automatically included in each case when a new case is opened.

Select the roles that you wish to be included in the case type from the  "Add role" drop-down shown below the listing of roles.

If you need to create a new custom role for your case type, click the drop-down, and type the name of the new role into the field. As well as displaying any matches from the existing list of roles, you will also see a blue bar containing your keyed entry, underlined. Simply click on this to define the new role. The new role will be created when you save your new case type. Using this method you can quickly create as many new roles as you need for your case type.

As each role is selected or created, it appears in the listing of Roles, where you can further set "Assign to Creator" and "Is Manager" options:

Any role marked with "Assign to Creator" is then automatically assigned to the person who creates the case.

You may also mark one of the roles as the manager. The case manager's name will be displayed prominently in case listings and reports.

Specific people may be assigned to case-roles -- after a case has been opened. 

New roles/relationship types created through the Case Type interface are individual-to-individual relationships. If you want roles that are individual-to-organisation relationships then, once you have finished creating your case type, you can change the relationship definition at Administer > Customize Data and Screens > Relationship Types.  There you will also be able to review and edit other details of the roles/relationships if you need to.

4. Include Activities
When working on a case, the user has access to a drop-down menu in the case summary enabling them to quickly record a new activity as part of the case. For example, if the case manager looks at a case and decides they need to check a point of detail with a colleague, they could make a phone call, and quickly log that call to the case by selecting Phone Call from the Add Activity menu, recording the details of the call in the activity. The Phone Call activity automatically gets filed on to the case. 

When defining the Case Type you can choose which Activity Types are made available within this drop-down menu.

If you are including most or all of your custom Activity Types in the Standard Timeline, or another timeline or sequence within your Case Type, you may not want to include these custom Activity Types in your 'Add Activity' menu, particularly if you want tight control over the workflow pattern in your case type. In a different scenario you might want to give your users more flexibility, and give them access to some or all of the custom Activity Types in the menu, allowing them to have much more control over the pattern and flow of activities in the case.

The first step is to create a list of all of the Activity Types that you would like to have readily available from within the case. This is the listing under the 'Activity Types' tab. You should focus on selecting just the activity types that your users will find useful. These might include Phone Call, Email, Meeting, and Follow Up along with any custom activity types. (CiviCRM also includes some special activity types -- such as Open Case,  Change Case Status, and Change Case Type. There is no need to manually add these activity types.)

NOTE - the Activity Types listing needs only those activities that a user might choose to add to the case.  Activities that you include in a Timeline or Sequence do not need to be in this list.

 Select the activity types that you wish to be included in the case type from the  "Add activity type" drop-down shown below the listing of activity types.

If you need to create a new custom activity type for your case type, click the drop-down, and key the name of the new activity type into the search field. As well as displaying any matches from the existing list of activity types, you will also see a blue bar containing your keyed entry, underlined. Simply click on this to define the new activity type. The new activity type will be created when you save your new case type. Using this method you can quickly create as many new activity types as you need.

As each activity type is selected or created, it appears in the listing of Activity Types. You can optionally specify the maximum number of times a given activity type can be used in a case using the 'Max Instances' element.

Once you have created your case type you can review and amend the details for any new activity types you may have created by editing them at Administer > Customize Data and Screens > Activity Types. New activity types created through the Case Type interface have default settings that should be fine in the majority of situations, but you may wish to amend the label, add a more useful description, or if you want to make the activity type available to be used more generally outside of CiviCase you can change the 'Component' setting from 'Cases only' to Contacts AND Cases'.

5. Having defined all of the Case Roles and the Activity Types that will be available for user selection in your new Case Type, you next need to define the Standard Timeline, any additional Timelines  and/or a Sequence that you want to use within the case type.

These are simply groups of activity types which define a series of interactions, giving you the ability to pre-define one or more standardised workflows for any given case type.

In a Timeline you control the scheduling of each activity in your timeline relative to the date the case is opened, or relative to another activity in the case, using the 'Reference' and 'Offset' fields. When you use a timeline, all of the activities defined in the timeline are created when the timeline is added to the case and are visible in the case summary. You can create multiple timelines for use in any given case type. 

The Standard Timeline is the default timeline for each new case type that you create, and provides the essential elements that will make your case types work correctly, so each case type must have a standard timeline.  The activities in the standard time line are added automatically when the case is opened.

The Standard Timeline starts with one predefined activity, Open Case, whereas additional timelines are empty to start with. As you control when an additional timeline is added to the case you will choose the first activity, which may also be a key reference activity for this timeline. 

A Sequence defines the order in which a set of defined activities should occur, but unlike the timeline it includes no information about time intervals between activities. A sequence also differs from a timeline in that the next activity in any sequence is created only when the preceding activity is marked as completed. You must make sure that any activity type included in your timeline(s) is not also included in your sequence and vice-versa.

You may add additional timelines or a sequence by selecting the option from the (Add) menu. Currently you can only add one sequence to any given case type.

To add activities to a timeline, select the tab for the timeline you want to work with: 

Select or create an activity using the drop-down list.

Select a status for the activity (the default is Scheduled).

Enter a Reference Activity. The default reference activity is Open Case and this is often appropriate. For the Standard Timeline any activity in the timeline can be selected as the reference for any other activity. For other timelines you can select any activity in the case type as a reference, bearing in mind that at the point in alive case where the additional timeline is activated, the reference activity must already exist in the case.

Enter an Offset (in days). Offset values can be positive, negative or zero.

The 'Select' option is helpful if there are multiple instances of the reference activity type, as it allows you to select whether the oldest or most recent instance of the reference activity should be used.

You can choose to use the "end date" of a case (i.e the final defined activity) as your reference and use negative offset values to schedule activities as the example below shows.

You can rename additional timelines or a sequence using the fields available in the 'Advanced' section below the main Activities section of the page as shown above.

To add activity types to a sequence simply select or create them using the Add Activity drop-down menu.

Once you have all the activity types you need  for your timeline(s) or sequence you can re-order them if necessary using the drag and drop handles to left of each activity type in your listing.

A set of sample case types are installed when you enable the CiviCase component. These can be useful either as a point of reference to see what a complete case type looks like, or even as a start point for your own case types.

Custom fields

It is likely that you will want to collect structured data in the case. You can collect data in custom fields connected to a specific activity type, or connected to the case type. For example, in Employment Counselling cases, you may want an activity type Skills Assessment, in which an employment counsellor records client job skills. This activity type will require one or more custom fields, perhaps a set of checkboxes. Alternately a generalized application case might need a custom field to indicate the type of application that is being tracked.

The main difference between using custom data at the case versus activity level is that custom fields attached to the case are visible inside the case management screen, while custom fields attached to activities are only visible if the user views details on that particular activity.

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.  

Please review the section on configuring custom data fields prior to beginning these steps.

Go to Administer > Customize Data and Screens > Custom Fields.

Click Add a Set of Custom Fields.

Under Used For, select Activities or Cases.

Select one or more specific activity type(s) or case type(s) for which this set of fields will be used.

Enter any help information you want to be displayed to your users.

Click Save.

Enter one or more custom fields for this set.

Repeat these steps for each activity type or case type which requires custom data to be recorded. 

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.

Filing Emails on Cases

Some organizations find it useful to record 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 both the sent email and the reply to become part of the case story.

You can choose to send outbound emails directly from the Manage Case screen, but you can also set up CiviCRM to integrate with your usual email client so you can send and receive emails as usual and also have them filed in CiviCRM.

In the CiviMail chapter the Email Processor was described as a way to get inbound and outbound emails into CiviCRM as non-case activities. When you enable CiviCase, a new action will be available that allows you to file any non-case activity onto a case.

Additionally, when email activities are sent from the Manage Case screen, if the Email Processor has been set up then replies will automatically be filed directly onto the case.

CiviCase permissions

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, Joomla! or WordPress user account.

For Joomla! and WordPress installations, staff members must have back-end (administrator) access. All CiviCase functions are done within the Joomla! and WordPress Administrator interfaces.

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.

In order for users to add and manage cases, you will need to configure CiviCase-related permissions for users in your CMS. You may want to create case management-specific user roles for staff, based on their responsibilities within your organisation. 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.

The following 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 see case data (i.e. hide all other contact information from them), assign "access my cases and activities" permission WITHOUT "edit and view contacts" permission. This permissioning model is useful for users who are external to your organisation and who should not be allowed to see contact details.  

FindDeletedCasesAccess 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.

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.

Administer CiviCase: gives access to Administer > CiviCase options including:

create and edit case types and case statuses

set rules for redacting case data. These rules are used to disguise data which could be used to identify the case client in case reports which are shared with external reviewers.  

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:

a summary of cases in the system (Summary of Case Involvement)

a list of your cases with upcoming activities (scheduled in the next 14 days)

a list of your cases with recently performed activities (completed in the last 14 days).

If you have permission to view cases other than ones that you are working on, you also have the option to see:

a list of all cases with upcoming activities

a list of all cases with recently performed activities.

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.

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:

client's name or email address: type characters from the name or email address into the Client name or email input field

type or types of cases: checking the case types that you would like to filter by

case status: selecting a status from the dropdown menu

all cases or your cases (if unselected, the default is to filter by your cases)

deleted cases: click the Deleted cases checkbox.

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:

Go to the contact's summary screen.

Select Add Case from the Actions dropdown menu, or alternatively click on the Cases tab.

Fill in the required fields in the Add Case form.

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:

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!.

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).

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.

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. You can manage Encounter Mediums by selecting the edit icon.

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.

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.

Manage Case Page

The manage case page gives users the ability to manage all aspects of a particular case on a single screen, including:

View summary case information

Change case status or reassign

Create/manage activities

Create/manage timelines

Create/assign case roles

Identify/manage client relationships

Run case audits (reports)

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).

Within a case, you can assign a case role to a contact:

Click the Case Roles area to open it.

Case roles that have not been assigned display (not assigned) in the Name column. Click the edit icon to assign someone to that role.

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.

Select the contact you want to assign to the role and click OK.

Where you need to have more than one contact assigned to a given case role you can do this using the Add New Role button. Clicking this brings up a pop-windwo window where you can select any of the roles defined in your case configuration, and select a contact from within your database to whom the role will be applied. The new role relationship will then be listed in the Roles pane of the case management screen.

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/him 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:

Reporter/Role

Activity Status

Activity Dates (enter a range by filling in both date fields, or search for activities performed on a specific date by filling out the first date only)

Activity Type (for instance, to find all follow-up activities, select Follow up from the list)

Deleted Activities (available to people with permission to view deleted activities).

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.

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 single new activity to a case

Navigate to the case (either using Find Cases or via the Cases Dashboard).

Choose an activity type from the select list labeled New Activity in the Case Summary.

Click Go.

Fill out the activity form. The Client field will be pre-populated with the case's client data.

Note: the drop-down list of activities is configurable. Refer to the instructions for Activity Lists in the set-up chapter

Adding a set of activities

 When the case is created, the Standard Timeline is added.  You may add additional set of activities when appropriate.

Navigate to the case (either using Find Cases or via the Cases Dashboard).

Choose a Timeline or Sequence from the select list labeled New Timeline in the Case Summary.

A dialog box will pop-up. Confirm that you wish to add the activities by clicking "OK"

The set of activities will be added to case. 

To send a copy of the activity to anyone with a case role for the case

Open the Send a Copy area.

Check the contacts or case roles whom you would like to be alerted about this activity.

To schedule a follow up activity

Open the Schedule Follow-up area.

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").

Click Go.

Complete the form and click Save.

To add an attachment to the activity

Open the Attachments area.

Click a Choose file button.

Up to five files can be attached to an activity. Select an attachment from your file browser.

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:

Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.

Click Edit at the far right side of the activities table at the bottom of the case form.

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:

Start typing the staff member's name into the Assigned to field; a list of possible contacts will appear.

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.  

Updating the status of case activities

You can quickly update the status of an activity from the Activities table (without opening the activity edit form):

Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.

Click on the status text (i.e. "Scheduled") in the activity table row.

 This brings up a pop-up form where you can select a new status. Click Ok to save your update.

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:

Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.

Click Manage Case.

Click the Edit icon next to the current status column in the Case Summary table. 

This will open the Change Case Status form (an activity with an additional field called Case Status).

Set the case status to the new status.

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. 

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.  

Reports and analysis

There are a number of techniques for reporting on and analysing your casework. You can run an audit of the activities for each case from within that case. 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.

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.

QA Audit / Redact

This report is run from the contact's case management screen. It provides details for the activities in the case. You can chose to report on all activities or to exclude those with 'Completed' status.  If you select Redact (hide) Client and Service Provider Data then contact numbers rather than names will be include in the report as shown here.

  The onscreen report displays information for one activity at a time. Click on the description in the table on the left to display the information for that activity.

If you print the report it will include the Case Summary and the Case Roles as well as the Case Activities.

CiviCase Reports

There are four report templates specifically for cases as shown below:

In addition as cases are made up of activities, 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:

Navigate to the case from the Case Dashboard, the Find Cases search form, or the contact's Cases tab.

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.

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:

create surveys and petitions

record responses to surveys and petitions

link activity such as donations, mailings and events to a particular campaign

track who has voted using Get Out The Vote (GOTV)

record individual members' levels of interest and engagement in a particular activity.

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:

created a Campaign as the umbrella for all related activities, including the duration of the campaign and the revenue goal

created a group consisting of the individuals they wanted to target for the activities in the campaign

called their most active members to help organize other constituents in their neighborhoods to participate, and recorded the activity phone call in the individual's record, indicating the specific campaign and the member's response

sent a mass fundraising mailing and indicated the campaign, which was then recorded in the contribution information of individuals' records

created an event to track who will be attending the mobilization, and indicate the campaign in the event setup.

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.

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:

Who are your target audience, and how will you reach them? Remember that the audience for your campaign activities may not be the same as the audience you are trying to reach with the actual campaign itself. Understanding your target audience will help you to choose the most appropriate strategies and communication activities to achieve the goal(s) of your campaign.

What activities and strategies, such as events and mailings, will be associated with this campaign?

How will you be gathering data during the campaign (e.g. surveys, petitions, event registrations) and who will be responsible for entering the data into CiviCRM?

What kind of reports will be useful for monitoring progress and evaluating the campaign at its conclusion?

CiviEngage and CiviCampaign

CiviEngage is a Drupal only feature 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. 

Set-up

This chapter will help you to set up CiviCampaign so that you can track related activities such as contributions, surveys, mailings that are part of your particular campaign or project.

Enable CiviCampaign

First, you need to enable the CiviCampaign component.

Go to Administer > System Settings > Enable CiviCRM Components.

Select CiviCampaign and click Enable then Save

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:

Direct Mail

Referral Program

Constituent Engagement.

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

To add a new campaign type:

Go to Administer > CiviCampaign > Campaign Types.

This will display a list of existing campaign types:

Click on Add Campaign Type, and give the new type a label and a description (optional).

Optionally, change the default weight: this affects the order in which this new event type appears in drop-down menus (smallest numbers appear highest).

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. 

Go to Administer > CiviCampaign > Campaign Status. 
The default statuses are Planned, In Progress, Completed, and Cancelled.

Click Add Campaign Status, give it a name and, optionally, a description. 

Changing the weight is not necessary but will affect the order in which this new status appears in drop-down menus. 

Click Save and the new status will then be available 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:

Go to Administer -> CiviCampaign -> Engagement Index.

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:

 Go to Campaign > New Campaign.

Enter information about your campaign:

Title (required): enter a unique name that describes your campaign. It's helpful to establish a naming convention for new campaigns so they alphabetize in drop-down lists automatically and are easy to sort through when associating and activity with the campaign. 

Campaign Type (required): select the type of campaign, e.g. Constituent Engagement. To add more options to the Campaign Type drop-down list, see the previous chapter on setting up CiviCampaign. 

Description: enter text that describes your campaign. 

Include group(s): if appropriate, select the group that contains the individuals you are targeting for this campaign. To find out more about creating groups, see the chapter on Tags and Groups.

Start Date & Time (required): enter the start date and time of the campaign

End Date & Time: enter the end date and time of the campaign. If these fields are empty, then the campaign will be considered ongoing.

Campaign Status: select the status of the campaign, e.g. In Progress, Planned, etc.  To add more options to the Campaign Status drop-down list, see the previous chapter on setting up CiviCampaign.

Campaign Goals: enter text the describes the goals and/or objectives of your campaign. You may also want to describe the activities you plan on conducting to meet those goals. 

Revenue Goals: if applicable, enter a number that indicates the amount you plan to raise during your campaign. 

External ID: if you want to track the campaign ID of the campaign when it existed in another database, you can enter the ID number of your legacy campaign. 

Is Active?: check the box if the campaign is an active campaign. If the campaign is inactive, then uncheck the box.

Click Save, to save the campaign.

Targeting constituents: create a group

You may want to target a specific group of individuals for all campaign activities. This is done by creating a group to target these individuals. See the chapter Tags and Groups for more information about how to create a group.

Send a mass mailing

A mass mailing to your target audience can generate interest and participation, and also be used to call for donations.  

Create the email using CiviMail. See the Email section of this book to learn more about configuring and using CiviMail.

Select the appropriate campaign from the drop-down list when setting up the mailing.

A Campaign Event

Events created using CiviEvent can be associated with a campaign. To find out more about configuring and using CiviEvent, see the Events section of this book.

Create and configure the event.

Select the appropriate campaign from the drop-down list when setting up a mailing for the event. 

Send a mass email using CiviMail to your target audience using a group or groups, and ask people to register for the event. 

Again, select the name of the campaign on the mailing set-up. 

Search for individuals who have indicated they want to register for the event.

Record Campaign Contributions

As contributions come in, either online or offline, they can be associated with a campaign; simply select the appropriate campaign from the drop-down menu when recording the contribution.

To find out more about configuring and using CiviContribute, see the Contributions section.

Record Event Participation

During and after an event, organizers can record who participated by either collecting sign-in sheets and entering the participants manually, or recording who participated directly online.

Have participants write their contact information on sign-in sheets when they arrive, or if you have an internet connection at the event venue you may be able to enter participants directly into the database.

To find out more about how to record participant information for an event, see the Events section.

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

As campaigns can be made up of many components there is no specific campaign report. Instead, once CiviCampaign has been enabled you will be able to add a column showing the associated campaign to contribution, pledge, event, mailing and membership reports.  In addition you will be able to "filter by campaign" to restrict the records displayed in these reports.

The activity report can be configured to display both the campaign and the engagement index and can also be filtered on either or both criteria. 

What is Survey?

CiviCampaign has a feature that enables offline surveys by providing a standardised way to record survey responses and to then generate reports from the survey 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.

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 profiles to capture survey participants' responses. Once you've decided on your questions and the types of responses, you need to create custom fields for the questions and responses with option values if you're collecting multiple choice responses. You can then either create a new profile from the main profile screen or create a new profile when you are creating a survey. A profile is used to display 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 result set options profiles that configure surveys to allow you to track the status of responses to the survey. 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

Is the survey part of a campaign? When creating a survey, you don't have to connect it to a specific campaign; a general survey may be used for any programme in your organisation. But if you are using surveys as a particular strategy within a campaign, connecting the survey to the campaign will enable you to analyse the survey along with other strategies and activities related to this campaign. 

Think about the specific questions and types of responses you want to gather. Do you want to standard set of responses to make it easier to analyse results to specific questions, e.g. Yes, No, Undecided, Declined? Or is an open-ended question more appropriate, to allow the individual to provide you with a narrative?

How many questions do you need to ask? If it is more than one, you will need to create custom fields; if it is more than three, consider using Petition instead of Survey.

Who will conduct the survey, and how will the data be entered into CiviCRM?

What group of your constituents do you want to survey?

Set-up

This chapter describes the steps to set up a survey. If you are connecting a survey to a specific campaign, you will want to review the Campaigns section as well.

Creating a survey requires that you use custom data sets to create the questions/responses you want to capture, and then use a profile to organize your questions the way you want them to appear on the survey. 

Tips:

If you plan on conducting many surveys throughout the year (let's say 20 - 30 surveys in a year) with only a few questions per survey (let's say 3-4 questions per survey), then we strongly suggest that you create ONE custom data set that includes all the questions for each of the surveys.  Then you can create individual custom profiles for each survey that pull in the questions that are particular to that survey.

If you plan on conducting just a few surveys per year (let's say about 3-4 surveys per year) with the number of questions no more than 10 per survey, then we suggest that you create different custom data sets for each group of questions per survey.  Then you can use custom profiles to pull in in the questions that are particular to a survey.

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: 

Go to Administer > CiviCampaign > Survey Types. 

Click on Add Survey Type and complete the form.

Creating the survey fields

Once you have determined your survey questions and responses, the next step is to create the custom data fields:

Create a custom data field set by going to Administer > Customize > Custom Data and clicking on Add a Set of Custom Fields. To learn more about how to create custom field sets (including adding fields with multiple answers), see the chapter called Creating Custom Fields in Your Data and CiviCRM.

Create the custom data set(s) so that they are used for Activities. The Activity type must be either/or; Canvas, PhoneBank, Survey, Walklist. 
Hint: If you plan on doing a PhoneBank and want to do the data entry directly into CiviCRM, then you may want to add the phone number in the profile, and set it to view only, so that you can see the phone numbers when you're interviewing the respondents.
Hint: If you are adding a Walklist survey, for each field you might want to add the field label in full but add shorter values. These values are then used in the printed list of Walklist addresses used by the survey collectors. This might make for easier question response recording. So a full question response (the label) might be 'Wrong address' and the value might be 'WA'. See the chapter Survey > Everyday Tasks for more information. 

Add the questions to the field set and any help text that you wish to provide and click Save to create the field set for the responses.

You can now either create a profile to hold your questions, from the main profile screen, or you can create the profile when you add your new survey. 

Create a new survey

Go to Campaigns > New Survey.

Enter a Title for your survey and if the survey is part of a campaign, select the campaign from the dropdown menu.

Choose the type of Activity (e.g. Canvas, PhoneBank,Survey or Walklist)

Instructions for Interviews: enter any appropriate information about the survey that would be helpful for the volunteers conducting the survey.

Maximum Reserved at one time: enter the maximum number of contacts that can be reserved at any one time to be interviewed.  This allows you to divide up the group of individuals for each volunteer to interview at one time.

Total reserved per interview: enter the total number of contacts that can be reserved by any interviewer.

Release frequency: enter the number of days that reserved respondents are released if they have not been surveyed within that time.

Click Save, or Save and Next to add questions to your survey

When adding questions you can add two profiles. One to collect information on the contact and one for the survey questions. In both cases you can either select an existing profile, edit/copy an existing profile or create a new profile*.

Survey Results are used to record and track the status of each completed survey (e.g. Completed, No Answer, Call . If you have created an earlier survey with a survey Result Set you want to use again, select the appropriate Result Set. Otherwise, click Create a new result set and enter the status results you want to track for responses to the survey, for example: 'Completed, Not Home, Moved, Wrong Address, Deceased'. 
Hint: The Drupal CiviEngage module creates Survey Default Result Set Options to help you track the status of the responses to the survey if appropriate (e.g. Completed, Moved, Wrong Number, Wrong Address, etc.). See the Setup chapter in the Civic Engagement section of this book. 

When you create a new profile within a survey you will be taken to a drag and drop profile builder screen. Here you can select any individual or activity standard or custom field and add them to your profile. Fields can be renamed, the order and other field settings can be changed and you can also name the profile.

Everyday Tasks

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:

Go to Campaigns > Reserve Respondents.

From the Survey dropdown menu select the name of the survey (required).

From the Group(s) dropdown menu select the name of the group of the contacts to be interviewed.

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 > Administration Console> Configuration Checklist > Address Settings, then in the Address Editing area, check the box for Street Address Parsing.)

Click Search.

On the Find Respondents to Reserve search results screen, select the contacts to be reserved for interviewing:

Select the individuals to be reserved for surveys 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).

Click Go to reserve the respondents.

On the Reserve Respondents screen, click Reserve. 

Interview Respondents

To interview respondents Click Campaign > Interview Respondents.

On the Find Respondents to Interview screen use the same criteria as for Reserve Respondents:

Survey: (required) select the name of the survey

Group(s): select the name of the group of the contacts to be interviewed

click Search.

On the search results screen, either select the individuals to record responses, or select All n records (where n is the number of contacts found in the reserve respondents search).

Click Go to record survey responses.

On the Record Survey Responses screen for each individual, record the responses to the questions.

In the Result column, select the status of responses to the survey. Like 'Completed, No Answer'.

Click Record Response, then choose one of the following:

Click Done if you have finished recording the responses and return to the Find Respondents to Interview screen.      

Click Release Respondents if you decide not to record responses for the contacts; then on the Release Respondents screen, click Release Respondents so they will no longer be reserved and another volunteer can reserve the contacts to be interviewed.

Click Reserve More Respondents to find more contacts to be interviewed.

Reviewing Results of the Survey

At the end of the canvass, a program lead may want to review the results of the survey. Refer to the chapter Reports and Analysis to learn how to view this report.

How to create a list of addresses for Surveys of type Walklist

Surveys allow you to easily print walk lists for your volunteers or staff who are doing door-knocking activities and want to conduct a survey at the door.

Door-knocking canvass activities may be one strategic activity that's part of a larger campaign, so you may want to set up a Campaign if you haven't done so already.

Create your WalkList report

Go to Reports > Create Templates from Reports > Survey Report (Detail).

In the Display Columns area, check the boxes for: Street Number, Street Name, Street Unit, Survey Responses.

In the Group By Columns area, check the boxes for: Street Name, Odd/Even Street Number.

In the Set Filters area, select your survey name in Survey, and for Respondent Status select Is Equal to and Reserved from the dropdown menus.

Click Preview Report, then Print Preview.   

Print your report. You will see that the print out includes a cover sheet with the survey questions (both label and value) and  and that the report is sorted by street name and odd and even street numbers. See the chapter Survey > SetUp for more information.

Conduct your door-knock canvass

Your organisers and volunteers are now ready to door-knock and collect responses on their WalkList report sheets.

Recording responses from the canvass

At the end of each day or evening of canvassing, each organiser or volunteer can record the responses directly into CiviCRM.

Go to Campaigns > Interview Respondents. 

Enter the name of your survey and the name of the target group you surveyed during the canvass; you may also enter the street name if you want to work with a smaller group of contacts to record responses.

On the Find Respondents to Interview screen, select the contacts for whom you want to record responses.

Click Go.

Enter the responses and results according to your WalkList sheet responses, then click Record Response.

REPORTS AND ANALYSIS

You can use the Survey Report (Detail) to analyse the results of your surveys

Review Survey Results in a Report

Go to Reports > Create Reports from Templates > Survey Report (Detail) or click on a survey name on the survey dashboard.

In the Display Columns area under Report Criteria, check the boxes for Survey Responses and anything else you want to view in the report, such as Street Number and Street Name.

In the Group by Columns, select the fields you want to group your information by, such as Street Name.

In Set Filters area, by Survey select the name of your survey, and in Respondent Status select Interviewed.

There will be another drop-down area that will be named after your custom data set of questions. You can select responses to questions to limit your report, for example to show all the "yes" responses to one of your questions.

Click Preview Report.

In the Survey Report (Detail) - Template screen, you can view the results. You can also export the report information to a CSV file if you want more detailed reporting.

If you would like to see a formatted report with the cover sheet of questions and responses and the street names in ascending order (as you indicated in the survey responses area criteria) then click Print Preview.

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

Before you can use the GOTV (Voter Tracking) feature, you will need to have created a survey, create the group of contacts you plan on interviewing, and reserve respondents (reserve the contacts you want to interview) for that survey.  To learn more about surveys and reserving respondents, refer to the section Surveys in this book.

To use the GOTV (Voter Tracking) feature:

Click Campaigns > GOTV (Voter Tracking).

On the GOTV (Voter Tracking) search screen:

Survey (required): select the name of the survey you are using to survey your contacts

Group(s): select the group of contacts whom you want to track who has voted

click Search.

On the GOTV (Voter Tracking) screen:

Check box under the column Voted? next to the individual you know has voted at the polls

You can float your cursor over the "individual contact" icon next to a person's name to find out more information about that individual

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. Petition is also best used as an online survey when you don't know who will be responding, e.g. you may put your petition on your website, so anyone can submit 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.

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 are essentially online surveys.

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 verify the submission and count signatures, especially since you won't want to count multiple submissions from a single person. 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. 

Drupal Permissions 

If you are using Drupal, you need to set permissions to allow specific roles to Sign CiviCRM Petitions. Refer to the next chapter called Set-up in this section, to find out what permissions you'll need to allow. To learn more about setting Drupal permissions, go to the Drupal documentation at http://drupal.org.

Key Questions

Think about the online strategies you will use and consider these questions before creating your petition:

Do you plan to send the petition via email? 

Will you link to the petition on your website for people to sign? 

Will you use other social media or offline strategies to drive people to your website to sign the petition? 

How will you frame your message so that people will want to sign your petition?  

What do you plan to do with the results from the petition? 

What follow-up activities are you planning to continue communicating and building a relationship with petition signers? 

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.

Go to Drupal Adminstration page and go to the Permissions page (if you don't see the Drupal Administration menu, then you do not have appropriate permissions to do this). 

Under Civicrm module area check the permission boxes: Sign CiviCRM Petition, Profile Create, and Access all Custom Data, for the roles you require. For example, if this is to be a public petition, you must check these boxes for anonymous users and authenticated users.

To learn more about setting Drupal permissions, go to the Drupal documentation at http://drupal.org.

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.

Go to Administer  >  Customize Data and Screens > Profiles and add a profile with fields 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.

Go to Administer > Customize Data and Screens > Custom Fields and add a set of custom fields to capture responses to the petition questions. From the Used For drop down menu select Activities. For the Activity Type select Petition Signature.

Under Administer > Customize Data and Screens > Profiles add a profile for the petition responses. Select Activity from the Field Name drop down menu, then select from the custom fields you created.

For both profiles, you may want to select the following settings in the Advanced Setting area:

For Drupal user account registration option?, select the radio button for No account create option if you do not want all petition signers to have a Drupal account created.

For What to do upon duplicate match, you can select the radio button for Allow Duplicate Contact to be Created if you don't want  anonymous users to update an existing contact record's information; you will then need to periodically dedupe records.

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.

Go to Campaigns > New Petition, then enter the following information about your petition: 

Petition Title (required): enter the name of your petition.

Introduction: enter text describing what your petition is about. Potential signers will read this, so create a good message to encourage individuals to sign the petition.

Campaign: if your petition is one strategy or activity of a campaign, then select the name of the campaign.

Contact Profile (required): select the name of the profile that will collect the contact information of petition signers.

Activity Profile: select the name of the activity profile that will collect petition responses.

Is Active?: check this box to make your petition active.

Is Default?: check this box to make your petition default.

Click Save to save the petition information.

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.

Go to Campaigns > Dashboard > Petitions.

Click More > Sign next to the name of your petition.

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:

Click Campaign > Dashboard > Petitions.

Click More > Signatures next to the name of your petition.

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.

Go to Reports > Create Reports from Templates > Activity Report.

In the Display Column area, select any fields you would like to view on the report, such as Target Contact Email.

Expand the Petition Questions area and select the criteria you want to see, such as specific responses to a petition question.

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. 

REPORTS AND ANALYSIS

There are a couple of simple tools to report and analyse petitions.

View signatories

To view who has signed the petition:

Click Campaign > Dashboard > Petitions.

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.

Go to Reports > Create Reports from Templates > Activity Report.

In Display Column area, select any fields you would like to view on the report, such as Target Contact Email.

Expand the Petition Questions area and select the criteria you want to see, such as specific responses to a petition question.

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 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! or WordPress, 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:

a package of custom fields, reports and features to track the history of engagement, involvement, and activities of constituents over time. This package integrates with Campaigns and Surveys to provide walk lists and phone bank lists. 

a model of how to conceptualise and best organise information about individual constituents, organisations and methods of tracking their history of interaction.

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 You Need To Know

CiviEngage is designed to manage interactions with constituents that happen as part of an organisation's civic engagement and base-building work, such as canvassing and phone banking. 

This chapter describes the concepts you need to understand to use CiviEngage effectively. Following key concepts, you will find key questions that will help you to model your universe of constituents using CiviEngage.  

CiviEngage enhances the use of CiviCampaign, and they are designed to be used together. Read more about CiviCampaign in the Campaign section.  

Key Concepts

Understanding the following concepts will enable you to use CiviEngage effectively. 

CiviEngage and CiviCampaign

CiviEngage and CiviCampaign are tied closely together in that each provides features and custom data that work together to accomplish community organising activities. For example, you can:

create and conduct surveys to capture responses during door-knocking canvasses (using walklists) and phonebanking from your target audience

create and conduct a petition to capture more detailed responses

create reports to analyse the responses from your constituency to help you determine the next strategies in a programme or campaign

record an engagement index in an individual's activity record to gauge their level of interest or potential to be a highly active member or be easily mobilised for direct actions.

To learn more about CiviCampaign, refer to the Campaign section. There are also separate sections for Survey and Petition which should be read in conjunction with this section.

Custom Fields and Profiles

CiviEngage packages custom fields sets that help you to organise information about your constituents for civic engagement and community organising work. In this way, CiviEngage helps you to take advantage of features such as walk lists and phone bank lists for civic engagement work, and surveys to collect responses form your constituents. See the chapter Creating Custom Fields in the section Your Data and CiviCRM for more details about how to use custom fields sets and custom profiles.

Cleaning your Address Data

Cleaning your address data means standardising addresses to conform to the conventions defined by your postal address standards. Standardising how addresses are entered into CiviCRM will allow for more accurate search results when searching by address and is essential to generating accurate walk list reports. CiviCRM will parse addresses based on address standards.

To find out more about how address parsing is handled and used in CiviCRM, refer to the Address Settings subsection of the Installation & Basic Set-up chapter of this book. When adding or editing contacts you will be entering or editing address elements including street number, street name, and street unit according to these standards.

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that you clean up address data before importing.

Disabling versus Deleting CiviEngage 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 custom group, field, or value rather than delete it.  Custom reports and searches rely on these custom fields, so deleting certain custom data could potentially break or at least cause problems for the reports and searches.

Working with Your Universe of Contacts

In preparing for a campaign, you will need to identify the audiences you will be targeting for your canvass or phone bank. CiviCRM uses Smart Groups and regular Groups as the mechanisms to target specific groups of contacts. Here are some examples of how you can use Smart Groups and regular Groups for targeting during your campaign:

use Smart Groups to identify contacts you want to target based on specific criteria, such as voter demographics, issue interests, primary language spoken, etc.

track voter demographics using the custom data group called Voter Info

use Groups set up as mailing lists to identify contacts who want to subscribe to a particular newsletter or issue to send an email blast about your campaign

use these Smart Groups and regular Groups to generate your walk list or phone bank list.

Learn more about working with Smart Groups and regular Groups in the Tags and Groups chapter of this book.

Working with Voter History

CiviEngage enables you to manage voter history and other voter information collected during a voter engagement, voter education or electoral cycle.

Many organisations 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, organisations will often 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, a voter ID, and their registered party can be imported and maintained in CiviCRM. These voter records then become contacts that organisers will continue to engage and target for their base-building efforts.

Custom Contact Subtypes

CiviEngage creates new contact subtypes for Individuals and Organisations:

Individual Contact Subtypes:

Media Contact

Funder Contact

Elected Official

Organisation Contact Subtypes:

Media Outlet

Foundation

These subtypes allow you to track specific contacts such as funders and foundations, media contacts and elected officials, and record tailored information for each one.

Funders and Foundations: 

Track due dates for grant proposals, letters of inquiries and reports by adding an activity to the funder's contact record and choosing from the Proposal, Letter of Inquiry, or Report activity types.

Tailor information about an individual funder, such as their funding areas and issue interests by creating a new contact record with the individual contact subtype Funder Contact and using the Funder Info custom field set.

Tailor information about a foundation (organisation record), such as their program areas for funding creating a new contact record with the organisation contact subtype Foundation and using the Grant Info custom field set. 

Media Contacts and Media Outlets:

Record which media contacts or outlets are interested in your organisation's issues, or have written articles about your work, and for identifying who to contact when you want to publicise the work the organisation is undertaking.

Tailor information about an individual media contact or organisation, such as their media type (e.g. TV, Newspaper, Photographer, etc.), issue interests and area of operation (or beat) using the Media Info custom field set.

Elected Officials:

Record who is an elected official in a specific district, and who to contact on their staff, such as the scheduler, or spokesperson.

Tailor information about an individual elected official, such as their elected position and role, using the Elected Official Info custom field set; staffers and spokespeople for an elected official can also be entered with the Elected Official subtype.

See the next chapter, Set-up, for information about how to tailor subtypes.

Key Questions

The following questions are designed to help you make best use of CiviEngage.

Who are your organisation's constituents and what issues affect them?

Who are other important individuals and organisations related to your work (such as community leaders, donors, elected officials, media contacts and funders)?  

What do you need to know about your constituents to create targeted communications and appeals to mobilise?  

Will you do voter engagement work and use the results to enhance your current contact data? 

Set-up

This chapter describes how to install CiviEngage and gives suggestions on how to use the custom field sets and profiles that it includes.

Installing CiviEngage

To install CiviEngage, which is a Drupal module, you will need Drupal Adminstrator permissions to:

enable the CiviEngage component within the CiviCRM module in Drupal

update the Permissions for the Adminstrator role to access CivCRM_engage module by checking the box for access civiengage settings.

Note that CiviEngage requires the component CiviCampaign to be enabled.

CiviEngage Contact Subtypes

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom field sets associated only with specific subtypes (see below for a description of the custom field sets). The following contact subtypes are created when you install CiviEngage:

Individual subtypes:

Media Contact: will expose the custom field set, Media Info, containing information specific to media contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "beat" (area of operation) and media issue interests.

Elected Official: will expose the custom field set, Elected Official Info, containing information specific to elected officials, such as their elected level (such as City Council or Senate) and the role (such as scheduler or spokesperson).

Funder Contact: will expose the custom field set, Funder Info, containing information specific to funders, such as their  programme areas and issue interests.

    Organisation subtypes:

Media Outlet: will expose the custom field set, Media Outlet Info, containing information about an outlet's type of media, such as TV, Radio, Wire, Newspaper, Magazine, etc.

Foundation: will expose the custom field set, Grant Info, containing fields where you track information specific to grants, such as the average grant amount a foundation will give and funding areas the foundation is interested in.

Modifying the custom field sets

When you install CiviEngage, a number of custom fields are automatically created. These fields are designed to support your community organising 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.

Note that CiviEngage has been developed with the North American context; if your organisation operates outside the USA you may need to customise the language but most of the concepts will be similar and useful to your organisation.

We strongly suggest that you do not delete any custom fields or custom field sets, since other features such as reports and searches may rely on these fields; deleting fields could potentially break these and other CiviEngage features.

To review the custom field sets, go to Administer > Customize > Custom Data in the navigation menu. 

The following list describes each of the custom field sets provided by CiviEngage; the bulleted items are custom fields within those custom field sets. You should add, edit, or disable (we highly suggest that you do not delete) the available options for each custom field to make them better fit your organisation's needs.

To learn more about using custom fields sets, see the chapter Creating Custom Fields in the section Your Data and CiviCRM.

Communications Details

This custom field set can be used to provide more details about when to best contact your constituents, if they have good addresses, email addresses, or phone numbers, and the reason why they don't want to be contacted by email, or phone, or mail.

Best Time to Contact: indicate if the best time to contact your constituent is in the morning, afternoon, or evening.

Communication Status: indicate if you have a bad email, bad address, or bad phone for the contact

Reason for Do Not Mail

Reason for Do Not Phone

Reason for Do Not Email

Voter Info

This custom field set may be used to capture voter demographics about your constituents. You may also want to add specific local voter fields that apply to you.

State Voter ID

Party Registration

If Other Party: use this field only if you don't want to add another option value in the  Party Registration custom field

Precinct

Ward

State District

City District

Congressional District

County Name

Voter History: A (Always votes), O (Occasionally votes), N (New Voter); you can add other values to describe how your constituents votes.

Constituent Info - Individuals

This custom field set may be used to describe additional information your individual contacts, such as how you want to classify your contacts for ease of searching and targeting form communications, which staff person is responsible for outreach to the individual, and how and when the individual was brought into your organisation.

Constituent Type: This is a required field used to categorize the type of contact, such as Volunteer, Activist, Board Member, Donor, Ally, etc.

Other Name: may be used to contain another name used by the contact, for e.g. an individual's name in chinese characters

Staff Responsible: note that the values for this field are also used for Event Contact Person. Replace the sample names in the list with your staff, member or volunteer coordinators, and other folks that have individuals assigned to them.

Date Started: may be used to indicate the date your constituent was brought in to your organisation.

How Started: edit this list to fit the ways in which members are brought into your organisation.

Grassroots Info

This custom field set may be used the to further capture information about how a constituent likes to engage with your organisation, the types of issues and volunteer activities they're interests, their level of leadership, and their status as a member. These fields provide another way to categorise your constituents to better target your audience for outreach and communications.

Member Status: three status choices of Active, Inactive and Deceased are included by default. Think about other member statuses that might work for your organization and add or remove as needed. 

Leadership Level: the default options for tracking an individual's leadership level within your organisation are 1-5. Change this to match however your organisation tracks this information.

Issue Interest: this may be used to capture what issues your contacts are interest in. This custom field shares the same set of options as the Funding Areas (for organisations), Media Issue Interest and Funder Issue Interest fields. It is a list of issues that your organisation works on or tracks.

Volunteer Interests: a list of volunteer activities that your members can take on.

Constituent Info - Organizations

This custom field set may be used to classify the type of organisational contact so that you can target your outreach and communications.

Constituent Type - Org: this custom field is required and may be used to classify the type of organisation contact, such as Member Organisation, Affiliate Organisation, Business, Government.

Grant Info

This custom field set may be used to capture information about grants for a particular foundation.  You can view and edit this custom field if you create an organisation contact with subtype Foundation.

Average Amount: average dollar amount for grants

Funding Areas: this custom field uses the same set of options for Issue Interest and Funder Issue Interest.

Requirements Notes

Proposal Info

This custom field set may be used to capture information about grant proposals. You can add, view and edit information about proposals when you create an activity of type Proposal for either a funder contact (an individual contact with type Funder Contact) or for a foundation contact (an organisation contact with type Foundation).

Ask Amount

Proposal Status

Amount to be Received

Date to be Received

Multiyear Grant

Years

Participant Info

This custom field set, which is available when you create a participants for your events, may be used to capture information about participants to your events, such as if they need childcare or rides to and from the event. Organisers who contact potential participants multiple times before an event can also capture responses from participants to track over time if they were able to get their constituents to participate and how many contacts it takes to encourage them to come to the event.

Childcare Needed

Ride To

Ride Back

Invitation Date

Invitation Response

Second Call Date

Second Call Response

Reminder Date

Reminder Response

Event Details

This custom field set is used to capture additional information about your event.

Event Contact Person: also used for Staff Responsible. Add all appropriate people to this list.

Organizational Details

This custom field set may be used to store information that is specific to organisations.

Rating: if you need to evaluate organisations in some way, change the options to reflect that.

Demographics

This custom field set may be used to capture demographic information about your constituents.

Ethnicity

Secondary Language

Media Outlet Info

This custom set is only applicable to the organization contacts with subtype Media Outlet.

Media Type - Org: this custom field uses the same set of options as Media Type - Ind field - TV, Radio, Wire, Newspaper, Magazine, etc.

Media Info

This custom field set is only applicable to the individual contacts with subtype Media Contact.

Media Type - Ind: this custom field uses the same set of options as Media Type - Org

Beat: this refers to the general category of topics that a media contact covers, such as local government, education, neighborhoods, religion, labor, etc.

Media Issue Interest: uses the same option list as Issue Interest. As you come to know a reporter, you will learn the issues they are particularly interested in, even if it differs from their assigned beat.

Funder Info

This custom field set is only applicable to individual contacts with subtype Funder Contact and may be used to capture information specific to the funder contact.

Funder Program Areas

Funder Issue Interest: this custom field uses the same set of options as Issue Interest and Funding Areas.

Elected Official Info

This custom field set is only applicable to individual contacts with subtype Elected Official.

Elected Level: the governmental body the individual is part of (City Council, state legislature, mayor, etc.)

Elected Staffer Role: whether the contact is the elected official, or the official's staff, spokesperson, etc.

Modifying CiviEngage's custom value options

CiviEngage includes many custom fields with value options. The following are examples of value options that you may want to consider reviewing and modifying to match the kinds of information you need to track for your work.

To learn more about working with value options or multiple choice options, see the chapter called Creating Custom Fields.

Value Options for Issue Interests

The value options for Issue Interests contain issues that your organisation works on or tracks. They are included in CiviEngage as a single option list shared across multiple contexts: 

Grassroots Info: Issue Interests for individuals

Media Info: Media Issue Interests for Media Contacts

Funder Info: Funder Issue Interests for Funder Contacts

Grant Info: Funding Areas for organisations

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 organisation and that you will want to utilise when tracking individuals' interest in your organisation's work, the issues that your media contacts may be interested in covering, a funders' general interests and the specific areas of work included in particular grants.

Value Options for Volunteer Interests

The value options for Volunteer Interests contain activities that your organisation'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 organisation'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.

Survey Default Result Set Options

When creating a new survey, especially when you have a survey with more than one quesiton, CiviEngage defines a default set of Result Options that may be used to indicate if a survey has been completed or why the survey was not completed:

label is Completed with value C

label is Not Home with value NH

label is Moved with value MV

label is Wrong Address with value WA

label is Wrong Number with value WN

label is Deceased with value DE

We strongly suggest that you create labels with names that are descriptive, and for the values use abbreviated names so that when printing out WalkLists or PhoneBank reports using the Survey Report, the code or value is displayed to keep your report neat and easy to look at for recording responses.

Custom profiles

CiviEngage creates several custom profiles for easier batch updating of individual or organisation information, such as voter demographics, issue interests, volunteer interests or event participant information. To learn more about profiles, please refer to the chapter called Profiles in the Core Functionality section.

Setting up Surveys for Walklists and Phonebanking

CiviEngage in combination with CiviCampaign allows you to easily set up your surveys for walklists during door-knocking canvasses and for phonebanking. You will want to think about the questions and responses you want to collect from your target audience in a manner that will be useful in analysing results from your efforts after you've conducted your canvass or phonebank.

There are a few steps to think about when creating your surveys (you can find out more about creating surveys in the Survey section of this book):

create your custom data set of questions and responses you plan to use for your survey if you plan to ask more than 1 question that extends Activities of type Walklist or Phonebank.

create the custom profile that includes the questions you will want to ask your audience. Hint: If you plan on doing a phonebank and want to do the data entry directly into civicrm, then you may want to add the phone number in the profile, and set it to view only, so that you can see the phone numbers when you're interviewing the respondents. The profile will allow you to display (view only or you can edit data) other fields of information when you're ready to interview and enter the data.

create the group or smart group of the individual contacts you plan to survey, which is your target audience.

Make a decision if this survey is part of a larger campaign, and if so create the Campaign and indicate this campaign when creating the survey (you can find out more about create campaigns in the Campaigns section of this book).

When you create your survey, you can then:

 indicate if the survey is for a walklist or phonebank

specify if the survey is part of a campaign

include the custom profile of the questions you plan to ask during the survey, if you plan on asking more than one question

use the Survey Default Result Set Options that's created by CiviEngage to help you track the status of the responses to the survey if appropriate.

Tips:

If you plan on conducting many surveys throughout the year (let's say 20 - 30 surveys in a year) with only a few questions per survey (let's say 3-4 questions per survey), then we strongly suggest that you create ONE custom data set that includes all the questions for each of the survey.  Then you can create individual custom profiles for each survey that pull in the questions that are particular to that survey.

If you plan on conducting just a few surveys per year (let's say about 3-4 surveys per year) with the number of questions no more than 10 per survey, then we suggest that you create different custom data sets for each group of questions per survey.  Then you can use custom profiles to pull in in the questions that are particular to a survey. 

Setting up custom data sets and profiles for use with Walklist or Phonebank Surveys

1. Create your custom data set to hold your questions (to learn more about creating custom data sets and fields, see the Organising Your Data section of this book).

For WalkList surveys:

Create your custom data set for use with Activities of type Walklist 

For PhoneBank surveys:

 Create your custom data set for use with Activities of type PhoneBank 

2. Then for both Walklist or Phonebank surveys you can create the questions as the custom field labels and the responses you want to collect as the option values.

 3. Next, create the custom profile that will pull in the questions for your survey (to learn more about creating profiles, see the Organising Your Data section of this book).

Everyday Tasks

This chapter provides instructions on how to do some of the common tasks using CiviEngage.

Conducting a door-knock canvass

CiviEngage allows you to easily print walk lists for your volunteers or staff who are doing door-knocking activities and want to conduct a survey at the door.

Door-knocking canvass activities may be one strategic activity that's part of a larger campaign, so you may want to set up a Campaign if you haven't done so already. To learn more about working with campaigns and surveys, refer to the sections Campaign and Survey respectively. You will also want to review the previous chapter called Set-Up in this section to learn more about setting the custom data sets and profiles to be used in your Walklist survey. 

Create the campaign and survey for the walk list

Create a new group of contacts that you will be targeting during your door-knock canvass. You may do this by searching for contacts who live in a particular geographic area or district. (To learn about working with groups, see the chapter Tags and Groups.)

To create a new Campaign (if you haven't already) go to Campaigns > New Campaign. Refer to the section Campaign for detailed instructions on how to create a campaign and add the group of contacts you created.

Go to Campaigns > New Survey; give the survey a title and select the appropriate campaign that it is part of.

From the Activity Type dropdown menu select WalkList. 

From the Profile dropdown menu select the custom profile you created for use with this Walklist survey.

For Survey Responses select Use existing result set and select Survey Default Results Set Options.

Click Save.

Reserve the target group you want to survey

Next, you'll need to reserve the target group of contacts you will be surveying during the door-knock canvass: 

Go to Campaigns > Reserve Respondents and select the appropriate survey.

Select your target group in Group(s), then click Search.

On the Find Respondents to Reserve screen, select the contacts you want to survey.

Click Go to Reserve Respondents.

On the Reserve Respondents screen, click Reserve.

Create your WalkList report

Go to Reports > Create Templates from Reports > Survey Report (Detail).

In the Display Columns area, check the boxes for: Street Number, Street Name, Street Unit, Survey Responses.

In the Group By Columns area, check the boxes for: Street Name, Odd/Even Street Number.

In the Set Filters area, select your survey name in Survey, and for Respondent Status select Is Equal to and Reserved from the dropdown menus.

Click Preview Report, then Print Preview.   

Print your report. You will see that the print out includes a cover sheet with the response codes and that the report is sorted by street name and odd and even street numbers.

Conduct your door-knock canvass

Your organisers and volunteers are now ready to door-knock and collect responses on their WalkList report sheets.

Recording responses from the canvass

At the end of each day or evening of canvassing, each organiser or volunteer can record the responses directly into CiviCRM.

Go to Campaigns > Interview Respondents. 

Enter the name of your survey and the name of the target group you surveyed during the canvass; you may also enter the street name if you want to work with a smaller group of contacts to record responses.

On the Find Respondents to Interview screen, select the contacts for whom you want to record responses.

Click Go.

Enter the responses and results according to your WalkList sheet responses, then click Record Response. 

Reviewing Results of the Survey

At the end of the canvass, a program lead may want to review the results of the survey. Refer to the chapter Reports and Analysis to learn how to view this report.

Conducting a PhoneBank

CiviEngage allows you to easily to enter responses from constituents during a PhoneBank directly into CiviCRM.

Phone banking activities may be one strategic activity within a larger campaign, so you will want to set up the Campaign if you haven't done so already. To learn more about working with campaigns and surveys, refer to the sections Campaign and Survey respectively. You will also want to review the previous chapter called Set-Up in this section to learn more about setting the custom data sets and profiles to be used in your PhoneBank survey.

Create the campaign and survey for the PhoneBank

Creating a survey for phonebanking is the same process as creating a survey for walklists.

Create a new group of contacts that you will be targeting during your phone bank. To learn about working with groups, see the chapter Tags and Groups.

Create a new Campaign (if you haven't already) by going to Campaigns > New Campaign. Refer to the section Campaign to find out how to create a campaign and add the group of contacts you created.

Go to Campaigns > Create New Survey and create a new survey of type PhoneBank. 

From the Profile dropdown menu select the custom profile you created for this phonebank survey. 

For Survey Responses select Use existing result set and the set, Survey Default Results Set Options.

Click Save.

Reserve the target group you want to survey

Next, you'll need to reserve the target group of contacts you will be surveying during the phone bank: 

Go to Campaigns > Reserve Respondents.

Select the name of your survey in Survey and your target group in Group(s). 

Click Search.

On the Find Respondents to Reserve screen, select the contacts you want to survey, then click Go to Reserve Respondents.

On the Reserve Respondents screen, click Reserve.

Conduct your phone bank and record responses

During the phone bank, organisers and volunteers can search for the group of contacts they will be calling and enter the responses directly into CiviCRM.

Go to Campaigns > Interview Respondents.

Enter the name of your survey and the name of the target group you surveyed during the phone bank.

On the Find Respondents to Interview screen, select the contacts whose responses you want to record, and click Go.

Enter the responses and results, then click Record Response.

Reviewing Results of the Survey

At the end of the phone bank, a program lead may want to review the results of the survey.  Refer to the chapter Reports and Analysis to learn how to view this report.

Mobilising Individuals to a Direct Action 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 organisation 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 organisation'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 organisers 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 mobilise individuals:

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.

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 Everyday Tasks chapter in the Events section in this book.

Once you have added 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:

Update Event Invite Responses - to record responses from multiple contacts with the participant.

Update Participant Info - to record general information about participants, such as if they need childcare or rides to the event.

Using the Engagement Index

You can record the level of interest or engagement in a specific activity by of an individual contact. This allows you to then review an individual's activities to understand if their interests or engagement has increased over time, or give you the opportunity to have further contacts with the individual to increase their participation in your issues. 

You can record an Engagement Index for the following activities or actions: Phone Call, Meeting or Interview.

From an Individual's contact record, click Actions then select an activity such as Meeting.

Fill out the information about the activity, then enter the Engagement Index. To find out how to create options for the Engagement Index, see the section called Campaign.

Manage Voter Information

CiviEngage enables you to manage voter history and other voter information collected during a voter engagement, voter education or electoral cycle.

If you wish to collect voter contacts with their demographics, history and additional information and add them as contacts, or enhance your contact list with voter information, you can:

Export the contacts you want, including the CiviCRM internal Contact ID, First name, Last name, address information, and any other contact information.

Upload the list into your voter management system and match to the voter records. You can then continue conducting your voter education and engagement activities there.

When the electoral cycle is over, export the contacts you want (new and existing), and import into CiviCRM. With the existing contacts, you'll be able to do an update import to match the contacts back into CiviCRM. 

Use the Voter Info custom field set to capture your voter information related to the contact.

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.

After you have recorded responses from your contacts, Click on Campaigns > Create Reports from Templates > Survey Report (Detail)

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

In Group By Columns area if you'd like to group the responses, check the boxes for: Street Name, Odd/Even Street Number

In Set Filters area, select your survey name in Survey, and select for" Respondent Status" 'Is Equal to" Interview.

Click Preview Report.

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.

After you have recorded responses from your contacts, Click on Campaigns > Create Reports from Templates > Survey Report (Detail)

In Display Columns area, check the boxes for: enter the information you'd like to display such, especially Survey Responses

In Set Filters area, select your survey name in Survey, and select for" Respondent Status" 'Is Equal to" Interview.

Click Preview Report.

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.

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:

What grant types does your organisation offer?

What is your grant application workflow and how can you map it to CiviGrant statuses?

Do you have an application form, and if so, how can you model it using custom data?

What kinds of reports to you want to generate from the grant process?

Set-up

Set up of CiviGrant is reasonably straightforward. The first thing to do is to enable the CiviGrant module in Administer > System 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

The option list for Grant status can be found on the Administer > System Settings > Option Groups screen. Select Options on the right of the Grant status line to view existing options or create new statuses to match your grant giving workflow.

Custom data for grants

You can add custom data to grants:

Go to Administer > Customize Data and Screens > Custom Fields.

Click on Add Set of Custom Fields.

Set Used For to Grant

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 compatible.

See the custom data chapter for more information on setting up custom data.

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:

The Grants dashboard gives a summary of the status of all grants in your CiviCRM, grouped by grant type. It also gives an overview of recent grants.

An individual contact's grants can be viewed from the Grants tab on their record.

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: 

Go to Other > Grants > New Grant.

Either select an already existing contact or create a new contact to add the grant to.

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.

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.

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

The Find Grants search form

The grants tab in advanced search

The Grant report

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.

Choosing your CMS

CiviCRM works with what are arguably the three most popular open source CMS

Drupal

Joomla

Wordpress

Before starting a project you should consider how you plan to use CiviCRM both now and in the future. Two big questions are; How much information from CiviCRM do we want to display on our website (e.g. A live list of our current members)? What information, collected through our website, do we want to store in CiviCRM (e.g. Family data from a public form with the family relationships automatically added). This is known as integration. How much integration you require will help you determine which is the best CMS for you.

You may also choose a CMS because you already know how to use it or it is already used by your organisation.  Each CMS has different advantages and disadvantages and different people will give you views on which is better. This chapter gives a quick introduction to each of them. 

Drupal is the most flexible and has the best integration with CiviCRM. If you have complex CMS needs or envisage a lot of interaction between users on your website and your CRM, then Drupal might be the CMS for you. The main negative is that this flexibility makes it harder for new site builders to get to grips with.

Joomla isn't as popular as WordPress, though it is more popular than Drupal. Joomla is easier to learn than Drupal. The amount of integration available is lower than then when using Drupal. 

WordPress is by a wide margin the most popular of the three CMS's.  It is considered to be very easy to build sites using Wordpress, especially for people that are not familiar with web technology.  A lot of people know WordPress as a blogging platform rather than a CMS, but it is becoming more powerful and flexible with each release. The amount of integration available is lower than when using Drupal. 

The following chapters in this section go into more detail about what is offered for each CMS.

Users and Contacts 

Anonymous site visitors and those with a website login are website Users
Individuals and organisations with a CiviCRM record are Contacts 

When you create a new Drupal site User and CiviCRM is installed a corresponding CiviCRM Contact is also created. Both users and contacts have a separate identification or index number.

Integrating with Drupal

Of all the three CMS that integrate with CiviCRM, Drupal has received the most attention, and offers the most options when it comes to integration.  This is in part due to the fact that the Drupal community is largely a developer community.

Drupal Roles and permissions

See also the permissions and access control chapter in initial set up for a general discussion of access control. 

Your Drupal website allows you to create a series of Roles. Your website administrator give roles to site users and grant each role the permission to perform a certain series of tasks (view, edit, delete, and administer contacts) or access a certain set of information (CiviCRM Contacts, CiviMail, CiviEvents, Drupal Users, specific content types, etc.)

For more information on Drupal Roles, please read the documentation on Drupal Roles at Drupal.org:

User: Access and management settings http://drupal.org/documentation/modules/user

Managing Access Control with Permissions and Drupal Roles  http://drupal.org/node/22275 

Drupal permission settings allow you to decide what tasks a specific Role can perform or what information a certain Role has access to. Drupal permissions determine how much access a certain type of user has to configure modules, view, create, edit, or change types of content, users, or CiviCRM Contact information.

For more information on Drupal Permission settings, please read the documentation on Drupal Permissions at Drupal.org:

User: Access and management settings  http://drupal.org/documentation/modules/user 

Assigning permissions and users to roles http://drupal.org/node/22278 

Adjusting permissions after adding modules  http://drupal.org/node/22279

Permissions reference  http://drupal.org/node/132202

Views module permissions  http://drupal.org/node/1089746

Drupal roles are global and will override relevant access controls (see chapter Initial Setup> Permissions and Access Control) setup in CiviCRM. For example you can setup Access Control in CiviCRM to restrict access to contacts but if the Drupal permission 'Access All Contacts' is set anyone with that role will be able to see all contacts regardless.

Drupal Taxonomies, Content Access, or other Role-based User Access Modules 

There are several Drupal Modules that determine what Drupal Roles have access to which types of content in your Drupal website. This can be based on Drupal taxonomies, by selecting access to specific nodes, settings on a specific views, pages, or panels, or based on certain contexts or rules. A few of the most common modules used for controlling access to content or include options for controlling content based on Drupal Roles are:

Views http://drupal.org/project/views

Panels http://drupal.org/project/panels

Chaos Tools Suite and Page Manager http://drupal.org/project/ctools

Context http://drupal.org/project/context 

Content Access http://drupal.org/project/content_access

Taxonomy Access Control http://drupal.org/project/taxonomy_access

Drupal Views

Views is a powerful Drupal module that allows you to display website content e.g. a list of latest news for the home page.  CiviCRM integrates with Drupal Views and allows CiviCRM data to be shown on your website. For instance, if you wanted to create a page called 'Partner Organizations' and display it publicly you could: 

1. Select criteria for what Contact data will be displayed such as: 
  a. Organization contacts only 
  b. That are tagged 'Partner' in CiviCRM 
  c. That have a membership of status 'New' or 'Current'   
2. Choose which data will be shown such as: 
  a. Organization name 
  b. State/Province 
  c. Website 
  d. Phone number 
3. Choose to show the data in either table or paragraph format   
4. Allow the public to filter the results themselves by State/Province 
This is just a simple example, the possibilities of Drupal Views and CiviCRM are far reaching.

Configuration 

If you have your Drupal and CiviCRM in separate databases adding CiviCRM support to Views takes a small bit of configuration.  Views must be told where to look for CiviCRM data.  Administer > System Settings > CMS Database Integration shows some code that must be copied and pasted into the Drupal settings.php file after (but not replacing) the existing database connection code.   If you have trouble consider asking for help in the forums or hiring a consultant. If you are using Custom Data sets in CiviCRM, anytime you add a new data set (not just a field) you must repeat this process.

Creating Views Using CiviCRM Data

Views are located in the Structure section of the Drupal administrative menu.  When you create a View, give it a name and select what kind of data you wish to show. 

Generally speaking if your view is focused on Contacts (which most are) you will select  Show: CiviCRM Contacts.  If you wish to display details about other CiviCRM data such as events, relationships, contributions or activities there are additional options that might provide more data fields for those types. 

After the View is created, edit the fields, filters, display and other configurations to show the data exactly how you'd prefer.  Views does take some experimentation and/or training to get it right.  Feel free to ask questions on the forums or hire a consultant if you become stuck.

This is a sample configuration using Views 3 in a Drupal 7 environment.  Your View will probably be slightly different, but this gives you some examples to get started with.

Other Things Views and CiviCRM Can Do

Lists of upcoming events

Building reports on contributions, activities or event registrants

Honor roll listing of recent donors

Staff, board of directors or committee lists

A list of current members

...and more! 

Drupal modules

When thinking about website integration with Drupal, it is important to understand the concept of Drupal modules.  It might help you to think of a module as an application which provides a certain bit of functionality.  For example the calendar module allows you to display calendars on your website.   

The Drupal distribution of CiviCRM comes with a number of Drupal modules which give you the ability to integrate CiviCRM with Drupal in various different ways. This chapter outlines CiviCRM's Webform integration module and then looks at the Drupal integration modules that come with CiviCRM.

Webform CiviCRM Integration

Just as Views can output data in virtually any way imaginable, this module allows you to have data input exactly the way you want. The webform CiviCRM integration is extensive and offers many different options for things that can happen as part of the form submission.

You can create and update contacts, group subscriptions, tags, relationships, cases, custom data,  activities, memberships, event participants and take payments online via webforms. They can offer greater flexibility when compared to standard CiviCRM Profiles.

For example, you can create a form which adds a family with all relationships / you can add a new member form with a multi-page form which includes question logic / you can create a new activity when someone submits the form. Webform CiviCRM has extensive online documentation which you should read to make the most out of its functionality.

For more information see:
http://wiki.civicrm.org/confluence/display/CRMDOC/Webform+CiviCRM+Integration

CiviCRM Organic Groups Sync

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:

A normal group containing a contact record for each corresponding user who is part of an Organic Group. This group is assigned the same name as the linked Organic Group.

An access control group containing the contact record of the administrator of the corresponding Organic Group. This gives the OG group admin the ability to view and edit members of their group in CiviCRM.

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. 

CiviGroup Roles Sync

The CiviGroup Roles Sync module allows administrators of Drupal Websites to streamline the user experience for donors and staff. The CiviGroup Roles Sync module allows you to:

Allow board members, committees, staff, and volunteers to access specific content or perform specific tasks.

Provide customized experiences for users of specific groups when they access your website. For example, when a major donor logs into the website display a letter from the President thanking the donor for his contribution and participation, or provide a major donors with pre-registration access to upcoming events and exclusive news or resources.

You should spend some time assessing the different ways that different sorts of users interact with your website, being sure to ask yourself whether or not the user experience is dependent on specific organized groups, teams, committees, or task forces or on whether or not a contact meets a specific set of criteria, or if you should apply roles to users manually.

In essence, it allows you to synchronize Drupal users that have a certain role with CiviCRM contacts in a certain group.

Preparation 

Before using CiviGroup Roles Sync module you should have the following prepared:

your organization's Groups should be created.

the roles you will need for each use case should be created in Drupal.

if you are using additional modules to fine-tune access, you should have all modules you need installed and configured

When determining what Groups and what Drupal Roles you should create it is important to remember that multiple Group Types may grant the same Drupal Role and each Group can be used to grant multiple Drupal roles.

You should enable the module from the Drupal module administration screen.

Syncing CiviCRM Groups to Drupal Roles

Navigate to the CiviGroup Role Sync configuration screen.

Click on Add Association Rule.

Under CiviCRM Group select the Group that you want a user to have in order to be granted a specific Drupal Role.

Under Drupal Role select the Drupal Role that should be granted.

Click on Add Association Rule when you are finished configuring your new association rule.

You can always edit or delete existing association rules from the same configuration screen.

CiviMember Roles Sync

The CiviMember Roles Sync module allows administrators of Drupal Websites to streamline the user experience for organization members. The CiviMember Roles Sync module allows you to.

Automatically grant a Drupal Role to a user based on the type of membership he/she has with your organization and whether or not he/she is currently in good standing.

Allow a user to access member-only content or perform specific member-only tasks.

Restrict a non-member or expired member user from accessing member-only content or performing member-only tasks until he/she registers or renews membership with your organization.

Scenario: Member-only Content

The Retail Baker's Association of America (RBA) connects bakery suppliers and owners across the country to foster a community that encourages exchange of business and industry information, networking, mentoring, and business opportunities, and establish industry standards through certification, research, and school programs.

Visitors to their website fall into three different user experiences:

Non-Members who purchase resources and materials from RBA's online boutique. A non-Member must register for a user account to make a transaction so that he or she can keep track of purchase history, so that RBA can petition him or her for membership in the future.

Current members in good standing who have access to member-only resources including discussion boards, programs, marketing materials, and digital version of RBA publications.

Members with expired memberships or former members who need to renew need to log into the RBA website to renew their membership, but should not have access to member-only resources until their membership has been reactivated.

In order to save their staff from having to grant the Drupal Role "Active Member" to a user each time he or she renews his or her membership and then remove the "Active Member" role if that user cancels his or her membership or allows his or her membership to expire, RBA uses CiviMember Role Sync to grant the "Active Member" role to any user who is either a new or current member and any user who's membership has fallen into the grace period. Now when a user registers or renews his or her membership he or she will automatically be granted access to RBA's Member-Only web content.

What You Need to Know

This section covers what you need to think about before beginning to work with CiviMember Role Sync.

You should spend some time assessing the different ways that different sorts of users interact with your website, being sure to ask yourself whether or not the use case is dependent on your membership structure or dependent on the organization of committees, teams, and contacts meeting a specific set of criteria, or if your workflow simply does not warrant the use of CiviMember Role Sync at all.

CiviCRM Membership Types

You should have a full understanding of CiviCRM Membership Types and CiviCRM Membership Statuses before you begin working with the CiviMember Role Sync module. You can learn more about the CiviMember component by reviewing the MEMBERSHIP chapter. 

Configuring CiviMember Roles Sync

Before using CiviMember Roles Sync module you should have the following prepared:

your organization's Membership Types and Membership Statuses should be created and configured in the CiviMember component.

the roles you will need for each use case should be created in Drupal.

what content each Membership Type should grant permissions to should be agreed upon by your staff

what tasks each Membership Type should grant permission to should be agreed upon by your staff

if you are using additional modules to fine-tune access, you should have all modules you need installed and configured

When determining what Membership Types and what Drupal Roles you should create it is important to remember that multiple Membership Types may grant the same Drupal Role and each Membership Type can be used to grant multiple Drupal roles.

For example: The Retail Bakers Association of America has five different membership types: Corporate Sponsor, Bakery, Individual, Student, and Retired Bakery. Having any one of the five Membership Types will grant a user the "Active Member" Drupal Role that gives access to the member-only content. In addition to this, users with the Corporate Sponsor Membership Type should have access to additional exclusive content. RBA decides calls the Drupal role used to access this additional exclusive content "Corporate Member" and user with the Corporate Sponsor Membership Type will be granted the "Corporate Member" role in addition to the "Active Member" role.

Enabling CiviMember Roles Sync Module

To enable the CiviMember Roles Sync Module navigate to your list of installed Drupal modules.

Drupal 6: Go to Administer > Site Building > Modules

Drupal 7: Go to Modules from the Administration Menu at the top of your screen.

Find the Module CiviMember Roles Sync and check the box to the left of the module's name.

Click on Save Configuration.

Syncing CiviCRM Membership Types to Drupal Roles 

 Navigate to the CiviMember Role Sync configuration screen.

Drupal 6: Go to Administer > Site Configuration > CiviMember Roles Sync

Drupal 7: Go to Configuration > CiviMember Roles Sync

Click on Add Association Rule.

Under Select a CiviMember Membership Type select the Membership Type that you want a user to have in order to be granted a specific Drupal Role.

Under Select a Drupal Role select the Drupal Role that should be granted.

Example: RBA wants any user with a Current Bakery Membership Type to be granted the "Active Member" role, so the RBA staff creates a new Association Rule and selects Bakery under Select a CiviMember Membership Type and selects "Active Member" under Select a Drupal Role.

 Under Current Status select the Membership Status that a user should have to be granted your selected Drupal Role.

Example: RBA wants to grant any user who has a Membership Status of either New, Current, or Grace access to the member-only website content, so the RBA staff checks the boxes next to those three Membership Statuses. 

Under Expired Status select the Membership Status that will revoke the Drupal Role from the user.

Example: RBA wants to make sure that any user who's membership expires or cancels their membership has their access to the member-only website content revoked, so the RBA staff checks the boxes next to Expired and Canceled.

Click on Add Association Rule when you are finished configuring your new association rule.

The page will reload, and you should see the message "Your Association Rule has been added."

Repeat steps 1-8 to add all necessary association rules for your organization. Once you have finished adding all of your association rules, move on to step 10.

Click on the tab Manually Synchronize

Click on Synchronize CiviMember Membership Types to Drupal Roles Now. This will put your new CiviMember Role Sync Association Role immediately into effect.

Editing Existing Association Rules

You can always edit or delete existing association rules.

To edit or delete an existing Association Rule, Navigate to the CiviMember Role Sync configuration screen.

Drupal 6: Go to Administer > Site Configuration > CiviMember Roles Sync

Drupal 7: Go to Configuration > CiviMember Roles Sync

 You should now see a list of all existing CiviMember Role Sync Association Rules. If not, click on List Association Rule(s) tab.

Edit an Existing Association Rule

Find the Association Rule you want to make changes to and click on edit for that Association Rule.

Make the changes to your Association Rule and when yo are finished click on Edit association rule.

Delete an Association Rule

Find the Association Rule you want to remove and click on delete for that Association Rule.

Your association rule will be deleted. You will not need to confirm deletion.

Configure when Synchronization Should Happen

 You can select several different options for when synchronization should occur by navigating to the CiviMember Role Sync Configure screen.

Drupal 6: Go to Administer > Site Configuration > CiviMember Roles Sync > Configure

Drupal 7: Go to Configuration > CiviMember Roles Sync > Configure

Automatic Synchronization Methods:

Synchronize whenever someone logs in or logs out: This method will trigger synchronization only after a user logs in or out of his or her account. You should be careful when using this method because if you have long user sessions a user could continue to have access to actions or content until he or she finally logs out. (This is the default setting)

 Synchronize when a Drupal Cron occurs: This method relies on a cron to trigger synchronization. Learn more about Drupal Cron at: http://drupal.org/cron

Synchronize when membership is updated: This method will synchronize when the user registers for or renews his or her membership and when the organization staff updates a user's membership information from the back office.

Disable Automatic Synchronization: This method relies on an organization staff member to manually trigger synchronization. To manually trigger synchronization, go to CiviMember Roles Sync settings, click on the Manually Synchronize tab, and click on Synchronize CiviMember Membership Types to Drupal Roles Now.

Be sure to click Save Configuration after making any changes.

Integrating with WordPress

CiviCRM integrates with WordPress as a plugin starting with Wordpress version 3.3.1 (those using earlier versions of WordPress will need to upgrade prior to installing CiviCRM).

CiviCRM public forms such as online contribution pages and event registration pages will be shown to the public in your selected WordPress theme.  When logged in to your Control Panel, CiviCRCM will be shown as a link in the left sidebar menu.

Synchronize WordPress Users to CivCRM Contacts

CiviCRM offers a function to Synchronize Users to Contacts: CiviCRM will check each user record for a contact record. A new contact record will be created for each user where one does not already exist. To perform this function go to Administer -> Users and Permissions -> Synchronize Users to Contacts  

Using Shortcodes to Publish CiviCRM Content in Wordpress

Wordpress shortcodes enable a user to be able to very easily display dynamic content within a Wordpress Page or Post with the use of just one line of text. For more information about Wordpress shortcodes check here:
http://en.support.wordpress.com/category/shortcodes/
After installing CiviCRM within your Wordpress environment, you can immediately take advantage of CiviCRM specific shortcodes that enable you to display content that relates to:

Contribution Pages

Event Pages

Profiles

User Dashboards

Petitions 

Keep in mind that prior to being able to display any CiviCRM content on you public website that record will have already been created within CiviCRM. 

To add a shortcode either create a new post or new page and you will now see a CiviCRM button next to Add Media. 

After you click on CiviCRM you will be displayed with the following options:

Dependent up the shortcode that you select you will have different sub options to cater the information to the end user.

When selecting a front end element of Contribution Page you will have the ability to select the specific Contribution Page that you want to be displayed then you will have the ability to chose between Live or Test mode.

When selecting Event Pages you can either chose from the following two options:

Information Page: By choosing this option your Wordpress page will be populated with the Summary Information about the event. This will include the description as well as the map of the location if you have specified to do so within your event settings. In addition there is a button provided on the Information page that will enable an end user to register for the event 

Registration page: This option bypasses the Summary Information and displays the page for an end user to register for a specific event.

Profile Pages give you 3 options to chose from: Create, View, and Edit.

Create: A blank form on your website that an end user can fill out and save which will then write to your CiviCRM database.

View: If an end user is logged into Wordpress, you can display what information you have on record for them within CiviCRM for this specific profile. For instance if you displayed the New Individual profile which consists of First Name, Last Name, and Email address the end user would be able to view this information. 

Edit: Similar to view mode, if an end user is logged in, you can display what information you have on record for them but also give them the ability to edit that information. For instance if an individual has recently changed their last name or email address and you are presenting the New Individual profile, they would have the ability to review the information and update it and save that information to CiviCRM all through the website.  

When selecting the User Dashboard you get no additional options. To identify what related information you have setup to be displayed within the user dashboard i.e. Contributions, memberships, etc. navigate to Administer > Customize Data and Screens > Display Preferences and select all of the information you would like to have visible to the user.

Finally, for Petitions, the only option presented is to select the specific petition that you wish to display on your website.  

Integrating with Joomla

CiviCRM integrates with Joomla! as a component.  CiviCRM public forms such as online contribution pages and event registration pages can be exposed as menu items on the front-end of Joomla! sites, using your selected theme.  When logged in to your Administration site, CiviCRM will be shown as a menu item under Components.

Creating Joomla! Menu Items for CiviCRM Content

CiviCRM content can be displayed on your website in a couple of different ways. The primary was is to create a specific Menu Item that pulls in CiviCRM data. Within your Joomla! menu navigate to Menu -> <YourMenu> -> Add New Menu Item.

Once you are inside of the Edit Menu item screen you will then have the option to select the menu item type. There will be a subsection called civicrm with the below options.

After choosing one of the below you will then need to go to Basic Options and select the corresponding CiviCRM page you wish to display.

Contribution Page: A specific contribution or membership page that you would like to publish on your website

Create Personal Campaign Pages: This type enables you to provide a direct link for an end users to create a personal campaign page that is tied to a specific contribution page for peer to peer fundraising. For instance, if you had an annual fundraiser called Support CiviCRM and you wanted to enable your constituents to raise money on your behalf you could create a Menu Item linking them directly

View Personal Campaign Page: 

Custom Search: Customer Searches can be created

CiviCRM Dashboard: Selecting this option enables you to show an end user all of their related information i.e. previous contributions they have made, active and expired memberships, event registrations, etc. When selecting the CiviCRM Dashboard though you will want to ensure that the Access level for this menu item is set to Registered because CiviCRM need to know who exactly to display information about. Thus by setting it to registered it will force the end user to log in to be able to see their specific information. 

Event Calendar: This option takes all of your current events and places them into a calendar view for your end user.

Event Information Page: This menu item type provides the summary information for the event that you have selected and then provides a link to directly register. 

Event Listing: This type displays all of the upcoming events in a list format. You have the ability to sort by each of the columns however there is no search capability by default on the Event Listing

Event Registration Form: 

Participant Listing: Dependent upon if you enabled a participant listing for your specific event you can display who will be attending your event by selecting this option.

Mailing List Subscription: If you have configured groups as mailing lists and have set the visibility to public you can enable your end users to sign up for these mailing lists on their own by selecting this menu item type. 

Profile Create Form: You can collect information on your constiuents 

Profile Edit Form: If an end user is logged into your site and you are presenting a Profile Edit Form they will have the ability to view the information that your organization has on record for them. In addition to that they will be able to edit that information and save it to CiviCRM. For instance if you are presenting the New Individual profile on your website as a Profile Edit Form, that end user who is logged in will then have the ability to view and update their first name, last name and email and save it to your CiviCRM instance.

Profile Search Form: If you have configured a profile as a standalone form or directory you have the ability to give an end user the ability to search your database via this specific profile. For instance, if you are a membership organization and you want to provide a directory of those members to the public, you could create a group called Members and then create a profile that limits the results of the search to only those individuals or organizations in that group. 

Profile View Form: This menu item type allows you to display information that you have on record for a logged in user. For instance

Access Levels with CiviCRM Menu Item Types 

An important thing to consider is that some of the Menu item types above require an end user to be logged into you site so that CiviCRM can know which contact record's information should be presented. For example, if John Smith comes to your website and is browsing without being logged in and you have a Profile View Form specified to have the access level of Public, CiviCRM will be completely unaware that John Smith is on your site and thus not have the ability to display John Smith's personal information back to him. In this scenario CiviCRM would present the following error:Every Joomla! user that is created has a corresponding contact within CiviCRM. So when someone logs in with their Joomla! credentials, CiviCRM can guarantee which contact's information to display. The following CiviCRM Menu Item types require an end user to be logged in to Joomla! and thus when creating these specific types they should have a minimum Access level set to Registered.

Profile Edit Form

Profile View Form

CiviCRM Dashboard 

The availability of additional modules to extend and modify CiviCRM behavior is fairly limited. However Joomla integrators have full access to the CiviCRM API's and hook system, and there are a number of 3rd party tools designed to solve specific problems and make customizations easier.

For more information, developers can refer to the 3rd party module listing on the wiki:
http://wiki.civicrm.org/confluence/display/CRMDOC/Joomla!+Extensions+for+CiviCRM+%283rd+party%29

… as well as the online Developer Guide:
http://wiki.civicrm.org/confluence/display/CRMDOC/Develop

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:

Asking general questions

Getting technical support for installing, upgrading, configuring, using, and customizing CiviCRM

Discussing and providing feedback on documentation

Feature requests and suggestions

Projects in internationalisation and localisation

Showcasing success stories and case studies

Conversations around modifying and extending CiviCRM

Coordination of testing

Obtaining or providing professional services

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 http://irc.civicrm.org/  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://forum.civicrm.org/index.php/board,73.0.html. Contact the CiviCRM crew if you'd like a discussion board for your own group on the site.

CiviCRM held the first CiviCon conference in April 2010 in San Francisco. These have now settled into a pattern of two CiviCons per year - one in the USA in April/May and one in London in September/October. Stay tuned to CiviCRM.org for announcements of future CiviCons.

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.

Contribute to CiviCRM documentation. This book was written by community members; you can contribute to it by going to http://booki.flossmanuals.net/civicrm/_edit/, registering, and clicking "Edit this page" on the page you want to edit. You can also find and contribute to the CiviCRM documentation wiki at http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation.

Share use cases and case studies that describe how your organization uses CiviCRM and the solutions and processes you've developed around the software. You can post your case studies to the CiviCRM.org website by clicking Add Case Study from the Case Studies page: http://civicrm.org/what/casestudies

You can also share your successes, experiences at Civi-related events, interesting customizations, etc. on the CiviCRM.org blog: http://civicrm.org/blog

Share your training resources and materials with the rest of the community through the wiki, the forums, or blog posts on the CiviCRM blog or your own sites.

Contribute code you've written to extend CiviCRM, because it's likely that someone else out there needs the same functionality. Check out the recommended steps for developing and contributing to the CiviCRM core codebase at http://wiki.civicrm.org/confluence/x/kADNAQ.  If you've developed a Drupal module, you should contribute it to Drupal.org; see http://drupal.org/node/7765 for more information on contributing modules. Joomla! extensions can be posted on http://forge.joomla.org/. Finally, you can post your code on the CiviCRM Forums or wiki as attachments.

Sponsor development of new features. If your organization needs certain features or functionality that doesn't yet exist for CiviCRM and can't develop those features in-house, you can sponsor their development by outside coders and developers. This can be a solo effort on the part of one organization or a coordinated effort sponsored by multiple organizations in need of the same set of functionality. Refer to the wiki at http://wiki.civicrm.org/confluence/display/CRM/Developing+with+the+CiviCRM+team  or write to info@civicrm.org  for more information on sponsoring development.

Report any bugs that you find in CiviCRM. See the Bug Reporting chapter of this book for more information.

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.

Misunderstanding the software - we don't claim our documentation is perfect. But please go back and check it very carefully when you hit a barrier. Frustration makes it hard to concentrate, so be sure to read slowly and thoroughly. Also remember that different parts of CiviCRM depend on each other, so check for problems in related modules, besides the one you think the problem is in.

Your server set up - servers can be configured in many different ways, and these settings can change the way CiviCRM operates. Depending on your issue your server configuration may be causing you issues. 

Using older or unsupported versions of CiviCRM, PHP, and MySQL - older and unsupported versions of software related to CiviCRM will most like cause unpredictable errors, so it is always a good practice to use the latest stable version of software.

Customisations made to the source code of your installation of CiviCRM - any changes made to the source code of CiviCRM may have unintended consequences. The community forums may be able to help you, but you will have to be patient, share source code, and try out suggestions. You may also want to check with your in-house development staff or outside consultant / service provider to determine whether CiviCRM has been customized in some way that might be related to the observed problem.

Other newly installed and enabled modules or components - you may need to review the additional modules and components you have installed and enabled that are not usually included in the install package to ensure that you have the latest stable version as well as using a version of the module that works with your particular version of CiviCRM.

Bugs in the version of CiviCRM you are using - after you have eliminated all the previous options, you can report your problem as a bug. In fact, we appreciate you doing this, because you are making CiviCRM better for everyone.

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:

What you did

What you expected to happen

What actually happened

Version of CiviCRM (must be included)

Which CMS platform and CMS version (must be included)

Which browser and browser version (must be included)

Version of PHP and MySQL

Screen shots of the errors or issue

History of the bug

The recreatibility of the bug (e.g. bug always happens, bug is reported by some but can't recreate it or not consistently, bug happens when using this browser but not another browser, etc.)

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.

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.

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.

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.

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.

A tips and tricks wiki page (http://wiki.civicrm.org/confluence/display/CRMDOC/Localisation+community+building+howto) explains how to set up your localization community.

A FAQ (http://wiki.civicrm.org/confluence/display/CRMDOC/Internationalisation+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):

Go to transifex.net and create an account.

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.

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/pages/viewpage.action?pageId=88408149  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:

Select a component on http://www.transifex.net/projects/p/civicrm/. This will display the list of language teams for this component.

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.

Click on the "pencil and paper" icon. This brings you to the online translation screen, which lists all the translatable strings in this file.

For each string, you can then enter a translation.

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:

Download the files from transifex.net you want to translate,

Load the files up in your translation tool and do your translations.

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:

Choose a good location, where people will be able to get online (enough computers for everybody, or desks to set up laptops and with a decent Internet connection).

Provide instructions in advance on how to install an offline translation tool such as PoEdit, and have people ready to help others install and use it.

Create the glossary in advance. Present the glossary, discuss terms which do not have consensus, make sure everybody has access to a copy of the glossary, and print a sufficient amount of copies beforehand.

Determine goals for the sprint: which component will be translated, and what percentage your team is trying to achieve.

Make sub-teams with clear objectives: per component or file or a part of it.

If your translators are not familiar with CiviCRM, do a demo of the features your team is about to translate.

Clearly designate someone who can be interrupted in order to answer questions.

Make sure you've got enough coffee, tea, chocolate, etc. in reserve to keep everybody going through the night.

At the end of the sprint, present the result of the translation in a demo CiviCRM installation.

Discuss whether the team has reached its goal and how to improve further.

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/accounts/signin/?redirect=/accounts/signin/ 

2. Write

Select the manual http://booki.flossmanuals.net/civicrm/_edit/ 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

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 and following these sprints.

Fifth edition

The fifth edition was written at the Woolman Sierra Friends Centre (woolman.org) in April 2012. Woolman use and contribute to CiviCRM. We are grateful for their hospitality.

Fourth edition 

The forth edition was written in Bourne, Lincolnshire, UK in September 2011. We were too busy writing this edition to say much about how it was put together. 

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 Everyday 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 in getting into the code. Finally, we updated the book to match CiviCRM 3.2 (which was 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 work 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.

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 this manual was written during a five-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), 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, used CiviCRM in different ways, and 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 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 helped us 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 (aka "CiviDog") just for being there.

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.

Our office for the week was Dave and Bob's house.

 We mitigated the hardship of late-night work with some tasty beverages.

 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:

CiviCRM will not go away, unlike non-free software from some companies that gets abandoned if the company goes bankrupt or decides to discontinue a specific product.

The software can be used and customised free of charge.

Nobody can suddenly take away features or change the terms under which you are allowed to use the software and its features.

If an organisation wants a feature that CiviCRM doesn't provide, the organisation can hire someone to create it. Of course, the organisation can also submit a feature request to the CiviCRM team as with any software product.

Similarly, anyone can fix a bug (error in the software) if he or she has the skills to do so. Because the source code is available, clients can also find bugs more easily.

Members of the community have much more input into how CiviCRM develops than is traditionally available via closed source/commercial software, because they can understand the product by reading the code and can make changes. Furthermore, many people can try different implementations of features and the community can decide by vote or consensus which one to make official.

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 is 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:

One of the priorities of FOSS projects, including CiviCRM, is to involve the community of users in the process of designing and building the software. In the long run, this not only assures that the software is doing exactly what it should do to sustain the needs of its users, but it also allows indirect exchange of knowledge and experience between organisations. By using CiviCRM, you are basically taking advantage of other non-profit and advocacy practitioners' experience.

Having access to the source code gives you and your organisation a certain level of independence. With proprietary software it is usually impossible to customise the tools to meet your specific needs. With FOSS, you can hire a developer or consultant and work with them on providing specific functionality needed in your work. Additionally, if you contribute your improvements to the project community other organisations will probably start using them. It means you can receive testing and further improvements of your functionality for free.

When a company which provided you with closed software goes out of business, the usual procedure for an organisation reliant on that software is to abandon the software and start investing in a new one (which is resource intensive and costly). It's less likely to happen with Free and Open Source Software - there is always a community of users and developers around it and there is no single "point of failure." With FOSS projects, if the main organisation behind a specific piece of software shuts down or changes their focus, the community takes over, a new organisation is formed and the software development and support continues. 

Apart from the 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 those 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 are 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 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 anywhere 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" or "high speed."

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 integrated with a CMS (currently WordPress, 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 

Cron is the time-based job scheduler in Unix-like computer operating systems. Cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates. It is commonly used to automate system maintenance or administration. Cron is used to in CiviCRM to trigger specific tasks, such as sending membership renewal reminders or processing ongoing payments, or to run all jobs enabled under the Scheduled Jobs page at their configured frequency.

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.

WordPress

The most popular CMS in use on the internet today, WordPress integrates as of CiviCRM version 4.1 and WordPress version 3.3.1.  Prior to these versions, CiviCRM didn't work directly with WordPress, although a Drupal/CiviCRM installation could be installed in parallel on the same server as WordPress.

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

About this book

Modifications:
michaelmcandrew - Michael McAndrew 2014

What is CiviCRM?

Modifications:
Stoob - Stuart G 2012
brylie - Brylie Oxley 2012
jchester - JoAnne Chester 2013, 2014
michaellogue - Michael Logue 2013
michaelmcandrew - Michael McAndrew 2013, 2012
davidshq - Dave Mackey 2013
adam - adam hyde 2011

Real world examples

Modifications:
tonyguzman4 - Tony Guzman 2012
Katymoon - Katy Jockelson 2011
davidshq - Dave Mackey 2012
AbrilRocabert - Abril Rocabert 2012

Components

Modifications:
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2013, 2014
phillipclarke29 - Philip Clarke 2013

Extensions

Modifications:
arandajl08 - Joshua Aranda 2014
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2013, 2014

Who is CiviCRM?

Modifications:
Katymoon - Katy Jockelson 2011
brylie - Brylie Oxley 2012
jchester - JoAnne Chester 2014
adam - adam hyde 2011

Is CiviCRM for you?

Modifications:
jchester - JoAnne Chester 2014
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2012
kasiawaka - Kasia Wakarecy 2012
adam - adam hyde 2011

Identifying your needs

Modifications:
reperry - Robyn Perry 2011
jehanley - Jane Hanley 2012
AbrilRocabert - Abril Rocabert 2012
kasiawaka - Kasia Wakarecy 2012
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011

Test it out

Modifications:
kasiawaka - Kasia Wakarecy 2012
brylie - Brylie Oxley 2012
jchester - JoAnne Chester 2014

Hosting

Modifications:
Simon_West - Simon West 2012
brylie - Brylie Oxley 2012
jchester - JoAnne Chester 2014

Transitioning to CiviCRM

Modifications:
reperry - Robyn Perry 2011
Stoob - Stuart G 2012
jchester - JoAnne Chester 2014
davidshq - Dave Mackey 2012
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011

Installation and basic set-up

Modifications:
reperry - Robyn Perry 2012
michaelmcandrew - Michael McAndrew 2011, 2013
jchester - JoAnne Chester 2014, 2013
phillipclarke29 - Philip Clarke 2013
DavidGreenberg - David Greenberg 2012
techczech - Dominik Lukes 2011
adam - adam hyde 2011
arandajl08 - Joshua Aranda 2014
Simon_West - Simon West 2012
Katymoon - Katy Jockelson 2011

Scheduled jobs

Modifications:
DavidGreenberg - David Greenberg 2012
jbertolacci - Jason Bertolacci 2013
Stoob - Stuart G 2012
michaelmcandrew - Michael McAndrew 2012
slovak - Peter Petrik 2013

Customizing the user interface

Modifications:
DavidGreenberg - David Greenberg 2012
jchester - JoAnne Chester 2014, 2013
tonymazz - Tony Mazzarella 2014
leesajay - Lisa Jervis 2012

Permissions and access control

Modifications:
michaelmcandrew - Michael McAndrew 2013, 2014
arandajl08 - Joshua Aranda 2014
Simon_West - Simon West 2012
brylie - Brylie Oxley 2012
jchester - JoAnne Chester 2014

Security

Modifications:
michaelmcandrew - Michael McAndrew 2012
jchester - JoAnne Chester 2014
davidshq - Dave Mackey 2012
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012

Email system configuration

Modifications:
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2013, 2014
cborgia - Chris Borgia 2012
marcel - Marcel Clausen 2012
jbertolacci - Jason Bertolacci 2013
DavidGreenberg - David Greenberg 2012
slovak - Peter Petrik 2013
techczech - Dominik Lukes 2011
Katymoon - Katy Jockelson 2011
craftee123 - Sarah Craft 2014

Logging

Modifications:
michaelmcandrew - Michael McAndrew 2013, 2011
jchester - JoAnne Chester 2014, 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011

Menu, dashboard and dashlets

Modifications:
reperry - Robyn Perry 2012, 2011
colemanw - Coleman Watts 2014
Katymoon - Katy Jockelson 2011
jchester - JoAnne Chester 2013

Keyboard shortcuts

Modifications:
michaelmcandrew - Michael McAndrew 2012
jchester - JoAnne Chester 2014
leesajay - Lisa Jervis 2012

Searching

Modifications:
reperry - Robyn Perry 2011, 2012
michaelmcandrew - Michael McAndrew 2013, 2011
jchester - JoAnne Chester 2013, 2014
phillipclarke29 - Philip Clarke 2013
colemanw - Coleman Watts 2013, 2014
DavidGreenberg - David Greenberg 2012
adam - adam hyde 2011
helen - helen varley jamieson 2011
Simon_West - Simon West 2012
Katymoon - Katy Jockelson 2011
gibsonoliver - oliver gibson 2012

Undelete

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2014

Overview

Modifications:
reperry - Robyn Perry 2011
jehanley - Jane Hanley 2012
davem - Dave Moreton 2011
kasiawaka - Kasia Wakarecy 2012
kellieateff - Kellie Brownell 2012
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011

Mapping your data

Modifications:
michaelmcandrew - Michael McAndrew 2012
jchester - JoAnne Chester 2013
phillipclarke29 - Philip Clarke 2013
kasiawaka - Kasia Wakarecy 2012
avaguilar - Alice Aguilar 2014
kellieateff - Kellie Brownell 2012
DavidGreenberg - David Greenberg 2012
brylie - Brylie Oxley 2012

Contacts

Modifications:
KatyJ - Katy Jockelson 2012
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2014, 2013
jbertolacci - Jason Bertolacci 2013
DavidGreenberg - David Greenberg 2012
davidshq - Dave Mackey 2012
adam - adam hyde 2011
LindseyM - Lindsey Mansfield 2012
Simon_West - Simon West 2012
Katymoon - Katy Jockelson 2011
tonymazz - Tony Mazzarella 2014

Groups and tags

Modifications:
reperry - Robyn Perry 2012, 2011
michaelmcandrew - Michael McAndrew 2012, 2013, 2011
jchester - JoAnne Chester 2014
colemanw - Coleman Watts 2014
adam - adam hyde 2011
LindseyM - Lindsey Mansfield 2012
Katymoon - Katy Jockelson 2011
waldir - Waldir Pimenta 2011
avaguilar - Alice Aguilar 2012

Smart groups

Modifications:
booki - adam or aco 2011
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2013, 2014
phillipclarke29 - Philip Clarke 2013

Activities

Modifications:
KatyJ - Katy Jockelson 2012
michaelmcandrew - Michael McAndrew 2012, 2011, 2013
davem - Dave Moreton 2011
DavidGreenberg - David Greenberg 2012
Katymoon - Katy Jockelson 2011
nathan.porter - Nathan Porter 2014

Relationships

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2013, 2011
jchester - JoAnne Chester 2014
colemanw - Coleman Watts 2014
DavidGreenberg - David Greenberg 2012
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011

Custom fields

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014
DavidEsrati - David Esrati 2013
jbertolacci - Jason Bertolacci 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012

Profiles

Modifications:
Stoob - Stuart G 2013
michaelmcandrew - Michael McAndrew 2012, 2013
jchester - JoAnne Chester 2013, 2014
colemanw - Coleman Watts 2014
JoeMurray - Joe Murray 2013
jbertolacci - Jason Bertolacci 2013
brylie - Brylie Oxley 2012
Simon_West - Simon West 2012
leesajay - Lisa Jervis 2012
gibsonoliver - oliver gibson 2013

Importing data

Modifications:
reperry - Robyn Perry 2012
michaelmcandrew - Michael McAndrew 2011
jchester - JoAnne Chester 2014
kasiawaka - Kasia Wakarecy 2012
slovak - Peter Petrik 2013
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011
nathan.porter - Nathan Porter 2014

Exporting data

Modifications:
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011

Deduping and merging

Modifications:
reperry - Robyn Perry 2012
michaelmcandrew - Michael McAndrew 2011
Upperholme - Graham Mitchell 2013
Simon_West - Simon West 2012
slovak - Peter Petrik 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
jamienovick - Jamie Novick 2013

Tokens and mail merge

Modifications:
michaelmcandrew - Michael McAndrew 2012
colemanw - Coleman Watts 2014
DavidGreenberg - David Greenberg 2012
techczech - Dominik Lukes 2011
adam - adam hyde 2011
Simon_West - Simon West 2012
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

Postal mail communications

Modifications:
DavidGreenberg - David Greenberg 2012
michaelmcandrew - Michael McAndrew 2012
jchester - JoAnne Chester 2014

Automating tasks

Modifications:
kellieateff - Kellie Brownell 2012
michaelmcandrew - Michael McAndrew 2012
kasiawaka - Kasia Wakarecy 2012
jbertolacci - Jason Bertolacci 2013

What is CiviContribute?

Modifications:
reperry - Robyn Perry 2011
booki - adam or aco 2011
DavidGreenberg - David Greenberg 2012
davidshq - Dave Mackey 2012
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011, 2012

What you need to know

Modifications:
reperry - Robyn Perry 2011
trish - TBA 2012
jchester - JoAnne Chester 2014
davem - Dave Moreton 2011
michaelmcandrew - Michael McAndrew 2013
jbertolacci - Jason Bertolacci 2013
DavidGreenberg - David Greenberg 2012
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2012

Set-up

Modifications:
jchester - JoAnne Chester 2014
jbertolacci - Jason Bertolacci 2013
avaguilar - Alice Aguilar 2012, 2014
Simon_West - Simon West 2012
DavidGreenberg - David Greenberg 2012, 2014
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
nathan.porter - Nathan Porter 2014
gibsonoliver - oliver gibson 2014

Everyday tasks

Modifications:
michaelmcandrew - Michael McAndrew 2011
jchester - JoAnne Chester 2014
avaguilar - Alice Aguilar 2012
jbertolacci - Jason Bertolacci 2013
DavidGreenberg - David Greenberg 2012
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012

Soft credits

Modifications:
jehanley - Jane Hanley 2014
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2013
adam - adam hyde 2011
marisaporter - Marisa Porter 2014
tonymazz - Tony Mazzarella 2014

Personal Campaign Pages

Modifications:
Simon_West - Simon West 2012
DavidGreenberg - David Greenberg 2013
Stoob - Stuart G 2012

Reports and analysis

Modifications:
Abril - Abril Rocabert 2011
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011

Accounting Integration

Modifications:
ehbk - Eliet Henderson 2013
jchester - JoAnne Chester 2014
jehanley - Jane Hanley 2013

Payment processors

Modifications:
reperry - Robyn Perry 2012, 2011
michaelmcandrew - Michael McAndrew 2012, 2014
davem - Dave Moreton 2011
JoeMurray - Joe Murray 2013
DavidGreenberg - David Greenberg 2012
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011

What is CiviPledge?

Modifications:
Simon_West - Simon West 2012
Stoob - Stuart G 2012

What you need to know

Modifications:
jbertolacci - Jason Bertolacci 2013
Simon_West - Simon West 2012
DavidGreenberg - David Greenberg 2012
Stoob - Stuart G 2012

Set-up

Modifications:
reperry - Robyn Perry 2011
Stoob - Stuart G 2012
davem - Dave Moreton 2011
avaguilar - Alice Aguilar 2014
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012

Everyday tasks

Modifications:
Simon_West - Simon West 2012
Stoob - Stuart G 2012

Pledges Reports and Analysis

Modifications:
avaguilar - Alice Aguilar 2014

What is CiviEvent?

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2014
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

What you need to know

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2014
jbertolacci - Jason Bertolacci 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

Set-up

Modifications:
reperry - Robyn Perry 2011
Stoob - Stuart G 2012
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2013
colemanw - Coleman Watts 2013
nathan.porter - Nathan Porter 2014
jbertolacci - Jason Bertolacci 2013
DavidGreenberg - David Greenberg 2012, 2013
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012

Creating an Event

Modifications:
colemanw - Coleman Watts 2013
jbertolacci - Jason Bertolacci 2013
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014

WHAT IS CIVICRM?

Modifications:

Everyday tasks

Modifications:
reperry - Robyn Perry 2012
Abril - Abril Rocabert 2011
Stoob - Stuart G 2012
michaelmcandrew - Michael McAndrew 2012, 2014
jchester - JoAnne Chester 2014, 2013
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011

REAL WORLD EXAMPLES

Modifications:

Event Badges

Modifications:
jchester - JoAnne Chester 2013

WHO IS CIVICRM?

Modifications:

Reports and analysis

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
techczech - Dominik Lukes 2011
adam - adam hyde 2011

ABOUT THIS BOOK

Modifications:
DavidGreenberg - David Greenberg 2011

Introduction to memberships

Modifications:
Upperholme - Graham Mitchell 2014
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014

IS CIVICRM FOR YOU?

Modifications:

Defining memberships

Modifications:
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014

Online membership sign up

Modifications:
jcrothers - Jennifer Crothers 2014
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014
arandajl08 - Joshua Aranda 2014

ORGANISATIONAL ANALYSIS

Modifications:

PROJECT MANAGEMENT

Modifications:

Manual entry of memberships

Modifications:
reperry - Robyn Perry 2011
jcrothers - Jennifer Crothers 2014
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014
avaguilar - Alice Aguilar 2014

Membership pricesets

Modifications:
laryn - Laryn Kragt Bakker, CEDC.org 2014
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014
leesajay - Lisa Jervis 2012

HOW DATA IS ORGANISED?

Modifications:

Finding and viewing memberships

Modifications:
arandajl08 - Joshua Aranda 2014
jchester - JoAnne Chester 2014
avaguilar - Alice Aguilar 2014
kckrupp - Kevin C. Krupp 2012

Membership reports

Modifications:
arandajl08 - Joshua Aranda 2014
jchester - JoAnne Chester 2014
avaguilar - Alice Aguilar 2014
kckrupp - Kevin C. Krupp 2012

EXTENDING CORE DATA

Modifications:

PROFILES

Modifications:
DavidGreenberg - David Greenberg 2011

Renewals

Modifications:
arandajl08 - Joshua Aranda 2014
Simon_West - Simon West 2012
michaelmcandrew - Michael McAndrew 2014
jchester - JoAnne Chester 2014

INSTALLATION

Modifications:
DavidGreenberg - David Greenberg 2011

Cancelling and expiring memberships

Modifications:
kellieateff - Kellie Brownell 2012
kbrownell - Kellie Brownell 2012
jchester - JoAnne Chester 2014
arandajl08 - Joshua Aranda 2014

Members only websites

Modifications:
arandajl08 - Joshua Aranda 2014
jchester - JoAnne Chester 2014
leesajay - Lisa Jervis 2012

MENU AND DASHBOARD

Modifications:
DavidGreenberg - David Greenberg 2011

What is CiviMail?

Modifications:
michaelmcandrew - Michael McAndrew 2012, 2011
ehbk - Eliet Henderson 2012
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

CONTACTS

Modifications:
DavidGreenberg - David Greenberg 2011

What you need to know

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2012, 2011
ehbk - Eliet Henderson 2012
techczech - Dominik Lukes 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

TAGS AND GROUPS

Modifications:

SEARCHING

Modifications:
DavidGreenberg - David Greenberg 2011

Set-up

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
jchester - JoAnne Chester 2014, 2013
colemanw - Coleman Watts 2014
ehbk - Eliet Henderson 2012
DavidGreenberg - David Greenberg 2012
techczech - Dominik Lukes 2011
tonymazz - Tony Mazzarella 2014
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
Simon_West - Simon West 2012
leesajay - Lisa Jervis 2012

Maintaining Healthy Email Lists

Modifications:
laryn - Laryn Kragt Bakker, CEDC.org 2014
jchester - JoAnne Chester 2014
tonymazz - Tony Mazzarella 2014
arandajl08 - Joshua Aranda 2014

IMPORTING

Modifications:

Everyday tasks

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2011
ehbk - Eliet Henderson 2012
DavidGreenberg - David Greenberg 2012
techczech - Dominik Lukes 2011
Simon_West - Simon West 2012
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

DEDUPING AND MERGING

Modifications:

Reports and analysis

Modifications:
michaelmcandrew - Michael McAndrew 2011
jchester - JoAnne Chester 2013
ehbk - Eliet Henderson 2012
techczech - Dominik Lukes 2011
Katymoon - Katy Jockelson 2011
leesajay - Lisa Jervis 2012

EXPORTING

Modifications:

POSTAL MAIL

Modifications:

Scheduled reminders

Modifications:
laryn - Laryn Kragt Bakker, CEDC.org 2014
michaelmcandrew - Michael McAndrew 2012, 2014
jchester - JoAnne Chester 2014
ChrisChinchilla - Chris Ward 2014
DavidGreenberg - David Greenberg 2012
tonymazz - Tony Mazzarella 2014
arandajl08 - Joshua Aranda 2014
leesajay - Lisa Jervis 2012
petednz - Peter Davis 2012

EVERYDAY TASKS

Modifications:

What is SMS?

Modifications:
Simon_West - Simon West 2012

WHAT IS CIVICONTRIBUTE?

Modifications:

Set-up

Modifications:
Simon_West - Simon West 2012

Everyday tasks

Modifications:
Simon_West - Simon West 2012

PLANNING

Modifications:

Reports and analysis

Modifications:
Simon_West - Simon West 2012

CONFIGURING

Modifications:

EVERYDAY TASKS

Modifications:

What is CiviReport?

Modifications:
Katymoon - Katy Jockelson 2011
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011

What you need to know

Modifications:
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2014
davem - Dave Moreton 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011

WHAT IS CIVIEVENT?

Modifications:

PLANNING

Modifications:

Set-up

Modifications:
jbertolacci - Jason Bertolacci 2013
davem - Dave Moreton 2011
adam - adam hyde 2011
Katymoon - Katy Jockelson 2011
helen - helen varley jamieson 2011

Everyday tasks

Modifications:
Katymoon - Katy Jockelson 2011
helen - helen varley jamieson 2011

CONFIGURING

Modifications:

EVERYDAY TASKS

Modifications:
DavidGreenberg - David Greenberg 2011

What is CiviCase

Modifications:
reperry - Robyn Perry 2011
jchester - JoAnne Chester 2014
Upperholme - Graham Mitchell 2014
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2012

What you need to know

Modifications:
michaelmcandrew - Michael McAndrew 2013
jchester - JoAnne Chester 2014
Upperholme - Graham Mitchell 2014
davem - Dave Moreton 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
totten - Tim Otten 2014
avaguilar - Alice Aguilar 2012
emason - Eliot Mason 2014

WHAT IS CIVIMEMBER?

Modifications:

Set-up

Modifications:
reperry - Robyn Perry 2011
jchester - JoAnne Chester 2014, 2013
Upperholme - Graham Mitchell 2014
davem - Dave Moreton 2011
demeritcowboy - Dave D 2011
JoeMurray - Joe Murray 2013
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
totten - Tim Otten 2014
avaguilar - Alice Aguilar 2012
emason - Eliot Mason 2014

PLANNING

Modifications:

Every day tasks

Modifications:
reperry - Robyn Perry 2011
Upperholme - Graham Mitchell 2014
demeritcowboy - Dave D 2011
DavidGreenberg - David Greenberg 2011
helen - helen varley jamieson 2011
arandajl08 - Joshua Aranda 2014
Katymoon - Katy Jockelson 2011
tonymazz - Tony Mazzarella 2014
emason - Eliot Mason 2014

CONFIGURING

Modifications:

Reports and analysis

Modifications:
Abril - Abril Rocabert 2011
Katymoon - Katy Jockelson 2011
jchester - JoAnne Chester 2014
davem - Dave Moreton 2011

EVERYDAY TASKS

Modifications:

WHAT IS CIVIMAIL?

Modifications:

What is CiviCampaign?

Modifications:
reperry - Robyn Perry 2011
DavidEsrati - David Esrati 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011

PLANNING

Modifications:

What you need to know

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
DavidEsrati - David Esrati 2013
avaguilar - Alice Aguilar 2011, 2012
helen - helen varley jamieson 2011

SYSTEM CONFIGURATION

Modifications:

Set-up

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
jchester - JoAnne Chester 2013
avaguilar - Alice Aguilar 2012, 2011
helen - helen varley jamieson 2011

Everyday tasks

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2012, 2011
helen - helen varley jamieson 2011

CONFIGURING

Modifications:

EVERYDAY TASKS

Modifications:

Reports and analysis

Modifications:
michaelmcandrew - Michael McAndrew 2011, 2013
jchester - JoAnne Chester 2014

WHAT IS CIVICASE?

Modifications:

What is CiviSurvey

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011

What you need to know

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
helen - helen varley jamieson 2011
avaguilar - Alice Aguilar 2011
gibsonoliver - oliver gibson 2013

PLANNING

Modifications:

Set-up

Modifications:
reperry - Robyn Perry 2011
michaelmcandrew - Michael McAndrew 2013
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011, 2012
gibsonoliver - oliver gibson 2013

CONFIGURING

Modifications:

EVERYDAY TASKS

Modifications:

Everyday tasks

Modifications:
reperry - Robyn Perry 2011
DavidEsrati - David Esrati 2013
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2012, 2011
gibsonoliver - oliver gibson 2013

Reports and analysis

Modifications:
michaelmcandrew - Michael McAndrew 2011
Katymoon - Katy Jockelson 2011
gibsonoliver - oliver gibson 2013
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011

GOTV voter tracking

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011

WHAT IS CIVICAMPAIGN

Modifications:
avaguilar - Alice Aguilar 2011

CAMPAIGN PLANNING

Modifications:
michaelmcandrew - Michael McAndrew 2011

What is CiviPetition?

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011, 2012
helen - helen varley jamieson 2011

CAMPAIGN CONFIGURATION

Modifications:
michaelmcandrew - Michael McAndrew 2011

CAMPAIGN EVERYDAY TASKS

Modifications:
michaelmcandrew - Michael McAndrew 2011

What you need to know

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2012, 2011
helen - helen varley jamieson 2011

Set-up

Modifications:
reperry - Robyn Perry 2011
Laurie - Laurie Sterling Jensen 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011, 2012

Everyday tasks

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011, 2012
helen - helen varley jamieson 2011

WHAT IS CIVIENGAGE?

Modifications:

Reports and analysis

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2012

PLANNING

Modifications:

INSTALLING

Modifications:

CONFIGURING

Modifications:

What is CiviEngage

Modifications:
reperry - Robyn Perry 2011
DavidEsrati - David Esrati 2013
adam - adam hyde 2011
helen - helen varley jamieson 2011
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011

EVERYDAY TASKS

Modifications:

What you need to know

Modifications:
reperry - Robyn Perry 2011
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011

Set-up

Modifications:
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
avaguilar - Alice Aguilar 2011
helen - helen varley jamieson 2011

Everyday tasks

Modifications:
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011, 2012
helen - helen varley jamieson 2011

WHAT IS CIVIREPORT?

Modifications:

PLANNING

Modifications:

Reports and analysis

Modifications:
Katymoon - Katy Jockelson 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011

CONFIGURING

Modifications:

What is CiviGrant

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011
helen - helen varley jamieson 2011

EVERYDAY TASKS

Modifications:

What you need to know

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
helen - helen varley jamieson 2011

INTRODUCTION

Modifications:

Set-up

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
jchester - JoAnne Chester 2013
helen - helen varley jamieson 2011

Everyday tasks

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
helen - helen varley jamieson 2011

TEMPLATES

Modifications:

Reports and analysis

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
adam - adam hyde 2011

REPORTS

Modifications:

CUSTOM SEARCHES

Modifications:
theMusician - Max Bronsema 2011

Choosing your CMS

Modifications:
michaelmcandrew - Michael McAndrew 2012, 2013
jchester - JoAnne Chester 2014
gibsonoliver - oliver gibson 2013

API

Modifications:
JoeMurray - Joe Murray 2011

Integrating with Drupal

Modifications:
Stoob - Stuart G 2012
michaelmcandrew - Michael McAndrew 2012, 2013
jchester - JoAnne Chester 2014
jbertolacci - Jason Bertolacci 2013
slovak - Peter Petrik 2013
gibsonoliver - oliver gibson 2013

HOOKS

Modifications:

Integrating with Wordpress

Modifications:
Stoob - Stuart G 2012
michaelmcandrew - Michael McAndrew 2013, 2012
jchester - JoAnne Chester 2014
michaellogue - Michael Logue 2013
DavidGreenberg - David Greenberg 2012
arandajl08 - Joshua Aranda 2014

IMPORTS

Modifications:

DEVELOPER TIPS

Modifications:

Integrating with Joomla

Modifications:
michaelmcandrew - Michael McAndrew 2012
arandajl08 - Joshua Aranda 2014
DavidGreenberg - David Greenberg 2012
jchester - JoAnne Chester 2014
tonymazz - Tony Mazzarella 2014

CIVICOMMUNITY

Modifications:

CiviCRM community

Modifications:
Katymoon - Katy Jockelson 2011
DavidGreenberg - David Greenberg 2012
jchester - JoAnne Chester 2014
adam - adam hyde 2011

Bug reporting

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2011
avaguilar - Alice Aguilar 2011
adam - adam hyde 2011

LOCALISATION

Modifications:

Localising CiviCRM

Modifications:
Katymoon - Katy Jockelson 2011
jchester - JoAnne Chester 2014
adam - adam hyde 2011

BUG REPORTING

Modifications:

Contributing to this manual

Modifications:
joemcl - Joe McLaughlin 2013
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011
grantbow - Grant Bowman 2013

HOW TO CONTRIBUTE?

Modifications:

HISTORY OF THIS BOOK

Modifications:
DavidGreenberg - David Greenberg 2011

History of this book

Modifications:
Katymoon - Katy Jockelson 2011
michaelmcandrew - Michael McAndrew 2012
davidshq - Dave Mackey 2012
adam - adam hyde 2011

About free software

Modifications:
Katymoon - Katy Jockelson 2011
davidshq - Dave Mackey 2012

ABOUT FREE SOFTWARE

Modifications:

GLOSSARY

Modifications:

Glossary

Modifications:
Abril - Abril Rocabert 2011
jbertolacci - Jason Bertolacci 2013
Katymoon - Katy Jockelson 2011
davidshq - Dave Mackey 2012
helen - helen varley jamieson 2011

CREDITS

Modifications:

Credits

Modifications:
Katymoon - Katy Jockelson 2011
adam - adam hyde 2011

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

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