Managing and customizing the Knowledge base widget

Plans supporting knowledge base widget

Customizing the knowledge base widget

You can customize each knowledge base widget to improve the user experience.

1. Log in to the Knowledge base portal and select your desired project.

2. Navigate to Knowledge base widget () in the left navigation bar. A list of widgets created will be displayed.

3. Hover over the desired widget and click the Edit () icon.

4. In the Configure & connect tab, expand the Style widget accordion.

5. The following widget customization options are available:

   • Widget color

   • Widget icon

   • Widget position

   • Hide widget

   • Hide most searched articles

Widget color

You can choose a theme color for the widget, which also sets the icon color.

1. Click Change color to open the color palette.

2. Select a color using the picker or enter a hex, RGB, or HSL code.

Widget icon

Similarly, under the widget color section, you can replace the icon with an image or an available icon.

1. Click Change icon.

2. Choose from the Icon set tab or insert an image under Insert image:

   1. From URL: Paste the image link and click Insert.

   2. From device: Click Upload an image and select a file.

3. Click Default to revert to the original icon.

Widget position

Control where the widget appears on your site:

• Choose Left or Right.

• Set Side spacing and Bottom spacing values to position the widget.

Hide widget

By default, the Hide widget toggle is turned off, so the Knowledge base widget remains visible on the site. To hide the widget, simply enable the Hide widget toggle.

Hide most searched articles

Turn on Hide most searched articles toggle to hide the top search articles section.

NOTE

Enabling the Hide most searched articles toggle will disable URL mapping functionality for the widget.

Once your changes are made, click Save next to the Widget name field.

NOTE

The autosave option is available for navigation between the Knowledge base widget tabs.

Content access for the Knowledge base widget

You may want to show only particular articles or hide some articles in your Knowledge base site. You can do this effectively with the Content access option.

Restricting content access in a Knowledge base widget

To restrict content access in a knowledge base widget:

1. Navigate to Knowledge base widget () in the left navigation bar.

2. Hover over a widget and click the Edit () icon.

3. In the Configuration & connect tab, expand the Content access section.

4. You have three options:

   1. Project

   2. Workspace

   3. Category

Project

All the articles in the Knowledge base appear in the Widget. By default, Project is selected.

Workspace

Display only specific workspaces or languages:

1. Select Workspace > Choose workspace

2. Select the desired workspace(s)/language(s) checkboxes

3. Click Done

4. Click Save to apply the changes

For example, you want to select a different workspace with a specific language.

Category

Display specific categories only:

1. Select Category > Choose category

2. Select categories from the current or other workspaces

3. Click Done

4. Click Save to apply the changes

You can make the desired categories appear in the Widget.

For example, you want to show only the Sales categories in the Widget.

CAUTION

Changes made to content access will directly impact your URL mapping.

If you modify the filter settings of the widget, the existing URL mapping may be removed and result in broken links.

Example 1:
You have set the filter widget content at the Project level and configured a URL mapping that includes a list of articles from Category A in Workspace V1. If you update the filter settings to show only Categories B and C in the same workspace, the previous URL mapping becomes invalid—because the originally mapped articles from Category A are no longer available in the widget.

You can only configure URL mappings using articles included in the current Filter widget content.

Example 2:
If the widget is filtered to display content only from Workspace V1, you cannot create a URL mapping for an article located in Workspace V2.

Adding custom links

You can add custom links to the Knowledge base widget. The links will appear in the order they were created. Use this option to direct end users to specific pages or resources.

To add a custom link:

1. Navigate to Knowledge base widget () in the left navigation bar.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, expand the Add links accordion

4. In the Section title field, enter the desired title for that section. This will appear in the widget.

5. Under the Section title, for each link, choose the desired icon, link text (which will appear in the widget), and the destination link.

   Example:

   • Icon:

   • Link text: Contact us

   • Link: support@document360.com

   NOTE

   You can use a mailto: in the link field. For example: mailto:<youremail@somedomain.com>

6. Click Add and the link will be added. Similarly, you can add multiple links.

7. To edit, click the Edit () icon. Click to save and to discard.

8. Click the Delete () icon next to the links to delete the links.

9. Once done, Click Save to save the changes.

Domain restriction

Document360 lets you restrict the Knowledge base widget to specific domains. Once a domain is added to the widget security list, any project member who wants to install the Knowledge base widget on a different domain must add that domain to the Widget security section.

If no domains are added to the list, the Knowledge base widget can be embedded into any SaaS application or public website without restriction.

Restrict the Knowledge base widget to a specific domain

To restrict your Knowledge base widget to a specific domain,

1. Navigate to Knowledge base widget () in the left navigation bar.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, expand the Widget security accordion. You can find the list of domains previously added (if added).

4. Enter the domain where you want the Knowledge base widget to be displayed.

5. Click Add and click Save.

NOTE

The "www" is not a valid part of your domain. Only add what comes after the www. in your URL.

Example: document360.com

Adding a ticket deflector in Knowledge base widget

