Providing self-help resources for your customers with a knowledge base
If you use Confluence, you can integrate its knowledge base capabilities with JIRA Service Desk to help customers find solutions on their own.
To integrate Confluence with JIRA Service Desk, go to the Settings tab and then Knowledge Base.
Search on the global portal
A search box appears on the landing page if you've connected Confluence with any service desk. Your customers can easily search for anything they need to find out across all the spaces of Confluence. If multiple Confluence servers are connected to service desks, only the primary one will be used by the search box on the landing page.
Restricting the topic search
You can control how Confluence suggests topics for each request type using the Request form search section. You can control this in two ways:
- Prevent Confluence from suggesting pages - Select No in the Search KB column for the request type. For example, you might not want the "Get access to a system" request type to suggest pages since users have to request access through the Customer Portal.
- Limit the pages that will be suggested - In the Restrict to articles with label column, enter the labels that must be applied to pages in order for them to appear in the suggested page list. For example, you might want to only include pages with the label "purchasing" to appear when customers enter a "Request new software" request.
Tip: If you add label restrictions to a request type, these labels will also appear as the default labels for knowledge base articles created in JIRA for issues based on that request type.
Creating knowledge base topics from an issue
If you link a Confluence space with a service desk, your team can create a knowledge base article based on an issue from the view issue page in JIRA. Service team members can choose whether to create the article with a How-To article or Troubleshooting article blueprint; those blueprints can help your knowledge base expand with cleanly organized topics.
The issue title and description are automatically added to the new Confluence page as its title and body text. (Any images in the issue aren't copied over to Confluence.) If you've set up label restrictions on the request type the issue was based on, those labels are automatically suggested for the article.
Service desk members must have the Add page permission in the Confluence space to create a knowledge base article from an issue in JIRA.
Integrating JIRA Service Desk with Confluence
- You can connect JIRA Service Desk with Confluence 5.6 or later.
If you use an installed version of JIRA and Confluence, they must be linked via an application link using OAuth.
- You must have permission to view a space in Confluence in order to select it as your knowledge base. If you don't have this permission, check with your Confluence administrator.
- In order to use the topic search from the Customer Portal, customers must be Confluence users with permission to view the space the or Confluence space must allow anonymous access.
If the Confluence space is set up to allow anonymous viewing, any user can search the service desk when they're putting in requests (in other words, they don't have to be Confluence users).
However, if the space viewing is restricted to certain users, customers must have the same username in Confluence in order to search the space from the service desk.
Notes on setting up a 2-legged OAuth application link
An application link lets two applications ask each other for data. One application consumes data from another application that produces data.
For JIRA Service Desk, the application that consumes data is JIRA and the application that produces data is Confluence. When configuring the application link for JIRA Service Desk, the incoming authentication tab inside Confluence must be correctly configured.
When configuring 2-Legged OAuth, it is important to understand that the two applications actually maintain independent sets of configuration information. The configuration in the incoming authentication tab of the application that produces data is different the configuration in outgoing authentication of the application that consumes data
- Confluence needs to correctly configure either "Allow user impersonation through 2-Legged OAuth" or specify a user in "Execute as" in the incoming authentication tab.
- JIRA only needs to enable 2-Legged OAuth on the outgoing configuration tab.
About 2-Legged OAuth (2LO)
Application links that use 2-Legged OAuth accomplish this communication in one of two ways. One way to handle this communication is to trust all requests made over the application link and grant those requests access to everything. The second way to have requests made over the application link is to pretend that each request is being made by an actual user. That pretend user is used to determine what permissions should be applied to the request. The user the application link picks depends on how the application link is configured. JIRA Service Desk uses the second way when making requests between applications.
- To enable a 2LO application link you need to enable OAuth and select "Allow 2-Legged OAuth" in both incoming authentication in Confluence and the outgoing authentication in JIRA.
- When you select 2LO, make sure that you also specify the user that is used by the application link when making requests.
How to choose the user that you want searches to be performed as
- If your applications have the same users and you would like 2-Legged OAuth to pretend your users are making the request as themselves: In the incoming authentication tab of the application that will serve the data, select "Allow user impersonation through 2-Legged OAuth". This must be checked in the incoming authentication tab of the application that will serve the data as it can only be configure by that application. Your users must have the same usernames in JIRA and Confluence.
- If your users do not have the same usernames in JIRA and Confluence, you can create a special user with correct permissions: In the incoming authentication tab of the application that will serve the data, add the user name you want to use in the text field beside "Execute as" to have all searches made over the link be performed as though that user made the request. The user name must be entered in the text field beside "Execute as" in the incoming authentication tab of the application that will serve the data as it can only be configure by that application.
Note: This setting only opens up the search restrictions for users who do not have the permission to view the space. When they open the Confluence pages by clicking the search results, they still do not get to see the pages due to the lack of the permission.
- If you want to retrieve data that is available to anonymous users, do not select “Allow user impersonation through 2-Legged OAuth” and do not add a user name in the text field beside “Exectue as”. The user that 2-Legged OAuth uses, in this case, is the anonymous user.
Troubleshooting issues with 2-Legged OAuth
You might see the following errors when connecting JIRA Service Desk to a Confluence knowledge base:
There was an error contacting Confluence. A possible cause of this could be an invalid Application Link. Another possible cause could be that the current user does not have access to Confluence. Please check that a valid Application Link to Confluence is set up and that you have access to Confluence and have the appropriate permissions for this action.
or
Client must be authenticated to access this resource.
These errors occur when the application link attempts to make a request in Confluence as a user that does not have permission to do so. In this case JIRA Service Desk is attempting to make a space search in Confluence. That search is being performed by the application link as a particular user and that user does not have permission to do the search.
To resolve the errors: