Using Relationship Queries with Data Category Selection Objects. salesforce Knowledge

Salesforce Knowledge with SOQL and SOSL Using Relationship Queries with Data Category Selection

Objects

Using Relationship Queries with Data Category Selection Objects

Data categories are used to classify records. In SOQL, you can use the Article__DataCategorySelection or QuestionDataCategorySelection objects. You can also build a relationship query with the

DataCategorySelections

relationship name in a

FROM

clause.

Imagine an Offer article type. The following query returns the ID of any categorization associated with an offer and the ID of the categorized article.

SELECT Id,ParentId

FROM Offer__DataCategorySelection

The following example uses the DataCategorySelections relationship name to build a relationship query that returns the ID of published offers and the ID of all the categorizations associated to these offers.

SELECT Id, Title

(

SELECT Id

FROM DataCategorySelections

)

FROM Offer__kav WHERE publishStatus='online';

About SOSL

Use the Salesforce Object Search Language (SOSL) to construct text-based search queries against the search index.

You can search text, email, and phone fields for multiple objects, including custom objects, that you have access to in a single query in the following environments.

• SOAP or REST calls

• Apex statements

• Visualforce controllers and getter methods

• Schema Explorer of the Eclipse Toolkit

Note: If your org has relationship queries enabled, SOSL supports SOQL relationship queries.

Compare SOSL and SOQL

Use SOQL when:

• You want to search against the org’s database. Results from a database search include matches for the exact search string.

• You know in which objects or fields the data resides.

• You want to:

– Retrieve data from a single object or from multiple objects that are related to one another

– Count the number of records that meet specified criteria

– Sort results as part of the query

– Retrieve data from number, date, or checkbox fields

Use SOSL when:

• You don’t know in which object or field the data resides, and you want to find it in the most efficient and fastest way possible.

175

Salesforce Knowledge with SOQL and SOSL Update an Article’s Keyword Tracking with SOSL

• You want to:

– Retrieve data for a specific term that you know exists within a field. Because SOSL can tokenize multiple terms within a field and build a search index off this, SOSL searches are faster and can return more relevant results. Depending on the search object,

SOSL searches also take advantage of the advanced features of the search index, such as out-of-order matching, synonyms, lemmatization, and spell check.

– Retrieve multiple objects and fields efficiently, and the objects might or might not be related to one another.

– Retrieve data for a particular division in an org using the divisions feature, and you want to find it in the most efficient way possible.

Define Efficient SOSL Text Searches

If your searches are too general, they are slow and return too many results. Use the following clauses to write more targeted and useful searches.

• IN : Limits the types of fields to search, including email, name, or phone.

• LIMIT : Specifies the maximum number of rows to return.

•

OFFSET

: Displays the search results on multiple pages.

• RETURNING : Limits the objects and fields to return.

• WITH DATA CATEGORY : Specifies the data categories to return.

•

WITH DivisionFilter

: Specifies the division field to return.

• WITH NETWORK : Specifies the community ID to return.

• WITH PricebookId : Specifies the price book ID to return.

IN THIS SECTION:

Update an Article’s Keyword Tracking with SOSL

Track keywords that are used in Salesforce Knowledge article searches with the UPDATE TRACKING optional clause on a SOSL query. You can use the language attribute to search by locale.

Update an Article’s Viewstat with SOSL

Determine how many hits a Salesforce Knowledge article has had by using the

UPDATE VIEWSTAT

optional clause on a SOSL query. You can use the language attribute to search by locale.

WITH DATA CATEGORY DataCategorySpec

WITH DATA CATEGORY is an optional clause that can be added to a SOSL query to filter all search results that are associated with one or more data categories and are visible to users. This clause is used in searches of Salesforce Knowledge articles and questions.

WITH SNIPPET

WITH SNIPPET

is an optional clause that can be added to a SOSL query for article, case, feed, and idea searches. On the search results page, excerpts below article titles show terms matching the search query highlighted within the context of surrounding text.

Snippets make it easier for users to identify the content they’re looking for.

Update an Article’s Keyword Tracking with SOSL

Track keywords that are used in Salesforce Knowledge article searches with the UPDATE TRACKING optional clause on a SOSL query.

You can use the language attribute to search by locale.

176

Salesforce Knowledge with SOQL and SOSL Update an Article’s Viewstat with SOSL

The

UPDATE TRACKING

clause is used to report on Salesforce Knowledge article searches and views. It allows developers to track the keywords used in Salesforce Knowledge article searches. Also, the language attribute can be used to search by a specific language

(locale). However, only one language can be specified in a single query. Make a separate query for each language that you want. Use the Java format, which uses the underscore (for example, fr_FR, jp_JP, and so on), to supply locales. Search the Web for “java locale codes” to get a list of supported locales.

You can use this syntax to track a keyword used in Salesforce Knowledge article search:

FIND {Keyword}

RETURNING KnowledgeArticleVersion (Title WHERE PublishStatus="Online" and language="en_US")

UPDATE TRACKING

Update an Article’s Viewstat with SOSL

Determine how many hits a Salesforce Knowledge article has had by using the

UPDATE VIEWSTAT

optional clause on a SOSL query.

You can use the language attribute to search by locale.

The optional

UPDATE VIEWSTAT

clause is used to report on Salesforce Knowledge article searches and views. It allows developers to update an article’s view statistics. Also, the language attribute can be used to search by a specific language (locale). However, only one language can be specified in a single query. Make a separate query for each language that you want. Use the Java format, which uses the underscore (for example, fr_FR, jp_JP, and so on), to supply locales. Search the Web for “java locale codes” to get a list of supported locales.

You can use this syntax to increase the view count for every article you have access to online in US English:

FIND {Title}

RETURNING FAQ__kav (Title WHERE PublishStatus="Online" and language="en_US" and

KnowledgeArticleVersion = 'ka230000000PCiy')

UPDATE VIEWSTAT

WITH DATA CATEGORY

DataCategorySpec

WITH DATA CATEGORY

is an optional clause that can be added to a SOSL query to filter all search results that are associated with one or more data categories and are visible to users. This clause is used in searches of Salesforce Knowledge articles and questions.

The

WITH DATA CATEGORY

clause can be used in API version 18.0 or later.

Syntax

The WITH DATA CATEGORY syntax is:

WITH DATA CATEGORY DataCategorySpec [ logicalOperator DataCategorySpec2 ... ]

Where

DataCategorySpec

consists of a groupName

,

Operator

, and category

.

Name groupName

Operator

Description

The name of the data category group to filter. For information on category groups, see “Create and

Modify Category Groups” in the Salesforce Help.

Use one of the following operators:

•

AT

—Queries the specified data category.

177

Salesforce Knowledge with SOQL and SOSL WITH DATA CATEGORY DataCategorySpec

Name category

Description

•

ABOVE

—Queries the specified data category and all of its parent categories.

• BELOW —Queries the specified data category and all of its subcategories.

•

ABOVE_OR_BELOW

—Queries the specified data category, all of its parent categories, and all of its subcategories.

The name of the category to filter. To include multiple data categories, enclose them in parentheses, separated by commas. For information on categories, see “Add Data Categories to Category Groups” in the Salesforce Help.

You can add multiple data category specifiers by using the logical operator AND . Other operators, such as OR and AND NOT , are not supported.

A SOSL statement using the WITH DATA CATEGORY clause must also include a RETURNING ObjectTypeName clause, with a WHERE clause that filters on the PublishStatus field.

In the

RETURNING

clause, specify one of the following for

ObjectTypeName

:

• To search a specific article type, use the article type name with the suffix __kav

• To search all article types, use KnowledgeArticleVersion

• To search questions, use Question

For information on article types, see “Knowledge Article Types” in the Salesforce Help.

The

WHERE

clause must use one of the following publish statuses:

• WHERE PublishStatus='online' for published articles

•

WHERE PublishStatus='archived'

for archived articles

• WHERE PublishStatus='draft' for draft articles

