jSugar

jsugar Node.js library is a REST API Client that addresses a server running SugarCRM.

SugarCRM's REST API is available on a SugarCRM server at the path http://<domain name>/service/v4_1/rest.php.

jsugar relies on Mocha and Chai for unitary testing. It relies on Istanbul for code coverage. And, it uses Travis CI for continuous integration and Coveralls.io to display test coverage.

Quick Startup

Test if the server is responding

const jsugar = require('jsugar');

const domain = 'http://www.xxxxx';   // the domain name of the server,

jsugar.getServerInfo(domain, (error, res) => {
  // the server returns:
  // res = { data: { flavor: 'CE', version: '6.5.x', gmt_time: '201x-xx-xx h:mn:s' } }
});

Retrieve the number of records in a given module

const jsugar = require('jsugar');

const domain = 'http://www.xxxxx';  // the domain name of the server,
const username = 'xxxxx';           // the account username,
const password = 'xxxxx';           // the account password,

// Get a session ID:
jsugar.login(domain, username, password, (error, res) => {
  const id = res.data.id;

  // Retrieve the number of Accounts
  const params = {
    session: id,
    module_name: 'Accounts',
    query: '',
  };
  jsugar.call(domain, 'get_entries_count', params, (error, res) => {
    // the server returns:
    // res = { data: { result_count: '561' } }

    // Close the session:
    jsugar.logout(domain, id);
  });
});

Retrieve the name of the first 20 records of 'Accounts'

const jsugar = require('jsugar');

const domain = 'http://www.xxxxx';  // the domain name of the server,
const username = 'xxxxx';           // the account username,
const password = 'xxxxx';           // the account password,

// Get a session ID:
jsugar.login(domain, username, password, (error, res) => {
  const id = res.data.id;

  // Retrieve the Accounts' records
  const params = {
    session: id,
    module_name: 'Accounts',
    query: '',
    order_by: '',
    offset: 0,
    select_fields: ['name'],
    link_name_to_fields_array: [],
    max_results: 20,
    deleted: false,
    favorites: false,
  };
  jsugar.call(domain, 'get_entries_list', params, (error, res) => {
    // the server returns:
    // res = {
    //   data: {
    //     result_count: 20,
    //     total_count: '50',
    //     next_offset: 20,
    //     entry_list: [
    //       [Object],
    //       [Object],
    //       [Object],
    //       ...
    //     ],
    //     relationship_list: []
    //   }
    // }

    // Close the session:
    jsugar.logout(domain, id);
  });
});

API

jsugar provides five functions:

• getServerInfo() tests if the server is responding,
• login() returns the session ID,
• getUserID returns the User ID,
• call() processes a SugarCRM's method,
• logout() closes the session.

getServerInfo (domain, callback)

getServerInfo requires two arguments:

• the domain name of the server,
• a callback function.

The callback gets two arguments: error and the server response.

error is null or contains the error message.

The response object contains:

{ data: { flavor: 'CE', version: '6.5.x', gmt_time: '201x-xx-xx h:mn:s' } }

login (domain, username, password, callback)

login requires four arguments:

• the domain name of the server,
• the account username,
• the account password,
• a callback function.

The callback gets two arguments: error and the server response.

error is null or contains the error message.

The response object contains:

{ data: { id: 'dfa56ebd6b383d746794530ade564c7c', ... }}

id is the session ID.

getUserID (domain, id, callback)

getUserID requires three arguments:

• the domain name of the server,
• the session id,
• a callback function.

The callback gets two arguments: error and the server response.

error is null or contains the error message.

The response object contains:

{ { data: '684f6427-2168-a221-a418-4d4ffa3fc397' }}

datais the User ID.

call (domain, method, params, callback)

call gets four arguments:

• the domain name of the server,
• the SugarCRM's method to execute,
• the parameters associated to this method,
• a callback function.

The method argument is a string that matches the SugarCRM method to process. For instance method="get_entries_count". The parameters argument is an object. Its content depends on the method. The first key/value pair is the session ID (§ quick startup).

The callback gets two arguments: error and the server response.

error is null or contains the error message.

The response object depends on the selected method. For instance get_entries_count returns:

{ data: { result_count: '561' } }

Enjoy!

License

MIT.