Summary

After connecting Jira Service Management (JSM) to Confluence and setting up a knowledge based in a project in Project Settings > Knowledge base and when everything goes well, customers should be able to search for Confluence articles from the Customer Portal in various locations:

• either from the Help Center Home page
  
• or from the portal corresponding to the project(s) which are linked to a knowledge base space
  
• or from the request creation form, if the form belongs to a project which is linked to a knowledge base space
  

However, in some cases, the search might fail in all these 3 places and not return any result:

If the search is not working at all in any of these 3 places, and impacts all the Jira users, then this knowledge base article might be relevant as it provides possible root causes for this situation.

However, if the issue impacts specific Jira users only, then this other KB article might be more relevant: The knowledge base search does not return any result from the Customer Portal for specific users only

Environment

• Jira Service Management (JSM) Server/Data Center (any version) with Confluence Server/Data Center (any version)
• OR Jira Service Management (JSM) Server/Data Center (any version from 4.12.0) with Confluence Cloud

Cause

Case where Confluence Server (or Data Center) is used as a Knowledge Base

Root Cause 1 - The Confluence application is either down or un-reachable from Jira

For the knowledge base search to work from the Customer Portal, it is necessary that the Jira Service Management can access the Confluence application so that it can search for relevant articles there.

If the Confluence application is not running or is not reachable from Jira (due to network/proxy/firewall issues), then the search will not work from the Customer Portal: no result will show in the search from any location (help center, portal, request creation form) and for any user.

Root Cause 2 - The application link is not configured with "impersonation" for both incoming and outgoing

For the knowledge base search to work from the Customer Portal, it is necessary that the application link configured between Jira and Confluence used "OAuth (impersonation)" for both incoming and outgoing requests, and on both Jira and Confluence side. If these conditions are not met, then the Knowledge Base search will not show any result, unless Confluence is configured with anonymous access on both the application and the space levels.

Root Cause 3 - The Confluence Knowledge Base Blueprints Plugin is disabled

The Confluence application comes with a bundle plugin called Confluence Knowledge Base Blueprints Plugin to handle any knowledge base search coming from the linked Jira Service Management application. If this plugin is disabled, the knowledge base search will not return any result from the Customer Portal: no result will show in the search from any location (help center, portal, request creation form) and for any user.

Root Cause 4 - The Confluence indexes are corrupted

When JSM searches for KB articles, it forwards the search request to the Confluence application, and then returns the results from Confluence to the Customer Portal. If the Confluence indexes are broken/corrupted, then no result will be returned to the Customer Portal.

Root Cause 5 - Confluence is running on an old version (5.5.1 or lower) and is impacted by a bug

Confluence is running on version 5.5.1 or earlier and is impacted by the bug CONF-35495 - Getting issue details... STATUS .

Case where Confluence Cloud is used as a Knowledge Base

Root Cause 6 - The knowledge base is incorrectly configured on the Jira application side

Depending on which platform Confluence is running (Server/Data Center vs Cloud), there is some difference in the way the knowledge base is configured on the Jira side: 

• When using Confluence Server/Data Center, Jira and Confluence need to be integrated via an application link (via the menu ⚙ > Applications > Application Links)
• When using Confluence Cloud, the application link will not help. Instead, Jira needs to be integrated with Confluence Cloud (via the menu ⚙ > Applications > Confluence Cloud integration from the Jira application)

More information can be found on how to integrate Jira Service Management with Confluence Cloud in the documentation Set up a knowledge base with Confluence Cloud.

If Confluence Cloud is integrated with JSM using an application link instead of the Confluence Cloud integration configuration, the knowledge base search will not work for any JSM project and user.

Diagnosis

Case where Confluence Server (or Data Center) is used as a Knowledge Base

Diagnosis for Root Cause 1

• Go to the application link page in Jira (in ⚙ > Applications > Application Links), click on the pencil button next to the application link to Confluence and check if you see any error:
  

