How to add a Case Note via REST API - SugarCRM Community Edition

January 1st at 12:00am

A little while back I was asked to help out with a friends small business. They needed an inexpensive CRM solution that could integrate with their billing system and existing workflow. We turned to SugarCRM Community Edition and found a serviceable platform.

The hard part about Sugar Community Edition is that the documentation kind of sucks in comparison to the paid offering. This article explains how to use the REST API to add notes to existing cases via PHP.

References

SugarCRM Community Edition [sourceforge.net]
How to connect with SugarCRM using Rest API and C# .Net [geekandyou.com]
SOAP API problem when adding note attachments [forums.sugarcrm.com]
Uploading Note attachments to Sugar via Web Services [developer.sugarcrm.com]
Creating Notes with Attachments [support.sugarcrm.com]
REST API - Create new Account and new Note tied to new Account [forums.sugarcrm.com]

What's Required

To add a note to an existing SugarCRM Case the following things need to happen:

Obtain the case GUID from SugarCRM
Login to SugarCRM and get an authentication token
Configure the notes array so it has a name, Description, and caseguid
Call the set_entry API to the Notes module

Create a PHP File To Push a Note via REST API

We'll cover each piece of this step-by-step, then show the complete result for ease of use

Configuration

Before we can access any APIs, we need to gather or configure a few things. This PHP file relies on a caseguid, notename and notedescription being passed in via GET, POST or PUT. It also relies on you configuring and implementing an API User to use when performing API operations.

// Configure the SugarCRM Login information
$url = "https://crelations.domain.tld/service/v4_1/rest.php";
$username = "sugarcrm_login_user";
$password = "sugarcrm_login_password";

// Get the raw data
$caseguid = $_REQUEST['caseguid'];
$notename = $_REQUEST['notename'];
$notedesc = $_REQUEST['notedesc'];

// Set the page we want to redirect to (Useful if you are using non-ajaxy form posts)
header('Location: http://domain.tld/someplace');

Function to make API Calls to SugarCRM CE

This call was taken from Creating Notes with Attachments from the sugarcrm support page.

//
// This function knows how to make a call to a SugarCRM API
//
function call($method, $parameters, $url)
{
    ob_start();
    $curl_request = curl_init();

    curl_setopt($curl_request, CURLOPT_URL, $url);
    curl_setopt($curl_request, CURLOPT_POST, 1);
    curl_setopt($curl_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
    curl_setopt($curl_request, CURLOPT_HEADER, 1);
    curl_setopt($curl_request, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl_request, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl_request, CURLOPT_FOLLOWLOCATION, 0);

    $jsonEncodedData = json_encode($parameters);

    $post = array(
        "method" => $method,
        "input_type" => "JSON",
        "response_type" => "JSON",
        "rest_data" => $jsonEncodedData
    );

    curl_setopt($curl_request, CURLOPT_POSTFIELDS, $post);
    $result = curl_exec($curl_request);
    curl_close($curl_request);

    $result = explode("\r\n\r\n", $result, 2);
    $response = json_decode($result[1]);
    ob_end_flush();

    return $response;
}

Login to the API

In order to perform any API operations, we need a session to the SugarCRM REST API. This code block performs that action and stores the session id for later use.

// Configure Login Parameters
$login_parameters = array(
    "user_auth"=>array(
        "user_name"=>$username,
        "password"=>md5($password),
        "version"=>"1"
    ),
    "application_name"=>"BoredWookie - Sample Note Pusher",
    "name_value_list"=>array(),
);

// Perform the login action
$login_result = call("login", $login_parameters, $url);

// Get the session id
$session_id = $login_result->id;

Create the Case Note

Now that we have all the information gathered, we need to create a set of parameters to be used to create the note. We need the API Session, the Module Name ("Notes" in our case), and a NameValueList which contains the note information).

Once the parameter array is generated, we call the call function defined earlier to interact with the REST API.

