SFDO::API
SFDO-API is a convenient way to use the Salesforce API to manipulate objects and fields on 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.
Installation
Add this line to your application's Gemfile:
gem 'SFDO-API'
And then execute:
$ bundle
Or install it yourself as:
$ gem install SFDO-API
Usage
All examples below are calling code, not SFDO-API code
To create a simple Account and get the ID for that Account:
def create_account_via_api(client_name)
@account_id = create 'Account', Name: client_name
end
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
account_object = select_api "select AccountId from Contact where Id = '#{@contact_id}'"
my_account_object = account_object.first
@account_id_for_contact = my_account_object.AccountId
end
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'
Likewise, when addressing custom fields, leave off any namespace values for the fields involved
#@relationshiop_id = create 'Relationship', npe4__Contact__c: contact, npe4__RelatedContact__c: related_contact
@relationshiop_id = create 'Relationship', Contact: contact, RelatedContact:
To delete a single instance of an object for which you have the Id value
def delete_account_via_api
delete_one_account(@account_id)
end
def delete_contacts_via_api
api_client do
@array_of_contacts.each do |contact_id|
delete_one_contact(contact_id)
end
end
end
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'")
delete_all_household_account(hh_accs)
end
end
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
end
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
delete_all_General_Accounting_Unit(gaus)
end
end
Likewise when using custom fields on any object, 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_Unitc" use plain "General_Accounting_Unit" instead, and instead of the field "npe01Account_Processor_c" use just "Account_Processor"
#@contact_id = create 'Contact', LastName: contact_name, MailingCity: 'hhmailingcity', npo02__Household__c: @hh_obj_id
@contact_id = create 'Contact', LastName: contact_name, MailingCity: 'hhmailingcity', Household: @hh_obj_id
SELECT and UPDATE actions with custom objects and custom fields
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 update_account_model(to_value)
api_client do
acc_id = select_api 'select Id from Contacts_And_Orgs_Settings'
acc = acc_id.first
#acc.npe01__Account_Processor__c = to_value
acc.Account_Processor = to_value
update_api(acc)
end
end
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'] }
TODO
At this time SFDO-API does not accept custom fields that are properly named. For example if a field is in fact named "npe01_Account_Processor_c" that field must be addressed as "Account_Processor" and will not function properly if the calling code uses the properly namespaced value of the field.
Development
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.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/SalesforceFoundation/SFDO-API.