coveo platform 6.5 - salesforce connector guide (string )...

Coveo Platform 6.5Salesforce Connector Guide

Coveo Platform 6.5 | Salesforce Connector Guide

NoticeThe content in this document represents the current view of Coveo as of the date of publication. BecauseCoveo continually responds to changingmarket conditions, information in this document is subject to changewithout notice. For the latest documentation, visit our website at www.coveo.com.

Copyright © 2012, Coveo Solutions Inc.

All rights reserved.

Coveo is a trademark of Coveo Solutions Inc. This document is protected by copyright and other intellectualproperty law and is subject to the confidentiality and other restrictions specified in the Coveo LicenseAgreement.

Document part number: PM-120112-ENRevision: APublication date: 2012-08-23

4www.coveo.com ii

http://www.coveo.com/



Table of Contents1. Salesforce Connector Features 1

2. Salesforce Connector Deployment Overview 2

3. Salesforce Connector Requirements 3

4. Configuring a Salesforce User Identity 4

5. Choosing How to set Permissions for a Salesforce Source 5

6. About the Default Salesforce Mapping File 7

7. Creating and Using a Custom Salesforce Mapping File 12

7.1Mapping file structure 13

7.2Mapping child nodes 13

7.3Mapping security 14

7.4Mapping local expressions 15

7.5Mapping foreign expressions 15

7.6 Using external resolvers 16

8. Configuring and Indexing a Salesforce Source 17

8.1Modifying Hidden Salesforce Source Parameters 20

8.2 Showing Advanced Hidden Source Parameters 23

9. Managing Custom Security Groups 25

10. Configuring a Salesforce Security Provider 27

11. Modifying Source Security Permissions 30

11.1Modifying the source permissions 30

11.2Mapping the security permissions of aWeb source 31

4www.coveo.com iii


4www.coveo.com iv




1. Salesforce Connector FeaturesThe Coveo Salesforce connector allows crawling Salesforce content and bring it into the unified index, makingthe it easily searchable by end-users. The connector uses amapping file that defines the database objectsignatures as well as the objects and fields to index. You canmodify themapping file to customize theindexed content and easily add new object types and custom fields to optimally index your Salesforcedatabase.

The features of the Salesforce connector:

Live indexing

The live indexing feature refreshes the content of the index based on themodification date of the objects inthe Salesforce environment. If an item is modified, the live indexing feature refreshes the itemautomatically.

Customizable object mapping

With themapping file, you can select which Salesforce objects to index. You can decide to indexadditional custom Salesforce objects and fields, or remove existing ones by just modifying themappingfile (see "Creating and Using a Custom SalesforceMapping File" on page 12).

Metadata

All the fields of the retrieved Salesforce objects are indexed as metadata. You can therefore customizeCES based on that metadata via custom fields.

CoveoPlatformversion

Connector feature history

6.5 build4631

Addition of ExcludeConvertedLeads and ExcludeDeletedItems hidden parameters toallow to optionally index converted leads and deleted items (see "Modifying Hidden SalesforceSource Parameters" on page 20).

6.5 build4488

l Changed used Salesforce API from version 19 to 23. Addition of theCustomLoginUriVersion hidden parameter to allow changing the API version (see"Modifying Hidden Salesforce Source Parameters" on page 20).

l Changed the external resolver parameters to enable passingmore characters in the string(see "Creating and Using a Custom SalesforceMapping File" on page 12).

What's Next?

Review the deployment process for the Salesforce connector (see "Salesforce Connector DeploymentOverview" on page 2).

4www.coveo.com 1



2. Salesforce Connector Deployment OverviewThe following procedure outlines the steps needed to deploy the Salesforce connector. The steps indicate theorder in which youmust perform key CES configurations. When needed, the step refers to a detailedprocedure.

1. Validate that your environment meets the requirements (see "Salesforce Connector Requirements" onpage 3).

2. Configure the user identity.

The Coveo connector needs an account to connect to your Salesforce environment and access the entirecontent that you wish to index (see "Configuring a Salesforce User Identity" on page 4).

3. Choose either the early-binding or late-bindingmethod to set permissions to the Salesforce content (see"Choosing How to set Permissions for a Salesforce Source" on page 5).

4. Optionally customize the default mapping file to adapt the Salesforce content to index (see "About theDefault SalesforceMapping File" on page 7 and "Creating and Using a Custom SalesforceMapping File"on page 12).

5. Configure and index the Salesforce source.

The Coveo connector needs to know details about the Salesforce database to be able to index the desiredcontent (see "Configuring and Indexing a Salesforce Source" on page 17).

6. Depending on themethod that you use to set permissions on the source:

l For early-binding security, assign appropriate users to the custom security group (or groups) definedin the default or custommapping file (see "Managing Custom Security Groups" on page 25).

OR

l For late binding security:

a. Create a security provider for your Salesforce source (see "Configuring a Salesforce SecurityProvider" on page 27).

b. Associate the security provider with your Salesforce source (see "Modifying Source SecurityPermissions" on page 30).

7. Add the out-of-the-box or custom Salesforce search interface to a search hub and then validate thatallowed users can search the Salesforce content.

8. Optionally, if you encounter issues, consider adding andmodifying default values of hidden sourceparameters (see "Modifying Hidden Salesforce Source Parameters" on page 20).

4www.coveo.com 2



3. Salesforce Connector RequirementsYour environment must meet the following requirements to be able to use the Coveo connector for Salesforcerepositories:

l Coveo license for the Salesforce connector