// Configure the create-note parameters
$note_params = array(
    'session' => $session_id,
    'module' => 'Notes',
    'name_value_list' => array(
        array(
            'name' => 'name',
            'value' => $notename,
        ),
        array(
            'name' => 'description',
            'value' => $notedesc
        ),
        array(
            'name' => 'parent_type',
            'value' => 'Cases'
        ),
        array(
            'name' => 'parent_id',
            'value' => $caseguid
        )
    )
);

// Create the note
$create_result = call("set_entry", $note_params, $url);

Return the NoteID and Case GUID

To demonstrate what happens when things work correctly, we echo a string which contains both the NoteID and the Case GUID.

// Obtain the note ID for the created note
$noteId = $create_result->id;

// Display information about what we just did
echo "NoteID: ".$noteId." was created successfully against case: ".$caseguid;

Complete PHP Listing

For convenience, here is the complete set of PHP code in one place.


/**
 * addCaseNote.php
 *
 *  Adds a case note to SugarCRM cases. Tested against SugarCRM Community Edition version 6.5.18
 *
 *  Created: 22-Decmeber-2014
 *  Author: The Bored Wookie (boredwookie.net)
 *  License: MIT
 *  Disclaimer: For educational purposes. Make sure you know what you are doing!
 */

// Configure the SugarCRM Login information
$url = "https://crelations.domain.tld/service/v4_1/rest.php";
$username = "sugarcrm_login_user";
$password = "sugarcrm_login_password";

// Get the raw data
$caseguid = $_REQUEST['caseguid'];
$notename = $_REQUEST['notename'];
$notedesc = $_REQUEST['notedesc'];

// Set the page we want to redirect to (Useful if you are using non-ajaxy form posts)
header('Location: http://domain.tld/someplace');

//
// This function knows how to make a call to a SugarCRM API
//
function call($method, $parameters, $url)
{
    ob_start();
    $curl_request = curl_init();

    curl_setopt($curl_request, CURLOPT_URL, $url);
    curl_setopt($curl_request, CURLOPT_POST, 1);
    curl_setopt($curl_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
    curl_setopt($curl_request, CURLOPT_HEADER, 1);
    curl_setopt($curl_request, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl_request, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl_request, CURLOPT_FOLLOWLOCATION, 0);

    $jsonEncodedData = json_encode($parameters);

    $post = array(
        "method" => $method,
        "input_type" => "JSON",
        "response_type" => "JSON",
        "rest_data" => $jsonEncodedData
    );

    curl_setopt($curl_request, CURLOPT_POSTFIELDS, $post);
    $result = curl_exec($curl_request);
    curl_close($curl_request);

    $result = explode("\r\n\r\n", $result, 2);
    $response = json_decode($result[1]);
    ob_end_flush();

    return $response;
}

// Configure Login Parameters
$login_parameters = array(
    "user_auth"=>array(
        "user_name"=>$username,
        "password"=>md5($password),
        "version"=>"1"
    ),
    "application_name"=>"BoredWookie - Sample Note Pusher",
    "name_value_list"=>array(),
);

// Perform the login action
$login_result = call("login", $login_parameters, $url);

// Get the session id
$session_id = $login_result->id;

// Configure the create-note parameters
$note_params = array(
    'session' => $session_id,
    'module' => 'Notes',
    'name_value_list' => array(
        array(
            'name' => 'name',
            'value' => $notename,
        ),
        array(
            'name' => 'description',
            'value' => $notedesc
        ),
        array(
            'name' => 'parent_type',
            'value' => 'Cases'
        ),
        array(
            'name' => 'parent_id',
            'value' => $caseguid
        )
    )
);

// Create the note
$create_result = call("set_entry", $note_params, $url);

// Obtain the note ID for the created note
$noteId = $create_result->id;

// Display information about what we just did
echo "NoteID: ".$noteId." was created successfully against case: ".$caseguid;