Salesforce

Polytomic connects to Salesforce using OAuth and requires a Salesforce account with read-write permissions. While not required, we recommend you create a user in Salesforce exclusively for Polytomic so that the audit logs in Salesforce distinguish all Polytomic activity.

📘

Salesforce sandbox

Connecting Polytomic to a Salesforce sandbox is no different than connecting to a production instance; the same instructions apply. Indeed, if you have a Salesforce sandbox available we recommend you create two Salesforce connections in Polytomic: one to your sandbox for testing and one to your production instance.

Creating a connection

1. In Polytomic, go to Connections → Add Connection → Salesforce.

2. Pick your connection name and enter your unique Salesforce domain or ID. The domain is often a string in the format foocorp.my.salesforce.com. You can also enter your unique ID instead, foocorp in this case.

3. Click Connect to Salesforce and go through OAuth authentication using a Salesforce account. Successful authentication will result in the connecting username being shown:

4. Click Save.

Connection maintenance

• Polytomic automatically enforces a conservative daily Salesforce API-call limit on itself derived from your Salesforce instance. You can override Polytomic's automatic behavior with a specific daily API-call limit of your choice by ticking the Enforce API limits box.
• If you need to change the authorized user, you can click the Force reconnect button and re-authenticate the connection with the new user.

Syncing from Salesforce

Formula fields

When it comes to Salesforce formula and rollup fields, many vendors skip syncing them or write them into intermediate representations in your data warehouse, in which case you need to do the work to parse and combine them with the rest of your data to see their true values.

Polytomic represents Salesforce formula and rollup fields as any other field, thus avoiding causing inconvenience for the data consumer. That is, when syncing from Salesforce to your other systems (data warehouses included), Polytomic materialises formula fields in the destination system as standard fields/columns, just like any other Salesforce field.

This applies to all formula fields, whether numeric, currency, date, text, or other. There is no special processing required on your part to digest the formula field values synced by Polytomic.

To do this, Polytomic syncs a bit more data beyond just checking Salesforce's last_modified timestamps (as those don't update with formula and rollup field updates).

At large scale, your data may be too large to wait for this sync every time. In that case, you can specify a multi-schedule frequency for your Salesforce bulk sync into your data warehouse, by picking the Per field type schedule option:

This will set up two separate schedules:

• Purely incremental updates based on last_modified fields and their analogues. These updates will not propagate updates to formula and rollup fields, but they will be fast. Fields that do not update on the incremental schedule are marked with a tortoise icon (as shown in the screenshot below).
• Non-incremental updates which will update the whole lot, including formula and rollup fields. In this scenario you can think of this as a catch-up sync to the latest formula and rollup field values.

Tooling API objects

Polytomic supports syncing from the metadata objects behind Salesforce's Tooling API (e.g. Entity Particles and others). To surface those in your Salesforce connection, make sure to tick the Enable support for Tooling API box in your Salesforce connection:

Surfacing these objects will consume a few extra Salesforce API calls.

History cutoff

When syncing objects from a large Salesforce instance, you may want to avoid syncing all history. You can set a history cutoff date in Polytomic which will restrict the sync to only those Salesforce records that were last updated after your chosen cutoff date:

While Polytomic offers a global date cutoff, you can also override this on a per-object basis:

And, of course, if you'd like even finer per-object filters to apply before your Salesforce data starts syncing, you can also use Polytomic's bulk sync table filters.

Syncing to Salesforce

Setting relationships between objects

When syncing to a Salesforce object, you are able to set relationships to other objects as part of your sync. For example, you may be creating a User record in Salesforce that requires a relationship set to a corresponding Usage Statistics custom object.

You can set these relationships using Polytomic by mapping to Salesforce find by fields. These are special target fields in Polytomic that are solely for relationship-setting within Salesforce. Syncing to them means finding the listed object by the designated field value then setting a relationship to it.

In the below screenshot, we have a sync to Contacts but, as part of the same sync, we are creating a relationship to Accounts using the ID field on Accounts:

If you need to set relationships to multiple instances of an object, just pass an array of IDs on the left-hand side of your mapping.

📘

Salesforce Enternal ID requirement

If you want to create a relationship (e.g. Accounts in the above screenshot), make sure the relationship field on the target object is marked as an External ID in Salesforce.

Substring-match identity mapping

By default, Polytomic will use exact equality as the matching function in your identity mapping. But there are situations where you may want a substring match. For example, if your source identity values are domains (e.g. acme.com) while your Salesforce target identity values are URLs (e.g. https://www.acme.com). This is a case where you may want a match despite the text on the two sides being different.

After you specify your identity mapping, you can enable substring identity matching by clicking on Equals and choosing Substring of instead, as shown in these screenshots:

Delete mode

When syncing to Salesforce, one of the sync modes supported by Polytomic is Delete mode:

This deletes designated records in Salesforce. Specifying what should be deleted is like with any other sync: pick your identity mapping from your source and set any filter conditions (other field mappings are unnecessary in this mode):

In the example above, Polytomic will delete all Contacts in Salesforce that meet these two conditions:

• The Salesforce Email field value matches that of the Email field of the source model.
• The source model's Is deleted field for the matching record is set to true.

Advanced settings

When syncing to Salesforce, you can override a few advanced settings at the bottom of your sync configuration:

Each setting is explained below:

Ingestion API (default: Automatic)

Salesforce can ingest data using either its Bulk APIs, or its REST API. The former is suited for larger datasets while the latter is best for small datasets.

Polytomic's default value here is 'Automatic', which means Polytomic will mix and match different Salesforce ingestion APIs depending on your data volumes. You can force Polytomic's use of certain APIs by overriding this section, though make sure you have a good reason to do so, as the vast majority of workloads don't need any modifications here.

Sort batches by (default: None)

You can instruct Polytomic to sort the records within the batches it sends to Salesforce by a particular ID in the data. This is rarely required except in a minority of cases where internal automations specific to your Salesforce instance may require this.

Copy null values (default: off)

If you're writing a null value to a Salesforce field, Polytomic's default behaviour is to not overwrite the Salesforce field with null. Turning on this setting means that sending a null value to a field in Salesforce will set the destination Salesforce field to null to match the source.

Ignore invalid external ID references (default: off)

When setting relationships as part of your sync to Salesforce, Polytomic's default behaviour is to drop source records if they contain an invalid relationship ID. Turning on this setting means that Polytomic will write the record anyway (and will log an entry in the Warnings column of your sync history, informing you of an invalid relationship attempt).

Only update if different from Salesforce (default: off)

When updating records in Salesforce, Polytomic will write all fields, even if the source value for a field is the same as the destination field's value in Salesforce. This is most efficient and almost always harmless, but there are rare situations where you may not want this. For example, if your Salesforce instance has an automation that fires every time a field is written to, even if the new value is identical to the old one.

In the above scenario you may want to block Polytomic from writing to fields in Salesforce with identical values, which you can do by turning on this setting. Once on, Polytomic will only write field values to Salesforce that differ from the existing values in Salesforce.

Note: turning this on will consume more Salesforce API calls.

Always do a full sync (default: off)

By default, all Polytomic's Model Syncs are differential: only updated/new records are synced since the last time. If, due to a particular idiosyncrasy within your Salesforce instance, you need all records synced on each run, you can do so by turning on this setting.

Skip backfill on first sync (default: off)

Polytomic's first sync is always a full one: all records from the source model(s) are synced to Salesforce (i.e. a backfill takes place). Subsequent syncs are then differential.

You may want to only sync future changes without an initial backfill. You can do by turning on this setting.