Set up a knowledge base with Confluence Cloud
Follow this step by step guide for linking Jira Service Management to a Confluence Cloud knowledge base so that customers can help themselves and agents can share their expertise.
1. Set up a Confluence Cloud account
You’ll need a Confluence Cloud account to create the integration. If you don’t have one already, check out this link:
2. Get the right number of Confluence licenses
Your service project agents will need a Confluence license to create and edit knowledge base articles. However, service project customers won’t need a license to view these articles.
Good to know
Read Confluence Cloud licensing and pricing to learn more.
3. Create a user with the right permissions to access Confluence
When integrating Jira Service Management with Confluence, you’ll need to choose a user that will be used to access Confluence. It’s important that this user’s permissions are similar to what you’d like customers to have.
Why are permissions important?
When customers search your knowledge base, they get results based on the permissions of the user you’ve chosen. If that’s an admin or someone with high permissions, customers might see results they shouldn’t have access to.
This will include the title and an excerpt of an article (that’s what’s displayed in the search). If an article is restricted, they won’t be able to view it as the article’s restrictions are checking permissions of a specific user who’s trying to access it. Nevertheless, it’s easy to reveal more than you’d like to, so make sure to set the permissions right.
4. Integrate Jira Service Management with Confluence
Audience: JIRA ADMINS
Once you’ve covered the requirements on the Confluence side, it’s time to integrate it with Jira Service Management. That’s a one time action after which your project admins will be able to link their projects to spaces in Confluence.
Go to Administration > Applications > Confluence Cloud integration.
Enter the URL of your Confluence site, including the
/wikisuffix, for example:
Enter a descriptive display name. This is what project admins will see when linking their projects to Confluence.
Specify the user that will be used to access Confluence. Make sure to set the right permissions for this user, as described in the previous step.
Enter your Confluence API token. You can generate it from your Atlassian account. For more info, see API tokens.
Good to know
In the past, you might have created integrations with other applications through Application Links. Although this would still work for Confluence Cloud, using it as the knowledge base requires that you create the integration through the Confluence Cloud integration page. No AppLinks this time.
5. Learn about knowledge base settings and permissions
The permissions you set in Confluence determine whether (or not) your agents can create articles and if your customers can view them.
Read Knowledge base settings and permissions in Confluence Cloud to decide what you need.
Good to know
- Knowledge Base articles can't be opened in the customer portal if anonymous access is not turned on in Confluence Cloud.
6. Link your project to a Confluence space
Audience: PROJECT ADMINS
When you link your service project to a Confluence space, agents can search for solutions and create new articles for common requests. Customers can then use the articles to self-service problems.
Before you begin
You need to create a space for your project in Confluence beforehand, as you can only link projects to existing spaces.
Go to Knowledge base > 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.
7. Write and search for knowledge base articles
Once you've linked to a Confluence space, agents are ready to start writing and sharing knowledge with customers and teammates.
Read Write and search for knowledge base articles to learn how to do this.
The pagination of search results is not available in Confluence Cloud, that's why when you search for knowledge base articles, you'll only see the top 3 articles.
When linking a project to a Confluence space, you'll need to create this space in Confluence beforehand. You won't be able to create it from within Jira Service Management.
You also won't be able to create a Confluence space when creating a service desk project.
To view articles linked in your requests, your customers will need to be logged in to their Atlassian cloud accounts (no license required) unless you allow anonymous access. That's a known issue that makes this integration different from using Confluence Server or Data Center.
To check what your customers need to view the articles, how to allow anonymous access for your Confluence spaces, and how to create Atlassian cloud accounts without them consuming extra licenses, see Knowledge base settings and permissions in Confluence Cloud.
There is a feature request to improve this behavior: