URL mapping in Knowledge base Widget

Plans supporting Knowledge base widget

Professional	Business	Enterprise

The URL Mapping feature within the knowledge base widget allows you to tailor the display of specific articles and categories based on the pages your end users visit. This functionality not only enhances user experience by directing users to relevant content but also enables you to hide the knowledge base widget on certain URLs or provide a search bar with custom placeholders, guiding users on what to search.

Using URL mapping

To configure URL mapping, you perform specific actions within the knowledgebase widget for designated URLs.

Actions

There are four actions you can execute with URL mapping:

Show article: Displays a single article on the specified URL.
Show list of articles: Lists selected articles under the Recommended section within the Knowledge Base widget on the specified URL.
Show search results: Allows you to set a specific search term to query your knowledge base, returning relevant search results on the specified URL.
Hide widget: Prevents the Knowledge Base widget icon from appearing on the specified URL.

You can find these actions under the URL Mapping tab or when editing an existing mapping.

NOTE
For URL Mapping to work, the Knowledge base widget must be installed within your site or app. For more information, read the article on Installing the Knowledge base widget.

URL Parameters

When configuring the Knowledge Base widget URL, you can include three types of parameters:

Include Path: /thisis/a/path
Include Query: ?animal=bear
Include Hash: #inbox

You can also enable the Is Regex toggle to incorporate regular expressions into your URL configurations.

Adding URL Mapping to your Widget

To integrate the desired widget into your knowledge base site, follow these steps:

Navigate to URL Mapping tab in the Widget () in the Knowledge base portal.
Click New URL mapping and specify the following:
- Name - The URL Mapping name will only be shown on the URL mapping record within Document360
- URL structure - Select the desired URL parameter type (Include path/Include query/Include hash). You must enable at least one URL parameter
- Type in the URL on which you want the article/category to show or action to occur.
  NOTE
  Your domain name is not included in the URL path. For instance, https://document360.com/ebook/rapid-guide-to-launch-your-knowledge-base/, your URL Path would be /ebook/rapid-guide-to-launch-your-knowledge-base/
- Action - Select the desired action.
- Select workspace - Select the desired version (if you have multiple versions).
- Language to - Select the desired language (if you have multiple languages).
- Article to show - In the search bar, select the articles/categories you want to show from your knowledge base documentation.
NOTE
Folder categories are not available for selection. Only page and index category types are available for selection.
Click Create.

Once an end user accesses your specified URL path and opens the Knowledge Base widget, they will see the mapped article/category. This information remains consistent as they navigate between the Knowledge Base widget tabs within the same version and language.

Editing URL mapping

To modify an existing URL mapping:

Navigate to Widget () in the Knowledge base portal.
Hover on the desired Knowledge base widget and click the Edit () icon.
In the URL mapping tab, you can find the list of available URL mapping.
Hover over the desired URL mapping and click the Edit () icon.
The Update URL mapping panel will appear.
Update the desired information and click Update.

Deleting URL mapping

You can delete a set URL mapping.

Navigate to Widget () in the Knowledge base portal.
Hover on the desired Knowledge base widget and click the Edit () icon.
In the URL mapping tab, you can find the list of available URL mapping.
Hover over the desired URL mapping and click the Delete () icon.
Click Yes in the Delete confirmation prompt.

URL mapping settings

You can define the Knowledge base widget behavior for URLs that do not have configured mapping. Defining this behavior can improve the user experience and accessibility to the documentation.

Navigate to Widget () in the Knowledge base portal > Configure & connect.
Under Set controls section, expand the URL mapping settings section.
Select the desired option:
- Navigate to the page help/knowledge base: Select this option to display the article/category in Page help or Knowledge base tab in the Widget.
- Do not make any changes to the existing setup: Select this option to display the last opened article/category in the Widget.
Click Save.

Basic URL matching

Understanding URL matching is crucial for effective URL mapping. A general-purpose regex for matching typical URLs looks like this:

^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$

Explanation of the components

^https?://?: Matches the protocol (e.g., http:// or https://). The ? makes the protocol optional.
NOTE
Ensure to add a backward slash (\) before every forward slash (/) while testing your URL on https://regex101.com.
[a-zA-Z0-9.-]+: Matches the domain name, including letters, numbers, dots (.), and hyphens (-).
/[a-zA-Z0-9/._-]*?: Matches the path after the domain, allowing slashes, alphanumeric characters, dots, underscores, and hyphens.
?[a-zA-Z0-9=&._-]*?: Matches optional query parameters (e.g., ?key=value), making this part optional.
#[a-zA-Z0-9_-]*?: Matches the fragment (e.g., #section), which is also optional.

Examples of URL mapping using Regex

Mapping URLs with specific paths

To map a URL pattern like /users/{id}, use:

^/users/[0-9]+$

This captures a user ID dynamically.

Example Matches

/users/123
/users/456

Mapping URLs with query parameters

For URLs like /search?q={query}, the regex would be:

^/search?q=[a-zA-Z0-9]+$

Example Matches

/search?q=apple
/search?q=123abc

Mapping URLs with optional parameters

For a URL pattern like /products/{category}/{id}, where category is optional:

^/products/[a-zA-Z]+?/[0-9]+$

Example Matches

/products/123
/products/electronics/123

Mapping URLs with wildcard or multiple paths

For /blog/*:

^/blog/.*?$

Example Matches

/blog
/blog/how-to-code
/blog/2021/10

Mapping URLs with subdomains
For subdomain URLs:

^https?://?[a-zA-Z0-9-]+.example.com$

Example Matches

http://blog.example.com
https://shop.example.com

Combining multiple components

To handle more complex URL mappings, you can combine the various components as needed. The comprehensive regex that matches a URL with an optional protocol, domain, path, query parameters, and fragment looks like this:

^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$

FAQs

How can I remove the Page help and Search bar from the widget when URL mapping for a single article is configured?

To remove the Page help and Search bar from the widget when URL mapping for a single article is configured:

Navigate to Widget () in the Knowledge base portal.
Hover over the desired widget and click the Edit () icon.

Paste the provided code in the Custom CSS tab:

li#page-help-tab {
    display: none;
}

.article-header .article-back-icon {
    display: none;
}

.search-container {
    display: none !Important;
}

Paste the provided code in the Custom JavaScript tab:

setTimeout(function() { $('.search-container').hide();}, 2000);
setTimeout(function() { $("#knowledge-base-tab").click();}, 2000);

Click Save.

This will hide the Page help tab and Search bar in the widget on the Knowledge base site when URL mapping for a single article is configured.

How can I see the updates immediately in the KB Widget after adding or updating a URL Map?

The updates are cached on the server for performance reasons and will automatically refresh every 15 minutes. However, if you need to see the changes immediately, you can clear the application cache.