Discover. Learn. Grow.

In the Pull Criteria tab, you can configure which data you'd like to get from Salesforce, and add into CustomerGauge.

To help you on your way, this article is split in two sections; "Setup" and "Details".

The former section will help you set-up, and goes more into the how, whereas the latter helps you avoid common pitfalls.

We recommend you to use this article as reference, as you work through each field.

Setup

Pull Setup

Pulling records from Salesforce into CustomerGauge is optional.

In case you just want to have your survey results in Salesforce, you would want to directly go to the Outgoing Webhooks.

For the purpose of this support article, we'll assume that you do want to Pull data from Salesforce.

Pull method

You can pull records from Salesforce automatically on a periodic basis, or wield the power yourself and do a manual pull.

Important note: Salesforce allows pulls of up to 2000 records. Should you need to pull more records, you'd need to Pull multiple times.

This counts for both Manual Pull and Automated Pull.

Manual Pull

Manual Pulls are ideal when you're testing, and/or when you want to closely monitor what gets pulled, sent out, etc.

To actually perform the Manual Pull, you should go through all the steps, review them in the Confirm tab, and hit the "Pull" button!

Automated Pull

With the Automated Pull we offer you a few settings to control when you pull records exactly.

Start date:

The start date option allows you to set at which date you want to start pulling.

The start date also decides on which day/date we pull records; more about that below.

Frequency:

Hour:

We'll pull again every hour, starting at the hour set next to the start date.

Day:

We'll pull again every day, at the configured hour.

Week:

We'll pull again every same weekday, at the configured hour.

For example, if the start date is a Monday 10:00, we'll pull every next Monday at 10:00.

Month:

We'll pull again every month on the same date.

For example, 31st becomes 30th on months where the 30th is the last day of the month.

Note: if the date exceeds the month, it'll fall back on the last day of the month.

Quarter:

We'll pull again every quarter on the same date.

For example, if we first pull on the 31st of March, we'll pull again on the 30th of June (3 months later).

Note: if the date exceeds a month, it'll fall back on the last day of that month.

Half year:

We'll pull again every half year on the same date.

For example, if we first pull on the 30st of June, we'll pull again on the 31st of December (6 months later).

Note: if the date exceeds a month, it'll fall back on the last day of that month.

Year:

We'll pull again every year on the same date.

For example, if we first pull on the 1st of January, we'll pull again on the 1th of January next year.

Note: if the date exceeds a month, it'll fall back on the last day of that month.

Number of Days:

We'll pull again every "nth" number of days after the configured Start Date.

Note: the date when the first Pull will happen is calculated as (Start Date + number of days). For example, if your Start Date is "01 January", and your number of days is "2", the first Pull will happen at "03 January".

Pull Details

Query

Writing a Query

You can write your Salesforce query using SOQL.

To learn more about SOQL, read here: https://developer.salesforce.com/docs/atlas.en-us.216.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm

To learn more about using date fields in your WHERE clause, read here:

https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_dateformats.htm?search_text=update

Testing your Query

To make sure your SOQL Query works and pulls the right data, you can go to https://workbench.developerforce.com/.

Jump to "SOQL Query", and select your main object under Object.

Simply copy/paste your SOQL Query from CustomerGauge, and run it in the Workbench and verify the results.

Pull Mapping

To set up which Salesforce field goes to which CustomerGauge field, you have to define your mapping in JSON.

Use CustomerGauge fields as the JSON key, and the Salesforce field (in a string, encapsulated in between curly brackets).

You can use this textbox to configure what data from Salesforce goes to which field in CustomerGauge. This should be valid JSON; we recommend validating your JSON before saving, using a tool like JSON Lint.

Case sensitivity

While in the Pull Query field names are not case sensitive, they are in the Pull Mapping!

Make sure that the Salesforce Field Names you use in the Pull Mapping match the capitalization of API names in Salesforce.

Details

How do I know what the CustomerGauge fields are called?

Right next to the Pull Mapping field, there is an area containing all available fields you can pull data into.

Simply copy the field name in the "CustomerGauge field" column, and add it as the JSON key in the Pull Mapping.

How do I know what my Salesforce fields are?

You can find your objects and fields in Salesforce's Object Manager.

Find the Objects you want to pull, and then go to the "Fields & Relationships" tab.

Use the values found in the "Field Name" (not "Field Label") column for your Pull Mapping.

Use the lowest relation when pulling from multiple objects

Pulling from multiple objects is quite easy, provided that the objects have a relationship.

Salesforce takes care of the relationship, so you just have to specify the fields and their objects.

However, there is a catch — Salesforce won't know which records to use from an object if there are multiple candidates.

To explain this, we'll have a look at a bad example;