Your Coveo licensemust include support for the Salesforce connector to be able to use this connector.

l An active Salesforce account to a Salesforce environment

This account requires a read permission on all the types of content crawled by the connector.

What's Next?

Create a CES user identity for Salesforce (see "Configuring a Salesforce User Identity" on page 4).

4www.coveo.com 3



4. Configuring a Salesforce User IdentityYoumust create a CES user identity that contains the credentials of a Salesforce account that has readaccess to all the Salesforce content that you wish to index. You will later assign this user identity to thesource to crawl your Salesforce environment.

To configure a Salesforce user identity

1. On the Coveo server, access the Administration Tool.

2. Select Configuration > Security.

3. In theSecurity page, in the navigation panel on the left, click User Identities.

4. In theUser Identities page, click Add.

5. In theModify User Identity page:

a. In theName field, enter a name describing the user identity. This namewill appear in theAuthentication drop-down list when you configure the source.

Example: Salesforce crawling account

b. In theUser field, enter the Salesforce username that you created or selected to be used by the Coveoconnector.

c. In thePassword field, enter the password for your Salesforce username.

d. The other parameters (Support basic authentication, Use client certificate, Store, andCertificate) do not apply to this connector.

e. Click Save.

What's Next?

Determine whichmethod to use to set permissions to your Salesforce content (see "Choosing How to setPermissions for a Salesforce Source" on page 5).

4www.coveo.com 4



5. Choosing How to set Permissions for a Salesforce SourceYou can configure the Salesforce connector to manage permissions for Salesforce content using two possiblemethods: early-binding or late-binding. Youmust select whichmethod to use before configuring yourSalesforce source.

Early-binding (recommended)

With the early-bindingmethod, the permissions associated to Salesforce content are incorporated into theunified index. When a user makes a query for Salesforce content, the index knows which content this userhas access to and only returns query results for content this specific user has access to. This method isrecommended because it provides optimal query performances.

The inconvenience of this method is that it cannot integrally reproduce the complex Salesforce securitymodel.

Using the default mapping file

The default mapping file includes a security bindingmapping (<AllowedUsers>) that grants access to allusers that aremembers of theSalesforce Users CES custom security group. This mapping is in the<CommonMapping> section of themapping file and therefore applies to all indexed Salesforce types ofcontent (see "About the Default SalesforceMapping File" on page 7).

When you index a Salesforce source using the default mapping file for the first time, CES creates theSalesforce Users custom security group. At this point, there are nomembers in this group. Consequently,nobody can search Salesforce content. In the Coveo Administration Tool, all you have to do is add usersand groups to theSalesforce Users custom security group (see "Managing Custom Security Groups" onpage 25). You canmanage access to the Salesforce search results by adding/removingmembers to/fromthis group without having to rebuild the Salesforce source.

Using a custom mapping file

You can customize themapping file to implement more specific early-binding security mappings, likecreating independent custom security groups for each Salesforce type of content (see "Creating and Usinga Custom SalesforceMapping File" on page 12). In the Coveo Administration Tool, you can then adddifferent users to the various custom security groups (see "Managing Custom Security Groups" on page25).

Example: Youmay want that only users from your Sales department can search theOpportunity type ofSalesforce content and only users from your Customer Support department can search theCase type ofSalesforce content.

Note: You can also directly allow specific users to the <CommonMapping> or the <Mapping> sectionof a specific type of Salesforce content without using custom security groups. The inconvenience of thismethod is that youmust modify themapping file and rebuild or refresh the source each time you need toadd/remove allowed users.

4www.coveo.com 5



Late-binding

With the late-bindingmethod, the permissions associated to Salesforce content are not in the index andmustbe fetched at query time. This method has the benefit of exactly matching the internal Salesforcepermissions. The configuration only implies creating a Salesforce security provider (see "Configuring aSalesforce Security Provider" on page 27) and associating the security provider to the Salesforce source (see"Modifying Source Security Permissions" on page 30).

Note:When you associate a security provider to a Salesforce source, the connector ignores securitysettings from the default or custommapping file.

The inconveniences of this method are:

l Query performances can dramatically decrease as for each query, the security provider must validate thepermissions of each query result to only return results to which the user has read permissions.

l Users must enter their Salesforce credentials in the search interface for each search session.

What's Next?

Once youmade the appropriate configuration for how you selected to set permissions on the source, configureand index the source (see "Configuring and Indexing a Salesforce Source" on page 17).

4www.coveo.com 6



6. About the Default Salesforce Mapping FileThe Coveo connector for Salesforce embeds an XMLmapping file that is appropriate for many Salesforcesetups. This default mapping file specifies to index the basic Salesforce database object types and thecorresponding fields.

The Salesforce object types indexed with the default mapping file are:

l Accountl Contactl Leadl Opportunityl Casel Eventl Taskl Case Commentl Email Messagel Documentl Attachment

You can create and configure the connector to use a custommapping file to adapt the behavior of theconnector to your needs (see "Creating and Using a Custom SalesforceMapping File" on page 12).

The following XML code presents the content of the default mapping file.

4www.coveo.com 7



<?xml version="1.0" encoding="Windows-1252" ?><SalesForce><CommonMapping><Fields><ContentType>binarydata</ContentType><syssfcreatedby>%[CreatedById.Name]</syssfcreatedby><syssfcreatedbyid>%[CreatedById]</syssfcreatedbyid><syssfcreateddate>%[CreatedDate]</syssfcreateddate><sysauthor>%[LastModifiedById.Name]</sysauthor><sysdate>%[SystemModstamp]</sysdate><syssfid>%[Id]</syssfid><syssfowner>%[OwnerId.Name]</syssfowner><syssfownerid>%[OwnerId]</syssfownerid>

