Parature knowledge base search control (client-side reference)

Article
07/27/2016

Applies To: Dynamics CRM 2015

With Microsoft Dynamics CRM Online 2015 Update 1 or later, when an organization has Parature integration enabled they can add a new knowledge base search control to forms. This control provides for programmability support to automate or enhance the user’s experience when using this control.

Important

For Microsoft Dynamics CRM Online organizations, this feature is available only if your organization has updated to Dynamics CRM Online 2015 Update 1. This feature is not available for Dynamics CRM (on-premises).

These events and methods aren’t directly connected to any Parature API. However, if the 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 knowledge base management 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 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 cannot be changed.

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

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.

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.

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();

getSelectedResult

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.getSelectedResult();

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 a Parature department This value is used as an alternate key. You can use it to see if this article already exists in CRM or not.
articleUid	String	The unique article ID for the Parature system. 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.
createdOn	Date	The date the article was created. 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. 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.
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. 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 or draft state. 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 which 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 Parature service desk. Use this link to open the article using the Parature service desk.
timesViewed	Number	The number of times an article is viewed on the Parature portal by customers.

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");