Set up a knowledge base with Confluence Cloud

Still need help?

The Atlassian Community is here for you.

Ask the community

This guide shows you how to link Jira Service Management to a Confluence Cloud knowledge base. If you're looking to link to Confluence Data Center, refer to Set up a knowledge base with Confluence Data Center.

1. Set up a Confluence Cloud account

You’ll need a Confluence Cloud account to create the integration. Don't have an account? Try Confluence Cloud

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.

Who can do this?

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 Jira Administration then Applications.
  2. From the sidebar, select Confluence Cloud integration.
  3. Enter the URL of your Confluence site, including the /wiki suffix, for example:

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

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

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

  7. 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 by the Confluence admin, and the permissions set by the project admin in Jira Service Management, 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.

6. Link your project to a Confluence space

Who can do this?

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 then select Link space.

  2. In the Link space dialog that displays, search and select the space you want to link to.
    You can only link spaces that you have permission to view,
  3. From the Who can view list, set permissions to define who can view knowledge base articles.

You can also unlink or change spaces in the Linked spaces section from Project settings then select Knowledge base. Unlinking spaces only removes them from your service project. These spaces will still be available in Confluence.

Good to know

  • You can link up to 10 spaces.

7. Write, search, and share knowledge base articles

Who can do this?

Agents

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

Read Write, search, and share knowledge base articles to learn how to do this. 

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 Dec 22, 2023

Was this helpful?

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