</Fields><AllowedUsers><AllowedUser type="CustomGroup" allowed="true"><Name>Salesforce Users</Name><Server></Server>

</AllowedUser></AllowedUsers>

</CommonMapping><Mapping type="Account"><Fields><Title>%[Name]</Title><Body>%[Name]

Owner: %[OwnerId.Name]Type: %[Type]Industry: %[Industry]Description:%[Description]

</Body><sysfiletype>SFAccount</sysfiletype><syssfbillingstreet>%[BillingStreet]</syssfbillingstreet><syssfbillingcity>%[BillingCity]</syssfbillingcity><syssfbillingstate>%[BillingState]</syssfbillingstate><syssfbillingcountry>%[BillingCountry]</syssfbillingcountry><syssfbillingpostalcode>%[BillingPostalCode]</syssfbillingpostalcode><syssfshippingstreet>%[ShippingStreet]</syssfshippingstreet><syssfshippingcity>%[ShippingCity]</syssfshippingcity><syssfshippingstate>%[ShippingState]</syssfshippingstate><syssfshippingcountry>%[ShippingCountry]</syssfshippingcountry><syssfshippingpostalcode>%[ShippingPostalCode]</syssfshippingpostalcode><sysworkphone>%[Phone]</sysworkphone><syssffax>%[Fax]</syssffax><syssfwebsite>%[Website]</syssfwebsite><syssfcurrency>%[CurrencyIsoCode]</syssfcurrency><syssfdescription>%[Description]</syssfdescription><syssfcountry>%[BillingCountry]</syssfcountry><syssfindustry>%[Industry]</syssfindustry>

</Fields></Mapping><Mapping type="Contact"><Fields><Title>%[FirstName] %[LastName] (%[Title])</Title><Body>%[FirstName] %[LastName]

%[AccountId.Name]Title: %[Title]Account: %[AccountId.Name]Email: %[Email]Phone: %[Phone]Address:%[MailingStreet]%[MailingCity],%[MailingState]

4www.coveo.com 8



%[MailingCountry]</Body><sysfiletype>SFContact</sysfiletype><syssffirstname>%[FirstName]</syssffirstname><syssflastname>%[LastName]</syssflastname><syssfstreet>%[MailingStreet]</syssfstreet><syssfcity>%[MailingCity]</syssfcity><syssfstate>%[MailingState]</syssfstate><syssfcountry>%[MailingCountry]</syssfcountry><syssfpostalcode>%[MailingPostalCode]</syssfpostalcode><sysworkemail>%[Email]</sysworkemail><sysworkphone>%[Phone]</sysworkphone><syscompany>%[AccountId.Name]</syscompany><syssfaccount>%[AccountId.Name]</syssfaccount><syssfaccountid>%[AccountId]</syssfaccountid>

</Fields></Mapping><Mapping type="Lead"><Fields><Title>%[Company] (%[FirstName] %[LastName])</Title><Body>%[FirstName] %[LastName]

Title: %[Title]Company: %[Company]Email: %[Email]Phone: %[Phone]Address:%[Street]%[City],%[State]%[Country]Status: %[Status]</Body>

<sysfiletype>SFLead</sysfiletype><syssffirstname>%[FirstName]</syssffirstname><syssflastname>%[LastName]</syssflastname><syscompany>%[Company]</syscompany><syssfcity>%[City]</syssfcity><sysworkemail>%[Email]</sysworkemail><syssfindustry>%[Industry]</syssfindustry><syssfleadsource>%[LeadSource]</syssfleadsource><sysworkphone>%[Phone]</sysworkphone><syssfcountry>%[Country]</syssfcountry><syssfstate>%[State]</syssfstate><syssfcity>%[City]</syssfcity><syssfstreet>%[Street]</syssfstreet><syssfpostalcode>%[PostalCode]</syssfpostalcode><syssfleadstatus>%[Status]</syssfleadstatus>

</Fields></Mapping><Mapping type="Opportunity"><CacheTables>

<Table name="OpportunityLineItem"><IndexedField name="OpportunityId" />

</Table><Table name="PricebookEntry" /><Table name="Product2" />

</CacheTables><Fields><Title>%[AccountId.Name] [%[Name]]</Title><Body>%[Name]</Body><sysfiletype>SFOpportunity</sysfiletype><syssfaccount>%[AccountId.Name]</syssfaccount><syssfaccountid>%[AccountId]</syssfaccountid><syssfcountry>%[AccountId.BillingCountry]</syssfcountry><syssfstagename>%[StageName]</syssfstagename>

4www.coveo.com 9



<syssfamount>%[Amount]</syssfamount><syssfcurrency>%[CurrencyIsoCode]</syssfcurrency><syssfopportunitytype>%[Type]</syssfopportunitytype><syssfclosedate>%[CloseDate]</syssfclosedate><syssfclosequarter>%[FiscalYear]-Q%[FiscalQuarter]</syssfclosequarter><syssfleadsource>%[LeadSource]</syssfleadsource><syssfname>%[Name]</syssfname>

