Coveo Platform 7.0 >

Administrator Help > Connectors > Salesforce Connector > Salesforce ObjectsToGet Configuration File

Salesforce ObjectsToGet Configuration File

The ObjectsToGet configuration file of the Salesforce connector contains the definition of all standard or custom objects that will be retrieved from the Salesforce organization. Each object definition is used to generate the SOQL query executed by the connector to retrieve the records for that object.

With this configuration file, you get control over:

Which information is retrieved by specifying the fields and relationships that should be fetched for each object. This information will be available to use in the mapping file.
Which records are returned by specifying conditions on the SOQL query that will be used to filter the query results.

Notes:

If you want to retrieve Salesforce Knowledge Base articles, you need to specify at least two queries for each type of Knowledge article, one for the *__ka object and one the *__kav object (see Salesforce ObjectsToGet Configuration File Example for Knowledge Base).
There is a bug in the Salesforce API that causes the returned JSON to be invalid when querying a binary field of an object, so ensure to not include any binary field in your query.
CES 7.0.7914+ (October 2015) Support for the * character to replace a list of Objects and Parent relationship fields that are queryable.
Example: When the mapping file contains the following:
```
<Query>
 <ObjectName>Case</ObjectName>
 <Fields>
  <string>*</string>
 </Fields>
</Query>
```
You can use the following SOQL query: <Query value="Select * from Case" />
CES 7.0.8047+ (December 2015) Support for the * character to replace a list of Child relationship fields that are queryable.

Example: <Query value="Select *,Parent.*, (Select * from Children) From Object/>

Salesforce Object Definition

To obtain the list of queryable fields on a specific object:

Salesforce developers can use the describeSObject() method to obtain the complete object definition in JSON format.

Example: https://na15.salesforce.com/services/data/v27.0/sobjects/Account/describe
Salesforce administrators can obtain the complete list of fields from Salesforce API online documentation (see Account, Task).

To obtain the list of available relationships on a specific object:

Salesforce administrators can access any object definition from Salesforce in the Setup under the Customize menu. Object relationships are identified by fields of data type Lookup (see AccountFields, TaskFields).

Configuration File Elements

The ObjectsToGet Salesforce configuration file is an aggregate of query XML nodes. A query node contains several elements, each one being used to generate the SOQL query of a Salesforce object.

Value attribute (optional)CES 7.0.7814+ (August 2015)

You can specify an SOQL query in the query value as shown in the following example (see Salesforce Object Query Language (SOQL)):

<Query value="Select Id, Owner.Id, (Select Id From Shares) From Case Where CaseNumber>10" />

Keep in mind that only what is already in the objects to get is supported.

ObjectName (required): The name of the object (standard or custom) to query (see Standard Objects).

Note: If you are using the value attribute, the object name is optional and must be the same.

GroupBy (optional): The name of the field on which results should be grouped by.

Limit (optional): The maximum number of items that will be retrieved by the query.

Offset (optional): The number of items that should be skipped in query results.

Fields (required)

Contains the name of the fields (Field Name column in Salesforce) that will be available on each record returned by the query. Each field name must be in a <string> element, no matter its data type. Fields specified in this section can be of any data type except Lookup.

Example:

<Query>
  <ObjectName>Account</ObjectName>
  <Fields>
    <string>Id</string>
    <string>IsDeleted</string>
    <string>Name</string>
    <string>Type</string>
    <string>BillingStreet</string>
    <string>BillingCity</string>
    <string>BillingState</string>
    <string>BillingPostalCode</string>
    <string>BillingCountry</string>
    <string>Phone</string>
    <string>Fax</string>
    <string>AccountNumber</string>
    <string>Website</string>
    <string>Sic</string>
    <string>Industry</string>
    <string>AnnualRevenue</string>
    <string>NumberOfEmployees</string>
    <string>Ownership</string>
    <string>TickerSymbol</string>
    <string>Description</string>
    <string>Rating</string>
    <string>Site</string>
    <string>CreatedDate</string>
    <string>LastModifiedDate</string>
    <string>SystemModstamp</string>
  </Fields>
</Query>

QueryCondition (optional)

Important: CES 7.0.6942– (August 2014) This operator is not validated and has a free form. However, the resulting SOQL must be in the format FIELD OPERATOR VALUE. Rather use QueryCondition2.

