After adding the Salesforce Authentication details to Agile, mappings must be added:
1. On the External Integration node, click the Field Mappings tab.
On this tab, mappings from Agile to Salesforce can be defined.
2. Select a Salesforce object to map to from the drop-down in the top-right corner.
3. To add a mapping field, double-click the box containing "Add mapping...". This will add a mapping row from which to select value.
4. Select a Field Type from the drop-down on the left. This will change which types of fields are displayed in the Agile Field section in the middle.
5. Select an Agile Field from the middle drop-down. This is the description for the field that will be sent to Salesforce.
Note: To add a 'static field' that will be the same for every object sent to Salesforce, type in the box after clicking it instead of selecting a value from the drop-down.
6. Finally, select a field from those available on the selected Salesforce object to have the Agile field mapped to.
7. To add another mapping, continue from step 2. Note that each mapping row can be mapped to a different Salesforce object.
8. Hit Apply in the bottom right to save all mappings. Any mappings with nothing selected in the far-right column, such as the one within the blue box below, will be deleted.
Currently, it is recommended to use the Salesforce "Contact" record to store Agile Customer and Membership information, and the Salesforce "Opportunity" record to store Agile Transaction information. This will allow the system to check the Agile Customer data against Salesforce Contacts to avoid creating duplicate records, and for these Contacts to be tied to the Opportunity records using an OpportunityContactRole so that they will be listed with the Contact in Salesforce.
Be aware that in order for the integration to work out-of-the box, a custom field "Agile_ID" must be added to the Salesforce Contact object. Instruction on adding custom fields like "Agile_ID" can be found at https://help.salesforce.com/articleView?id=adding_fields.htm&type=5. This is one of the fields used to prevent adding duplicate contacts. By default, a duplicate is found if there is an existing Contact that matches:
Last names with the new Contact, and matches either Agile_ID or Email with the new Contact
If a duplicate is found, Agile will update the existing Salesforce Contact record instead of adding a new one. If use of a different field for Agile_ID or a custom duplicate definition is desired, it will need to be manually changed by Agile.
Selecting different Field Types for a mapping row will cause the list of Agile Fields for that row to change. The data contained under each field type is as follows:
- Customer Property - General customer information, such as name, address, and email
- Phone Type - Customer phone numbers for each phone type
- Membership Property - Membership information such as Member Number, Expiration Date, and Membership level name. Values for each active membership for the organization can be selected, or values for "Last Expiring Membership", which will find and map values for whichever membership in the organization has the furthest expiration date for the customer
- Customer Question - allows the mapping of the customer's answers for the selected question
- Order Question - allows mapping of the customer's answer to the selected order question
- Transaction Property - allows mappings of transaction data, such as Transaction ID, price, quantity, close date time, and event time, if any.
- There are 5 fields that can be selected, "Price External Field 1-5". These will send a user-definable value from the price for the transaction's items
Next, you may wish to define Duplicate Checks or Object Relationships. This can be done on the Object Relationships tab.
There are three different kinds of object relationships defined by Salesforce. (see Salesforce article: Create Object Relationships)
Lookup relationships can be defined simply by mapping an object's ID to a Lookup field on the Field Mappings tab in Agile.
Master-detail and Many-to-many Relationships
The first section on this tab allows for the administration of Junction Objects, which allow for the definition of Master-detail or Many-to-many relationships within Salesforce. Unless they are standard objects pre-defined by Salesforce, these objects must first be defined in Salesforce (see Salesforce articles; Create Object Relationships, Understand Custom & Standard Objects), then mapped on this tab so that the Agile system will know how to handle them when synchronizing data with Salesforce.
The example below shows how to define the relationship between the standard Salesforce objects Contact and Opportunity, which allows a list of Opportunities associated with a Contact to be listed on the Contact's page in Salesforce, but the process will be the same for any object relationship, including for Custom objects that have a junction object defined.
1. Click the Add Relationship button
This will display the Add Salesforce Object Relationship... dialog.
2. Select the Junction Object
In the upper box, select the Junction Object. In the case of Contact-Opportunity objects, this is OpportunityContactRole
3. Select the Junction Object Fields
Select the fields to map the Primary and Secondary object's IDs to. Usually, this will be named something like "<primary/secondary object> ID." In the case of the OpportunityContactRole, this is Contact ID in the Primary column and Opportunity ID in the secondary column.
Note: Be sure to put the correct object in each column. If they are entered in the wrong column, they will not link correctly.
4. Select the Primary (Master) Object
In the box on the left, select the Primary object. This is the object that will have a list of the Secondary objects. In the case of Contact-Opportunity objects, this is Contact.
5. Select the Secondary (Detail) Object
In the box on the right, select the Secondary object. In the case of Contact-Opportunity objects, this is Opportunity.
6. Select the Object IDs
Under each object selected in steps 4 and 5, select the object's ID field. In most cases, this field is called "ID", "Record ID" or "<object> ID". The system will attempt to automatically select this field. In the case of Contact this will be Contact ID and for Opportunity, it will be Opportunity ID.
After clicking Save, the relationship will appear in the list of Junction Objects. For a Many-to-many relationship, repeat the above steps for the second Junction object.