</Fields></Mapping><Mapping type="Case"><Fields><ContentType>binarydata</ContentType><Title>%[Subject] (%[CaseNumber])</Title><Body>AssetId : %[AssetId]CaseNumber : %[CaseNumber]ClosedDate : %[ClosedDate]Contact : %[ContactId.Name]CurrencyIsoCode : %[CurrencyIsoCode]IsClosed : %[IsClosed]IsEscalated : %[IsEscalated]Origin : %[Origin]Priority : %[Priority]Reason : %[Reason]Status : %[Status]Subject : %[Subject]SuppliedCompany : %[SuppliedCompany]SuppliedEmail : %[SuppliedEmail]SuppliedName : %[SuppliedName]SuppliedPhone : %[SuppliedPhone]Type : %[Type]Description :%[Description]

</Body><sysfiletype>SFCase</sysfiletype>

</Fields></Mapping><Mapping type="Event"><Fields><Title>%[Subject]</Title><Body>%[Description]</Body><sysfiletype>SFEvent</sysfiletype><syssfduration>%[DurationInMinutes]</syssfduration><syssflocation>%[Location]</syssflocation>

</Fields></Mapping><Mapping type="Task"><Fields><Title>%[Subject]</Title><Body>%[Description]</Body><sysfiletype>SFTask</sysfiletype><syssfstatus>%[Status]</syssfstatus><syssfpriority>%[Priority]</syssfpriority>

</Fields></Mapping><Mapping type="CaseComment"><Fields><Body>%[CommentBody]</Body><sysfiletype>SFCaseComment</sysfiletype><syssfcaseid>%[ParentId]</syssfcaseid>

</Fields></Mapping><Mapping type="EmailMessage">

4www.coveo.com 10



<Fields><Title>%[Subject]</Title><Body>%[TextBody]</Body><sysfiletype>SFEmailMessage</sysfiletype><syssfcaseid>%[ParentId]</syssfcaseid><sysdate>%[MessageDate]</sysdate><sysrecipients>%[ToAddress]</sysrecipients><sysfrom>%[FromAddress]</sysfrom><syscc>%[CcAddress]</syscc><sysbcc>%[BccAddress]</sysbcc><sysconversationsubjectid>%[ParentId]</sysconversationsubjectid><sysmailbox>Salesforce.com</sysmailbox>

</Fields></Mapping><Mapping type="Document"><Fields><clickableuri>https://na4.salesforce.com/servlet/servlet.FileDownload?file=%[Id]

</clickableuri><filename>%[Name]</filename><body>%[Body]</body><Title>%[Name]</Title>

</Fields></Mapping><Mapping type="Attachment"><Fields><clickableuri>https://na4.salesforce.com/servlet/servlet.FileDownload?file=%[Id]

</clickableuri><filename>%[Name]</filename><body>%[Body]</body><Title>%[Name]</Title>

</Fields></Mapping>

</Salesforce>

4www.coveo.com 11



7. Creating and Using a Custom Salesforce Mapping FileYou can create a custommapping file to modify the behavior of the Salesforce connector to adapt to yourSalesforce 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 custommapping file. You can simply specify the Salesforce types to index in theMapping Types field for the Salesforce source (see "Configuring and Indexing a Salesforce Source" onpage 17).

To create and use a custom mapping file

1. Copy the content of the default mapping file (see "About the Default SalesforceMapping File" on page 7).

2. Using an administrative account, connect to the CoveoMaster server.

3. Using a text editor:

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

b. Edit the content of themapping file to suit your needs, referring to the following subsections for detailson how tomodify the file:

l "Mapping file structure" on page 13l "Mapping child nodes" on page 13l "Mapping security" on page 14l "Mapping local expressions" on page 15l "Mapping foreign expressions" on page 15l "Using external resolvers" on page 16

c. Save the custommapping file on the CoveoMaster server.

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

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

l When you create a Salesforce source (see "Configuring and Indexing a Salesforce Source" on page17).

OR

l For an existing Salesforce source:

a. On the Coveo server, access the Administration Tool.

b. Select Index > Sources and Collections.

c. UnderCollections, select the collection containing the Salesforce source.

d. UnderSources, select the Salesforce source.

4www.coveo.com 12



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

f. In theMapping File parameter, enter the full path to your custommapping file.

g. Click Apply Changes.

5. Rebuild the source.

7.1 Mapping file structureThemapping file can be divided into three sections:

l CommonMapping: All the settings applied to all themappings.

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

You can addmappings for custom Salesforce types not included in the default mapping file simply bycopying and editing amapping section for an existing type.

l ExternalResolvers: When you need to apply a sophisticatedmapping, you can specify an externalassembly type to call to resolve it.

7.2 Mapping child nodes<Fields>

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

l System fields

System fields can be used directly under the <fields> node. They aremapped to an existing systemfield.

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

l Custom fields

Custom fields can bemapped to a custommetadata name. Themetadata is filled with the string content.

Example: The <CustomField name="SFLocation">%[Location]</CustomField> nodemaps the field named Location on the Salesforce object to themetadata SFLocation on thedocument in the unified index.

<AllowedUsers>

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

l Name: Name of the userl Server: Usually references to the domain

4www.coveo.com 13



7.3 Mapping securityWhen you choose to use the early-binding security method (see "Choosing How to set Permissions for aSalesforce Source" on page 5), you can configure the Salesforce connector by adding or removing allowedgroups and users to themapping file for each object types. The permissions are therefore incorporated in theindex. Using this method is recommended as CES does not have to fetch the security permissions at querytime for each query. However, security permissions can only be set for each object type. This means thatindividual objects of the same type will always have the same security permissions.

Example: The followingmapping code gives to theWindows group Sales from the MyOrganizationdomain access to all the index types as the CommonMapping section applies to all the indexedmappings.

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

