Skip to main content

NULL and Blank Handling

Understanding how Speediful processes NULL values and empty strings is crucial for achieving the desired data outcomes in Salesforce. Speediful aims for compatibility with existing conventions across different Salesforce APIs.

The way NULL values and empty strings are handled differs between the SOAP API and Bulk APIs due to the underlying capabilities of each Salesforce API.

API Comparison Table​

Value TypeBulk APIsSOAP (ignore_nulls=0)SOAP (ignore_nulls=1)
NULLBlanks fieldBlanks fieldPreserves data
Empty string ('')Preserves dataBlanks fieldBlanks field
#N/A string ('#N/A')Blanks field'N/A''N/A'
Whitespace/NBSPWrites to SFWrites to SFWrites to SF

SOAP API Behavior​

Default Behavior (@ignore_nulls = 0)​

By default, NULL values and empty strings are processed the same way via the SOAP API:

  • NULL value: Sets the field to blank in Salesforce (behaves like empty string)
  • Empty string (''): Sets the field to blank in Salesforce

This means that both NULL and empty string will explicitly blank out the field value in Salesforce.

Ignore Nulls Enabled (@ignore_nulls = 1)​

When @ignore_nulls is set to 1:

  • NULL values: Are ignored and not sent to Salesforce - existing data or field defaults are preserved
  • Empty string (''): Still sets the field to blank in Salesforce

This option allows you to update only the fields with actual data while preserving existing values for NULL fields.

Bulk API Behavior (Bulk v1 and Bulk v2)​

The Bulk APIs do not support the @ignore_nulls parameter. Their behavior is fixed:

  • NULL value: Sets the field to blank in Salesforce
  • #N/A string ('#N/A'): Sets the field to blank in Salesforce (This is a Salesforce special value)
  • Empty string (''): Has no effect - existing data or field defaults are preserved

Important Notes​

What Counts as an Empty String?​

An empty string is exactly '' - a zero-length string. The following are NOT empty strings and will write their data to Salesforce:

  • Strings containing whitespace (spaces, tabs, etc.)
  • Strings containing non-breaking spaces (NBSP)
  • Any string with a length greater than zero

Default Values​

Salesforce only sets default values during record insert operations, and only if the field is not being set to blank. Default values are not applied during update operations, regardless of whether fields are blanked or omitted.

Best Practices​

  1. Backup data to establish a rollback snapshot before performing a data load

  2. Be explicit for update/upsert operations:

    • NULL is the consistent way to blank out data across the APIs
    • Ensure you know how NULL and blank data in your source dataset should be interpreted and handled
    • Use the backup data to provide defaults when preparing the data to be loaded

  3. Check your data to ensure no unintended whitespace is being treated as real data

  4. Test Before Production to validate the results of your intended operations