What is the Federated Help Center search EAP?
PinnedUntil now, when you searched a Guide Help Center, the content that you could find to help you resolve your issue was limited to Guide Articles and Gather community posts.
However many Zendesk customers have great self service content on websites, blogs, other Knowledge bases, learning management systems, and on other community platforms. All of this content may in any given situation be the most relevant content to help an end user or agent resolve their issue.
Therefore we are proud to launch the Guide Federated Help Center search EAP which will let you surface all that great content hosted outside Guide and Gather in your Help Center search results.
The Federated search EAP gives you the ability to ingest content records to be indexed by the Guide search engine that is then used to generate external content search results. External and non-external search results are presented to the end user in a unified rank on the SERP. For external content records only the title and body is weighted.
When an end user clicks an external content search result they are taken to the URL of that external content record.
To allow you to do this we are providing a REST API to ingest the external content records and curlybars helpers to let you create the end user experience you want in your Help Center. You can also fetch this EAP branch of the Copenhagen theme so you can try it out without having to do theme customistions.
Getting started
- First sign up for the EAP here. We will notify you as soon as the EAP is enabled on your account.
- Ingest the external records you would like to be indexed and made searchable.
- Set up your Help Center theme for Federated search.
Ingest your external records
External content records have a number of properties that you will recognise from articles, post and topics if you are already familiar with the Help Center API.
Beyond those each content record is associated with a content source object and a content type object which are used to allow filtering by the end user just like articles and posts can be filtered by Help Center (if using multi Help Center search) and by type (Articles or Community).
You are able to customize External content sources to suit your needs, and each is given a unique source id. This allows you to group external records in a way that is equivalent to the way articles and posts are grouped by the Help Center they originate from in multi Help Center search use cases.
The types property is an extension of the two types of Guide and Gather content, articles and community posts. External content types can be completely custom and each is also given a unique id just like sources and records.
Initially you are not able to designate one of the two existing types, Articles and Community, to an external record for filtering, but we are adding that capability.
Set up your Help Center theme for Federated search
Once you have ingested external content records through the API that content can surface as search results in your default Help Center. Before we release this feature for general availability we will support multiple help center set ups by allowing you to set what external content you want to show up on which of your help centers.
Filtering on sources + Help Centers and types using the Copenhagen theme EAP branch,
Copenhagen theme EAP branch
The quickest way to get up and running is by importing the EAP branch of the Copenhagen theme using the GitHub integration for Guide themes. Alternatively you can also just download the theme from GitHub and import the ZIP it to Guide.
Customize your existing Guide theme
If you have a custom theme you will need to replace the old {{help_center_filters}} and {{filters}} helpers with the new {{source_filters}} and {{type_filters}} helpers to get filtering by source and type for external search results.
You also have to use the {{search}} helper to generate your search box and the {{results}} to render the external search results together with results from Guide Articles and Gather Posts. If you are not using a 3rd party search provider, but the Guide natice search, this part is already set up.
For more details and example on how to do this see How to add federated search results to your Help Center theme.
Known feature limitations
- External source and type names are not currently localizable.
- Ingested content is only surfaced in the default Help Center. We are adding multi brand support and a settings Interface for associating external content records to specific Help Centers.
- External content search results are only surfaced in Help Center search not in other Guide search powered interfaces.
- The EAP focusses on the use case for federated search for public 3rd party content, however external records do have a users_segment_id property that allows you to use user segments to restrict surfacing of external records in the same way that user segments are applied to articles and topics. If you want to try to use this EAP for surfacing non-public content only to users that has access to that content, you can do so if you can map user permissions in your 3rd party system to user segments in Guide, however we do not in the EAP offer specific guidance or support for this use case.
- External content search results are only shown on your account's default help center. Before we release this feature for general availability we will support multiple help center set ups by allowing you to set what external content you want to show up on which of your help centers.
- It is not possible to designate one of the two existing types, Articles and Community, to an external record for filtering, but we are adding that capability.
Product limits
Normal Zendesk API rate limits applies to the External content API if no tougher rate limit is documented below. Character limits are documented in the developer documentation:
- Federated Search - External Content Type API
- Federated Search - External Content Record API
- Federated Search - External Content Source API
There is no rate limit on Help Center searches.
|
Limit |
Max |
|
|
External record creation |
700/min |
|
|
External record size |
10000bytes/record |
|
|
External sources |
3 |
|
|
External types |
5 |
|
|
External record |
3000 |
|
|
Who can join the EAP?All Guide enterprise customers can join. Just sign up for the EAP here! |
-
Thank you - that is an important and forward-looking feature!
A question about Answer Bot.
Will Answer Bot also be able to find this external contents or are they limited on the search functionality in guide?
-
Hi Michael, thanks for the feedback!
As of right now federated search results can only be consumed through Help Center search, but this is only the first step and we will make federated search results available through more interfaces. I can't give a timeline at this point, but Answer Bot availability is one of the top priorities.
-
Thank you Gorka!
We have discussed some plans for our next steps yesterday.
Will this EAP also works with the Knowledge Capture App within the zendesk ticket or would that be a separated EAP?
-
Unfortunately KCapp support will not be covered this EAP, it will be a seperate one.
-
I am starting to enable this feature for our help center, but am having issues generating 'Types'. I receive the following response: {"error":"InvalidEndpoint","description":"Not found"}%
My 'Source' creation worked so, I do think everything for the EAP is set up properly. Any assistance is appreciated.
-
Hi Nicole Haberman,
Would you mind posting the full URL (or just the path, without the subdomain) that you're trying to hit with that request returning InvalidEndpoint when trying to create Types?
Thanks
-
Sure thing!
curl "https://******.zendesk.com/api/v2/external_content/types" -d '{"type": { "name": "Guides" }}' -u *******/token:*************
{"error":"InvalidEndpoint","description":"Not found"}% -
You're missing the `guide` part of the URL.
You have:
***/api/v2/external_content/types
It should be:
***/api/v2/guide/external_content/types
See more info on our documentation: -
Ah! That would do it - thanks!
The curl example in the docs doesn't have that:
-
I'm sorry about that. I'll go ahead and fix the documentation 🙏
Let us know if you encounter any other issue or if you have any other questions.
-
How will this impact the ability to search for tickets AND knowledge AND community posts while in one spot? Will users be able to see any of these items, or will they have to do separate searches in Help Center or Guide and Gather to find what they are looking for? Ideally customers can find whatever they want to with one search.
-
Hey Kim,
Federated Search allows you to add content from external sources like API documentation platforms, e-commerce sites etc. into your existing Help Center search. Help Center search already enables searching across both the knowledge base and the community, Federated Search allows you to add more content sources into the mix.
Thanks!
-
I didn't see anything about tickets. Ideally, if someone asks a question, it would be great if it showed articles, community discussions or tickets - anything that matches what they are searching for. Maybe they had a past case about it. Can it be used for that? Or do you still have to do a separate search of your tickets?
-
Ticket search continues to live under My Activities tab for the time being unfortunately and is outside the scope of this particular early access program.
-
Hi Adrian Bordinc / Zendesk Team,
My team is looking to implement the federated search into a CI/CD process and had a question of clarity in regard to the API docs. Is a record update a destructive update? The docs say this:Updates a record
PUT /api/v2/guide/external_content/records/{id}
Given an id, delete the corresponding record
Thanks! -
Hi Nicole Haberman,
I'm sorry for this; it seems like a copy-paste error in our documentation. That description is from the section below: Delete a record
The Update is not a destructive action, but instead, it does what you'd expect it to do.
The description for the Update a record endpoint should be:
Updates the record identified by the given ID with the request body.
I'll go ahead and fix it. I apologize for the trouble, and thanks for letting us know.
Feel free to ask if anything else shows up.
/Adrian
-
Hi there (again :) ),
We are having difficulty getting back all of our records from List external records endpoint once they start paging. The documentation says that we should be able to use "page" in the query, but I can't seem to figure out what that should look like. Can you provide a few working examples of paging complete with full curl or at least a sample URL?
Here's what I've tried so far:curl https://hiddengarden.zendesk.com/api/v2/guide/external_content/records?page=2 -u removed
curl https://hiddengarden.zendesk.com/api/v2/guide/external_content/records/2 -u removed
curl https://hiddengarden.zendesk.com/api/v2/guide/external_content/records?page=2 \ -d '{"page": {"before": 1}'https://developer.zendesk.com/rest_api/docs/help_center/federated_search___external_content_record_api#lists-external-records
I totally understand this is an EAP so things aren't perfect, and really appreciate the assistance with the documentation.
Thanks,
Nicole -
Looks like our documentation still needs a few things ironed out :-)
Here's some working examples based on your link above:
curl https://your_subdomain.zendesk.com/api/v2/guide/external_content/records?page[size]=1☝️ the above will paginate the results, 1 per page, you can configure this setting using the page[size] parameter (I believe we have a maximum allowed page size of 10 for now)
In order to get the following results, you need to set the page[after] parameter.
curl https://you_subdomain.zendesk.com/api/v2/guide/external_content/records?page[after]=CURSOR_HERE
The CURSOR_HERE variable, is taken from the previous response.https://developer.zendesk.com/rest_api/docs/help_center/federated_search___external_content_record_api#example-response
In the example above, the cursor is MQ, so the link should be:
curl https://your_subdomain.zendesk.com/api/v2/guide/external_content/records?page[after]=MQ
Thanks for pointing this to us. Really appreciate it. I'll add a task for us to clarify the documentation around pagination,Reach out if anything else shows up
/Adrian
-
Hi, how is the EAP going? When will this be a standard feature of Zendesk? And who will it be available for? Thanks
-
i know it's not part of this EAP, but i'm curious if there are plans to be able to initiate the federated search from an external, non-help-center site, which would then be able to search the resources on that site + guide, and redirect as necessary.
now that i'm typing this out, i'm thinking similar to the web widget... but also searches the site it's implemented on.
let me know if i've confused everyone.
thanks!
-
I too would like what Rachel M asks for! A two way relationship with search so it doesn't mater where customers are they receive all would be much desired. So would be great to hear your response :)
-
Hey there, any update on a rough estimate for integrating this with Answer Bot? It's pretty much all we need!!
Please sign in to leave a comment.
22 Comments