One or more conditions that will be applied to the SOQL query used to retrieve object records.

Field (required):

Case-insensitive name of the object field on which the condition is applied. Relationship names can also be used (ex.: Parent.Type).
Operator (required):

The operator to apply to the condition. Any operator supported by Salesforce SOQL queries can be used (see Comparison Operators).
Value (required):

Case-sensitive value used to evaluate the condition. String values must be enclosed in single quotes.

Example:

<Query>
  <ObjectName>Account</ObjectName>
  <Fields>
    <string>Name</string>
    <string>AccountNumber</string>
  </Fields>
  <Conditions>
    <QueryCondition>
      <Field>Type</Field>
      <Operator>!=</Operator>
      <Value>'Prospect'</Value>
    </QueryCondition>
    <QueryCondition>
      <Field>Owner.Name</Field>
      <Operator>=</Operator>
      <Value>'John Smith'</Value>
    </QueryCondition>
  </Conditions>
</Query>

The generated query is:

SELECT Name FROM Account WHERE Type != 'Prospect' AND Owner.Name = 'John Smith'

QueryCondition2 (optional)

Note: This query condition is validated and has more options. This is the prefered way to create a query condition.

One or more conditions that will be applied to the SOQL query used to retrieve object records.

Field (required): Case-insensitive name of the Object Field on which the condition is applied. Relationship names can also be used (e.g. Parent.Type).
Relation (required): The operator to apply to the condition. Supported operators are Equal, NotEqual, Less, LessOrEqual, Greater, GreaterOrEqual, Like, NotLike.
SoqlString|SoqlBoolean|SoqlDateTime (required): Case-sensitive value (not Like) used to evaluate the condition.

Example:

<Query>
  <ObjectName>Account</ObjectName>
  <Fields>
    <string>Name</string>
  </Fields>
  <Conditions>
    <QueryCondition2>
      <Field>Type</Field>
      <Relation>NotEqual</Relation>
      <SoqlString>Prospect</SoqlString>
    </QueryCondition2>
    <QueryCondition2>
      <Field>IsEscalated</Field>
      <Relation>Equal</Relation>
      <SoqlBoolean>true</SoqlBoolean>
    </QueryCondition2>
    <QueryCondition2>
      <Field>LastViewDate</Field>
      <Relation>GreaterOrEqual</Relation>
      <SoqlDateTime>2014-04-28T00:00:00.0000000-00:00</SoqlDateTime>
    </QueryCondition2>
  </Conditions>
</Query>

Note: For SoqlDateTime, the date/time format must exactly match YYYY-MM-DDTHH:MM:SS.0000000-00:00

The generated query is:

SELECT Name FROM Account WHERE Type != 'Prospect' AND IsEscalated = true AND LastViewDate >= 2014-04-28T00:00:00

InCondition (optional)

Field (required): Case-insensitive name of the Object Field on which the condition is applied. Relationship names can also be used (e.g. Parent.Type).
AllowedValues (required): Case-sensitive possible values of the field.

Example:

<Query>
  <ObjectName>Account</ObjectName>
  <Fields>
    <string>Name</string>
  </Fields>
  <Conditions>
    <InCondition>
      <Field>Type</Field>
      <AllowedValues>
        <SoqlString>Prospect</SoqlString>
        <SoqlString>Client</SoqlString>
      </AllowedValues>
    </InCondition>
  </Conditions>
</Query>

The generated query is:

SELECT Name FROM Account WHERE Type IN ('Prospect', 'Client')

InQueryCondition (optional)

CES 7.0.7183+ (November 2014) Semi-joins are supported in query's conditions (see Comparison Operators). Semi-joins are useful when you want to index only a subset of records based on another set of records.

Field (required):

Case-insensitive name of the object field on which the condition is applied. Relationship names can also be used (ex.: Parent.Type).
Query (required): A valid query object (with ObjectName, Fields, etc) (see Semi-Joins or Anti-Joins Relationship Query Limits).

Example:

<Query>
   <ObjectName>Case</ObjectName>
   <Fields>
     <string>Id</string>
   </Fields>
   <Conditions>
     <InCondition>
       <Field>Id</Field>
       <Query>
         <ObjectName>CaseComment</ObjectName>
         <Fields>
           <string>ParentId</string>
         </Fields>
         <Conditions>
           <QueryCondition>
             <Field>CommentBody</Field>
             <Operator>=</Operator>
             <Value>'this is a test'</Value>
           </QueryCondition>
         </Conditions>
       </Query>
     </InCondition>    
   </Conditions>
 </Query>

