SFDO-API is a convenient way to use the Salesforce API to manipulate objects in a target org. SFDO-API was intended orginally to facilitate the sharing of common API calls across multiple source repositories, but the project is evolving to provide powerful tools for handiling SF objects, like support for managed and unmanaged namespaces, multiple namespaces in an org, etc.

SFDO-API accepts commands from the calling script, and then lets the restforce Ruby gem deal directly with the Salesforce API.


Add this line to your application's Gemfile:

gem 'SFDO-API'

And then execute:

$ bundle

Or install it yourself as:

$ gem install SFDO-API


All examples below are calling code, not SFDO-API code

To create a simple Account and get the ID for that Account:

  def (client_name)
    @account_id = create 'Account', Name: client_name

When issuing a SELECT query, use the select_api() method with your query:

  def create_contact_via_api(client_name, street = '', city = '', state = '', country = '', zip = '')
    @contact_id = create 'Contact', LastName: client_name,
                                    MailingStreet: street,
                                    MailingCity: city,
                                    MailingState: state,
                                    MailingCountry: country,
                                    MailingPostalCode: zip
     = select_api "select AccountId from Contact where Id = '#{@contact_id}'"
     = .first
    @account_id_for_contact = .AccountId

When doing operations for a custom object, leave off any namespace value at the front of the object name, and leave off any custom trailer values like "c" or "r": SFDO-API retrieves the appropriate namespace and trailer values at run time. Instead of addressing "npsp_General_Accounting_Unit_c" use plain "General_Accounting_Unit" instead

      gaus = select_api 'select Id from General_Accounting_Unit'

To delete a single instance of an object for which you have the Id value

  def delete_contacts_via_api
    api_client do
      @array_of_contacts.each do |contact_id|

To delete all instances of an object

  def delete_household_accounts
    api_client do
      hh_accs = @api_client.query("select Id from Account where Type = 'Household'")

Custom Objects

To create instances of custom objects do not use any namespace value at the front of the object name, and leave off any custom trailer values like "c" or "r, SFDO-API handles that for you. Instead of addressing "npsp_General_Accounting_Unit_c" use plain "General_Accounting_Unit" instead:

  def create_gau_via_api(gau_name)
    @gau_id = create 'General_Accounting_Unit', Name: gau_name

When using delete_one_foo or delete_all_foo do not use any custom namespace value, SFDO-API does that for you

  def delete_gaus_via_api
    api_client do
            gaus = select_api 'select Id from General_Accounting_Unit'
puts gaus.inspect

SELECT and UPDATE actions with custom objects

Use the select_api() and update_api() methods without namespaces or trailing characters.

Issuing the select_api() call populates the entire object hash in restforce. Alter the value in the object hash you wish to change, then call update_api() with the altered version of the restforce object hash.

 def (to_value)
    api_client do
      acc_id = select_api 'select Id from Contacts_And_Orgs_Settings'
      acc = acc_id.first
      acc. = to_value

Note that at this time, fields on objects with custom namespaces are not discovered automatically at runtime. See TODO section below:

Using objects where local override changes required fields

Note that ISVs may override required fields on standard Salesforce objects, and these may be needed for SFDO-API to work properly

  # NPSP will automatically create certain fields on certain objects based on required input values for those records.
  # There is no way to know in advance from the API which these are, so we find them empirically and note them here
  # before calling the create() method in SfdoAPI
  @fields_acceptibly_nil = { 'Contact': ['Name'],
                             'Opportunity': ['ForecastCategory'] }


Fields on namespaced object may be namespaced themselves. SFDO-API does not handle this case yet.

Custom fields on standard Salesforce objects may have namespaces. SFDO-API does not handle such fields yet.


After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.


Bug reports and pull requests are welcome on GitHub at https://github.com/SalesforceFoundation/SFDO-API.