1/32

Engage for Salesforce Documentation

11/2/2015

Overview

What is Engage for Salesforce?

Engage for Salesforce is a Salesforce application (available from the AppExchange) integrating the leading advocacy and grassroots technology, Engage, with Salesforce, the leader in CRM. Leverage your Engage and Salesforce data using Engage for Salesforce to:

Eliminate double entry and manual imports.

Eliminate complicated record matching in Excel or with other tools.

Centralize your view of your advocacy campaign.

Add value to your advocacy data by integrating with Salesforce. Once installed, Engage for Salesforce will synchronize user data, elected officials data, and activity data from the date of activation forward. Any new activity on your Engage site, or updates made to your Salesforce records, will be appropriately synchronized following activation.

Administration

Who Should Setup Your App CQ Roll Call recommends a Salesforce Administrator or Business Systems Analyst follow the below documentation to provision and install Engage for Salesforce. If you require service support to provision and install the application, CQ Roll Call will refer you to a trusted service provider. Please contact us for additional information. engageforsalesforce@cqrollcall.com /202-650-6443

2/32

Provisioning & Installation

Overview of Process

1. Preparation and Summary of Events 2. Provisioning of an Engage site. 3. Provisioning of the Engage Connect service 4. Uploading of initial Salesforce data set into Engage 5. Installation of the Engage for Salesforce in the Salesforce org 6. Configuration of Engage for Salesforce in the client’s Salesforce org

a. Connect Application service credentials and sync options are set 7. Testing Engage for Salesforce.

Note: Engage for Salesforce makes updates to your Salesforce instance. Updates that occur after October, 29 2015 will only impact clients on base package 1.27.5 or a later version. If there any validation rules, triggers (either set up by your administrators or by any 3rd party applications) etc. that check or verify contact/activity/campaign creation (i.e. address, zip-code, email, other field formats shared between the two systems or other requirements) they may cause conflicts with the Engage for Salesforce plug-in. These conflicts can cause the sync to fail.

Preparation & Summary of Events

Prepare Engage Instance: Provisioning

Your Engage Account Executive should provide you with login information for your Engage site, as well as an initial username and password for the Connect Application. If you need to create an alternate username and password, you can do from your Engage site via "Connect Applications" (under the Sites drop down). Note: The Connect Application credentials are different that your Engage login credentials. To begin the process, access Engage Admin>Account>Connect Applications>Enter Credentials>Submit

Prepare Engage Instance

Install App Validate

Sync Configure Settings

Data Integrity

3/32

4/32

Install the app from the Salesforce AppExchange

You may be asked to log into the destination Salesforce Organization during this process. First navigate to the URL below or perform a search in the Appexchange to find the application. Search for "Engage for Salesforce" or follow this link. https://appexchange.salesforce.com/listingDetail?listingId=a0N3000000B519uEAB

5/32

The Engage for Salesforce AppExchange listing will load. Click ‘Get it Now’

6/32

Login using your Salesforce credentials. If you are already logged in, you will see the second screenshot below. In either case click the item indicated by callout #2.

If you want to install the app first in your SandBox, then in Production (recommended), you will need to select ‘Install in Sandbox’ or replace the initial portion of the URL with https://test.salesforce.com./ which will load the sandbox installation page. You should be prompted to select Production or Sandbox. If you are not, append the URL, as needed.

Read and agree to the terms and conditions. Select the checkbox and click ‘Confirm and Install’

7/32

The installer will ask you to permit data to be shared with a third-party website. These are the web-based services to which Salesforce connects to access Engage data. Select ‘Approve’ and click ‘Continue’.

Your version of Salesforce may require approval of the API Connection. Select ‘Yes’ and click ‘Continue’

8/32

Once the installation is complete, you will be redirected to view all installed packages. Validate ‘Engage for Salesforce’ is listed.

Optional: Installing the Extension Package V1.3.2