</AllowedUser></AllowedUsers>

</CommonMapping>

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

Mapping types to CES custom security groups ( <AllowedUser type="CustomGroup"allowed="true">) simplifies the Salesforce access management since you can add/remove users fromthe Coveo Administration Tool without having tomodify themapping file and rebuild the source (see"Managing Custom Security Groups" on page 25).

Example: The followingmapping code gives access to the Account type to the CES custom securitygroup Salesforce Account Users from the MyOrganization domain.

<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 themapping file. This method however requiresthat youmodify themapping file and rebuild the source each time that you add or remove users or groups.

4www.coveo.com 14



Example: The followingmapping code gives access to the Task type to the Active Directory group Salesfrom the MyOrganization domain.

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

7.4 Mapping local expressionsThe Salesforce 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 thebrackets for this Salesforce object.

Example: The expression <ModifiedDate>%[LastModifiedDate]</ModifiedDate> replaces thestring %[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 unifiedindex.

7.5 Mapping foreign expressionsAs some objects can reference to others in Salesforce, you can fetch the value of a foreign field in yourmappings, 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 retrievesthe value of the fields FirstName and LastName on that object. Then the resulting string is aconcatenation 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 hasto be queried for every foreign expression. Coveo has a local cache for each field value; however theperformance decreases every time it has to fetch field values on a new object. Use them carefully.

4www.coveo.com 15



7.6 Using external resolversWhen declaring an external resolver, you need to provide a unique name as well as a fully qualified type nameto call.

<SalesForce><ExternalResolvers>

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

</SalesForce>

Note: Formore information on fully qualified type names, refer to theMicrosoft document Specifying FullyQualified 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, youmust specify an additional bracketnode 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 asparameters 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, youmust write a DLL that implementsthe 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 ispassed as well as p_CurrentRecord. Finally, the connector cached records, connection, disk cache,etc. can be accessed using themapping utilities. The string returned by the resolve function will be usedas themapping value.

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

4www.coveo.com 16


http://msdn.microsoft.com/en-us/library/yfsftwz6(VS.71).aspx






8. Configuring and Indexing a Salesforce SourceA source defines a set of configuration parameters for a specific Salesforce database.

Note:When your organization has access tomore than one Salesforce environment, youmust define onesource for each Salesforce environment that you wish to index.

To configure and index a Salesforce source


2. Select Index > Sources and Collections.

3. In theCollections section:

a. Select an existing collection in which you wish to add the new source.

OR

b. Click Add to create a new collection.

4. In theSources section, click Add.

5. In theAdd Source page:

4www.coveo.com 17



a. Enter the appropriate value for the following required parameters:

Name

A descriptive name of your choice for the connector source.

Example: Salesforce site

Source Type

The connector used by this source. In this case, select SalesForce.

Note: If you do not seeSalesForce in theSource Type list, ensure that your currentenvironment meets the requirements (see "Salesforce Connector Requirements" on page 3).

Addresses

Enter the SalesforceWebsite URI: http://www.salesforce.com/

Mapping File

Leave this field empty to use the default mapping file that instructs the connector to index basicSalesforce elements (see "About the Default SalesforceMapping File" on page 7) and use theSalesforce Users CES custom security group tomanage securities (see "Choosing How to setPermissions for a Salesforce Source" on page 5).

When you choose to create a custommapping file, enter the absolute full path pointing to yourcustommapping file (see "Creating and Using a Custom SalesforceMapping File" on page 12).

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

Mapping Types

Leave this field empty to instruct the connector to index all themapping types defined in thedefault or custommapping file.

This parameter is useful to easily index only a subset of mapping types among the ones defined inthemapping file. Enter each type to index separated by semicolons (see "About the DefaultSalesforceMapping File" on page 7).

Example: Enter: Event;Task;Case. The content for the other types will not be indexed.

Authentication

Select the Salesforce user identity that you created previously (see "Configuring a SalesforceUser Identity" on page 4).

b. The following parameters generally do not need to be changed:

4www.coveo.com 18



Rating

Change this value only when you want to globally change the rating associated with all items inthis source relative to the rating of other sources.

Example:When this source replaces a legacy system, youmay want to set this parameter toHigh, so that in the search interface, results from this source appear earlier in the list comparedto those from the source for the legacy system.

Document Types

If you defined a custom document type set for this source, select it.

Active Languages

If you defined custom active language sets, ensure to select themost appropriate for this source.

Fields

If you defined custom field sets, ensure to select themost appropriate for this source.

Refresh Schedule

Time interval at which the index is automatically refreshed to keep the index content up-to-date.By default, theEvery day option instructs CES to refresh the source everyday at 12 AM.

Parameter

Click Add Parameterwhen you want to show advanced source parameters (see "ModifyingHidden Salesforce Source Parameters" on page 20).

c. TheOption check boxes generally do not need to be changed:

Index Subfolders

Keep this check box selected (recommended). By doing so, all subfolders from the specifiedstarting address are indexed.

Index the document's metadata

When selected, CES indexes all the document metadata, evenmetadata that are not associatedwith a field. The orphanmetadata are added to the body of the document so that they can besearched using free text queries. This option is cleared by default.

Document's addresses are case-sensitive

Leave the check box cleared. This parameter needs to be checked only in rare cases for systemsin which distinct documents may have the same name but different casing.

Generate a cached HTML version of indexed documents

When you select this check box (recommended), at indexing time, CES creates HTML versionsof indexed documents. In the search interfaces, users can thenmore rapidly review the content byclicking the Quick View link rather than opening the original document with the original application.

4www.coveo.com 19



Consider clearing this check box only when you do not want to useQuick View links or to saveresources when building the source.

Open results with cached version

Leave this check box cleared (recommended) so that in the search interfaces, themain searchresult link opens the original document with the original application. Consider selecting this checkbox only when you do not want users to be able to open the original document but only see theHTML version of the document as aQuick View. In this case, youmust also select Generate acached HTML version of indexed documents.

d. Click Save and Start to save the source configuration and start the indexing of the new source.

6. Validate that the source building process is executed without errors:

l In the navigation panel on the left, click Status, and then validate that the indexing proceeds withouterrors.

OR

l Open the CES Console tomonitor the source building activities.

What's Next?

Depending on themethod that you chose to set permissions on the source (see "Choosing How to setPermissions for a Salesforce Source" on page 5):

l For early-binding security, assign appropriate users to the custom security group (or groups) defined in thedefault or custommapping file (see "Managing Custom Security Groups" on page 25).

OR

l For late binding security:

a. Create a security provider for your Salesforce source (see "Configuring a Salesforce SecurityProvider" on page 27).

b. Associate the security provider with your Salesforce source (see "Modifying Source SecurityPermissions" on page 30).

8.1 Modifying Hidden Salesforce Source ParametersTheAdd Source andSource: ... General pages of the Administration Tool present the parameters withwhich you can configure the connector for most Salesforce setups. More advanced andmore rarely usedparameters are hidden. You can choose tomake one or more of these parameters appear in theAdd SourceandSource: ... General pages of the Administration Tool so that you can change their default value.Consider changing values of hidden parameters only when you encounter time out error messages orperformance issues.

Note: The Salesforce connector uses the open connector framework and can therefore bemodified usingcustom parameters such as liveindexingdelay.

4www.coveo.com 20



The following list describes the available advanced hidden parameters for Salesforce sources. The parametertype (integer, string,…) appears between parentheses following the parameter name.

Timeout (string)

The communication timeout allowed for any request sent to the SalesforceWeb services. The defaultvalue is 100 seconds.

NbRefreshThreads (string)

The number of threads used to handle the indexing operation of the Salesforce repository. The defaultvalue is 1.

FilterExpression (string)

The list of conditions to add to any query sent to Salesforce. These conditions are appended to the WHEREclause of the Salesforce Object Query Language (SOQL) statement sent via theWeb services. There isno default value.

Example: ParentId='5007000000JQpLnAAL' indexes all items that have the specified parent ID.

CustomLoginUri (string)

The URI used to login to SalesforceWeb services. The default value ishttps://login.salesforce.com/.

CustomLoginUriVersion (string)

The API version of SalesforceWeb services to connect to, specified in the ##.# format. The default valueis 23.0.

CustomBaseUri (string)

The base URI used for indexed documents. In other words, this forces the Uri and ClickableUriproperties to have the specified base URI. The default value is https://na1.salesforce.com/.

FixXmlNamespace (Boolean)

Whether or not empty XML namespaces received inWeb service responses must be fixed beforeprocessing. The default value is False .

QueryLimit (integer)

Themaximum number of results returned by a query to Salesforce. The default value is 5000 items.

QueryBatchSize (integer)

Themaximum number of results contained in a query result object (QueryMore). The default value is 200items.

4www.coveo.com 21



ForeignCacheSize (integer)

The B-tree cache size used by the foreign cache. The default value is 3145728 bytes.

ForeignPageSize (integer)

The B-tree page size used by the foreign cache. The default value is 65536 bytes.

PrefetchCacheSize (integer)

The B-tree cache size used by the prefetch cache. The default value is 1000 items.

ExcludeConvertedLeads (Boolean)

When True, leads that are converted will not be indexed. The default value is True . This parameter wasintroduced in CES 6.5.4631.

ExcludeDeletedItems (Boolean)

When True, items that aremarked as "IsDeleted" will not be indexed. The default value is True . Thisparameter was introduced in CES 6.5.4631.

Use the following procedure only when you want to modify one or more of the above hidden sourceparameters.

To modify hidden Salesforce source parameters1. Refer to "Showing Advanced Hidden Source Parameters" on page 23 to add one or more Salesforce

hidden source parameters.2. For a new Salesforce source, access theAdd Source page of the Administration Tool to modify the

value of the newly added advanced parameter:a. Select Index > Sources and Collections.b. UnderCollections, select the collection in which you wish to add the source.c. UnderSources, click Add.d. In theAdd Source page, edit the newly added advanced parameter value.

3. For an existing Salesforce source, access theSource: ... General page of the Administration Tool tomodify the value of the newly added advanced parameter:a. Select Index > Sources and Collections.b. UnderCollections, select the collection containing the source you wish tomodify.c. UnderSources, click the existing Salesforce source in which you wish tomodify the newly added

advanced parameter.d. In theSource: ... General page, edit the newly added advanced parameter value.

What's Next?

Rebuild the source to take into account the changes to the hidden parameters.

4www.coveo.com 22



8.2 Showing Advanced Hidden Source ParametersWhen you create or configure a source, the Coveo Administration Tool presents source parameters withwhich you can configure the connector for most setups. For many connectors, more advanced andmorerarely used source parameters also exist but are hidden by default. CES then uses the default valueassociated with each of these hidden parameters.

You can however choose tomake one or more of these parameters appear in theAdd Source andSource: ...General pages of the Administration Tool so that you can change their default value.

Note: Refer to the documentation of each connector to get information on available hidden parameters.

To show advanced hidden source parameters


2. Access theModify Additional Connector page:a. Select Configuration > Connectors.b. In the panel on the left, select Additional Connector.c. In the list on the right, select the connector for which you wish to show advanced hidden parameters.

3. In theModify Additional Connector page, for each hidden parameter that you wish tomodify, performthe following steps:

a. Click Add Parameter.

b. In theModify the parameters of the additional connector page:

i. In the Type list, select the parameter type as specified in the parameter description.

ii. In theName box, type the parameter name exactly as it appears in the parameter description.Parameter names are case sensitive.

iii. In theDefault Value box, enter the default value specified in the parameter description.

Important: Do not set the value that you wish to use for a specific source. The value that youenter here will be used for all sources defined using this connector so it must be set to therecommended default value. You will be able to change the value for each source later, in theAdd Source andSource: ... General pages of the Administration Tool.

iv. In the Label box, enter the label that you wish to see for this parameter.

To easily link the label to the hidden parameter, you can simply use the parameter name, and ifapplicable, insert spaces between concatenated words.

Example: For theBatchSize hidden parameter, enter Batch Size for the label.

v. Optionally, inQuick Help, enter the help text that you wish to see for this parameter whenclicking the questionmark button beside the parameter value.

Tip: Copy and paste the key elements from the parameter description.

4www.coveo.com 23



vi. For thePredefined values parameter type only, in theValue box, enter the parameter valuesthat you wish to see available in the drop-down parameter that will appear in the AdministrationTool interface. Enter one value per line. The entered values must exactly match the values listedin the hidden parameter description.

vii. Select theOptional parameter check box when you wish to identify this parameter as anoptional parameter.

When cleared, CES does not allow to save changes when the parameter is empty. Thisparameter does not appear forBoolean andPredefined values parameter types.

viii. Select theSensitive information check box for password or other sensitive parameter so that inthe Administration Tool pages where the parameter appears, the parameter value appears hidden(ex.: ). This parameter appears only for theString type.

ix. Select theValidate as an email address check box when you want CES to validate that thetext string that a user enters in this parameter respects the format of a valid email address. Thisparameter appears only for theString type.

x. In theMaximum length box, enter themaximum number of characters for the string. Thisparameter appears only for theString type.

xi. Click Save.

c. Back in theAdditional Connector page, click Apply Changes.

The hidden parameter now appears in theAdd Source andSource: ... General pages of theAdministration Tool for the selected source. You can change the parameter value from these pages. Referto the documentation for each connector for details.

4www.coveo.com 24



9. Managing Custom Security GroupsYou can create custom security groups defined in Coveo Enterprise Search (CES) by declaring them in themapping file used by a connector. A declared custom security group is created the first time themapping file isused to index content from a source.

Custom security groups allow you to easily and efficiently add or remove users or groups having access tospecific index content. Themanagement of members to a custom security group is done from the CoveoAdministration Tool. You can add or remove Active Directory users or groups to a custom security group tomake the change immediately effective.

Example: In themapping file for a Salesforce source, you can assign different custom security groups toeach Salesforce type of content, and then assign different Active Directory users/groups to each customsecurity group (see "Creating and Using a Custom SalesforceMapping File" on page 12).

To manage custom security groups


2. Select Index > Security Details.

3. In theSecurity Details page, underCustom andGroups, click the custom security group for which youwant to add or removemembers.

4. In theSecurity Mapping page for the selected custom security group:

a. To add amember to the custom security group, in theGroup Members lower text box, type theActive Directory user or group name, and then click Add.

The valid Active Directory user or group appears in theGroup Members upper text box.

b. To remove amember from the custom security group, in theGroup Members upper text box, selectthe user or group that you wish to remove, and then click Remove.

c. Click Apply Changes.

4www.coveo.com 25



The corresponding Salesforce content is immediately available from the search interface for themembers of the custom security group.

4www.coveo.com 26



10. Configuring a Salesforce Security ProviderA security provider must be used when you choose to use late-binding security for your Salesforce source(see "Choosing How to set Permissions for a Salesforce Source" on page 5). The Coveo connector needs toresolvemappings between users and groups from your Salesforce environment andMicrosoft ActiveDirectory.

Once the security provider is created, youmust associate it to the Salesforce source. The security provider isinvoked every time a user performs a query and validates with Salesforce if the user performing the query hasthe right to view each document in the query results. This process can be slow; however it allows individualsecurity permissions for each document instead of having permissions for each object type. Users arerequired to enter their account information for Salesforce sources in the Search Interface when using thissecurity method.

To configure a Salesforce security provider


2. Select Configuration > Security.

3. In theSecurity page, in the navigation panel on the left, click Security Providers.

4. In theSecurity Providers page, click Add to create a new security provider.

5. In theModify Security Provider page:

a. Configure the following required parameters:

Name

Choose ameaningful name to identify the security provider.

Example: Salesforce Security Provider

DLL Path

The path to the custom crawler security provider DLL. Enter the following path:

[CES_Installation_Path]\Bin\Coveo.CES.CustomCrawlersSecurityProvider.dll

where you replace [CES_Installation_Path] by the actual path where CES is installed onyour server (by default: C:\Program Files\Coveo Enterprise Search 6).

User Identity

Leave this parameter blank.

b. In theParameters text box, specify custom configuration parameters, entering all parameters as asingle string in the following format:

ParameterName1="ParameterValue1";ParameterName2="ParameterValue2"; etc

4www.coveo.com 27



i. Include the following required parameter:

AssemblyPath

Path to the Salesforce custom crawler executable: [CES_Installation_Path]\Bin\Coveo.CES.CustomCrawlers.Salesforce.dll

where you replace [CES_Installation_Path] by the actual path where CES is installedon your server (by default: C:\Program Files\Coveo Enterprise Search 6).

Example:AssemblyPath="C:\Program Files\Coveo Enterprise Search6\Bin\Coveo.CES.CustomCrawlers.Salesforce.dll"

ii. Consider including the following optional parameters only when you want to change their defaultvalue:

Timeout (string)

The communication timeout allowed for any request sent to the SalesforceWeb services.The default value is 100 seconds.

CustomLoginUri (string)

The URI used to login to SalesforceWeb services. The default value ishttps://login.salesforce.com/.

CustomLoginUriVersion (string)

The API version of SalesforceWeb services to connect to, specified in the ##.# format. Thedefault value is 23.0 .

c. Leave all the Security AssertionMarkup Language (SAML) parameters as is.

6. In theOption section:

a. Youmust select the following check box for the Salesforce connector to work:

Require authorization

To use late-binding security, select to instruct CES to retrieve document-level permissions atquery time from the repository.

b. Youmust clear the following check boxes for the Salesforce connector to work:

Support access list

To use early-binding security, select to instruct the connector to add an Access Control List (ACL)to each document when crawling the repository.

Support expand group

Select to instruct the connector to expand the repository group into a list of repository users.

4www.coveo.com 28



Support expand users

Select to instruct the connector to convert the list of repository users into a list of Microsoft ActiveDirectory users.

c. Clear theDo not block exceptions check box unless instructed to select it by a Coveo Supportagent.

When selected, this option instructs the security provider to transmit errors to CES. In rare cases,this option can provide additional information that may help to diagnose security provider problems.

d. On a 64-bit Coveo server, select theRun in 64 bits check box to instruct CES to run the securityprovider in 64-bit mode and therefore take advantage of the 64-bit performance. Clear this option onlyfor rare connectors (not this connector) for which the security provider must run in 32-bit mode. On a32-bit server, this option is disabled.

7. Click Save.

What's Next?

Associate the security provider with your Salesforce source (see "Modifying Source Security Permissions" onpage 30).

4www.coveo.com 29



11. Modifying Source Security PermissionsThree levels of security exist in CES:

l Collection-level security;l Source-level security;l Document-level security.

Source-level permissions determine which users have access to a source. By default, sources can beaccessed by all users who have access to the parent collection. You can however override thesepermissions. Even if a user has access to a source, document-level permissions are required to display itscontent.

Note: Source-level permissions are not indexed forWeb Pages sources; however, if Web files are storedlocally (i.e. on the same network as CES), it is possible to associate file server permissions to them. Also,Manual Connector sources do not have permissions.

This topic contains the following sections:

l "Modifying the source permissions" on page 30

l "Mapping the security permissions of aWeb source" on page 31

11.1 Modifying the source permissions1. On the Coveo server, access the Administration Tool.

2. Access theSources and Collections page (Index > Sources and Collections).

3. In theSources section, expand the appropriate source drop-down list.

4. Select Edit Permissions. ThePermissions page corresponding to the source is displayed.

5. In thePermissions section, select one of the following options:

4www.coveo.com 30



Index security permissions

Grants access to all users having the appropriate collection permissions. Document-level security isindexed.

Specify the security permissions to index

Grants access only to users whose accounts are entered in theAllowed Users field. Document-levelpermissions are not indexed.

Important: Because document-level permissions are not indexed, even users who do not haveaccess to a document are able to view its excerpt, summary andQuick View from the searchresults.

Index security permissions and specify additional security permissions to index

Indexes document-level permissions and grants additional access to users whose accounts areentered in theAllowed Users field and denies access to users whose accounts are entered in theDenied Users field.

Important: The accounts entered in theAllowed Users field override document-level permissions.This means that even users who do not have access to a document are able to view its search resultexcerpt, summary, andQuick View.

Use a security provider

Select this option when the permissions used by the source are not Windows-based. In theSecurityProvider drop-down list, select the security provider that you created for this source.

6. When you selectedSpecify the security permissions to index or Index security permissions andspecify additional security permissions to index, for each user to which you want to modify thesource permissions:

a. In theAllowed Users field, using the domain\user form, enter the NT/AD account allowed toaccess the source, and then click Add.

b. In theDenied Users field, using the domain\user form, enter the NT/AD account denied to accessthe source, and then click Add.

7. Click Apply Changes.

11.2 Mapping the security permissions of a Web sourceMappingWeb Page sources with local files allows the indexing of document-level security permissions forthese sources.

Example: If http://www.coveo.com is mapped with its equivalent folder on\\CoveoServer\WebPage\, the permissions granted to the files in the \\CoveoServer\WebPage\folder are also indexed for theWeb Pages sources.

4www.coveo.com 31




2. Access theSources and Collections page (Index > Sources and Collections).

3. In theSources section, expand the web source drop-down list.

a. Select Edit Permissions. ThePermissions page corresponding to the source is displayed.

b. Click Add. TheEdit Web File Security page is displayed.

4. In theWeb Address field, enter the address of theWeb source.

Example: http://www.coveo.com

5. In theNetwork File Path field, enter the path of the folder containing theWeb files.

Example: \\CoveoServer\WebPage\.

6. Click Save.

4www.coveo.com 32


coveo platform 6.5 - salesforce connector guide (string )...

Documents