English فارسی Suomi
Français Nederlands Translate

CiviCRM

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, and most (but definitley not all) of the CiviCRM developers are Drupal developers.

Introduction to 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 app which provides a certain bit of functionality.  For example the calendar module allows you to display calendars on your website, and the fivestar module allows users to rate the content that they see 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.  You can also download other drupal modules which offer different integrations from the Drupal website and other places.

This chapter outlines the main Drupal integration modules that come with CiviCRM and other common integration modules, including

  • CiviGroup Roles Sync - for syncing CiviCRM groups with Drupal roles
  • CiviMember Roles Sync - for syncing CiviCRM members with Drupal roles
  • Views - useful for displaying different data from CiviCRM on your website (views is similar to profiles but more powerful)

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.

Scenario: Limit access to contribution, donation, and payment information to specific staff members

Sigma Phi Epsilon Fraternity (SigEp) is one of the largest social and leadership development fraternities in the United States with over 240 chapters and serving 300,000 undergraduate members, alumni, staff, volunteers, and parents. With the wide range of different users served by SigEp's programs, extra care must be taken to ensure that certain information is accessible to people with specific roles within the organization.

Each SigEp chapter features a group of undergraduate members who manage the chapter's programming, leadership programs, and finances. This executive board includes a President and Director of Finance who are responsible for collecting dues and tracking academic standing of chapter members. While the President and Director of Finance need to keep track of when members are late on their dues payments the programming, events, and committee coordinators should never see another member's financial information.

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

Key Concepts

Drupal Roles

Your Drupal website allows you to create a series of different Roles. Your website administrators may grant roles to different users and grant each role the permission to perform a certain series of tasks (view, edit, delete, and administer) 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:

Drupal Permissions

Drupal permissions settings allow you to decide what task 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:

For more information on CiviCRM permissions in Drupal, please see the CiviCRM Drupal Permissions section.  

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:

CiviCRM Groups

You should have a full understanding of CiviCRM Groups, including how to create, edit, and add and remove contacts to both Groups and Smart Groups. You can learn more about Groups by reviewing the GROUPS AND TAGS section under the ORGANIZING YOUR DATA chapter. 

Configuring CiviGroup Roles Sync

 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.
  • what content each Group should grant permissions to should be agreed upon by your staff.
  • what tasks each Group 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 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.

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 CiviGroup Roles Sync Module

  1. To enable the CiviGroup 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.
  2. Find the Module CiviGroup Roles Sync and check the box to the left of the module's name.
  3. Click on Save Configuration.

Syncing CiviCRM Groups to Drupal Roles 

  1.  Navigate to the CiviGroup Role Sync configuration screen.
    • Drupal 6: Go to Administer > Site Configuration > CiviGroup Roles Sync
    • Drupal 7: Go to Configuration > CiviGroup Roles Sync
  2. Click on Add Association Rule.
  3. Under CiviCRM Group select the Group that you want a user to have in order to be granted a specific Drupal Role.
  4. Under 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 CiviGroup Membership Type and selects "Active Member" under Select a Drupal Role.
  5. Click on Add Association Rule when you are finished configuring your new association rule.
  6. The page will reload, and you should see the message "Your Association Rule has been added."
  7. Repeat steps 1-8 to add all necessary association rules for your organization.

Editing Existing Association Rules

You can always edit or delete existing association rules.

  1. To edit or delete an existing Association Rule, Navigate to the CiviGroup Role Sync configuration screen.
    • Drupal 6: Go to Administer > Site Configuration > CiviGroup Roles Sync
    • Drupal 7: Go to Configuration > CiviGroup Roles Sync
  2.  You should now see a list of all existing CiviGroup Role Sync Association Rules. If not, click on List Association Rule(s) tab.

    Edit an Existing Association Rule
  3. Find the Association Rule you want to make changes to and click on edit for that Association Rule.
  4. Make the changes to your Association Rule and when yo are finished click on Edit association rule.

    Delete an Association Rule
  5. Find the Association Rule you want to remove and click on delete for that Association Rule.
  6. Your association rule will be deleted. You will not need to confirm deletion.

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.

Key Concepts

Drupal Roles

Your Drupal website allows you to create a series of different Roles. Your website administrators may grant roles to different users and grant each role the permission to perform a certain series of tasks (view, edit, delete, and administer) 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:

Drupal Permissions

Drupal permissions settings allow you to decide what task 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:

For more information on CiviCRM permissions in Drupal, please see the CiviCRM Drupal Permissions section.  

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:

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

  1. 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.
  2. Find the Module CiviMember Roles Sync and check the box to the left of the module's name.
  3. Click on Save Configuration.

Syncing CiviCRM Membership Types to Drupal Roles 

  1.  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
  2. Click on Add Association Rule.
  3. 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.
  4. 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.
  5.  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. 
  6. 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.
  7. Click on Add Association Rule when you are finished configuring your new association rule.
  8. The page will reload, and you should see the message "Your Association Rule has been added."
  9. 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.
  10. Click on the tab Manually Synchronize
  11. 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.

  1. 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
  2.  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
  3. Find the Association Rule you want to make changes to and click on edit for that Association Rule.
  4. Make the changes to your Association Rule and when yo are finished click on Edit association rule.

    Delete an Association Rule
  5. Find the Association Rule you want to remove and click on delete for that Association Rule.
  6. 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.

Drupal Views

Views is a powerful Drupal module that allows a vast array of search, input and display options for data within Drupal nodes and blocks.  CiviCRM integrates with Drupal Views by allowing CiviCRM data to be shown within Views.

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

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 the process by copying and pasting the CiviCRM database code for Views into settings.php again.

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
  • ...and more!



 


EDIT