Serving customers with a knowledge base
1. Install Confluence
User: JIRA ADMINS
You'll need Confluence 5.10 and above and JIRA Service Desk 3.1 and above to access knowledge base features. Get the latest versions of each for all the bells and whistles.
Steps
- Install the latest version of Confluence.
- Have the same user base in both JIRA and Confluence by one of the following methods:
- Check that you're an administrator in both JIRA and Confluence.
Good to know
- Read Use JIRA applications and Confluence together to check version compatibility between products.
Having the same user base in both JIRA and Confluence means you won't have to manually create and maintain customer accounts.
2. Get the right number of Confluence licenses
User: JIRA ADMINS
Your service desk agents will need a Confluence license to create and edit knowledge base articles. However, service desk customers won't need a Confluence license to view articles.
Good to know
- Read Confluence licensing and pricing to learn more.
3. Link JIRA Service Desk to Confluence
User: JIRA ADMINS
Linking two applications allows you to share information and access one application's functions and resources from within the other.
Steps
- Go to JIRA Administration > Applications > Application links.
- Enter the URL of your Confluence instance and select Create new link.
- Check The servers have the same set of users, to configure using OAuth (with impersonation) authentication.
- If you're not an admin on both servers you won't be able to set up a 2-way (reciprocal) application link. If you want to go ahead and create a 1-way link anyway, clear the I am an administrator on both instances checkbox.
- Use the wizard to finish configuring the link.
Good to know
- Read Linking to another application to learn how to set up a reciprocal link from Confluence.
- Read this troubleshooting article if you get into difficulty linking JIRA to Confluence.
4. Set up knowledge base permissions
The permissions you set in Confluence determine whether (or not) your agents can create articles and if your customers can view them.
Who needs a Confluence license
If you want your service desk agents to create, comment on, and search the spaces on your Confluence site, they'll need a Confluence license. Your service desk customers however, don't need a Confluence license to view knowledge base articles.
To check if someone has a license:
- Go to JIRA Administration > User management.
- Select the user from the list.
- If the Confluence box under Application access is checked, the user has a Confluence license.
Choose who can view articles
Go to Project settings > Knowledge base > Access > Viewing.
This setting determines who can view articles via the help center or a link your team shares. You have two options to choose from:
Option 1. All active users and customers
Users who don't have a Confluence license can view knowledge base articles via the customer portal and help center.
Choose this if:
- You want your team to write articles and share them with customers.
Limitations:
- If your service desk site and Confluence site have separate user bases, you'll need to create a Confluence user account for each Service Desk customer. If you don't want the customer to use a Confluence license, don't assign the Confluence user to a group.
Option 2. Only licensed users
Users who don't have a Confluence license can't read knowledge base articles unless you allow anonymous access in the knowledge base space.
Choose this if:
- You only want to use your knowledge base for internal articles.
Limitations:
Anonymous access is not compatible with SSO using 2-legged OAuth.
Data privacy
If you choose the All active users and customers setting, you'll see the following message in the Confluence space permission screen:
This permission overrides all existing space permissions. Any logged in Confluence user will be able to see the space (regardless of their group membership).
You can disable this permission at any time, but it can only be re-enabled from JIRA Service Desk.
Login process
If you aren't using SSO or something that passes login information between instances, then users will need to log in to Confluence using their JIRA Service Desk credentials to view articles.
Check if agents can create articles
Your agents will need a Confluence license to create and edit articles, and permission to create articles in the Confluence space.
To check if an agent can create articles:
- Go to Project settings > Knowledge base > Access > Authoring.
- Select the space permissions link, this will take you to your space permission's page.
- Check that the agent (or a group they are a member of) has the Add page permission.
Learn more about Confluence permissions
There are three levels of permissions in Confluence that determine who can view and create articles:
- Global permissions are site-wide and can be assigned by a system or Confluence admin.
- Space permissions are space specific and are managed by the space admin.
- Page restrictions affect both viewing and editing and are managed by space admin.
If you, your agents or your customers are having difficulty viewing articles, check the permissions with your Confluence admin.
5. Link your project to a Confluence space
User: PROJECT ADMINS
When you link a Confluence space to your service desk project, agents can search for solutions and create new articles for common requests. Customers can then use the articles to self-service problems.
There are two ways to link your service desk to a Confluence Space:
Link to an existing space
- Go to Knowledge base (sidebar) > Link existing space.
- Select the space you want from the dropdown.
- Choose the link Define who can view knowledge base articles to set permissions.
You can also unlink or change spaces in Project settings > Knowledge base.
Link to a new space
- Check you have Confluence admin and Create space permissions.
- Go to Knowledge base (sidebar).
- Select Create new space.
- Congratulations, you have created a new Confluence space.
Good to know
- Read Use Confluence as a knowledge base to learn how to set up a knowledge base blueprint.
6. Write and search for knowledge base articles
User: SERVICE DESK AGENTS
Once you've linked to a Confluence space, agents are ready to start writing and sharing knowledge with customers and teammates.
Your knowledge base is there for customers, even when you're working on other requests, at home for the day, or away on holiday.
Here are some reasons you might write knowledge base articles:
- You get a lot of similar requests. Like "How do I access office wifi?". When customers search for 'wifi' in the help center, they'll find your article. If they send you a request, you can share the article rather than walking them through the steps in a comment.
- You're upgrading a system. You can write a step by step upgrade guide and link to it from an announcement in the help center.
- You're troubleshooting the same issue with customers. If you normally walk people through a series of steps to diagnose and troubleshoot a problem, such as a broken printer, a troubleshooting guide will save you time.
How to write articles
After you set up your knowledge base space, the issue view displays a panel called Related knowledge base articles:
If you don't see a relevant article, you can create a new one from the issue. You'll need the Add page permission in the Confluence space. Customers can read any article that doesn't have a red padlock.
To create a new article:
- Click the create an article link.
- By default, the issue summary becomes the new article's title, you can edit this.
- Choose either the How-To or Troubleshooting template.
- Follow the prompts to create the article, then Publish.
- Check how it displays in the issue view.
Page labels are essential in knowledge base spaces. These are used to add topics to your articles, and allows your knowledge base to become self-organizing over time.
You can also create articles from the sidebar, then Knowledge base > Create article.
How to share articles
There are two ways you can share articles with customers:
- Hover over an article to share it as a comment on a request
- Share links from a knowledge base article that you access via Knowledge base in the sidebar.
When customers click the link from a request or their email, the article opens in the help center:
Help people find articles
The knowledge base suggests articles to customers and agents using keywords from request summaries. For the knowledge base to work properly, make sure your request types have a visible Summary field.
Learn how to set up request type fields.
Help customers find articles
When customers search the portal or help center, they see related articles that might help them troubleshoot their problem. To make it even easier for customers to find what they need, you can also suggest articles when they fill out a request:
In the above example, the request type wifi access is restricted to the label wifi. When the customer starts typing in the Summary field, the help center uses their text to search the knowledge base and suggest matching articles that are labeled with wifi.
To suggest articles for certain request types, go to Project settings > Knowledge base > Auto-search on request types, then in the Search KB column, choose Yes. To help make sure customers get the right articles for their request, you can also restrict the search to articles with a certain label. To make it easy for agents who write articles to remember which label to use, we recommend using a label similar to the request form.
You can't use labels as a way of restricting access to an article. For example, if you create a knowledge base article and add the label Display, and then create another article and don't add the label Display – the page without the Display label will still show up in the search. Adding labels are a way to filter related articles, not to assign viewing permissions.
If you need to restrict an article so that only certain users can view it, do this by setting up the right knowledge base permissions.
Help agents find articles
When agents view a request, the knowledge base suggests related articles that they can reference or share with customers.
Your service desk uses the request Summary to search your knowledge base space for articles. If you don't see an article that you think you should see, try changing the article title to use more keywords from the Summary.
Agents can also search for articles via the Knowledge base in the project sidebar.