Knowledge base search control (client-side reference)

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can add a knowledge base search control to entity forms in your Dynamics 365 instance that has the knowledge management feature enabled. With this control, you can programmatically automate or enhance users’ search experiences when they use the control to consume knowledge in Dynamics 365. More information: Knowledge management entities

Note

• You can choose native Dynamics 365 knowledge or Parature knowledge as the source for knowledge management and search. If you use Parature as your knowledge base source and the knowledge base search control is present in the form, a connection with Parature should already be established so that you can directly make Parature API calls without requiring a security token. However, these will be cross-domain requests so you must use cross-origin resource sharing (CORS).

  The following new client APIs introduced in CRM Online 2016 Update 1 and Dynamics 365 Service Pack 1 (on-premises) are not supported if you are using Parature as your knowledge base source: PostSearch event, addOnPostSearch, removeOnPostSearch, getTotalResultCount, and openSearchResult.

• With CRM Online 2016 Update 1 and Dynamics 365 SP1 (on-premises) release, knowledge base search control is also supported for the Dynamics 365 mobile clients (phones and tablets).

The knowledge base search control is an Xrm.Page.ui control, so it supports all the standard methods that controls have. But it also supports additional events and methods. For information about the standard control methods, see Xrm.Page.ui control (client-side reference).

If you know the name of the control, you can access it using the following code where <name> represents the name of the control.

kbSearchControl = Xrm.Page.getControl("<name>");

Note

When the knowledge base search control is added to the social pane the name will be "searchwidgetcontrol_notescontrol". This name can’t be changed.

All of the examples in this topic will use kbSearchControl to represent the knowledge base search control in the form.

In This Topic

Knowledge base search control events

Knowledge base search control methods

Knowledge base search control events

Use the events for this control to allow code to respond to the selected or opened item.

OnResultOpened

This event occurs when a KB article is opened in the knowledge base search control in line or through the pop-out action. Use the addOnResultOpened and removeOnResultOpened methods to manage event handlers for this event.

OnSelection

This event occurs when a KB article is selected in the knowledge base search control. Use the addOnSelection and removeOnSelection methods to manage event handlers for this event.

PostSearch

This event occurs when the search is complete, and the results are displayed. Use the new addOnPostSearch and removeOnPostSearch methods to manage event handlers for this event.

Knowledge base search control methods

Use the methods for the knowledge base search control to set or remove event handlers and interact with the search query and search results.

addOnPostSearch

Use this method to add an event handler to the PostSearch event.

Parameter: Function. The function to add.

Example: Add the function named myFunction to the PostSearch event.

kbSearchControl.addOnPostSearch(myFunction);

addOnResultOpened

Use this method to add an event handler to the OnResultOpened event.

Parameter: Function. The function to add.

Example: Add the function named myFunction to the OnResultOpened event.

kbSearchControl.addOnResultOpened(myFunction);

addOnSelection

Use this method to add an event handler to the OnSelection event.

Parameter: Function. The function to add.

Example: Add the function named myFunction to the OnSelection event.

kbSearchControl.addOnSelection(myFunction);

getSearchQuery

Use this method to get the text used as the search criteria for the knowledge base management control.

Return Value: String. The text of the search query.

Example: Set the variable searchQuery to the text of the search query.

var searchQuery = kbSearchControl.getSearchQuery();

getSelectedResults

Use this method to get the currently selected result of the search control. The currently selected result also represents the result that is currently open.

Return Value: KBSearchResult. The currently selected result.

Example: Set the variable kbSearchResult to the currently selected result.

var kbSearchResult = kbSearchControl.getSelectedResults();

KBSearchResult properties

The following table describes the properties of the KBSearchResult object.

