SalesforceCache: SFDC sObject / SOQL Request Caching

Synopsis

Salesforce sObject system to retrieve and cache queries from Salesforce.com including sObjects and SOQL results. This currently uses the file system to cache results though other storage methods may be supported in the future.

Prior to version 0.0.6, SalesforceCache was named SalesforceFsdb.

Installing

To install SalesforceCache, use the following command:

$ gem install salesforce_cache

Examples

require 'salesforce_cache'

paramsGeneral     =  {
  :api_fqdn       => 'na1.salesforce.com',
  :api_version    => '29.0',
  :data_dir       => '/path/to/sf_data',
  :max_age        => 60*60*24*7,            # seconds
  :disable_remote => false                  # optional
}

paramsToken       =  {
  :grant_type     => 'password',
  :client_id      => 'my_client_id',
  :client_secret  => 'my_client_secret',
  :username       => 'my_username',
  :password       => 'my_password'
}

# using the filesystem cache with max_age
sfCacheClient = SalesforceCache::Client.new(paramsGeneral,paramsToken)
sObjectHash   = sfCacheClient.getSobjectForSfidAndType('my_sobject_id','Account')

sSfid = '1234567890'
sSoql = %{ SELECT Id,AccountId,Name,IsWon,StageName,CloseDate from Opportunity where AccountId='\#{sSfid}' }
sPath = "AccountOpportunities/sf_act_\#{sSfid}_opps.jff"

dResults = sfCacheClient.getResForSoqlAndPath( sSoql, sPath )

# without using a filesystem cache
sfRestClient = SalesforceCache::RestClient.new(paramsGeneral,paramsToken)
sObjectHash  = sfRestClient.getSobjectForSfidAndType('my_sobject_id','Account')

# get list of cached Ids as an array of hashes of format: {:id=>id,:type=>type}

ids = sfCacheClient.getCachedIds                             # all cached Ids for all types
ids = sfCacheClient.getCachedIds('Account')                  # all cached Account Ids
ids = sfCacheClient.getCachedIds('Account,Opportunity')      # cached Account & Opporunity Ids
ids = sfCacheClient.getCachedIds(['Account','Opportunity'])  # cached Account & Opporunity Ids

Documentation

This gem is 100% documented with YARD, an exceptional documentation library. To see documentation for this, and all the gems installed on your system use:

$ gem install yard
$ yard server -g

Notes

  1. Max Age

The :max_age parameter is used to indicate the maximum age in seconds for cached data. If local data exceeds maximum age, a new copy of the data is retrieved from Salesforce.com. To ensure retrieval of a new copy, use :max_age=-1.

  1. Disable Remote Requests

If the optional :skip_remote parameter is set to true, the :max_age parameter is ignored and a local copy will be used if available. A remote call to Salesforce will not be issued if a local cache is not found. This is for environments when it is undesirable to make outside requests.

The default value is false.

  1. Directory Paths

    1. Salesforce Sobjects are stored on the file system under File.join( paramsGeneral[:data_dir], Sobject_type ).
    2. SOQL results are stored in the path indicated. Sub-directories are created for SOQL paths. If a relative directory is provided, it is appended to the :data_dir. If an absolute directory is provided, it is used as an absolute directory in its entirety.

  2. Object Size

Some large Salesforce Objects may generate Salesforce errors. A future release will allow specifying specific fields for retrieval.

  1. Redirection

In the event an Account sObject request results in a NOT_FOUND error for a given Salesforce Id, the library will attempt to use the Id as an Opportunity Id and, if successful, will return the proper Account sObject.

Change Log

  • 2014-03-07: 0.0.8
    • Add #getCachedIds([type]) method to get Ids of cached items for iteration
  • 2014-03-06: 0.0.7
    • Documentation fix for example
  • 2014-03-05: 0.0.6
    • Ability to disable remote downloading from Salesforce.com when it is not desirable
    • Convert README and CHANGELOG files to Markdown format
    • Rename to SalesforceCache from SalesforceFsdb
  • 2014-03-05: 0.0.5
    • Deprecation notice for SalesforceFsdb
  • 2014-02-19: 0.0.4
    • Add "redirect" in case an Opportunity Id is presented for an Account sObject
    • Add autoload to enable "require 'salesforce_fsdb'" (now require 'salesforce_cache')
  • 2014-02-06: 0.0.3
    • Add SOQL result caching
  • 2014-01-28: 0.0.2
    • Use sObject types in filenames to enable wider, more generic sObject support
  • 2014-01-27: 0.0.1
    • Initial release
    • Filesystem cache of Account, Contact, Opportunity and User sObjects.

Please see the CHANGELOG document for additional release information.

Links

Salesforce REST API Reference

http://www.salesforce.com/us/developer/docs/api_rest/

Copyright and License

SalesforceCache © 2014 by John Wang.

SalesforceCache is licensed under the MIT license. Please see the LICENSE document for more information.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.