Building a New Feature for CRM Core

Oct
03

CRM Core is a tool for managing contact information within a Drupal website. It was designed to act as a platform, where developers can add small, useful applications on top of the core components to handle specific use-cases. It was also designed to be highly interoperable with Drupal so that people without any specialized programming knowledge could work with it.

CRM Core was launched a little over a year ago, and one of the most common questions we encounter is about creating a new feature to interact with the platform. Creating a CRM Core feature should not be a huge hurdle for anyone with a basic knowledge of how to work with Drupal. The process is pretty simple and should require minimal amounts of code; in fact, it's possible to create them without writing any code at all.

This blog post presents a step-by-step guide to creating CRM Core features within Drupal. It will demonstrate how someone can set up a site to collect information about contacts, create useful interfaces for interacting with the information that is collected, and build forms for collecting this information from the public. It also outlines how to create portable features for CRM Core that can be used across multiple sites, allowing people to build their own CRM systems to serve niche needs.

This exercise can be carried out by anyone with a fresh copy of Drupal, and can be completed in as little as 30 minutes. We have included sample code demonstrating all of the points in this exercise, in case you get stuck at any point or just wish to jump to the end.

What Are We Building

CRM Core is designed as a platform for building small, useful applications that add functionality to the system. The modules are designed with a fairly robust API to interact with, meaning a Drupal developer should be able to find lots of ways to hook into the system without much work. Developers are going to be building features, which should be familiar to most people with any kind of background with that module.

It's important to start off with a clear sense of what you are trying to accomplish. Stating the business case you are trying to capture can make all the difference in what you get out of building your feature. We suggest taking an approach where developers will start by building a small prototype that demonstrates what you want to accomplish, before going back to refine it over time using Drupal and CRM Core's APIs. This will save a lot of time by getting tools into your hands early and providing you with simple proofs of concept that can be efficiently built out into powerful tools through successive iterations.

In this case, let's say we are going to build a lead generation tool for tracking contacts who have come to the site and asked questions by filling out forms. In addition, we want to be able to manage leads by assigning them to specific users - our sales people - and ask them to follow up with each lead. It's pretty easy to assign further requirements from the get go, but this is a pretty simple list to get us started. What we are looking to get is a contact form for people to fill out, and an interface on the backend that allows people to see what leads have been submitted (and their status).

In CRM Core terms, we are going to be carrying out a number of simple steps to enable lead generation, focused on assembling a prototype that can be refined to make our new application very useful. To help you visualize the overall process:

  • Begin by installing Drupal and CRM Core.
  • Configure contact types and activity types for storing data.
  • Create a profile form for collecting information.
  • Customize the way information is handled in the system (optional).
  • Build a view to act as an interface for your data.
  • Export everything as a feature so you can encapsulate your code and share it with others.

There is very little in this list that basic site builders would find unfamiliar. The feature included with this message is an example you can look at in case you get stuck.

What You Need

To begin with, you need to install CRM Core and it's dependencies. The basic requirements for CRM Core are listed below, and there is not much configuration required for any of them to work. Using a fresh installation of Drupal, install and activate the following modules:

  • Views
  • CTools
  • CRM Core
  • CRM Core UI
  • CRM Core Activity
  • CRM Core Activity UI
  • CRM Core Contact
  • CRM Core Contact UI
  • CRM Core Relationship
  • CRM Core Relationship UI
  • Entity API
  • Entity Reference
  • Relation
  • Field UI
  • Image
  • File
  • Address Field
  • Email
  • Link
  • Phone Number
  • Fieldgroup
  • Name Field
  • Date API
  • Date Popup
  • Date Views

This may sound like a long list, but remember: a lot of these modules are simply field definitions, and some of them are things you would need elsewhere in your site regardless of whether or not CRM Core was installed.

