Troubleshooting Integrations and Extensions issues

GitHub connector stuck in a connection loop

If selecting Connect repeatedly redirects you to GitHub without completing the connection, your GitHub account is already linked to another Document360 connection. You can resolve this by uninstalling the Document360 app from your GitHub account and reconnecting.

Before you begin

• Have access to the GitHub account you're using to connect to Document360.
• This applies regardless of which Document360 project you're connecting from, since the conflict exists at the GitHub account level.

Fix the GitHub connection loop

1. Sign in to GitHub and navigate to Settings > Applications > Installed GitHub Apps.
2. Find Document360 in the list of installed apps.
3. Select Uninstall.
4. Return to Document360 and select Connect to start the connection again.

Document360 completes the GitHub authorization and the connection finishes without looping.

Verify the fix

1. After reconnecting, confirm you're redirected back to Document360 instead of GitHub.
2. Check that the GitHub integration shows as connected in your Document360 project settings.

FAQ

Why does this loop happen instead of showing an error?
GitHub doesn't return an explicit error when an account already has an active app connection. Instead, it repeats the authorization redirect, which appears as a loop.

Do I need to uninstall the app from every GitHub organization I belong to?
Only from the account or organization that holds the existing Document360 connection. If you're unsure which one that is, check each organization's installed GitHub Apps list.

I uninstalled the app but the loop still happens. What should I try next?
Clear your browser cache and cookies for GitHub, then attempt the connection again in a private browsing session.

Material Icons displaying incorrectly or appearing on every page

Material icons appear as a string across the top of every knowledge base page, or don't display correctly within article content. This happens when Material Icon HTML elements are added directly to the Knowledge Base Portal integration code instead of the stylesheet reference alone. You can resolve this by keeping only the stylesheet link in the integration settings and adding icon elements within individual articles instead.

Before you begin

• Confirm you have access to Settings > Knowledge Base Portal > Integrations.
• This applies to any knowledge base using Material Icons through the integration code.

Fix icons appearing across every page

1. Navigate to Settings > Knowledge Base Portal > Integrations.

2. Review the code in the integration section.

3. Confirm that only the stylesheet reference is present:

   <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
   

4. Remove any <span class="material-icons">...</span> elements from the integration code.

5. Select Save, then refresh your knowledge base.

The icon string no longer appears across the top of your knowledge base pages.

Fix icons not displaying correctly in articles

1. Confirm the Material Icons stylesheet reference is present in the integration, as described above.

2. Within the article content, add the icon markup directly, for example:

   <span class="material-icons">edit</span>
   

3. Save and preview the article.

The icon renders inline with the article content.

Verify the fix

1. Refresh your knowledge base and confirm no icon string appears at the top of any page.
2. Open an article containing icon markup and confirm the icons render correctly inline.

Why this happens

The integration section is meant for global resources like stylesheets, which apply across the entire knowledge base without rendering visible content. Icon elements such as <span class="material-icons">edit</span> are actual page content, not styling, so when placed in the integration section, Document360 renders them as content on every page rather than restricting them to a single article.

FAQ

Can I use Material Icons without adding anything to the integration settings?
No. The stylesheet reference in the integration section is required for the icon font to load. Without it, icon markup in articles won't render correctly even if added.

Does this affect all articles or only specific ones?
The page-wide icon string affects every page in the knowledge base, since the integration code applies globally. Icons added correctly within individual articles only affect that article.

I removed the icon elements from the integration but the page-wide string is still there. What should I try next?
Clear your browser cache and refresh the knowledge base. If the issue persists, confirm the changes were saved by reopening Settings > Knowledge Base Portal > Integrations and reviewing the code again.

Keeping the AI Chatbot widget open by default

The AI Chatbot widget requires users to select the widget icon before it opens, and there's no built-in setting to change this. You can achieve the same outcome by adding custom JavaScript to the website where the widget is embedded, so the widget opens automatically when the page loads.

Fix the widget so it opens by default

1. Work with your development team to add custom JavaScript to the website hosting the widget.
2. Configure the script to trigger the widget's open action when the page finishes loading.
3. Deploy the change to your website.

The widget opens automatically for users when they visit the page, without requiring them to select the widget icon.

Verify the fix

1. Open the website in a new browser session, ideally in a private/incognito window.
2. Confirm the widget opens automatically without any manual interaction.

FAQ

Does this require changes within Document360, or only on my website?
Only on your website. The widget embed code itself doesn't need to change — the JavaScript trigger is added separately on the page hosting the widget.

Can I control which pages the widget opens automatically on?
Yes. Since the trigger is custom JavaScript on your website, your development team can scope it to specific pages rather than applying it site-wide.

Providing reader-level permissions in the AI Chatbot widget

The AI Chatbot widget doesn't support reader-specific permissions by default — content access is limited to project, workspace, language, or category-level controls. You can provide reader-level permissions by implementing JWT (JSON Web Token) authentication, which lets the widget identify each reader and display content based on their reader group.

Before you begin

• Reader-level access requires JWT authentication to be implemented for the widget.
• Without JWT, content access can only be configured at the project, workspace, language, or category level, not per reader.

Fix reader-level access in the widget

1. Implement JWT authentication for the AI Chatbot widget.
2. Set up the reader groups that correspond to the access levels you need.
3. Assign each reader to the appropriate reader group.

The widget identifies the authenticated reader through JWT and displays content based on the permissions associated with their reader group.

Verify the fix

1. Sign in to the website as a test reader assigned to a specific reader group.
2. Confirm the widget displays only the content assigned to that reader group, and not content outside of it.

FAQ

Can I restrict widget content to individual readers without setting up JWT?
No. Without JWT authentication, content access in the widget can only be configured at the project, workspace, language, or category level, not per individual reader.

What access controls are available if I don't want to implement JWT?
Project, workspace, language, and category-level content segregation. These limit what's available in the widget overall, but don't vary by individual reader.

Do I need a separate JWT setup for the widget if I already use JWT for my Knowledge Base Site?
Yes. JWT authentication for the widget and for the Knowledge Base Site are configured independently of each other.

Making multiple languages available in the widget when JWT is enabled

When JWT authentication is enabled for the AI Chatbot widget, readers may see fewer languages than expected, even if the workspace contains content in multiple languages. This happens because the widget only displays languages that overlap between the reader's assigned reader group permissions and the widget's content access settings. You can resolve this by adding all the required languages to the reader group's permissions.

Before you begin

• JWT authentication must already be enabled for the widget.
• This applies when the workspace contains content in more than one language and readers need access to more than one of them.

Fix language access for readers in the widget

1. Identify which languages each reader group should have access to.
2. Open the reader group's permission settings.
3. Add all the required languages to the reader group's permissions.
4. Check the widget's content access settings to confirm they aren't restricted to a narrower set of content than the reader group allows.
5. Save the reader group configuration.

On the reader's next login, the widget displays content in all the languages included in their reader group's permissions.

Verify the fix

1. Sign in as a reader belonging to the updated reader group.
2. Confirm the language selection in the widget includes all the languages you added.

Why this happens

During login, Document360 validates the reader's permissions against the widget's content access settings and applies only the overlap between the two. If a reader group has language-level permissions that are narrower than the widget's configuration, such as project-level access, the reader group's narrower permissions determine what the reader actually sees, even though the widget itself is configured more broadly.

FAQ

If the widget is configured for project-level access, does that automatically give readers access to all languages in the project?
No. If the reader's group has language-specific permissions, those permissions take precedence over the widget's broader project-level configuration.

Do I need to update every reader group individually?
Yes. Language access is configured per reader group, so each group that should see multiple languages needs its own permissions updated.

I added the languages to the reader group, but the reader still doesn't see them. What should I try next?
Confirm the reader is assigned to the updated reader group and ask them to sign out and sign back in, since permission changes apply on the reader's next login.

Open Article / Open Site redirects to an access-denied or login page

Users can view articles inside the embedded Knowledge Base Widget, but selecting Open Article or Open Site redirects them to an access-denied page or a login page instead of the article. This happens because the widget and the Knowledge Base Site use separate access control mechanisms, so a user can have access through one without having access through the other. You can resolve this by either restricting users to the widget experience or granting them direct access to the Knowledge Base Site.

Before you begin

• Confirm whether the affected users have been added as Readers and assigned to Reader Groups.
• Confirm whether users are expected to access content only through the embedded widget, or through the Knowledge Base Site as well.
• Test the behavior in an incognito or private browsing session to validate the end-user experience before and after applying a fix.

Fix the access-denied redirect

Choose the method that matches how your users should access content. Both produce a consistent experience; they don't need to be combined.

Restrict users to the widget experience

Use this method if users should access documentation only through the embedded widget, and don't need direct access to the Knowledge Base Site.

1. Keep content access configured through the widget's existing permissions (project, workspace, or category-level).
2. Add custom CSS in the widget to hide the Open Article / Open Site option.
3. Save the widget configuration.

Users no longer see the option to navigate to the Knowledge Base Site, so they can't encounter the access-denied or login page.

Grant users access to the Knowledge Base Site

Use this method if users need to open articles directly on the Knowledge Base Site, in addition to using the widget.

1. Add the affected users as Readers.
2. Assign the users to Reader Groups with the content permissions they need.
3. Confirm that the site-level permissions align with the content these users are expected to access.

Users can now select Open Article or Open Site and reach the article instead of an access-denied or login page.

Verify the fix

1. Test the change in an incognito or private browsing session, signed in as one of the affected users.
2. If you used Method 1, confirm the Open Article / Open Site option no longer appears in the widget.
3. If you used Method 2, confirm the user can select Open Article or Open Site and lands on the article instead of an access-denied or login page.

Why this happens

Widget access is controlled through the widget's own content access settings, such as project, workspace, or category-level permissions. Site access is controlled separately, through authentication methods such as JWT, SSO, and Reader Group permissions. JWT authentication for the widget and JWT authentication for the site are configured independently, so enabling or disabling it for one doesn't affect the other. As a result, a user can satisfy the widget's access requirements without meeting the separate requirements for the Knowledge Base Site.

FAQ

Why can users view content in the widget but not on the site?
The widget and the site use separate access control mechanisms. Widget access depends on content access settings like project, workspace, or category permissions, while site access depends on authentication methods like JWT, SSO, or Reader Group permissions.

Does enabling JWT for the widget also enable it for the site?
No. JWT authentication for the widget and for the site are configured independently, so you can use different access control methods for each.

I assigned the user to a Reader Group but they still see an access-denied page. What should I try next?
Confirm the Reader Group's permissions actually include the content the user is trying to open, and check the result in a private browsing session in case cached credentials are affecting the test.

Why does the Document360 Salesforce extension keep loading indefinitely in the Salesforce Cases page after configuring Salesforce extension?

The Document360 Salesforce extension keeps loading indefinitely on the Salesforce Cases page after you've configured the extension. This happens because the Connected App's OAuth policies and profile access in Salesforce haven't been set up to allow the required users to authenticate. You can resolve this by updating the Connected App's OAuth policies, granting profile access, and reconnecting the sandbox in Document360.

Before you begin

• Have Salesforce admin access to Setup in the Salesforce Sandbox.
• Have Document360 admin access to the project's Connections settings.
• This applies when the extension is configured but the iframe on the Salesforce Cases page never finishes loading.

Fix the Salesforce extension loading indefinitely

Configure Connected App policies

1. In Salesforce, navigate to Setup > App Manager.
2. Locate Document360 in the list of connected apps.
3. Select the row dropdown, then select Manage.
4. Select Edit Policies.
5. Set Permitted Users to Admin approved users are pre-authorized.
6. Set IP Relaxation to Relax IP restrictions (recommended).
7. Select Save.

Grant profile access

1. Return to the Manage page for the Document360 connected app.
2. Scroll to the Profiles section.
3. Select Manage Profiles.
4. Enable access for all required profiles, such as System Administrator, Standard User, Support Agent profiles, and any custom support profiles your team uses.
5. Select Save.

Refresh the user session

Ask affected users to:

1. Close all open Salesforce tabs.
2. Perform a hard refresh: Ctrl+Shift+R on Windows, or Cmd+Shift+R on Mac.
3. Reopen the Salesforce Case page.

Reconnect the sandbox in Document360

1. Open the Document360 portal for the required project.
2. Navigate to Connections > Extensions > Salesforce.
3. Select Sandbox.
4. Select Connect with Salesforce.
5. Authorize using the Salesforce sandbox credentials.

Document360 populates and saves the sandbox instance URL for the project.

Verify the fix

1. Refresh the Salesforce Case page.
2. Confirm the Document360 iframe loads correctly instead of loading indefinitely.

Why this happens

The Connected App's OAuth policies control which users are pre-authorized to use the extension, and the Profiles section controls which Salesforce profiles can access it. If these aren't configured, Salesforce blocks the authentication request needed to load the extension, which appears as the iframe loading indefinitely rather than as an explicit error.

FAQ

Does this affect all users or only some?
It typically affects any user whose profile hasn't been granted access in the Connected App's Profiles section, even if other users in the same org can load the extension successfully.

Do I need to repeat this configuration for production as well as sandbox?
Yes. Connected App policies and the Document360 connection are configured separately for each Salesforce environment, so production needs its own setup.

I completed all the steps but the extension still loads indefinitely. What should I try next?
Capture a HAR file after the policy changes, a screenshot of the Connected App Manage page showing the Permitted Users setting and Profiles section, and the browser developer tools console output from the failing Salesforce Case page. Share these with support@document360.com.

Troubleshooting: iframe stuck loading or authentication errors after setup

If the Document360 iframe keeps loading indefinitely inside your Salesforce Cases page after setup, or you see a Canvas authentication error, check the following:

1. OAuth approval not granted

If Salesforce returns a "user_approval_required" state (visible in browser network logs as _sfdc_canvas_auth=user_approval_required), the required user authorization has not been granted for the installed Document360 Connected App.

To resolve this:

1. go to Salesforce Setup, then App Manager, locate Document360, select Manage, then Edit Policies.
2. Set Permitted Users to "Admin approved users are pre-authorized," and set IP Relaxation to "Relax IP restrictions."
3. Save your changes.
4. Allow 5 to 10 minutes for Salesforce to propagate the change, then have affected users close all Salesforce tabs, hard-refresh, and reopen the Case page.

2. 500 error after OAuth is corrected

If the iframe still fails to load with a 500 error after confirming the OAuth policy changes above, the issue may be that your Document360 project is missing its saved Salesforce instance URL.

To resolve this:

1. go to your Document360 portal, navigate to Connections, then Extensions, then Salesforce, select Sandbox or Live depending on your environment
2. click Connect with Salesforce, authorizing again with your Salesforce credentials for that environment.This populates and saves the correct instance URL for your project.
3. Refresh the Salesforce Case page and verify the iframe loads successfully.