Managing and customizing the Knowledge base widget

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

Editing a widget

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

2. Navigate to Knowledge base widget () in the left navigation bar. You will see a list of existing widgets.

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

Styling the Widget

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

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 the 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 the 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 the Hide most searched articles toggle to hide the top search articles.

NOTE

Enabling the Hide most searched articles toggle will disable URL mapping 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 can configure content access in your knowledge base widget even when JWT is enabled for the widget. This gives you more flexibility in controlling what your end users can see.

To configure content access with JWT enabled:

1. Navigate to the 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 Content access section.

4. The filter levels available are:

   • Project

   • Workspace

   • Category

5. Choose the desired workspaces, languages, and categories to display in the widget.

6. Click Done, then click Save to apply the changes.

Validating reader group content permissions

• When a reader logs in, the system will validate whether their reader group permissions match the widget’s content access filters. Only the intersecting permissions between the widget-level settings and the reader group settings will be considered for validation.

• This ensures that users see only the articles they are authorized for, in both widget-level and reader group permissions.

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, leading to 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. Repeat the steps to add additional 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 them.

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 the 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 to apply changes.

   

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 the 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 the 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, 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 to apply changes.

   The widget now includes the selected Ticket Deflector.

   

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 the 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 to apply changes.

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

Use this C# snippet to implement JWT authentication for the Knowledge base widget.

[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

• The tokenValidity value is set in seconds. It must be between 300 seconds (5 minutes) and 86,400 seconds (24 hours). If you enter a value outside this range, it will automatically be adjusted to the nearest allowed limit. For example, if you set tokenValidity to 100 seconds, the system will automatically increase it to the minimum allowed value of 300 seconds.

• You must include the comma-separated reader group IDs as security group IDs to configure and render the Knowledge base 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 the 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 is 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.

<div style="font-family:Arial, sans-serif;font-size:14px;color:#333333;line-height:1.6;">
  <p>
    The <strong>test line</strong>
  </p>
</div>