Write, search, and share knowledge base articles
How to create 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. 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:
- How to use page restrictions in Confluence Data Center
- How to use page restrictions in Confluence Cloud
To create a new article:
- Select the create an article link.
You can also create articles from the sidebar. Select Knowledge base
then Create article. 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.- If multiple spaces are linked to your service project, select the appropriate space.
- Choose either the How-To or Troubleshooting template.
- Follow the prompts to create the article, then select Publish.
- 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 similar. However, you'll need to search for and select the space and page template manually.
- 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:
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.
Recommending articles
You can configure how you recommend articles from your knowledge base.
To recommend articles for a request type:
- Go to Project settings then Knowledge base.
- In the Auto-search on request types section, select Yes in the Search KB column against the request type.
- 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.
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.
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.
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.
Check out Confluence Search Syntax for an overview of this function.