The Extension package is dependent on your Salesforce Org’s use of Campaigns. If you do not have Campaigns, there is no need to install the extension package. Please continue to Configuration. Prior to beginning the configuration process if you do have Campaigns, it is necessary to also install the Engage for Salesforce Extension to the Base package. The Base Package installs and syncs Contacts, Advocates, and Elected Officials objects. The Extension Package installs and syncs Engage Activities. In order for Engage Activities (e.g. Write a Letter, Make a Call, etc.) to appear and sync in Salesforce, both packages must be installed. To install the extension click the following link.

https://login.salesforce.com/packaging/installPackage.apexp?p0=04tj0000001iJXN If not prompted and you want to install to the Sandbox, it is necessary to append the URL to be https://www.test.salesforce.com/

9/32

10/32

Before beginning configuration, validate you are in the Engage for Salesforce App. You can tell by viewing the Engage banner at the top of the screen, or selecting the Engage app in the App drop down menu on the right side of your installed packages page.

11/32

Configuration

Select Engage for Salesforce from your installed packages.

The Engage for Salesforce splash-page will load.

12/32

Configuration of the Credentials

Click the ‘Configuration’ tab. This will configure credentials for the base package, to allow syncing of contact and advocate records and elected officials.

Enter the Username, Password, and Endpoint associated with your Connect Application. The Username and Password should be provided for you by your Engage Account Executive. These are not the same credentials as your Engage Admin access username and password. Be sure to save your changes. If you do not remember these credentials, login to Engage Admin>Account>Connect Application and they will be stored there. If you’re still having trouble, contact your Account Executive. The Endpoint URL is (the default for all Engage customers): https://connect.cqrcengage.com/api/v1

13/32

Click on the Campaign Configuration tab. This will configure credentials for the extension package, to allow syncing of Engage activities. Enter the Password associated with your Connect Application. Your Username and Endpoint will already be pre-filled. Be sure to save your changes. Click the ‘Advanced’ tab. Test your credentials. Click the ‘Check Engage Credentials’ button.

The ‘Engage Connection’ status should change from ‘Not Tested’ to ‘OK. See callout #1. If the status changes to ‘Failed’, verify the username, password, and endpoint. Then repeat the ‘Check Engage Credentials’ process again.

14/32

Configuring your Sync Preferences

Once Engage for Salesforce successfully connects to the Engage Connect API, the synchronization preferences should be configured. Click the ‘Sync Options’ tab. This page configures how the data between the two systems will flow. Note: If you do not want all of you records to continuously sync, come back to the page at any time to turn off the sync and stop the data flow.

15/32

The name and email are the matching criteria between Engage and Salesforce. For most configurations we recommend choosing Primary Address, and Custom Address fields, Name, Email, and Phone for sync. The click Save. For more on bi-direction sync, field mapping, or turning off sync – see the Appendix.

Now you want to create a test case to validate sync. Then, we will move on to customizing Page Layouts to show Elected Officials and Activities Objects and related fields. Finally, we will test again to confirm those customizations. To create a quick test, create and advocate record in Engage or in Salesforce, and check to see if the record was created and looks accurate. For additional testing detail, there is more information in the Testing the Sync section.

Page Layouts: Configuration Continued

Before running final tests, we need to customize the Page Layouts to show Elected Officials and Activities Objects and related fields.

16/32

Add Elected Officials related list in Contact Page Layout: Go to Setup -> Customize - > Contacts -> Page Layouts

Click the Edit link near the Contact Layout (which is being assigned to users) that you want to edit Now the Layout Editor will be launched. Do the following steps in the Layout Editor. Select “Related Lists” in the side menu (at the top). Then Drag and Drop the “Elected Officials” related list from the top menu into the layout Click on the “wrench” symbol in the Elected Officials related list that you just dropped in the layout and add the following fields into “Selected Fields” box of the popup that is launched

17/32

Suggested fields:

Engage Person Name

Current Position Label

Current Position District Code and/or Current Position State

Total Number of Advocates

All options:

Engage Person: Engage Person Name

Engage Person: First Name

Engage Person: Last Name

Engage Person: Current Position District Code

Engage Person: Current Position Label