Examples

Search Type

Search all published (online)Salesforce

Knowledge articles with a category from one category group.

Example

FIND {tourism} RETURNING KnowledgeArticleVersion

(Id, Title WHERE PublishStatus='online')

WITH DATA CATEGORY Location__c AT America__c

Search online FAQ articles with categories from two category groups.

FIND {tourism} RETURNING FAQ__kav

(Id, Title WHERE PublishStatus='online')

WITH DATA CATEGORY Geography__c ABOVE France__c

AND Product__c AT mobile_phones__c

Search archived FAQ articles from one category group.

FIND {tourism} RETURNING FAQ__kav

(Id, Title WHERE PublishStatus='archived')

WITH DATA CATEGORY Geography__c AT Iceland__c

178

Salesforce Knowledge with SOQL and SOSL

Search Type

Search all draft Salesforce Knowledge articles from one category group.

Example

FIND {tourism} RETURNING KnowledgeArticleVersion

(Id, Title WHERE PublishStatus='draft')

WITH DATA CATEGORY Geography__c BELOW Europe__c

WITH SNIPPET

For information on the

WITH DATA CATEGORY

clause, see the

WITH DATA CATEGORY filteringExpression

.

Tip: You can also search for articles by ID, without using the

WITH DATA CATEGORY

clause. For more information, see

Example WHERE Clauses.

WITH SNIPPET

WITH SNIPPET

is an optional clause that can be added to a SOSL query for article, case, feed, and idea searches. On the search results page, excerpts below article titles show terms matching the search query highlighted within the context of surrounding text. Snippets make it easier for users to identify the content they’re looking for.

Note: To generate search results with highlighted matches but not snippets, use WITH HIGHLIGHT .

Search snippets and highlights are generated from the following field types.

• Email

• Text

• Text Area

• Text Area (Long)

• Text Area (Rich)

Search snippets and highlights are not generated from the following field types.

• Checkbox

• Currency

• Date

• Date/Time

• File

• Formula

• Lookup Relationship

• Number

• Percent

• Phone

• Picklist

• Picklist (Multi-Select)

• URL

179

Salesforce Knowledge with SOQL and SOSL WITH SNIPPET

Example: The following SOSL statement returns snippets for articles that match the search term

San Francisco

.

FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE

PublishStatus = 'Online' AND Language = 'en_US') WITH

SNIPPET (target_length=120)

The matching terms are highlighted with

<mark>

tags within the context of the snippet results. Stemmed forms of the term and any synonyms defined are also highlighted.

Example:

[ {

"attributes" : {

"type" : "KnowledgeArticleVersion",

"url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaKD00000000001MAA"

},

"Id" : "kaKD00000000001MAA"

"Title" : "San Francisco"

"Summary" : "City and County of San Francisco"

"snippet.text" : "<mark>San</mark> <mark>Francisco</mark>, officially the City and

County of <mark>San</mark> <mark>Francisco</mark> is the... City and County of

<mark>San</mark> <mark>Fran</mark>"

"highlight.Title" : "<mark>San</mark> <mark>Francisco</mark>"

}, {

"attributes" : {

"type" : "KnowledgeArticleVersion",

"url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaBD0000000007DMAQ"

},

"Id" : "kaBD0000000007DMAQ",

"Title" : "San Francisco Bay Area",

"Summary" : "Nine county metropolitan area",

"snippet.text" : "The <mark>SF</mark> Bay Area, commonly known as the Bay Area, is a populated region that"

"highlight.Title" : "<mark>San</mark> <mark>Francisco</mark> Bay Area"

}, {

"attributes" : {

"type" : "KnowledgeArticleVersion",

"url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/ka3D0000000042OIAQ"

},

"Id" : "ka3D0000000042OIAQ",

"Title" : "California",

"Summary" : "State of California",

"snippet.text" : "(Greater Los Angeles area and <mark>San</mark>

<mark>Francisco</mark> Bay Area, respectively), and eight of the nation’s 50 most"

} ]