Property	Type	Description
answer	String	The HTML markup containing the content of the article. You could pass this content to a custom action that could include it in an email to send to the customer.
articleId	String	The article ID in Dynamics 365 or a Parature department This value is used as an alternate key. You can use it to see if this article already exists in Dynamics 365 or not.
articleUid	String	The unique article ID in Dynamics 365 or in the Parature system. When using Parature as knowledge source, this will contain Parature account ID and department ID as well, for example, “7924/8112/Article/25.” This value is used as an alternate key. This ID is needed to create a new KB record while associating an article if one doesn't exist already.
attachmentCount	Number	Number of attachments in the article. This is applicable only when using Parature as knowledge source.
createdOn	Date	The date the article was created. This value will be in the current user’s time zone and format. You may want to use the age of the article in your business logic.
expiredDate	Date	The date the article was or will be expired. This will be null when using Dynamics 365 as the knowledge source. You can compare this date to the current data to determine whether the article has expired or not. The value uses the current user’s time zone and format.
folderHref	String	The link to the folder path of the article in Parature. This is applicable only when using Parature as knowledge source.
href	String	The direct link to the article in Parature API, which can be used to get article content directly. This is applicable only when using Parature as knowledge source.
isAssociated	Boolean	Indicates whether the article is associated with the parent record or not. You can check this value before associating the article with the current record using form scripts or in another process initiated by form scripts.
lastModifiedOn	Date	Date on which the article was last modified. This value will be in the current user’s time zone and format.
publicUrl	String	Support Portal URL of the article. If the Portal URL option is turned off, this will be blank. Use a custom action to include this in a link in the content of an email to send to a customer.
published	Boolean	Indicates whether the article is in published state. True if published; otherwise False. You should check whether the article is published before you send information about it to a customer.
question	String	The title of the article. If you’re going to reference the article in any business process, you can refer to it by name using this value.
rating	Number	The rating of the article.
searchBlurb	String	A short snippet of article content that contains the areas where the search query was hit. Use this to give a glimpse of article to the users in the search list and help them determine if this is the article they are looking for.
serviceDeskUri	String	Link to the article in the Dynamics 365 or Parature service desk. Use this link to open the article using the Dynamics 365 or Parature service desk.
timesViewed	Number	The number of times an article is viewed on the portal by customers.

getTotalResultCount

Gets the count of results found in the search control.

Return Value: Integer. The count of the search result.

Example: Set the variable searchCount to the count of the search results in the search control.

var searchCount = kbSearchControl.getTotalResultCount();

openSearchResult

Opens a search result in the search control by specifying the result number.

var openResultStatus = kbSearchControl.openSearchResult(resultNumber, mode);

Arguments

• resultNumber (Integer): Numerical value specifying the result number to be opened. Result number starts from 1. Required.

• mode (String): Specify "Inline" or "Popout". Optional. If you do not specify a value for the argument, the default ("Inline") option is used.

  The "Inline" mode opens the result inline either in the reading pane of the control or in a reference panel tab in case of reference panel. The "Popout" mode opens the result in a pop-out window.

Return Value: Boolean. Status of opening the specified search result. Returns 1 if successful; 0 if unsuccessful. The method will return -1 if the specified resultNumber value is not present, or if the specified mode value is invalid.

removeOnPostSearch

Use this method to remove an event handler from the PostSearch event.

Parameter: Function. The function to remove.

Example: Remove the function named myFunction from the PostSearch event.

kbSearchControl.removeOnPostSearch(myFunction);

removeOnResultOpened

Use this method to remove an event handler from the OnResultOpened event.

Parameter: Function. The function to remove.

Example: Remove the function named myFunction from the OnResultOpened event.

kbSearchControl.removeOnResultOpened(myFunction);

removeOnSelection

Use this method to remove an event handler from the OnSelection event.

Parameter: Function. The function to remove.

Example: Remove the function named myFunction from the OnSelection event.

kbSearchControl.removeOnSelection(myFunction);

setSearchQuery

Use this method to set the text used as the search criteria for the knowledge base management control.

Parameter: String. The text for the search query.

Example: Set the text of the search query to “How to solve the problem”.

kbSearchControl.setSearchQuery("How to solve the problem");

See Also

Work with knowledge articles in Dynamics 365
Use Parature knowledge in Dynamics 365
Client-side programming reference
Write code for Microsoft Dynamics 365 forms
Extend Microsoft Dynamics 365 on the client

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright