Creating and Using a Custom Salesforce Mapping File for the Legacy Connector

You can create a custom mapping file to modify the behavior of the Salesforce legacy connector to adapt to your Salesforce database.

Tip: When you want to index only a subset of Salesforce types that are defined in the default mapping file, you do not have to create a custom mapping file. You can simply specify the Salesforce types to index in the Mapping Types field for the Salesforce source (see Configuring and Indexing a Salesforce Source for the Legacy Connector).

To create and use a custom mapping file

1. Copy the content of the default mapping file (see About the Default Salesforce Mapping File for the Legacy Connector).

2. Using an administrator account, connect to the Coveo Master server.

3. Using a text editor:

   1. In an empty file, paste the content of the default mapping file.

   2. Edit the content of the mapping file to suit your needs, referring to the following subsections for details on how to modify the file:

      • Mapping file structure
      • Mapping child nodes
      • Mapping security
      • Mapping local expressions
      • Mapping foreign expressions
      • Using external resolvers

   3. Save the custom mapping file on the Coveo Master server.

      Example: C:\CES7\Config\SalesforceMappingFile.xml

4. Configure the connector to use the custom mapping file in the Salesforce source:

   • When you create a Salesforce source (see Configuring and Indexing a Salesforce Source for the Legacy Connector).

     OR

   • For an existing Salesforce source:

     1. On the Coveo server, access the Administration Tool (see Opening the Administration Tool).

     2. Select Index > Sources and Collections.

     3. Under Collections, select the collection containing the Salesforce source.

     4. Under Sources, select the Salesforce source.

     5. In the navigation panel on the left, select General.

     6. In the Mapping File parameter, enter the full path to your custom mapping file.

     7. Click Apply Changes.

5. Rebuild the source.

Mapping file structure

The mapping file can be divided into three sections:

• CommonMapping: All the settings applied to all the mappings.

• Mapping: Individual mappings for each object type to index.

  You can add mappings for custom Salesforce types not included in the default mapping file simply by copying and editing a mapping section for an existing type.

• ExternalResolvers: When you need to apply a sophisticated mapping, you can specify an external assembly type to call to resolve it.

Mapping child nodes

<Fields>

Fields for this mapping. From this point, you either define a system or custom field:

• System fields

  System fields can be used directly under the <fields> node. They are mapped to an existing system field.

  Example: The <uri> is mapped directly to the system field URI for this type.

• Custom fields

  Custom fields can be mapped to a custom metadata name. The metadata is filled with the string content.

  Example: The <CustomField name="SFLocation">%[Location]</CustomField> node maps the field named Location on the Salesforce object to the metadata SFLocation on the document in the unified index.

<AllowedUsers>

• Type of users: Windows, CustomGroup, CustomUser, ExternalGroup, ExternalUser, WindowSid

• Name: Name of the user

• Server: Usually references to the domain

Mapping security

You can configure the Salesforce legacy connector by adding or removing allowed groups and users to the mapping file for each object types. The permissions are therefore incorporated in the index. Using this method is recommended as CES does not have to fetch the security permissions at query time for each query. However, security permissions can only be set for each object type. This means that individual objects of the same type will always have the same security permissions.

<CommonMapping>
  <AllowedUsers>
    <AllowedUser type="Windows" allowed="true">
      <Name>Sales</Name>
      <Server>MyOrganization</Server>
    </AllowedUser>
  </AllowedUsers>
</CommonMapping>  

You can specify different security permissions for each mapping type by adding an AllowedUsers child node to every mapping node.

<Mapping type="Account">
  <AllowedUsers>
    <AllowedUser type="CustomGroup" allowed="true">
      <Name>Salesforce Account Users</Name>
      <Server>MyOrganization</Server>
    </AllowedUser>
  <Fields>
    <Title>%[Subject]</Title>
    <Body>%[Description]</Body>
    <CustomFields>
      <CustomField name="SFOwner">%[OwnerId.FirstName]%[OwnerId.LastName]</CustomField>
      <CustomField name="SFOwnerID">%[OwnerId</CustomField>
      <CustomField name="SFStatus">%[Status]</CustomField>
      <CustomField name="SFPriority">%[Priority]</CustomField>
    </CustomFields>
  </Fields>
</Mapping>  

You can also directly set Active Directory users or groups in the mapping file. This method however requires that you modify the mapping file and rebuild the source each time that you add or remove users or groups.

<Mapping type="Tasks">
  <AllowedUsers>
    <AllowedUser type="Windows" allowed="true">
      <Name>Sales</Name>
      <Server>MyOrganization</Server>
    </AllowedUser>
  <Fields>
    <Title>%[Subject]</Title>
    <Body>%[Description]</Body>
    <CustomFields>
      <CustomField name="SFOwner">%[OwnerId.FirstName]%[OwnerId.LastName]</CustomField>
      <CustomField name="SFOwnerID">%[OwnerId</CustomField>
      <CustomField name="SFStatus">%[Status]</CustomField>
      <CustomField name="SFPriority">%[Priority]</CustomField>
    </CustomFields>
  </Fields>
</Mapping>  

Mapping local expressions

The Salesforce legacy connector uses a specific mapping expression to represent a value on a Salesforce object. Occurrences of the expression %[field] are replaced by the value of the field specified by the name in the brackets for this Salesforce object.

Example: The expression <ModifiedDate>%[LastModifiedDate]</ModifiedDate> replaces the string %[LastModifiedDate] by the value of the LastModifiedDate field for each Salesforce object. The value fetched is then assigned to the system field ModifiedDate on each document in the unified index.

Mapping foreign expressions

As some objects can reference to others in Salesforce, you can fetch the value of a foreign field in your mappings, as long as the foreign type has the requested field.

Example: The expression <CustomField name="SFOwner">%[OwnerId.FirstName] %[OwnerId.LastName]</CustomField> retrieves the specific object pointed by OwnerId and retrieves the value of the fields FirstName and LastName on that object. Then the resulting string is a concatenation of both results. An example of the result for this expression could be John Smith.

Important: Foreign expressions can dramatically slow down the indexing process, as a remote object has to be queried for every foreign expression. Coveo has a local cache for each field value; however the performance decreases every time it has to fetch field values on a new object. Use them carefully.

Using external resolvers

When declaring an external resolver, you need to provide a unique name as well as a fully qualified type name to call.

<SalesForce>
    <ExternalResolvers>
        <ExternalResolver name="Resolvername" type="FQTypename"/>
    </ExternalResolvers>
</SalesForce>  

Note: For more information on fully qualified type names, refer to the Microsoft document Specifying Fully Qualified Type Names.

Once the external resolver has been defined, you can use it in any mapping using the following syntax: @[resolvername].

Parameters can be defined to pass to the external type. In this case, you must specify an additional bracket node with parameters separated by a semicolon (;): @[resolvername][param1;param2].

As the external resolvers are called last, fields to resolve (such as %[field]) can be specified as parameters and will be resolved before the external resolver is called.

External resolver type limitations

For the external type to be used with the external resolver system, you must write a DLL that implements the IMappingResolver interface defined as follows:

namespace Coveo.CES.CustomCrawlers.SalesForce
{
  //****************************************************************************
  /// <summary>
  /// the Interface the callback functions in the mapping file must implement.
  /// </summary>
  //****************************************************************************
  public interface IMappingResolver
  {	
    string Resolve(string[]         p_Parameters,
                   Record           p_CurrentRecord,
                   MappingUtilities p_Utilities);
  }
}

The parameters are passed as an array of string in p_Parameters. The current record being parsed is passed as well as p_CurrentRecord. Finally, the connector cached records, connection, disk cache, etc. can be accessed using the mapping utilities. The string returned by the resolve function will be used as the mapping value.

All these classes and interfaces are in the Salesforce legacy connector assembly, the external assemblies will need to add the Salesforce connector assembly as a reference.