You can integrate a Ticket Deflector to help deflect support queries. To add a ticket deflector to your Knowledge base widget, follow the steps below:

1. Navigate to Knowledge base widget () in the left navigation bar.

   The list of widget will be listed.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, expand the Ticket deflector accordion.

4. Turn on the Show ticket deflector toggle.

5. Select the desired ticket deflector from the dropdown.

6. If required, edit the Menu name field.

7. Click Save.

   The Ticket deflector is added to the Knowledge base widget.

Securing Knowledge base widget authentication using JWT

You can implement an authentication configuration for the widget using JWT, ensuring a secure environment for private and mixed projects.

1. Navigate to Knowledge base widget () in the left navigation bar.

   The list of widgets will appear.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, navigate to the JWT accordion and turn on the JWT Enable toggle.

1. Client ID: The client ID will be your project’s ID.

2. Widget ID: Since multiple widgets may exist, a Widget ID is provided for their unique purposes.

3. Token endpoint: A token endpoint is an HTTP endpoint that allows you to obtain an access token given an authorization code.

4. Client secret: Click Regenerate to generate the client secret. You need to save this for future purposes and the same client secret will apply to all widgets in the future.

NOTE

The Client secret will be required for JWT widgets you may create. Note that this information will not be stored in Document360.

e. Authorize URL: Paste the authorized URL from your knowledge base widget webpage.

5. Click Save.

Embed the authorized URL within your code and paste it into the script section on your webpage. This will implement a secure, authenticated widget that prevents unauthorized third-party access.

Implementing the auth endpoint

[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
    if (HttpContext.User.Identity.IsAuthenticated)
    {
        var clientData = new ClientDetails()
        {
            ClientId = "{Client ID}",
            Secret = "{Client secret}",
            TokenEndpoint = "{Token endpoint}",
            WidgetId = "{Widget ID}",
            SecurityGroupIds = "{Comma separated reader group IDs}", // mandatory for configuration to render KB widget
            TokenValidity = 15, // integer representing token validity in minutes
        };

        if (clientData == null)
            return NotFound();

        List<string> readerGroupids = null;
        if (!string.IsNullOrEmpty(clientData.SecurityGroupIds))
            readerGroupids = clientData.SecurityGroupIds.Split(',').Select(c => c.Trim()).ToList();

        var payload = new
        {
            username = "{Username}",
            firstName = "{First name}",
            lastName = "{Last name}",
            emailId = "{Email address}",
            readerGroupIds = readerGroupids,
            tokenValidity = clientData.TokenValidity,
            widgetId = clientData.WidgetId,
            projectId = clientData.ClientId
        };

        var payloadString = JsonConvert.SerializeObject(payload);

        var result = await client.RequestTokenAsync(new TokenRequest
        {
            Address = clientData.TokenEndpoint,
            ClientId = clientData.ClientId,
            ClientSecret = clientData.Secret,
            GrantType = "Widget",
            Parameters =
            {
                {
                    "payload",  payloadString
                },
                {
                    "id", clientData.ClientId
                },
            }
        });

        return Ok(new
        {
            accessToken = result.AccessToken,
            expiresIn = result.ExpiresIn
        });
    }
    else
    {
        return Unauthorized(new { success = false });
    }
}

NOTE

You must include the comma-separated reader group IDs as security group IDs to configure and render the KB widget.

Troubleshooting

This section provides step-by-step guidance to address common challenges that you may encounter while managing or accessing your knowledge base widget.

Widget icon is visible even after mapping to a button

Even after mapping the Knowledge base widget to a custom button, the default widget icon continues to appear on the Knowledge base site. This happens because the widget script includes the default icon display, and it doesn’t automatically get hidden when using a button trigger.

Steps to resolve:

1. Navigate to Knowledge base widget () in the left navigation bar.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, expand the Style widget accordion.

4. Locate the Hide widget toggle and ensure it is turned on.

5. Click Save to apply the changes.

   Refresh your Knowledge base site to see the changes.

Once done, the widget icon will no longer be visible on the site, but it will still function as expected when triggered via your custom button.

NOTE

If you're also using URL mappings to control widget visibility, refer to Customizing the Knowledge base widget using Custom CSS/JavaScript for advanced hiding options.

"Most searched articles" section not visible on the Knowledge base site

The Most searched articles section and the mapped list of articles for a specific URL are not appearing in the Knowledge base widget.

This issue typically occurs when the "Hide most searched articles" toggle is enabled in the widget style settings. Enabling this option hides both the Most searched articles section and any mapped article list associated with a specific URL.

Steps to resolve:

1. Navigate to Knowledge base widget () in the left navigation bar.

2. Hover over the desired widget and click the Edit () icon.

3. In the Configure & connect tab, expand the Style widget accordion.

4. Locate the Hide most searched articles toggle and ensure it is turned off.

5. Click Save to apply the changes.

   Refresh the Knowledge base site and verify that the Most searched articles and the mapped articles list are now visible.

NOTE

If the issue persists even after disabling the toggle, double-check the article-to-URL mappings and review other display settings within the widget configuration.