SugarCRM as an Applicant Tracking System

I wrote a few posts about SugarCRM some time ago, including ways to play with their SOAP interface to gather and input data. Today we’ll discuss the flexibility of SugarCRM and the way it could nicely fit into an applicant tracking system.

In short, almost every aspect of SugarCRM is a module. Leads, opportunities, tasks, projects. All these are modules. SugarCRM comes with a Module Builder and a Studio which not only help you customize your existing modules, but also let you build your own! So basically SugarCRM is flexible enough to become a project management system, a contact management system and a recruitment system.

Of course if you need some non-standard features such as live time tracking, or better e-mail handling, contract templates, etc, you’ll have to do some coding. Which is why SugarCRM is available as an open source php project – SugarCRM Community Edition. Okay, so back to our Recruitment or Applicant Tracking System:

An Applicant Tracking System (ATS) is a software application that enables the electronic handling of recruitment needs. An ATS system can be implemented on an Enterprise or small business level, depending on the needs of the company. ATS systems are very similar to Customer Relationship Management Systems, but are designed for recruitment tracking purposes.

So a very rough sketch of a very basic recruiting process (in my mind) looks something like this:

I’m not an HR expert so please don’t criticize my scheme too much. But I am using this scheme and I will show you how to implement it in SugarCRM, so before we proceed make sure you have found your Admin panel and fired up the Module Builder and/or Studio.

Designing and Building the New Modules

Now, the scheme above has four entities: HR Manager, Recruiting Agency, Position and Candidate. Let’s lay this down onto Sugar – HR Manager would be the current user, a Recruiting Agency fits nicely into an Account. Positions and Candidates are the only ones that have to be created in order to meet the scheme above. So here are the steps:

  1. Create a new Package – call it HR or however you wish
  2. Create a new Module called Positions, set the type to Basic
  3. Create a new Module called Candidates, based on the Person type

Basically, this is something that could be used already, so if you’d like to check it out, save and deploy your package. Then browse to the Admin panel, hit Configure Tabs and make sure that Positions and Candidates are in the “Displayed Tabs” list. This makes them available system-wide, but does not make them visible to you, as newly created modules are hidden by default. In order to make them visible, browse to your account settings and click Edit, then move the two options to the “Display Tabs” list in your Layout Options. Save and refresh the page, voila!

Okay that doesn’t give you much functionality, as Candidates doesn’t differ from Contacts and Positions is quite empty. We’ll have to create new fields, get rid of the extra ones and setup relations between modules, which is not that difficult either, so browse back to your Module Builder, open up your Positions module, hit View Fields and add the following new fields:

  1. Title (text) – the title of our position
  2. Department (text) – we’ll keep this text too for simplicity
  3. Budget (currency) – in case we have a strict budget for a certain position
  4. Status (drop-down data type) – at this point you should create a new drop-down list with the following options: Open, Closed

These are the essentials for our Positions module, but feel free to add more fields if you wish. Let’s go over to our Candidates module and add the following set of fields:

  1. Position (relate to Positions) – this will hold the position which the candidate is applying for
  2. Status (drop-down) – create a new list of: New, Rejected, Hired, Pending
  3. Agency (relate to Accounts) – this will hold our Recruiting Agencies link
  4. Salary (currency) – the salary expectations of our candidate

That’s about it. Now our Candidates and Positions are linked via fields and Candidates are also linked to Accounts, but don’t rush to save and deploy. You will not notice any changes in the module, as the new fields that you’ve added are no use if they’re not displayed. New fields are not displayed in modules by default so you’ll have to customize the layouts for Candidates and Positions.

Customizing Sugar Layouts

So, browse back to your Positions module and hit the View Layouts button. The three essential layouts are EditView, DetailView and ListView. You should customize them all based on your needs and don’t forget to add the new fields to those views. I prefer to keep things simple so I put only the basic stuff in all my views, but you may try different variants to meet your needs. The same should be done for the Candidates module, and once that is complete you should save and deploy your package.

The following screenshot illustrates the detailed view of a candidate:

Sweet eh? You might wonder where did the History section come from? Quite simple, it’s all about relations in SugarCRM. The History and Activities (not visible on screenshot) fit well into the Candidates entity as you’ll probably have e-mails, tasks, meetings and calls attachable to them.

Building Relationships

To create such a relation simply browse to your Module Builder, fire up the Candidates module, hit View Relationships and add a new relationship. You’ll have to link Candidates as a primary module and Activities as a related one with a one-to-many relationship. Hit save, deploy the package and refresh your Candidates page. Voila! Easy as that ;)

For the lazy ones of you, I’ve attached my copy of the HR module, so feel free to download (no longer available, sorry!) and expand it to your own needs. As for future modules, I guess I’ll be working on Contracts and/or Deals, so stay tuned. Thanks for reading and don’t forget to share this post ;)

