Set up a knowledge base with Confluence Cloud

Still need help?

The Atlassian Community is here for you.

Ask the community

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

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.

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.

Steps

  1. Go to Administration > Applications > Confluence Cloud integration.

  2. Enter the URL of your Confluence site, including the /wiki suffix, for example:

    https://confluence.atlassian.net/wiki
  3. Enter a descriptive display name. This is what project admins will see when linking their projects to Confluence.

  4. 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.

  5. Enter your Confluence API token. You can generate it from your Atlassian account. For more info, see API tokens.

  6. Click Save.

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. 

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.

Steps

  1. Go to Knowledge base > Link existing space.

  2. Select the space you want from the dropdown. 

  3. 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

Audience: AGENTS

Once you've linked to a Confluence space, agents are ready to start writing and sharing knowledge with customers and teammates.

Known issues

Not all search results are available...

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.

Creating spaces...

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.

Articles can't be viewed without logging in

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:

JSDSERVER-7175 - Getting issue details... STATUS

Last modified on Jul 12, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.