module Restforce::Concerns::API

def upsert!(sobject, field, attrs)

case the conflicting IDs can be found by looking at the response on the error)
error returned if the external ID provided matches multiple records (in which
Raises an exception if an error is returned from Salesforce, including the 300
Returns the Id of the newly created record if the record was created.
Returns true if the record was found and updated.

client.upsert!('Account', 'External__c', External__c: 12, Name: 'Foobar')
# Update the record with external ID of 12

Examples

attrs - Hash of attributes for the record.
field - The name of the external Id field to match against.
sobject - The name of the sobject to created.

Public: Update or create a record based on an external ID 
def upsert!(sobject, field, attrs)
  attrs = attrs.dup
  external_id =
    extract_case_insensitive_string_or_symbol_key_from_hash!(attrs, field).to_s
  if field.to_s != "Id" && (external_id.nil? || external_id.strip.empty?)
    raise ArgumentError, 'Specified external ID field missing from provided ' \
                         'attributes'
  end
  response =
    if field.to_s == "Id" && (external_id.nil? || external_id.strip.empty?)
      version_guard(37.0) do
        api_post "sobjects/#{sobject}/#{field}", attrs
      end
    else
      api_patch "sobjects/#{sobject}/#{field}/" \
                "#{ERB::Util.url_encode(external_id)}", attrs
    end
  response.body.respond_to?(:fetch) ? response.body.fetch('id', true) : true
end