Engage for Salesforce Documentation 11/2/2015

Transcription

1 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. [email protected] / /32

2 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, will only impact clients on base package or a later version. If there any validation rules, triggers (either set up by your administrators or by any 3 rd party applications) etc. that check or verify contact/activity/campaign creation (i.e. address, zip-code, , 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 Install App Validate Sync Configure Settings Data Integrity 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 2/32

3 3/32

4 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. 4/32

5 The Engage for Salesforce AppExchange listing will load. Click Get it Now 5/32

6 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 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 6/32

7 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 7/32

8 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. If not prompted and you want to install to the Sandbox, it is necessary to append the URL to be 8/32

9 9/32

10 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. 10/32

11 Configuration Select Engage for Salesforce from your installed packages. The Engage for Salesforce splash-page will load. 11/32

12 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): 12/32

13 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. 13/32

14 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. 14/32

15 The name and are the matching criteria between Engage and Salesforce. For most configurations we recommend choosing Primary Address, and Custom Address fields, Name, , 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. 15/32

16 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 16/32

17 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 17/32

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

19 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. 19/32

20 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) 20/32

21 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. 21/32

22 22/32

23 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 3 rd party tools like the following for data management. DemandTools by CRMFusion o Dupe Eliminator by Salesforce Labs o 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: 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. 23/32

24 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. 24/32

25 Minimal record requirements for new records If the Advocate does not already exist, the Advocate must have the address and/or first name, last name AND Zip Code columns entered in the CSV upload file. Field Mappings Engage & Salesforce Salesforce Field Engage Field Name Name required Id externalid required Notes Salutation prefix FirstName firstname LastName lastname MailingStreet address1 If the Salesfoce value of MailingStreet contains MailingStreet address2 multiple lines, line one should be mapped to address1 and line two to address2. MailingCity city MailingState state USPS state MailingPostalCode zip Five or nine digit ZIP code. MailingCountry country (Requires ISO alpha-2 code format. Click here to see ISO 2-character codes ) Phone phone global optout 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 25/32

26 Login using your Salesforce Username, Password and security token Select the Contact as the Data Object 26/32

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

28 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 Notification: Enter the address of the person to whom the status confirmation 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 will be sent. If the 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. 28/32

29 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 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 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 Update on ID No Yes No No Insert No Yes Yes Yes - from 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 29/32

30 Engage ID Present Syncing Salesforce Contacts to Engage - Matching Cases - Handled by Engage First Last ZIP Present Present Strategy Decision Yes No No ID Yes Yes No ID Yes Yes Yes ID Yes No Yes ID No Yes No No Yes No No Yes Yes 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 oneway 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). 30/32

31 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 Engage Address Street Engage Address City Engage Address State Engage Address PostalCode Engage Address Country Field Name e4sf Engage_Address_Street c e4sf Engage_Address_City c e4sf Engage_Address_State c e4sf Engage_Address_PostalCode c e4sf Engage_Address_Country c Name, , 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, , 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: Field Label: Field Name: Field Type: Contact Engage Never Sync to Engage e4sf Engage_Never_Sync_To_Engage c Checkbox If this field s value is checked (true), the Contact record will be excluded from all synchronizations to Engage. 31/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: Field Label: Field Name: Field Type: Contact Engage_Opt_Out e4sf Engage_Opt_Out c Checkbox While Engage for Salesforce shares this information to and from Salesforce by an Engage for Salesforce applicationspecific 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 32/32