In my last blog post I talked about ways you can integrate the Salsa CRM system with your Drupal site using the Salsa API and Salsa Entity modules. In part 2, I'll dive into using Salsa API with your own custom code.

The Salsa API module creates a class with several methods, corresponding to the calls in Salsa's external API. There are three main methods that you'll use.

salsa_api()->getObject

$supporter_key = 33333266;
$supporter = salsa_api()->getObject ('supporter',
$supporter_key);

In this code snippet we're asking Salsa to give us one object of the 'supporter' type, which is uniquely identified by $supporter_key. The call returns an associative array, corresponding to field names and values for every field in the supporter object, including any custom fields you've added:

array(
'supporter_KEY' => 33333266,
'organization_KEY' => 17594,
'Last_Modified' => 'Tue Feb 19 2013 18:30:52 GMT-0500 (EST)',
'Date_Created' => 'Tue Feb 05 2013 17:41:42 GMT-0500 (EST)',
'Title' => '',
'First_Name' => 'John',
'MI' => 'Q',
'Last_Name' => 'Public',
'Suffix' => 'Jr.',
'Email' = 'john@test.null',
'Receive_Email' => 1,
'Email_Status' => 1,
'Email_Preference' => 'html',
etc.
.
.
.
);

salsa_api()->getObjects

Frequently, you don't know the unique key for the supporter or other Salsa object you want, or you want to retrieve more than one. The getObject method comes to the rescue, which lets you query by condition.

$include = array('supporter_KEY', 'Last_Modified', 'First_Name', 'Last_Name', 'Email', 'City', 'State', 'Zip');
$conditions = array(
'Last_Modified' => array(
'#operator' => '>’,
'#value' => date("Y-m-d H:i:s", $lastrun)
),
);
$orderBy = array('Last_Modified DESC');
$limit = $offset . ",500";
$supporters = salsa_api()->getObjects('supporter', $conditions, $limit, $include, $orderBy);

Here, we're retrieving supporters that have been modified since the timestamp contained in the $lastrun variable, in reverse chronological order. Since Salsa's external API will only return a maximum of 500 records per request, we're asking for them in batches of 500 (presumably we're iterating through and incrementing $offset just outside of this code snippet). We can also specify the fields that are returned, since we probably don't need the entire supporter record. This will return an array of objects, each containing one supporter, indexed by supporter key.

salsa_api()->save

We can also save information to Salsa, using the save method:

$fields = array(
  'First_Name' => 'John',
  'Last_Name' => 'Doe',
  'Email => 'john@zoom.com',
  'Zip' => '01234',
);
$links = array(
  array(
    'link' => 'supporter_groups',
    'linkkey' => 10000,
  ),
  array(
   'link' => 'supporter_groups',
    'linkkey' => 10001,
  );
);
$new_key = salsa_api()->save('supporter', $fields, $links);

At minimum, we just need to give the method the name of the Salsa object we're saving to (here it's 'supporter'), and an asssociative array of field names and values. If the $fields array includes the unique key for an existing record (e.g., 'supporter_KEY' => 12345678,), it will update that record, otherwise it will create a new record. The $links array lets us save across multiple Salsa objects at the same time. This is most commonly used to create or update a supporter, while simultaneously adding the supporter to one or more Salsa groups. In the code snippet above, we're creating a new supporter, and adding him to groups 10000 and 10001 at the same time.

Several other methods exist, allowing you to perform count queries and joins, or retrieve canned queries stored in Salsa. For details, see the in-code documentation. If you have questions about using the Salsa API module, or have an improvement or bugfix to contribute, just post an issue in the issue queue.