@grouparoo/salesforce

Last Updated: 2021-09-01

Grouparoo's Salesforce plugin enables you to export contacts and groups to Salesforce.

This guide will show you how to work with the Salesforce plugin to create a Destination to export your data.

Install the Salesforce Plugin

To work with the Salesforce plugin, you must first install it in an existing Grouparoo project. You can do this using the install command from our CLI:

$ grouparoo install @grouparoo/salesforce

This adds the package to your package.json file as a dependency, and also drops the plugin in the grouparoo.plugins section in that same file, which enables it.

// package.json
{
// ...
"dependencies": {
"@grouparoo/salesforce": "...",
// ...
},
"grouparoo": {
"plugins": [
"@grouparoo/salesforce",
// ...
]
}
}

Once the plugin is installed, you'll be working primarily with the CLI's configuration commands to get everything set up.

Create a Salesforce App

With Grouparoo, an App is how we establish a connection with a source or destination. Add this connection by generating an App:

$ grouparoo generate salesforce:app my_salesforce_app

This will generate a file at config/apps/my_salesforce_app.js. Open this file and edit the connection details to match your desired configuration. Here is an example of what this config object will look like after generation:

// config/apps/my_salesforce_app.js
exports.default = async function buildConfig() {
return [
{
class: "app",
id: "my_salesforce_app",
name: "my_salesforce_app",
type: "salesforce",
options: {
}
},
];
};

Validating & Applying Your Config

You can validate your config at any time using the validate command:

$ grouparoo validate

And you can apply that config (save it to your Grouparoo application's database) using the apply command:

$ grouparoo apply

Create a Salesforce Destination

Once your App exists, you can generate a Salesforce Destination using the generate command. You must specify a parent, which should match the id of the App you just created.

This is the simplest form of Generator for Destinations:

$ grouparoo generate salesforce:destination salesforce_destination --parent my_salesforce_app

This would generate a config file at config/destinations/salesforce_destination.js in your Grouparoo project. You can then edit this file to match your desired configuration. Here is an example of what this config object will look like after generation:

// config/destinations/salesforce_destination.js

exports.default = async function buildConfig() {
  return [
    {
      id: "salesforce_destination",
      name: "salesforce_destination",
      class: "destination",
      type: "salesforce-export",
      appId: "my_salesforce_app",
      groupId: "...",
      syncMode: "...",

      options: {
        profileObject: "Contact",
        profileMatchField: "Email",
        groupObject: "Campaign",
        groupNameField: "Name",
        membershipObject: "CampaignMember",
        membershipProfileField: "ContactId",
        membershipGroupField: "CampaignId",
        profileReferenceField: "AccountId",
        profileReferenceObject: "Account",
        profileReferenceMatchField: "Name",
      },

      mapping: {
        Email: "email",
        FirstName: "firstName",
        LastName: "lastName",
      },

      destinationGroupMemberships: {
        "High Value Customers": "highValueCustomers",
      },
    },
  ];
};

For more information on what all these properties mean and how to configure them, see Configuring your Destination.

Sync Modes

The Salesforce Destination supports all three sync modes:

  • Sync (sync): Add, update, and remove profiles as needed.
  • Additive (additive): Add and update profiles as needed, but do not remove anybody.
  • Enrich (enrich): Only update profiles that already exist in the Destination. Do not add or remove anybody.

You can set the desired sync mode through the syncMode property in the config file:

syncMode: "additive";

Destination Options

Here are the available options for a Salesforce Destination:

profileObject

Which object in Salesforce represents a Grouparoo profile?

profileMatchField

Which field in the profile Object is used to match Grouparoo profiles?

groupObject

Which object in Salesforce represents a Grouparoo group?

groupNameField

Which field in the group Object is used for the name of a Grouparoo group?

membershipObject

Which object in Salesforce maps the profile object to the group object?

membershipProfileField

Which object in Salesforce maps the profile object to the group object?

membershipGroupField

Which field in the membership Object is the reference to the group?

profileReferenceField

Is there a reference field on the profile Object to fill out?

profileReferenceObject

If there is a reference field, which Object should be created to apply to the profile?

profileReferenceMatchField

If there is a reference field, how should it be matched to Grouparoo profiles?

You can configure these options by setting them inside the options object of the config file:

options: {
  profileObject: "Contact",
  profileMatchField: "Email",
  groupObject: "Campaign",
  groupNameField: "Name",
  membershipObject: "CampaignMember",
  membershipProfileField: "ContactId",
  membershipGroupField: "CampaignId",
  profileReferenceField: "AccountId",
  profileReferenceObject: "Account",
  profileReferenceMatchField: "Name",
},

Property Mappings

These mappings are what tell Grouparoo which Properties you want to sync to the Destination and what they should be called. For this plugin, Grouparoo Properties can be mapped to a Salesforce Object specified on the options object.

You can also map to custom attributes that you've defined on Salesforce by adding them directly to the mapping object (also include the __c suffix).

Here's an example of how this would look in the config file. Note that the keys refer to Salesforce Attribute names and values refer to Grouparoo Property IDs.

mapping: {
  Email: "email",
  FistName: "firstName",
  "custom_lifetime_value__c": "ltv",
},

Group Mappings

You can use Group Memberships to automatically add your contacts to Salesforce Objects, defined by the property groupObject on the options object.

Here's an example of how to configure this in the config file. Keys refer to the name of the tag to be shown on Salesforce and values refer to the Grouparoo Group ID.

destinationGroupMemberships: {
  "High Value Customers": "highValueCustomers",
},

Salesforce Next Steps

Once you have the plugin installed, App created, and a Source or Destination configured, you are ready to validate, apply, then import or export your data!