How To: Retrieve a User ID via SOAP in SugarCRM

Following the Lead Generation Forms with WordPress and SugarCRM post, I came across the need to assign the generated lead to some person in the CRM. It would be easy if you could do it by simply using usernames in the system, but unfortunately usernames may change, but user IDs do not.

User IDs in SugarCRM are stored in a 36-byte alphanumeric string with symbols, which is easy to capture from the database, but not very usable that way. I worked a little more on the snippet I gave before and came up with a new function called getUserId, where a search is performed based on the username.

I’m not sure if this is very secure, but will surely work if you need to simply capture the ID of a certain user and perhaps hard-code it in your script or settings file. Make sure you read the previous post about SugarCRM to capture the whole Sugar class together with the authentication and lead creation functions. The following function is simply an addition to the class:

function getUserId($username)
{
	$result = $this->soap->call('get_entry_list', array(
		'session' => $this->session,
		'module_name' => 'Users',
		'query' => "user_name = 'pavel'",
		'max_results' => 1
	));

	return $result;
}

Once you’re done with that, use your sugar object to authenticate and request for a user id:

$sugar = new SugarCRM('username', 'password');
$sugar->login();

$result = $sugar->getUserId('john');
print_r($result);

So $result will contain an array where you’ll find the alphanumeric ID of the person with the username “john”.

I believe there was some other method for doing that in SugarCRM version prior to 5.5.2 CE, but the new SOAP Web Services are mostly based on a few general methods – get_entry, get_entry_list, set_entry, etc, which are applicable to basically any module including Users.

Now, in order to assign the new lead to your retrieved user (using the createLead function), just add an extra parameter to the array:

$result = $sugar->createLead(array(
	'lead_source' => 'Web Site',
	'lead_source_description' => 'Contact form on my website',
	'lead_status' => 'New',
	'first_name' => $_POST['firstname'],
	'last_name' => $_POST['lastname'],
	'phone_work' => $_POST['phonenumber'],
	'description' => $_POST['description'],
	'email1' => $_POST['email'],
	'assigned_user_id' => $user_id // Your ID goes here
));

Now your newly created leads will be assigned to your user, which is quite convenient when you have e-mail notifications turned on during assignment. Hope that helped somebody! Cheers, and thanks for sharing!

Lead Generation Forms with WordPress and SugarCRM

It took me quite some time to get around this, but I finally managed to get it working. As you might have heard, SugarCRM has a Community Edition, which is open source and free of charge. It’s a very neat tool to play with and it’s functionality will suit most SMEs and maybe some corporations.

I started playing with Sugar a few months ago, mostly with the modules functionality. Cannot compare it to Sales Force, but it’s quite flexible, as each module is customizable. If not within the built-in visual editor (Studio), then within the php sources in the modules directory of a SugarCRM installation. I managed to get some customized modules for real estate and took a few attempts to create a project management module.

Anyways, a few days ago I decided to take it outside Sugar and see what their Web Services are like. I was quite amazed at the flexibility there too. You can literally access any piece of information that’s inside the Sugar database, via quite simple to form SOAP requests. So today I’d like to show you how to construct a basic Lead Generation Form, and for the fun of it, let’s hook it up to WordPress.

If you’re a sales guy, you probably know what leads are. If you’re not, I’ll explain my understanding of it. A lead is a subset of information details about somebody, who in some way or another, is interested in your product or service. The minimum set for a lead would be a name and a phone number or an e-mail address. The maximum could be the inquiry description, budget, tonnes of contacts and more. Once a lead is processed and the person inquiring is still interested (perhaps after a phone call), it’s converted into an Opportunity, and that’s why there are Leads and Opportunities in basically every CRM system.

So, if you’re a business and you have a website, you probably have an inquiry form there somewhere. That inquiry form would be your Lead Generation form, which probably sends an e-mail to your backoffice, who parses the request and inputs it into the CRM, after which your sales team starts working on it. What a massive waste of time! Oh and by the way, e-mail was invented in 1965. Whaa? Come on, you gotta do better than this! I wonder if anybody has this tuned around Twitter accounts. It would be nice to get a DM when a new lead arrives.

Make sure you have a copy of SugarCRM installed somewhere. Locally will do. As I already mentioned, the SugarCRM Web Services works via the SOAP protocol, both to read and write data. But before we proceed, let’s build very a simple contact form somewhere in your WordPress theme files (sidebar maybe?):

<form method="POST">
	<label>First name:</label><input type="text" name="first_name" /><br />
	<label>Last name:</label><input type="text" name="last_name" /><br />
	<label>E-mail:</label><input type="text" name="email" /><br />
	<label>Message:</label><input type="text" name="message" /><br />
	<input type="hidden" name="lead-generation-form-submit" value="1" />
	<input type="submit" />
</form>

I guess there’s no reason to explain the code above, it’s more than straightforward ;)

