Write, search, and share knowledge base articles

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Your knowledge base is there for customers and other agents, 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 and can help themselves. 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.

On this page:

How to create articles

After you set up your knowledge base space, the issue view displays a panel called Related knowledge base articles:

Related knowledge base articles section in the issue view

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. The red padlock indicates that the reporter of the issue doesn't have permissions to view the article. So if an agent (who has permissions to view) links such articles in response to the reporter, the reporter will not be able to view them.

To prevent articles from being viewed by customers, see:

Create a new article dialog

To create a new article:

  1. Select the create an article link. 
    You can also create articles from the sidebar. Select Knowledge base  then Create article.
  2. By default, the issue summary becomes the new article's title, you can edit this.
    Note that images and attachments will not be automatically copied from the issue.
  3. If multiple spaces are linked to your service project, select the appropriate space.
  4. Choose either the How-To or Troubleshooting template.
  5. Follow the prompts to create the article, then select Publish
  6. Check how the article displays in the issue view.
  • The above steps describe how to create an article in Confluence Data Center. The steps to create an article in Confluence Cloud are very similar.
  • Page labels are essential in knowledge base spaces. Add them to your articles so you knowledge base becomes self-organizing over time. are used to add topics to your articles, and allows your knowledge base to become self-organizing over time.

How to share articles

There are two ways you can share articles with customers and other request participants:

  • Hover over an article in the issue view to share it as a comment on a request:
  • Access Knowledge base from the sidebar and share links to articles. 

When customers select the link from a request or their email, the article opens in the help center:
An example article in the help center view

How the search works

The knowledge base recommends articles to customers and agents using keywords it pulls from the Summary field of a request. 

Help center and customer portal search results

When a customer types something in the search field on the help center or customer portal, the results return the following:

  • Related knowledge base articles. These help customers resolve their own issues, without needing to raise a request. 
  • Related request types. These are recommended to customers, so they know which request type to fill out based on their issue. 

To make it even easier for customers to find what they need, you can recommend articles when they fill out a particular request type.

Articles recommended when a customer starts typing the summary

Recommending articles

You can configure how you recommend articles from your knowledge base.

To recommend articles for a request type:

  1. Go to Project settings then Knowledge base.
  2. In the Auto-search on request types section, select Yes in the Search KB column against the request type.
  3. To recommend only the articles with certain labels, type the labels in the Restrict to articles with labels field.
    To make things easier for yourself, use a label similar to the name of the request form.

Image of auto search on request types you see in product

Restricting articles

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 label will still display in the search. Adding labels are a way to filter related articles, not assign viewing permissions.

If you need to restrict an article so that only certain users can view it, do this through knowledge base settings and permissions.

Using multiple knowledge bases

If you have multiple knowledge bases (Confluence instances) connected to your Jira Service Management instance and are searching through the Help Center, only articles from the primary knowledge base will be returned. This is a known issue related to the Help Center, you can follow a feature request here. Articles from remaining knowledge bases will be returned when searching on individual customer portals.

You can set any Confluence instance as the primary instance by going to Administration then Applications then Application links

Knowledge base vs request type search

The knowledge base search and the request type search are independent of each other. The request type search will display a maximum of five results, and:

  • The primary search picks up words that the customer is typing in the Summary field, and looks for them in the request type's Name and Description.

  • The secondary search uses JQL queries to find relevant request types based on the request's Summary field.

Issue view search results

When agents view a request, the knowledge base recommends related articles that they can reference or share with customers. Your service project will search the Confluence space you have linked for any articles that contain keywords in the Summary field of the request.

Important things to note:

  • The search ignores all other fields from the request (only the summary field is used).
  • Check that your request types have a visible Summary field. Read Setting up request types.
  • The search skips articles that the agent doesn't have permission to view.
  • The search and ranking follows the same rules as the Confluence search. In short, Confluence identifies all articles that contain keywords matching those in the request's Summary field, and sorts them by word frequency.
  • Agents can only share articles that the customer has permission to see.
tip/resting Created with Sketch.

Change the article title to include more keywords from the request summary field, if you don’t see an article that you think you should.

Agents can also search for articles via the Knowledge base in the project sidebar.

How to access the advanced search help

When you link a Confluence knowledge base to your service project, a Search help link appears below the search field. 

Search help link is displayed below the search box

When you select on this link, you're shown a screen that explains how to create an advanced search query using Confluence search syntax (including wildcards) for more precise knowledge base search queries.

Confluence search syntax with definitions.

Check out Confluence Search Syntax for an overview of this function.

Last modified on Mar 19, 2024

Was this helpful?

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