The generated query is:

SELECT Id FROM Case WHERE Id IN (SELECT ParentId FROM CaseComment WHERE CommentBody = 'this is a test')

Not InQueryCondition (optional)

CES 7.0.7183+ (November 2014) Anti-joins are supported in query's conditions (see Comparison Operators). Anti-joints are useful when you want to index only a subset of records based on another set of records.

Field (required):

Case-insensitive name of the object field on which the condition is applied. Relationship names can also be used (ex.: Parent.Type).
Query (required): A valid query object (with ObjectName, Fields, etc) (see Semi-Joins or Anti-Joins Query Limits).

Example:

<Query>
   <ObjectName>Case</ObjectName>
   <Fields>
     <string>Id</string>
   </Fields>
   <Conditions>
     <NotCondition>
       <InCondition>
         <Field>Id</Field>
         <Query>
           <ObjectName>CaseComment</ObjectName>
           <Fields>
             <string>ParentId</string>
           </Fields>
           <Conditions>
             <QueryCondition>
               <Field>CommentBody</Field>
               <Operator>=</Operator>
               <Value>'this is a test'</Value>
             </QueryCondition>
           </Conditions>
         </Query>
       </InCondition>
     </NotCondition>
   </Conditions>
 </Query>

The generated query is:

SELECT Id FROM Case WHERE NOT Id IN (SELECT ParentId FROM CaseComment WHERE CommentBody = 'this is a test')

ParentRelationship (optional)

One or more relationships which information will be available on each object record returned by the query. An object relationship is defined by a lookup field which creates a relation between the current object being queried and another object. These relations allow SOQL query operations similar to SQL joins.

RelationshipName (required):

The field name of data type Lookup.
Fields (required):

The name of the fields of the related object that will be available on each record returned by the query.
ParentRelationships (optional):

Another level of parent relationship, but this time, the relationship applies to the related object.

Example:

<Query>
  <ObjectName>Account</ObjectName>
  <Fields>
    <string>Name</string>
    <string>AccountNumber</string>
  </Fields>
  <ParentRelationships>
    <ParentRelationship>
      <RelationshipName>Owner</RelationshipName>
      <Fields>
        <string>Name</string>
        <string>Email</string>
      </Fields>
    </ParentRelationship>
  </ParentRelationships>
</Query>

Important: The parent field is copied to the record. If the parent is modified, the indexed record is not updated.

ChildRelationship (optional)

One or more relationships which information will be available on each Object record returned by the query. An Object relationship is defined by a Lookup Field which creates a relation between the current Object being queried and another Object. These relations allow SOQL query operations similar to SQL joins.

Query (required): A valid query object (with ObjectName, Fields, etc).

Example:

<Query>
  <ObjectName>Opportunity</ObjectName>
  <Fields>
    <string>Id</string>
    <string>Name</string>
  </Fields>
  <ChildRelationships>
    <Query>
      <ObjectName>Attachments</ObjectName>
      <Fields>
        <string>Id</string>
        <string>Name</string>
      </Fields>
    </Query>
  </ChildRelationships>
</Query>

The generated query is:

SELECT Id, Name, (SELECT Id, Name FROM Attachments) FROM Opportunity

The generated metadata, when an attachment is found on the opportunity:

"Attachments.attribute.type" => "Attachment"
"Attachments.attribute.url" => "/services/data/v29.0/sobjects/Attachment/00PG000000B8RUvMAN"
"Attachments.Id" => "00PG000000B8RUvMAN"
"Attachments.Name" => "a_stash_of_werthers.jpg"

Note:

When more than one child exist, the fields contain values separated with a semicolon.

Example: Attachments.Name: a.jpg;b.jpg
Nested child relationships (sub-sub queries) are not supported.

Important: CES 7.0.8850– (March 2017) The child field is copied to the record. If a child is modified, the indexed record is not updated.

CreateRecord (optional)

CES 7.0.8996+ (June 2017) To be used only inside a ChildRelationship. It creates an item from child records.

In the following example, Attachments from Opportunities are created as items in the Coveo index.

