Skip to main content

With the Federated Search API, you can unify external content into your the search results displayed on your community. 

Federated search via API is a paid add on. Please contact your CSM to start using it.

How do federated search results appear in your community search?

Live search dropdown

The results from the federated search appear in a section below the community results. If you integrate content from different sources, they will each have a different section in the live search dropdown. 

You can use phrases to rename that section. 

 

Search result page

The results from the federated search appear in the list of results. A filter on the left allows to display only results from different sources of the federated search. Make sure you strip any HTML tags from the content before indexing it in our platform, as this won’t show up in the search results.

 

How do I set up a federated search integration through the API?

Note: You will need the help of a developer to use this API and integrate federated content. Alternatively, you can reach out to your CSM to discuss options of our Professional Services team helping you build this integration.


Access the API documentation:

Check out this KB article to learn how to access our API

You can decide to implement the integration in two different ways:

  • Either the federated content gets updated at defined frequency. For example once a day the content is synchronised. So if you delete one URL, it will still appear as a search result for a few hours. This first option is usually the simplest to implement.
  • Either the federated content gets updated in real time. So as soon as a URL is deleted for instance it will not show up anymore in the search results. This option is usually more complex to implement

Good to note is that you need a scraping tool in order to set up the data structure before using the APIs.

Here is an example flow we recommend to push a single source  of data into the community by API. You will want to create a workflow per source:

  • Obtain API credentials from both the community and the external platform. If you are federating multiple sources, we recommend setting up client credentials per source within the community. 
  • In the workflows engine of your choice follow these basic steps (Workato, Zapier, Google AppScripts, etc)
    • Create a trigger. Most customers use a time-based trigger to run the full workflow on a recurring basis during off hours. 
    • Clear all Federated search results for that particular source using a POST request and passing the source name originally provided. 
      • This is an optional step but helpful when you have data that was recently removed from the external source that you don't want indexed anymore. 
    • GET request to pull data from the external source API. Normally looping through pagination of some sort of "Get all" Endpoint. 
      • You'll need to decide if the response from this endpoint gives you the content necessary to provide enough keywords for the search. For example, if it only returns an ID, you'll want to make another request to pull more information.
    • Alternatively, you can scrape a public website if an API is not available.
    • Organize the data into a batch of objects with 4 parameters: Title, Content, URL and Source. 
      • The source name will always be the same per source.
      • The content is where you can store as much text as you think is necessary. This content is what is used for keywords when users are searching
    • POST the data in batches into the community

 

Frequently asked questions:

How do I add the source for a federated search integration, so we can differentiate these in our search results?
You need to add ‘source’ to the payload through the API (see example below). After that, it will show the source you entered there (i.e. externalAcademy) as a category in the search results. For “source” make sure there are no numbers and only alpha characters in there.

You can then use Phrases to change that name to a friendly name (i.e. Academy).

 

How much external content can I federate in my search results? 
You can federate up to 25,000 records (including all sources). One record equals to one search result.

Can I federate content from different languages?
Yes, you can add any content, no matter the language.

Will the federated content appear in the Embeddable widget?
No, the search in the Embeddable widget will not show any federated content. The Embeddable widget will only show Community content and Knowledge base content).

Will the federated content appear in the topic creation form in the "Related topics" section? 
No, the "Related topics" section will only show community topics.

This is a nice feature to have.

 

A few quick questions that came to my mind.

  1. Looking at the API docs we can push the title, content and URL of the content source. Is there a way to indicate the source too? (There could be multiple sources from ). Actually this question came to my mind after seeing the screenshot of the search which shows the “Blog” section which I believe is the name of the external source.

    Update: After reading the article carefully (which I did not do the first time :)) Understood that all federated content will appear together. How do we define the name of the that section? I see in the example show its named as ‘Blog’

     
  2. What is the intended value to be sent in ‘content’ of the API request. Is it kind of like the description of the content?

 

TIA

 

Hi!

Currently there is no way to specify the source so indeed all content will appear in one section.

How do we define the name of the that section? I see in the example show its named as ‘Blog

This can be done using phrases tool. We’ve got an article here that explains how to use it:

 

What is the intended value to be sent in ‘content’ of the API request. Is it kind of like the description of the content?

Yes, you can send a short description that will be used for searching in addition to the title. In our case (with blog articles) we populate content field with the contents of the article.

Hi!

Currently there is no way to specify the source so indeed all content will appear in one section.

 

 

Is this something that’s in the roadmap?
If not I would like to suggest this as an idea :)

A workaround I found for this was the qualify the title with the source name.


For example

Blog: XXXX
Docs: YYYY

 

How do we define the name of the that section? I see in the example show its named as ‘Blog

This can be done using phrases tool. We’ve got an article here that explains how to use it:

 

 

This did the trick.

 

What is the intended value to be sent in ‘content’ of the API request. Is it kind of like the description of the content?

Yes, you can send a short description that will be used for searching in addition to the title. In our case (with blog articles) we populate content field with the contents of the article.


 

Hello @mefarazath thanks a lot for your feedback. Would you be able to create an idea about it so we can gather more input and votes on your suggestion? thanks a lot :)

We’re using the Zendesk app federated search and the section is labelled “Zendesk” by default. But I’m not sure whether adding a standard Federated search API on top of that will appear under the same section or if that will create another section? Anybody know?

Hi @SmartlyGreg! If you add external content through the API then it will appear as a separate section, below the Zendesk section.

This is a nice feature to have.

 

A few quick questions that came to my mind.

  1. Looking at the API docs we can push the title, content and URL of the content source. Is there a way to indicate the source too? (There could be multiple sources from ). Actually this question came to my mind after seeing the screenshot of the search which shows the “Blog” section which I believe is the name of the external source.

    Update: After reading the article carefully (which I did not do the first time :)) Understood that all federated content will appear together. How do we define the name of the that section? I see in the example show its named as ‘Blog’

@mefarazath, we just released the ability to also separate the search results based on source. You can read the Product update below, and we’ve updated this knowledge base article to include this as well. Thanks for your feedback and your patience!

 

Reply


Terms & ConditionsCookie settings