Before we start, be sure to see Mapping Custom Salesforce Fields in the InsightSquared Platform to get more background information on mapping fields in the Platform.
In Salesforce, Lookup fields are used to related two record types together using an id. For example, you may have a Contact lookup field called My_Important_Champion__c that represents the champion of an opportunity.
Using the documentation linked above, mapping My_Important_Champion__c into IS2 will simply pull in the id (as a string) of the important champion to the field it is mapped to, into IS2. This is important to map in for IS2 write-back functionality to Salesforce.
What if I want to see more than just the id ? What about the contact name?
This is where the Salesforce relationship syntax comes into play. In order to pull in more properties via a lookup we must specify each salesforce property as a property in IS2. Using the __r notation rather than the usual __c notation, we can access the properties of the underlying lookup object. For example, mapping My_Important_Champion__r.Name will get the contact name. Another emails, My_Important_Champion__r.Email will get the champion's Email. Each of these properties needs to be mapped to an IS2 property like My Important Champion Email or My Important Champion Name .
NOTE: non-custom salesforce Lookups do not need the __r notation. For example, CamaignId on the Opportunity object can be mapped like above but without the __r or id suffix: Campaign.Name will retrieve the campaign name.