Note: In this example, “SF” (as a synonym defined for “San Francisco”) and “San Fran” (as a stemmed form of “San Francisco”) are also highlighted in the results as matching terms.

180

Salesforce Knowledge with SOQL and SOSL WITH SNIPPET

Usage

For SOSL statements using the

WITH SNIPPET

clause, we recommend using a

RETURNING ObjectTypeName

clause, with a

WHERE

clause that filters on the

PublishStatus

field.

In the RETURNING clause, specify one of the following for ObjectTypeName :

• To search a specific article type, use the article type name with the suffix __kav.

• To search all article types, use KnowledgeArticleVersion .

• To search case, case comment, feed, feed comment, idea, and idea comment types, use

Case

,

CaseComment

,

FeedItem

,

FeedComment

,

Idea

, and

IdeaComment

. For example:

FIND {San Francisco} IN ALL FIELDS RETURNING FeedItem, FeedComment WITH SNIPPET

(target_length=120)

Other objects that are included in searches that contain WITH SNIPPET don’t return snippets.

Snippets aren’t displayed for search terms that contain a wildcard, when the search doesn’t return any articles, or if the user doesn’t have access to the field that contains the snippet. Even if you add the WITH SNIPPET clause, searches that don’t return snippets don’t return snippets.

Snippets are only displayed when 20 or fewer results are returned on a page.

Tip: Use the LIMIT or OFFSET clause to return only 20 results at a time.

Escaped HTML Tags

When matching terms within HTML tags are returned in a snippet, the HTML tags are escaped and the matching terms are highlighted in the results.

Example: A search for salesforce returns an article with the text “For more information, visit <a href='http://salesforce.com'>salesforce.com</a>”. The original hyperlink tags from the article are escaped (encoded) and “salesforce” is highlighted in the snippet result.

For more information, visit &lt;a href='http://salesforce.com'&gt;salesforce.com&lt;/a&gt;

Target Snippet Length

By default, each snippet displays up to approximately 300 characters, which is usually three lines of text in a standard browser window display. The number of characters displayed is the target length, within a statistically insignificant degree of variance.

Snippets consist of one or more fragments of text that contain the matching terms. If the returned snippet includes multiple text fragments

(for example, for matches within multiple fields), the target length is the maximum total length of all the returned fragments.

To specify an alternate target length, add the optional target_length

parameter to the

WITH SNIPPET

clause. You can specify a target length from 50 to 1,000 characters. When the target_length is set to an invalid number, such as 0 or a negative number, the length defaults to

300

.

Example: A target_length parameter of 120 characters is useful for displaying a snippet of approximately three lines of text in a standard mobile interface.

FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE

PublishStatus = 'Online' AND Language = 'en_US') WITH

SNIPPET(target_length=120)

181

Salesforce Knowledge with SOQL and SOSL WITH SNIPPET

Supported APIs

The

WITH SNIPPET

clause can be used in API version 32.0 or later. The

WITH SNIPPET

clause in SOSL is supported in SOAP API,

REST API, and Apex.

182

CHAPTER 6 Salesforce Knowledge, Apex, and

Visualforce

In this chapter ...

•

PublishingService

Class

With the power of Apex and Visualforce, you can customize the look and feel of your knowledge base; for example, with custom search pages or a robust article publishing cycle.

Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control statements on the Force.com platform server in conjunction with calls to the

Force.com API. Using syntax that looks like Java and acts like database stored procedures, Apex enables developers to add business logic to most system events, including button clicks, related record updates, and Visualforce pages. Apex code can be initiated by Web service requests and from triggers on objects.

Visualforce is a framework that allows developers to build sophisticated, custom user interfaces that can be hosted natively on the Force.com platform. The Visualforce framework includes a tag-based markup language, similar to HTML, and a set of server-side “standard controllers” that makes basic database operations, such as queries and saves, very simple to perform.

Due to the endless possibilities with Apex and Visualforce, only the Apex Publishing Service class is in this guide. For more Apex and Visualforce information see the Apex Developer Guide and the Visualforce

Developer Guide .

183