Example:

<Query>
  <ObjectName>Opportunity</ObjectName>
  <Fields>
    <string>Id</string>
    <string>Name</string>
  </Fields>
  <ChildRelationships>
    <ChildRelationship>
      <RelationshipName>Attachments</RelationshipName>
      <Fields>
        <string>Id</string>
        <string>Name</string>
      </Fields>
      <CreateRecord>true</CreateRecord>
    </ChildRelationship>
  </ChildRelationships>
</Query>

PolymorphicRelationship (optional)

Polymorphic relationships can be useful for parent relationships on a Lookup field that can be related to multiple types of objects (ex.: Lookup(Contract,Campaign,Account,Opportunity,Product,Asset,Case,Solution)). The polymorphic relationship allows for different fields to be retrieved depending on the object that will be related for a specific record.

Notes:

CES 7.0.8047+ (December 2015) Polymorphic relationships no longer depend on a parent relationship to work.
Example: You can add the following on feed items (TextPost, LinkPost, ContentPost, PollPost) to create the CreatedBy.SmallPhotoUrl metadata when indexing FeedItem, FeedComment and collaborationgroup:
```
<PolymorphicRelationship>
<RelationshipName>CreatedBy</RelationshipName>
<ObjectName>User</ObjectName>
<Fields>
<string>Name</string>
<string>Type</string>
<string>PhotoURL</string>
</Fields>
</PolymorphicRelationship>
```
The two following metadata appear on the record with polymorphic relationships: <polymorphic_relationship_name>.<field> and <polymorphic_relationship_name>_<object_name>.<field>.
CES 7.0.7104– (October 2014) The record with polymorphic relationships only provided the metadata named <polymorphic_relationship_name>_<object_name>.<field>.

RelationshipName (required):

The field name of data type Lookup.
ObjectName (optional):

The related object type this polymorphic relationship applies to.

Note: CES 7.0.7104– (October 2014) The ObjectName field is required.
Fields (required):

The name of the fields of the related object that will be available on each record returned by the query.
ParentRelationships (optional):

Another level of parent relationship, but this time, the relationship applies to the related object.

Example:

<Query>
  <ObjectName>Task</ObjectName>
  <Fields>
    <string>Id</string>
    <string>Subject</string>
    <string>ActivityDate</string>
  </Fields>
  <ParentRelationships>
    <ParentRelationship>
      <RelationshipName>What</RelationshipName>
      <Fields>
        <string>Name</string>
        <string>Type</string>
      </Fields>
    </ParentRelationship>
  </ParentRelationships>
  <PolymorphicRelationships>
    <PolymorphicRelationship>
      <RelationshipName>What</RelationshipName>
      <ObjectName>Account</ObjectName>
      <Fields>
        <string>Name</string>
        <string>AccountNumber</string>
      </Fields>
    </PolymorphicRelationship>
    <PolymorphicRelationship>
      <RelationshipName>What</RelationshipName>
      <ObjectName>Opportunity</ObjectName>
      <Fields>
        <string>Amount</string>
        <string>TotalOpportunityQuantity</string>
      </Fields>
    </PolymorphicRelationship>
  </PolymorphicRelationships>
</Query>

Important: The parent field is copied to the record. If a parent is modified, the indexed record is not updated.

Order (optional) CES 7.0.6607+ (April 2014)

One or more order restrictions that will be applied to the SOQL query used to retrieve Object records.

Ascending (optional): The direction of the ordering. Default is true (ascending). Use false for descending.
NullsFirst (optional): Whether records with NULL values in the specified fields must be returned first or last. Default is true.
Fields (required): One or more fields to base the ordering on, in the specified field order.

Examples:

With the following configuration:

Opportunity.Id shows that we can specify the query object name as the parent of the field.
Account.Foo.Id is a field on the parent Foo, which is also a field of the parent Account of Opportunity.
What.Id is a field on the polymorphic parent What of Opportunity.

<Query>
  <ObjectName>Opportunity</ObjectName>
  <Fields>
    <string>Id</string>
  </Fields>
  <Order>
    <Ascending>true</Ascending>
    <NullsFirst>false</NullsFirst>
    <Fields>
      <string>Name</string>
      <string>Opportunity.Id</string>
      <string>Account.Foo.Id</string>
      <string>What.Id</string>
    </Fields>
  </Order>