In addition to the basic requirements, install CRM Core Profile (http://drupal.org/project/crm_core_profile). This module is important, it will allow you to create contact forms that can be displayed anywhere within your Drupal site for collecting information. We are going to use it in this example to create one form for capturing contact information, and it can be used over and over again to collect lots of information from your users.

Step One: Configure your Contact Types

To begin with, you will want to configure your contact types so there is a way to store information about contacts. This can be done through the web-based admin interface by going to Structure > CRM > CRM Contact Types, or through the following path: admin/structure/crm/contact-types.

Select the individual contact type and start configuring fields. There's not much to say about this page, administrators will configure fields for collecting contact data in the same manner he or she would for a content type. This page allows you to specify the information you are going to track about conations coming to your site. You can add an unlimited number of fields from this page, and you will likely come back to it at some point to set up more fields to collect about people.

For this exercise, make sure there are fields for name, image, email address, address, and phone number. These will be the basic fields we use to collect information from users in the site. Feel free to add additional fields, but they are not required to complete this exercise.

Step Two: Create an Activity Type

The next step is to configure an activity type that will be used to track information submitted by users. We are going to configure the system to capture leads, and to associate them with specific contacts so you can track them over time.

In case you are wondering, an activity type is simply a way of tracking action for a contact. In CRM Core terms, this is the basic way to track interaction with someone, it stores information about the interaction as opposed to information about the person. When you plan for a CRM Core installation, it's important to think about the ways you are going to want to track people and set up the appropriate activities to capture information efficiently. This is a page you will probably come back to each time you need to track something new about interaction with people.

Begin by going to Structure > CRM > CRM Activity types in the web based administrative interface, or simply by going to the path admin/structure/crm/activity-types.

From here, create a new activity type called "Lead" and create some fields for that activity type. There will be some default fields already configured. Leave those alone, and create some additional fields that will be used to capture information. For the purpose of this exercise, set up the following custom fields using the web-based administrative tool:

  • Status - to track the state of the lead
  • Assigned To - to track who is responsible for the lead. Use entity reference to associate the activity and a user.

Like contacts, activities can store any number of custom fields you need to effectively track information. You can associate any additional fields required as part of this activity type, and it can easily be expanded to capture other points of data over time. For right now, we simply want to know that leads are being acted on, and that someone is responsible for them. Save the activity and continue.

Step Three: Export the Activity Type to a Feature Module

A best practice with CRM Core is to export your customizations to features. On the one hand, this makes your new application portable, meaning you can share it with others and use it on multiple websites. On the other hand, it helps to keep your work organized and free from defects that can emerge over time. It's a good idea to export features early and often, and occasionally test them using another installation of Drupal.

Within the web-based administrator, go to Structure > Features and create a new feature called 'CRM Core Leads.' From within the components drop down, select the crm_core_activity_type option, and check off the box for Lead. This will create a feature that simply stores our new activity type. We will add additional information to it over time.

Export the feature and save it in your sites directory, preferably somewhere like sites/all/modules/features/crm_core_leads. Afterwards, return to the features page and make sure the new feature you just created is enabled.

Step Four: Create a crm_core_profile Form

At this point, your site has the ability to store contacts, and associate leads with them. The next step is to create the contact form that will be used to capture the lead and store it in the system.

CRM Core Profile is a module that builds forms to collect information about contact and activities. It's a very powerful tool for collecting information, and can be used to create any number of forms in your site that populate fields in contact and activity records. The CRM Core API can be used along with CRM Core Profile to efficiently handle very complex business requirements. The module itself contains many examples of how to write code for CRM Core Activities that can be used as templates for other modules.

In this example, we are simply going to use the out of the box components to create a new contact form, which will drive the creation of leads within CRM Core.

Begin by going to the Structure > CRM > CRM Core Profile in the web-based administrator, or directly to the path admin/structure/crm/profile. This will present you with a list of all profile forms that are configured for your system. Click the link to add a new profile at the top of the screen.

Start by giving the new profile the name Lead Inquiry. Note the machine name being generated next to the title of the form. Programmers will use this when they need to reference the profile from Drupal's API, and we will show you an example of how to do this in this exercise.

You will be presented with a screen that allows you to select the fields you want to use to populate the contact record and the activity. Select the following fields from the Contact Record:

  • Name
  • Email
  • Phone Number

In addition to the basic fields, you can provide some information to help users access your new profile through this screen as well. Optionally, you can provide a path to get to the form, which will allow public access to the form from the specified URL. You can provide a redirect path to take users to a new URL after submitting the form. You can enter a message to display when users successfully submit the form. You can also enable a block to display the form within your site. These are not necessary for the purposes of this exercise, but may help you to visualize the results.

Below, in the activity information section, use the select box to select the Lead activity type. The screen will refresh with a list of fields. Select the description box, this will simple be used to collect some notes about the activity.

Click the create button. At this point, you will have a form that allows you to collect leads within your site. You can see it listed on the CRM Core Profile screen in the web-based admin screen, and can browse to it via the path specified in the configuration screen.

Step Five: Add Customization in the Feature Module

This step is completely optional. If code makes you all upset, skip to step six.

One of the challenges that comes from creating new activity types is identifying individual ones in the system. Over time, contact records can generate a lot of activities. It's important to lay out activities n a meaningful way, in order to ensure you will be able to understand what has happened with a contact over time.

We need to do some scripting to people can easily identify a lead in the system. As part of this exercise, we are going to add some code to the feature module we created for our new lead generation tool, which is going to add a distinct name for each lead that comes in.

Open crm_core_leads.module from within your feature and insert the following code:

<?php
/**
* Implements hook_crm_core_profile_activity_alter
*/
function crm_core_lead_crm_core_profile_activity_alter(&$form, $profile_name) { 
  if (
$profile_name == 'lead_inquiry') {
   
$form['title']['#value'] = t('Contact Form Lead');
  }
}
?>

In Drupal terms: we are implementing a hook which will override and change the name of the activity to "Contact Form Lead" when it is being associated with the contact record. Every new lead associated with the contact record will have the same name, "Contact Form Lead." Optionally, if you wanted some additional control over the name, a developer could include any other information from the profile form in the title (for instance, a date or the name of the contact). For practical purposes, this is all that is needed.

It's important to note that this example does not use CRM Core's API or any special code outside of Drupal's APIs. A developer does not really need to understand anything specific to CRM Core in order to make this work, but it helps to know why are doing it. There are many other ways to extend and customize this feature module, but the above is all that is useful for this exercise.

Go ahead and export your feature again at this point. While it's not strictly necessary, it's a good idea to export a feature any time you have added new code or changed any settings associated with it, for the reasons stated previously.

Step Six: Add Some Administrative Screens

At this stage, we have our contact records configured, an activity type for tracking information, and a profile form for collecting information. We have customized the feature to carry out some basic operations that allow users to identify their leads more easily in the system. The only thing really left is to give people a simple way to interact with their leads by creating an interface to track them.

As part of this exercise, we are going to create a screen within our feature that allows people to lookup leads, change their status, and assign leads to specific users within our system. The simplest way to create such an interface is the views module, which will be used to present lists of leads and operate on them within the site.

Create a new view with the following basic setup:

  • Name the view 'CRM Core Leads.'
  • Use select Activity Types from the show select menu, and select activity types of 'Lead.'
  • Check the box to create a page for the view, call it 'All Leads,' and give it a path of 'all_leads'.
  • For display format, have it display a table.

Press the continue and edit button. On the resulting page, add fields for the contact and the activity type as part of this exercise. Views will give us a list of fields referencing the activity itself, and we are going to add relationships to get information about the associated contact.

Within the advanced menu, click the link to add a relationship. Check the box for 'Entity Reference: Referenced Entity' and apply it to all displays. On the resulting screen, just select the option to apply it to all displays. This will allow you to add fields to the view for the contact associated with the lead.

From here, add fields to the view. For this exercise, we are going to add the following:

  • Name (from crm_core_contact:individual)
  • Email address (from crm_core_contact:individual)
  • Status (from CRM Activity)
  • Assigned To (from CRM Activity)
  • Date (from CRM Activity)
  • Edit Link (from CRM Activity)

With these fields in place, turn off the page and save the view.

This view can be customized to include any fields you are looking for. Just remember, the relationship is important, it is what lets you reference content from the actual contact record. You can use this along with aggregation to get some really interesting data into your interface.

Once your new view is created, save it along with the CRM Core Leads feature, and export the view.

Step Seven: Extend Your Feature

This exercise provides an overview of the basic method for creating a new feature for CRM Core. This feature provides an interface for users to look at information related to a contact, tracks leads along with status and assignment, and stores information in manner where it can easily be identified within the system.

From here, it's up to you to extend it to handle the specific business rules for your website. There are a lot of ways to go from here, and you may want to consider some of the following as paths for how to make the site awesome:

  • Securing the view, assigning the appropriate permissions to make sure only the right people can access it.
  • Implementing views bulk operations, to allow you to modify a bunch of leads all at once.
  • Implementing exposed filters within the view, to limit the number of records returned or for only viewing leads assigned to a specific user.
  • Implementing additional views to show how many leads have come in in a given month.
  • Implement filters within the views to ensure users can only access their own leads.
  • Add triggers around the submission of the profile form to receive emails whenever you receive a new lead.
  • Associate contact records with users in your Drupal site to allow people to self-maintain their contact information.
  • Associate your CRM Core profile forms with other content types, in order to allow in-line submissions.
  • Create organic groups to manage large lists of contacts.
  • Repeat this exercise for other types of interaction with users besides creating leads.

Take the time to consider how long it took to carry out this exercise. In general, adding a new feature to CRM Core is the sort of activity a developer can handle in less than a day to get to a prototype stage. A best practice around CRM Core development is to build features quickly before going back to refine specific interface and business rule requirements. Something we like to say at Trellon, no one ever knows exactly what they want until they have their hands on it.

A word of advice: take features seriously. At some point, we are going to set up a features exchange for CRM Core, to allow people to share the features they create with the community. For right now, it's helpful for developers to maintain a stock of the features they have created to keep handy for when they are building sites. Trellon has a set of features for event management, membership, claiming profiles, controlling access to physical resources, donations, store purchases and more. We plan on releasing them along with the features exchange, and will be happy to share them before it is ready if you ask us nicely.

Feel free to download a copy of the sample code used for this exercise, and enjoy your new web-to-lead functionality.

6 Comments

Thank you for this post. I

Thank you for this post. I had heard about CRM Core before, but did not really understand what you could do with it. Following this recipe made things totally clear.

Question: you mention have features for events and membership? How can I get a hold of these? Also, these features make CRM Core sound a lot like CiviCRM. Can you tell me how you see these systems stacking up against one another?

Hi, please look forward for

Hi, please look forward for upcoming blog post about building more complex features such as events or membership.

As far as comparing against CiviCRM, I think there's no comparison system CRM Core is more of a application building blocks and a set of APIs rather than a CRM solution that has its intend and purposes.

Best

Great tutorial BUT I can't

Great tutorial BUT I can't pass step 4. For some reason I can found CRM Core Profile under CRM. I tried unistalling and installing the module and no luck. Any ideas?

Also, for the lazy ones out there the drush command to install all the modules is;

drush dl views ctools crm_core crm_core_activity crm_core_activity_ui crm_core_contact crm_core_contact_ui crm_core_relationship crm_core_relationship_ui relation email link date_api date_popup date_views date entityreference name field_group cck_phone addressfield entity crm_ui relation_endpoint crm_core_profile features

drush en views ctools crm_core crm_core_activity crm_core_activity_ui crm_core_contact crm_core_contact_ui crm_core_relationship crm_core_relationship_ui relation email link date_api date_popup date_views date entityreference name field_group cck_phone addressfield entity crm_ui relation_endpoint crm_core_profile features

I added Features to the list that was missing.

The turorial is just what I

The turorial is just what I am looking for. But in step 6, when I selected the crm activity type, an Ajax Http error occurred. HTTP Result Code:200.. I tried to correct it according to some suggestions I found, but it is still there. Could you give any advice?
Overall, thank you for the great tutorial.

Great tutorial, what are the

Great tutorial, what are the best practices in building Event Registration & Membership management with CRM Core ? The said are very critical in setting up a CRM. Thanks a lot.

For those who follow after

For those who follow after me, as of today several details of the process have changed substantially from what is described here. Names, locations and methods have been changed. Nevertheless, with a bit of struggle and in some cases pure dumb luck I was able to find a way through the process, even though I really didn't know what I was doing. Now I know a bit more about how to use Views as well as the CRM Core.

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • You may post code using <code>...</code> (generic) or <?php ... ?> (highlighted PHP) tags.

More information about formatting options