Salesforce Writer

Writing to Salesforce

NFT leverages the Salesforce Data Loader (as does the Salesforce Reader) in order to write directly to Salesforce data entities.

It highly facilitates scripting/batching uploading data to Salesforce by using the command line interface (and generating the necessary configuration files for it) of the Data Loader.

In order to write to a Salesforce Entity, use the following syntax:

<Target config="[path to config file]">sfdc://[entity].[method][:[external id field]]</Target>

Salesforce Writer Configuration

The configuration of the Salesforce Writer (and Salesforce Reader) is stored in a separate XML configuration file.

The documentation on that can be found on the Salesforce Configuration File page.

Salesforce Writer Parameters

The following parameters have to be supplied:

Parameter	Description
entity	The target entity in Salesforce; both standard and custom objects are supported. E.g. Account, or MyObject__c
method	One of the following: insert, update, upsert or delete. See below
external id field	Optional: If using the upsert method, supply the external ID custom field here to use for referencing an object.

Example:

<Target config="sfdc_config.xml">sfdc://Account.upsert:SapId__c</Target>

This configuration tries to upsert Salesforce Accounts based on the external ID field SapId__c, which in turn has to be marked "External ID" in Salesforce (see Salesforce documentation on this).

If the external ID field is left out, upsert will try to upsert using the Id field (which has to be present).

Obviously, there has to be a field mapping for the field defined for upserting in the target configuration. In the example, a <Field> must be defined with the name of SapId__c.

Using the insert method

When using the insert method for inserting records to Salesforce, all mandatory fields for the entity must be passed on to Salesforce. This depends on the entity to insert into and has to be verified with the Salesforce API documentation.

Each record written to the target will trigger an insert on Salesforce, even if the same record already exists! Try to rather use the upsert method if you only want to amend or correct data.

Please be aware that you will need the API names of the Salesforce fields, not the Labels. These can be seen either using the Data Loader, or the Setup UI in Salesforce.

An error and a success log will be written to the log files specified in the Salesforce Configuration File.

Using the update method

When using the update method, the Salesforce ID of the entity to update needs to be supplied as a field Id (in the mapping).

Please confer to the Salesforce documentation which fields can be updated on already existing records; this may vary heavily from object type to object type.

Using the upsert method

When using the upsert method, the entity to be upserted (inserted or updated) mandatorily needs a custom external ID field which can be used to reference the objects. This is usually an ID from a second system, such as SAP, or some other database which is used for integrating with Salesforce.

Other than that, the same restrictions apply to upsert as to update regarding updateable fields. Please see the Salesforce API documentation for details.

Using the delete method

The delete method can be used to delete objects/records from Salesforce. It is only possible to delete objects by using their Salesforce ID, which have to be supplied.

The only mapping used is the ID of the objects to be deleted.

Tip: You can retrieve the IDs of objects to be deleted using a SOQL query (see Salesforce Reader) and then immediately issue the delete method on them. Example:

<Transformation>
  <Source config="sfdc_config.xml">soql://select Id from Account where IsBad__c=true</Source>
  <Target config="sfdc_config.xml">sfdc://Account.delete</Target>

  <Mappings>
    <Mapping>
      <Fields>
        <Field name="ID">$Id</Field>
      </Field>
    </Mapping>
  </Mappings>
</Transformation>

Note: Handle with care ;-)

Salesforce Field Mappings

The field names in the field mappings must correspond 100% with the fields in Salesforce. I.e., the field name attribute must match the field name in Salesforce.

Example:

...
<Target config="sfdc_config.xml">sfdc://Contact.insert</Target>
...
<Field name="FirstName">$given_name</Field>
<Field name="LastName">$last_name</Field>
...

Leveraging external ID dereferencing

There is only one exception to this rule, and that is for de-referencing (Salesforce) Lookup fields using external IDs. The Data Loader can reference Lookup objects using their external ID fields (if present), and to use this feature, apply the following syntax to the field definition:

<Field name="[field name]" config="[lookup field]:[external ID field]">[expression]</Field>

Example: Cross-linking Products using Custom Fields

<Field name="ParentProduct" config="ParentProduct__r:SapId__c">$ParentProduct</Field>

In this case, the field ParentProduct__c has the type Lookup(Product2), and Product2 has the custom field SapId__c which is marked as an external ID. When upserting this product record, an SAP ID (SapId__c value) is passed into the ParentProduct__c field; the Data Loader dereferences the correct Salesforce ID value for this SapId__c content.

Please note the usage of the __r suffix instead of the __c suffix for the custom field. This is the standard notation in Salesforce when referencing lookup values. For this method, the field ParentProduct__c becomes ParentProduct__r.

The Salesforce Data Loader can give further information on this technique.