Open the respective Knowledge Base search result using the openSearchResult API

Introduction:

Microsoft presents a range of client APIs that enable developers to interact flawlessly with Dynamics 365 CRM. One of its recent addition is the openSearchResult, which opens one of the knowledge base article listed as per the search in the search control.

Now whenever we search for any article in knowledge based search control, we get the list of available articles as a result. A user can click on any of the listed article to open it and read it. Now what if we want to automatically open the first article every time we search. This is where this new API openSearchResult plays its part.

The openSearchResult accepts two parameters.

• The first one is the resultNumber which is nothing but any numeric value starting from 1. This is the parameter where we can mention which article from the list of search results we want to open directly on every search. If we want to open the first record the value should be 1, for the second record the value should be 2 and so on.
• The second parameter defines how we want to view the opened article. Whether we want to view it as an “Inline” or “Popout”. If nothing is passed then by default it is “Inline”.

Also the openSearchResult API returns the following three values:

1. Returns 1 on successful Status of opening the specified search result.
2. Returns 0 on unsuccessful Status of opening the specified search result.
3. Return -1 if the specified resultNumber value is not present, or if the specified mode value is invalid.

Scenario:

Now let’s look into an approach by which every user will be able to pass the resultnumber dynamically as per their convenience and based on that value on every search the respective article shall auto open. Also we shall store the outcome of this search on the form i.e. if any article was found at the specified resultnumber or not.

To proceed with the demonstration we have used ‘Product’ entity/table. In the product form we have added a new tab called ‘Knowledge Base’ on the main form.

We will add two fields on the ‘Knowledge base’ tab.

• Record to be opened – This will be a whole number field on the form which would be used by the user to enter the result number to be opened.
• Record Present? – This will be a Boolean field which will act as a flag to notify the users that the specified record is present or not.

Now we will add knowledge base control to the same tab, for that we will have to enable ‘Knowledge Management’ on the selected entity, in our case it’s the ‘Product’ entity/table.

To understand how to add the knowledge base search to the form follow this link. We have added the Knowledge base search control to the ‘Knowledge Base’ tab.

Now we will write the JavaScript code to implement the OpenSearchResult API.

var new = window.Sdk || {}; new.KBSearchOnResultOpened = function (executionContext) { //Getting the formcontext var formContext = executionContext.getFormContext(); //Getting field control var productKBControl = formContext.getControl('Product_Knowledge_Base'); //Getting the user specified number var count = formContext.getAttribute('new_searchresultcount').getValue(); //Calling the openSearchResult client API var openResultStatus = productKBControl.openSearchResult(count); //Setting the recordPresent field to Yes/No openResultStatus == 1 ? formContext.getAttribute('new_countpresent').setValue(true) : formContext.getAttribute('new_countpresent').setValue(false); }; 

As you can see on the line number 3, using formcontext.getAttribute(‘Product_Knowledge_Base’) function, we get the control of knowledge base search.

We are getting the result number from the user on line number 5 which we are passing as the first parameter at line number 6. We shall not pass any value for the second parameter as the second parameter is mode which by default is ‘Inline’.

The above piece of code has been added as a webresource and the method Sdk.KBSearchOnResultOpened() has been called on change of ‘Record To Be opened’ field.

If user provided result number is present then openSearchResult API will open the record and based on the return value of client API  we will set the ‘Record present?’ field value as ‘Yes’, otherwise ‘No’ on line number 7.

Demonstation :

 Search for any Article / Record.

Enter the result number to be opened in custom field. On change of custom field, client API will open the result. As you can see in the below screenshot we have entered ‘2’ as a resultNumber and second record is opened in the reading pane. You can try other resultNumbers.

‘Record present?’ field is set to ‘Yes’ as the record number is present in the search results.

What if we enter a number which does not have any records in the search results ?

So for the same search let’s enter the number 11 as shown in the screenshot below.

And as expected no record will be opened and Record Present field will show ‘No’ value.

Conclusion:

As illustrated above, OpenSearchResult Client API will improve the user experience and make the existing feature more flexible to use.