• Alternatively, if you have a support zip from the Jira application, you can check in the Health Check log file if the Health Check is complaining about un-healthy application links:

  Name: Application links
  Is healthy: false
  Failure reason: One of your application links is reporting "Network error".
  Severity: WARNING

• If you find any issue related to the application link configuration, then it means that the Confluence application is not running or is not reachable from the Jira Server, and this Root Cause is relevant. In this case:
  • Check if the Confluence application is up and running
  • If the Confluence is already up and running, make sure that it is reachable from the server where the Jira application is running. You can verify this by running some curl/ping/nc(netcat) commands in a terminal from the Jira Server to the Confluence Server

Diagnosis for Root Cause 2

Go to the Application Links configuration page in Jira and also in Confluence. If either incoming or outgoing request is configured without "Oauth (impersonation)" either on Jira or Confluence side, then this root cause is relevant:

Diagnosis for Root Cause 3

• Verify that the Confluence application is up and running, and that the Jira application is able to reach the Confluence application over the network
• Go to the Confluence UI to the page ⚙ > Manage Apps, and search for the add-on Confluence Knowledge Base Blueprints Plugin
• If this add-on is disabled as shown in the screenshot below, then this root cause is relevant:
  

Diagnosis for Root Cause 4

Try to search any page directly in the Confluence application. If the search does not return any result, then it is likely that the Confluence indexes are corrupted.

Diagnosis for Root Cause 5

Check the Confluence version. If it is on 5.5.1 or lower, then this root cause is relevant.

Case where Confluence Cloud is used as a Knowledge Base

Diagnosis for Root Cause 6

To check if this root cause is relevant:

• Confluence needs to be on Cloud (if Confluence is on Server/Data Center, this root cause is not relevant)
• In Jira, go to the page ⚙ > Applications > Confluence Cloud integration,
  • Check if the Confluence Cloud application is configured there
  • If it is not, then this root cause is relevant

• Additionally, you can also generate a HAR file while replicating the KB search issue (or simply check the Network tab from the Browser Dev Tool), and check if you see the error below for the end point /rest/servicedesk/knowledgebase/latest/articles/search?project=<SOME_PROJECT>&resultsPerPage=3&pageNumber=1&query=<SOME_SEARCH_WORD>.

  {
    "errors": [
      {
        "errorMessage": "Service not found in the knowledge base server."
      }
    ],
    "reasonKey": "sd.knowledge.base.applink.not.found",
    "reasonCode": "500"
  }

  •  If you find this error above, then this root cause is relevant.

Solution

Solution for Root Cause 1

• If the Confluence application is down, start it
• If the Confluence application is already up and running, but not accessible from the Jira Server, reach out to your Network/Firewall administrator to ensure that the Jira server can reach the Confluence server

Solution for Root Cause 2

Make sure that application link configured between Jira and Confluence used "OAuth (impersonation)" for both incoming and outgoing requests, and on both Jira and Confluence side

Solution for Root Cause 3

Enable the add-on Confluence Knowledge Base Blueprints Plugin from Confluence ⚙ > Manage Apps

Solution for Root Cause 4

Schedule a maintenance window for Confluence, and then run a full lock re-index.

Solution for Root Cause 5

Upgrade Confluence to version 5.5.2 or later following the instructions on the Upgrading Confluence document.

Solution for Root Cause 6

To fix this issue, integrate Jira Service Management with Confluence Cloud as explained in the documentation Set up a knowledge base with Confluence Cloud:

• In Jira, go to the page ⚙ > Applications > Confluence Cloud integration 
  • Add the Confluence Cloud application in this page (you will need to first configure an API token in Cloud as per Manage API tokens for your Atlassian account)
• Still in Jira, go to the Service Desk project administration page
• Go to Project Settings > Knowledge Base
  • Unlink the knowledge space that was previously linked
  • Link a new knowledge space
  • In the application field, this time select the name used in the configuration ⚙ > Applications > Confluence Cloud integration (instead of the Confluence name that came from the application link configuration)
  • Select the Confluence space from Confluence Cloud that you want to use as a knowledge base space