Engage Person: Current Position State

Engage Person: Current Chamber

Engage Person: Government Level

Engage Person: Party

18/32

Click Ok and then click “Save” in the Layout Editor (if you are prompted with additional confirmation click “Yes”.

19/32

Add Activities related list in Contact Page Layout: Go to Setup -> Customize - > Contacts -> Page Layouts

Click the Edit link near the Contact Layout (which is being assigned to users) that you want to edit Now the Layout Editor will be launched. Do the following steps in the Layout Editor. Select “Related Lists” in the side menu (at the top). Then Drag and Drop the “Engage Activities” related list from the top menu into the layout Click on the “wrench” symbol in the Engage Activities related list that you just dropped in the layout and add the following fields into “Selected Fields” box of the popup that is launched. Follow the same process as with Elected Officials. Engage Activities Suggested Fields:

Action Date

Action Type

Recipient

Salesforce Campaign Click Ok and then click “Save” in the Layout Editor (if you are prompted with additional confirmation click “Yes”.

20/32

Testing the Sync

Once the final customization is complete, there are a number of tests you can run to validate the sync. Set the Automation Level (on the Configuration tab) to ‘Run Once and Stop’. This causes the system to synchronize once and then turn itself off, providing an opportunity to add or edit records in each system on an ad-hoc basis. Click ‘Save’.

Note: the sync should be set to ‘Run One Batch & Stop’ BEFORE any changes in Salesforce or Engage are made. Edit or create a record in Salesforce and/or Engage (depending on the sync direction configuration settings you chose earlier). For example, For the Engage to Salesforce sync, create a new Advocate record in Engage & vice versa. Seeing What Happened

Logs Page

Successes and errors can be viewed on the Logs page under the Logs tab. Note: The sync runs every 5 minutes; Advocates and Contacts may not sync right away check the last sync time. (In this example the next sync time would be 12:36PM)

21/32

Engage Sync Batch Status

From the Advanced page follow the link to Engage Sync Batch Status in the Staging and Status section.

Status Page

The status of the most recent batches, along with a quick view of activity throughout the current day.

22/32

23/32

APPENDIX

Data Integrity

Optional Data Cleansing Prior to Integration

If you have a robust number of Engage records or Salesforce records you will be syncing from one solution to the other, we recommend validating the data is clean, before syncing. If you are confident in the integrity of the data, this is not a required step. It is possible to install the application first, and then auto-sync the data. We recommend following the optional guidelines only if you are concerned about the integrity of the data. There is no single process that covers all clients’ needs with regards to the initial mapping, de-duplication, and export/import processes. How to deal with records in Salesforce and not in Engage, in Engage and not in Salesforce and/or records in both systems is a client business process decision. Furthermore how to identify a record in one system as being the ‘same’ in the other system would vary from client to client. Some clients 3rd party tools like the following for data management.

DemandTools by CRMFusion o http://www.crmfusion.com/demandtools/

Dupe Eliminator by Salesforce Labs o https://appexchange.salesforce.com/listingDetail?listingId=a0N3000000178g7EAA

CQ Roll Call does not specifically endorse any of these products. Please note that many of CQ Roll Call’s clients use these tools for the types of tasks listed above. In addition CQ Roll Call cannot support data management efforts on behalf of the client.

Optional Export/Import Process Before Integration

For clients who wish to export data from Salesforce into Engage as the first step in the integration. Whether this is to add data to Engage from Salesforce or establish an external ID link between Engage and Salesforce, the same process applies. This is not required. This process can be completed after integration, which is recommended unless you have concerns about data integrity. Existing Advocates are matched based on the following criteria:

Email address

The combination of First Name, Last Name, Zip Code

External ID To upload records from Salesforce to Engage, you must first export a file from Salesforce, formatted as a CSV (comma separated value) document and verify it contains the necessary Advocate fields. You will be prompted to upload this file when you select the Upload Advocate option in Engage. Your file must have a .csv extension. If you are using a tool like Excel, make sure to save your document as type .csv before trying to upload it into Engage.

24/32

They can be in any order in the CSV file, but columns headers used for file upload must exactly match the names as listed below (including all spaces, case sensitivity, etc.). If the format does not match, the upload will fail.

25/32

Minimal record requirements for new records

If the Advocate does not already exist, the Advocate must have the email address and/or first name, last name AND Zip Code columns entered in the CSV upload file.

Field Mappings – Engage & Salesforce

Salesforce Field Name

Engage Field Name Notes

Email email required

Id externalId

required

Salutation prefix

FirstName firstName

LastName lastName

MailingStreet address1 If the Salesfoce value of MailingStreet contains multiple lines, line one should be mapped to address1 and line two to address2.

MailingStreet address2

MailingCity city

MailingState state USPS state

MailingPostalCode zip Five or nine digit ZIP code.

MailingCountry country (Requires ISO 3166-1-alpha-2 code format. Click here to see ISO 2-character codes )

Phone phone

globalEmailOptout Valid values: True, False

active

If Advocate record is active; it is eligible to receive communications sent from Engage this value should be set to 1, otherwise 0. The default value is 1.

Generating the Export from Salesforce using Salesforce Dataloader

Select Export

26/32

Login using your Salesforce Username, Password and security token

Select the Contact as the Data Object

27/32

Select the following query fields from the Contact object: Select Id, Salutation, FirstName, LastName, MailingStreet, MailingCity, MailingState, MailingPostalCode, MailingCountry, HomePhone

28/32

Open the CVS file and rename the columns according to the mapping table above. In this specific example it would be: [externalId, prefix, firstName, lastName, address1, city, state, zip, country, phone]

Uploading the CSV File

Once you have created your CSV file, you are ready to upload your file:

In Engage, go to Advocates: Upload Advocates (on right column).

A Batch Upload Advocates in CSV pop-up window will display. o Email Notification: Enter the email address of the person to whom the status confirmation email should be

sent once the upload has completed processing. o Upload CSV File: Select an existing CSV file to upload from your computer. o Click “Submit”.

After uploading your file, a status confirmation email will be sent. If the email indicates that the upload was processed successfully, then all the Advocates were saved to the database. Note: it may take a few minutes before confirmation is received, depending on the size of your upload and other upload activity on the Engage servers.

29/32

Data Relationships

Following is the mapping of entities between Engage and Salesforce

Engage Salesforce

Advocate Contact / Person Account

Activity Engage Activity

Engagement Campaign

Elected Officials Elected Officials / Engage Persons

Principle of Operation / Troubleshooting

Overview

The matching strategy for Salesforce Contact and Engage Advocate records is illustrated below (in the order in which they appear). Once a match is found no other matching queries.

1. Is there a primary key from the destination system on the source record? 2. Is the Email address present? 3. Are the First, Last AND ZIP Code present?

Case List with Updates/Insert Actions

Syncing Engage Advocates to Salesforce - Matching Cases

SF ID Present Email

Present First Last ZIP

Present Found ID? Strategy Decision

Yes No No N/A - Have ID already Update on ID

Yes Yes No N/A - Have ID already Update on ID

Yes Yes Yes N/A - Have ID already Update on ID

Yes No Yes N/A - Have ID already Update on ID

No Yes No Yes - from Email Update on ID

No Yes No No Insert

No Yes Yes Yes - from Email Update on ID

No Yes Yes Yes - from First Last ZIP Update on ID

No No Yes Yes - from First Last ZIP Update on ID

No No Yes No Insert

No No No N/A Insert

30/32

Syncing Salesforce Contacts to Engage - Matching Cases - Handled by Engage

Engage ID Present

Email Present

First Last ZIP Present Strategy Decision

Yes No No ID

Yes Yes No ID

Yes Yes Yes ID

Yes No Yes ID

No Yes No Email

No Yes No Email

No Yes Yes Email

No No Yes First Last ZIP

No No Yes First Last ZIP

No No No No Match

What Triggers Synchronization

Contacts synchronized between the systems will be matched on the following criteria in the order shown: Syncing of Advocates/Contacts

1. Upon the creation or modification of a contact record in Salesforce, the same is created or modified in Engage. 2. Upon the creation or modification of a contact record in Engage, the same will be created or modified in

Salesforce. 3. Upon the creation of an activity record in Engage, the same will be created in Salesforce. Upon the creation of

an Engagement, Campaign, or Issue in Engage, a Campaign will be created in Salesforce (if that option is selected and configured).

4. Record matching criteria and address location are configured by the user. 5. Other configuration parameters to control the synchronization, logging, log maintenance, and display

functionality are provided.

Salesforce Campaign and Engage Engagements

When an Engagement is created in Engage it will be automatically be created in Salesforce as a Campaign. This is a one-way synchronization from Engage to Salesforce. This Campaign may then be left as is, meaning a top-level Campaign, or assigned to a parent Campaign. Should the Engagement be edited those changes will be reflected in Salesforce. However, there is no automated deletion of an Engagement in Salesforce. Need a very specific statement (early on) regarding retroactive syncing of data, emphasis on turning sync on BEFORE uploading/changing any data & directions on how they can do an ad-hoc upload with “changes” to update the last modified date on Advocate records so they will sync to SF (include the link to the directions in Engage).

31/32

Setting Sync Direction

Sync for Salesforce provides both uni-directional and bi-directional synchronization. Use the Engage to Salesforce Sync Flow and the Salesforce to Engage Sync Flow check boxes to activate (or deactivate) synchronization in that particular direction.

Engage to Salesforce Options

Address 1

Contact data may be synchronized to any of the Salesforce address fields from the Engage Advocate record. Engage for Salesforce can use the standard Contact object Primary Address or Optional Address in Salesforce. Primary Address is usually the field in use, but Custom Address fields can also be used for mapping to Engage, much like the standard fields do.

Field Label Field Name

Engage Address Street e4sf__Engage_Address_Street__c

Engage Address City e4sf__Engage_Address_City__c

Engage Address State e4sf__Engage_Address_State__c

Engage Address PostalCode e4sf__Engage_Address_PostalCode__c

Engage Address Country e4sf__Engage_Address_Country__c

Name, Email, Phone 2 If selected, the corresponding fields from Engage will be synchronized to Salesforce.

Salesforce to Engage Options

Address 3

Engage for Salesforce Advocate records contain a single address field. Therefore a single destination field in Salesforce (or none) may be selected.

Name, Email, Phone 4

If selected the corresponding field from Engage will be synchronized to Salesforce.

Selectively Preventing Some Salesforce Records From Syncing

Engage for Salesforce provides the ability for selectively excluding Contact records via a custom field (Engage Never Sync to Engage) that may be populated manually, upload, trigger, calculated field, etc.

Object: Contact Field Label: Engage Never Sync to Engage Field Name: e4sf__Engage_Never_Sync_To_Engage__c Field Type: Checkbox

If this field’s value is checked (true), the Contact record will be excluded from all synchronizations to Engage.

32/32

Global Opt-Out

In Engage, the global opt-out flag may be set on an Advocate record. This value is synchronized with the Engage_Opt_Out__c field on the Contact object. I it will be synchronized to Engage if it is changed.

Object: Contact Field Label: Engage_Opt_Out Field Name: e4sf__Engage_Opt_Out__c Field Type: Checkbox

While Engage for Salesforce shares this information to and from Salesforce by an Engage for Salesforce application-specific field on the Contact record, it will need to be integrated into client systems e.g.

A custom trigger may be required to update another object based on the change in value of the Global Opt-out field.

Reports can be created to use this field as part of their query.

Miscellaneous – Other Custom Contact Fields

Object: Contact Field Label: Engage Is Advocate Field Name: e4sf__Engage_Is_Advocate__c Field Type: Checkbox Default Value: Unchecked

Object: Contact Field Label: Engage Date Last Sync Field Name: e4sf__Engage_Date_Last_Sync__c Field Type: Datetime Default Value: Null