</Query>

The generated query is:

SELECT Id FROM Opportunity ORDER BY Name, Opportunity.Id, Account.Foo.Id, What.Id ASC NULLS LAST

Configuration including a child relationship:

<Query>
  <ObjectName>Opportunity</ObjectName>
    <Fields>
      <string>Id</string>
    </Fields>
    <ChildRelationships>
      <Query>
        <ObjectName>Attachments</ObjectName>
        <Fields>
          <string>Id</string>
        </Fields>
        <Order>
          <Fields>
            <string>Name</string>
          </Fields>
        </Order>
      </Query>
    </ChildRelationships>
 </Query>

The generated query is:

SELECT Id, (SELECT Id FROM Attachments ORDER BY Name ASC NULLS FIRST) FROM Opportunity

XML Schema Definition

Note: CES 7.0.7183+ (November 2014) Each of the ObjectsToGet in your Salesforce sources are validated against the XSD.

If it is not the case, a SALESFORCE_INVALID_CONFIGURATION error message appears in the CES console and logs.

Use the following XML schema definition to validate your configuration file.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="ArrayOfQuery" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
  <xs:element name="Fields">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="string" nillable="true" minOccurs="0" maxOccurs="unbounded">
          <xs:complexType>
            <xs:simpleContent msdata:ColumnName="string_Text" msdata:Ordinal="0">
              <xs:extension base="xs:string">
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="ParentRelationships">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ParentRelationship" minOccurs="0" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="RelationshipName" type="xs:string" minOccurs="0" maxOccurs="1" />
              <xs:element ref="Fields" minOccurs="0" maxOccurs="unbounded" />
              <xs:element name="ParentRelationships" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="ParentRelationship" minOccurs="0" maxOccurs="unbounded">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="RelationshipName" type="xs:string" minOccurs="0" maxOccurs="1" />
                          <xs:element ref="Fields" minOccurs="0" maxOccurs="unbounded" />
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="Query" type="QueryType" />
  <xs:complexType name="QueryType">
    <xs:sequence>
      <xs:element name="ObjectName" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="GroupBy" type="xs:string" minOccurs="0" />
      <xs:element name="Limit" type="xs:string" minOccurs="0" />
      <xs:element name="Offset" type="xs:string" minOccurs="0" />
      <xs:element name="FoundRecordsAreDeleted" type="xs:string" minOccurs="0" />
      <xs:element ref="Fields" minOccurs="0" maxOccurs="unbounded" />
      <xs:element name="Order" minOccurs="0" maxOccurs="1">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Ascending" type="xs:boolean" minOccurs="0" maxOccurs="1" />
            <xs:element name="NullsFirst" type="xs:boolean" minOccurs="0" maxOccurs="1" />
            <xs:element ref="Fields" minOccurs="0" maxOccurs="unbounded" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="Conditions" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="QueryCondition" minOccurs="0" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="Field" type="xs:string" minOccurs="0" maxOccurs="1" />
                  <xs:element name="Operator" type="xs:string" minOccurs="0" maxOccurs="1" />
                  <xs:element name="Value" type="xs:string" minOccurs="0" maxOccurs="1" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element ref="ParentRelationships" minOccurs="0" maxOccurs="unbounded" />
      <xs:element name="PolymorphicRelationships" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="PolymorphicRelationship" minOccurs="0" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="RelationshipName" type="xs:string" minOccurs="0" maxOccurs="1" />
                  <xs:element name="ObjectName" type="xs:string" minOccurs="0" maxOccurs="1" />
                  <xs:element ref="Fields" minOccurs="0" maxOccurs="unbounded" />
                  <xs:element ref="ParentRelationships" minOccurs="0" maxOccurs="unbounded" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="ChildRelationships" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Query" type="QueryType" minOccurs="0" maxOccurs="unbounded" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>  
  <xs:element name="ArrayOfQuery" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="Query" minOccurs="0" maxOccurs="unbounded">
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

What's Next?

Create your ObjectsToGet configuration file (see Creating a Salesforce ObjectsToGet Configuration File).

Ask your questions on connect.coveo.com.

People who viewed this topic also viewed

Community

Product DocsMenu

Salesforce ObjectsToGet Configuration File

Salesforce Object Definition

Configuration File Elements

XML Schema Definition