Next, let’s prepare a short form processor where we’ll squeeze in the Sugar functions at a later stage. To keep it as simple as possible let’s just add a new action to the ‘init’ level where we could check for the existance of our POST data. Put this in your theme functions.php:

add_action('init', 'my_form_processor');
function my_form_processor() {
	if (isset($_POST['lead-generation-form-submit'])) {
		// Process data here
	}
}

The “Process data here” part is the one where people usually send the e-mail with the form data. We’ll put some Sugar there instead ;)

In order to work with the Sugar Web Services we’ll use the NuSOAP Web Services Toolkit for PHP, which is an open source library hosted at SourceForge. The choice is based on what is shipped with the SugarCRM CE bundle, so you can go ahead and just copy the whole nusoap directory from the include folder in Sugar, just note that they add an extra line at the very beginning of their files. You can remove them if you like, otherwise just define what they’re asking for at the beginning of your functions.php:

define('sugarEntry', true);

Let’s create a directory in your WordPress theme and call it “sugar”. Put the nusoap folder inside that directory and we’re almost ready to go.

Now, the next part is the tricky one, where you actually have to deal with SOAP and Sugar (soap and sugar, haha!). To make things simpler, I wrapped the functions I used into a tiny class which could then be extended based on your needs. In order to create a new lead we will need two functions. One to authenticate (login), which returns a session string that should be used for the other requests. The second one to create the new lead (createLead), which accepts a data array and returns the result of the SOAP request.

I also wrote a class constructor which stores the access credentials provided and initiates a new SOAP client, and don’t forget to include the NuSOAP library. Here’s the full code of my sugar.php file:

require_once('nusoap/nusoap.php');

// Wrapper class for SugarCRM Web Services
class SugarCRMWebServices {
	// Let's define a place to store our access credentials
	var $username;
	var $password;

	// We'll store the session ID here for later use
	var $session;

	// We'll initialize a new NuSOAP Client object into this one
	var $soap;

	// Constructor (PHP4-style)
	function SugarCRM($username, $password)
	{
		// Copy the credentials into our containers and initialize NuSOAP
		$this->username = $username;
		$this->password = $password;
		// Replace the URL with your copy of SugarCRM
		$this->soap = new nusoapclient('http://localhost/sugarcrm/soap.php');
	}

	// Login function which stores our session ID
	function login()
	{
		$result = $this->soap->call('login', array('user_auth' => array('user_name' => $this->username, 'password' => md5($this->password), 'version' => '.01'), 'application_name' => 'My Application'));
		$this->session = $result['id'];
	}

	// Create a new Lead, return the SOAP result
	function createLead($data)
	{
		// Parse the data and store it into a name/value list
		// which will then pe passed on to Sugar via SOAP
		$name_value_list = array();
		foreach($data as $key => $value)
			array_push($name_value_list, array('name' => $key, 'value' => $value));

		// Fire the set_entry call to the Leads module
		$result = $this->soap->call('set_entry', array(
			'session' => $this->session,
			'module_name' => 'Leads',
			'name_value_list' => $name_value_list
		));

		return $result;
	}
}

When you’re done with this, go back to your functions.php and find the “Process data here” comment which we left. The code below shows how to create a new lead when the form is posted:

// Process data here

// Load and initialize our sugar object
require_once('sugar/sugar.php');
$sugar = new SugarCRMWebServices('username', 'password');

// Login  and create a new lead
$sugar->login();
$result = $sugar->createLead(array(
	'lead_source' => 'Web Site',
	'lead_source_description' => 'Inquiry form on the website',
	'lead_status' => 'New',
	'first_name' => $_POST['first_name'],
	'last_name' => $_POST['last_name'],
	'email1' => $_POST['email'],
	'description' => $_POST['message']
));

That’s about it! You might be wondering where I got hold of all the field names, such as lead_source, etc. Well, some of them are quite obvious. Open up your SugarCRM, browse to the Admin panel and select Studio from Developer Tools. Pick Leads from the tree view on your left and select Fields. Most of the fields are there with their names, data types and labels, so feel free to add some extra input forms on your website, such as a phone number, etc.

Other fields, such as the email1 field I used above are pretty tricky to find. Open up your SugarCRM sources, browse to the modules directory and open up Leads. You’ll find a file called vardefs.php there. If you read carefully through that file, you’ll notice that all fields are there, even the ones hidden from the Studio.

You might also want to edit the Lead module and add an extra field or two to suit your needs, for instance a Website URL. Don’t forget to save and deploy. For more information visit the Sugar Developer Zone for some great Tools and Tutorials on SugarCRM tuning and customization.

That’s about it I guess! Don’t forget to give your form a good look (Web Form Design: Modern Solutions and Creative Ideas by Smashing Magazine) and of course descriptive and good looking error messages (Error Messages Design Showcase by SmileyCat.com).