SELECT
  Id,
  FirstName,
  LastName,
  Email,
  Case.Id,
  Case.Subject
FROM Contact

This is bad, because one contact can contain multiple cases.

We should change this query so that we use the lowest relation, which in this case is "Case" (pun slightly intended);

SELECT
  Contact.Id,
  Contact.FirstName,
  Contact.LastName,
  Contact.Email,
  Id,
  Subject
FROM Case

Since a Case can't have multiple Contacts, this is okay!

You can use Salesforce's Schema Builder to see the relationships between objects.

If multiple lines enter an object (  ), it's an object with multiple candidates.

This means that you probably want to use that as the main object to pull from.

If there is no relationship between objects, you should either

• Find a mutually connected object and use that as the main object to pull from
• Create a custom relationship field to connect the objects involved

Differences in Sandbox connections

Pull Mapping for Sandbox

Due to how Salesforce returns data from Sandbox systems, you'll need to write your pull mapping slightly different.

To successfully pull from your Sandbox environment, you'll need to prefix your Salesforce fields with "fields." (except for the Id field).

{
  "number_customer": "{Id}",
  "first_name": "{fields.FirstName}",
  "last_name": "{fields.LastName}",
  "email": "{fields.Email}"
}

Not adding the "fields." prefix will result in empty values for those fields.

You do not need to prefix the main "Id" field.

Pull Mapping for Sandbox with multiple Objects

To successfully pull from multiple objects from your Sandbox environment, you'll need to prefix each additional Object with "fields.".

{
  "number_customer": "{Id}",
  "segment_a": "{fields.Status}",
  "first_name": "{fields.Contact.fields.FirstName}",
  "last_name": "{fields.Contact.fields.LastName}",
  "email": "{fields.Contact.fields.Email}"
}

For easy reference, see the example below how to convert your queried fields to your pull mapping below;

Certain fields return the value 'true' when they're blank

In Sandbox connections, Salesforce returns the value 'true'  on the field types Email, Phone, Fax, Address, Text, Date, Datetime, if they're blank.

We will store 'true' in CustomerGauge, as that is what Salesforce returns to us.

Examples

Simple query, single object

The most simple example would be to just pull the first name, last name, and e-mail, as well as the main Salesforce reference.

SELECT
  Id,
  FirstName,
  LastName,
  Email
FROM Contact

The Pull Mapping would then be as displayed below.

{
  "number_customer": "{Id}",
  "first_name": "{FirstName}",
  "last_name": "{LastName}",
  "email": "{Email}"
}

We map Contact ID, First Name, Last Name, and Email to their respective CustomerGauge fields (note that the Salesforce fields are in between single {} brackets).

Prevent pulling flagged objects

You probably don't want to pull the same records multiple times — which is what we're doing in the above example.

To prevent this from happening, you can Flag records that are pulled, and then exclude them in your query (using the WHERE clause).

Note that you'd usually use a custom field to set this status.

SELECT
    Id,
    FirstName,
    LastName,
    Email,
    Owner.Name
FROM Contact
WHERE CGuploaded__c != true

Static data

You can also provide static data when pulling data from Salesforce.

This is particularly useful if you want to filter or segment based on the source of your data later on!

The Pull Mapping would then be as displayed below.

{
  "number_customer": "{Id}",
  "first_name": "{FirstName}",
  "last_name": "{LastName}",
  "email": "{Email}",
  "segment_z": "Salesforce"
}

We put the value "Salesforce" in segment_z, so we can segment our reporting based on source of data.

Note that we have not encapsulated "Salesforce" with curly brackets, so we'll directly treat it as the value.

Multi-object references

When referencing to fields from objects other than the main object, you should specify the Object before the Field, separated by a dot.

For example, to get the Owner Name of a Contact, you would select "Owner.Name".

You would then refer to that in your pull mapping with an underscore, rather than a dot. 

Following the same example, we would use "Owner.Name" in the Pull Mapping.

In short; if there is a dot in the query, use an underscore in the Pull Mapping.

For example, the following simple query will return the Account Manager's name, along with other data.

SELECT
  Id,
  FirstName,
  LastName,
  Email,
  Owner.Name
FROM Contact
WHERE id IN('XXX')

The Pull Mapping would then be as displayed below.

{
  "number_customer": "{Id}",
  "first_name": "{FirstName}",
  "last_name": "{LastName}",
  "email": "{Email}",
  "segment_j": "{Owner.Name}"
}

Examples

Looking for some inspiration, or would you just like to see more examples?

Our Examples page should help you on your way!

Got stuck?

Don't worry, we got you! Visit our Troubleshooting support article to see how to solve your issue. If your issue is not listed here, please let us know so we can expand it !

« Back to "Authenticate"

Continue to "Flag Criteria" »