Write and search for knowledge base articles
How to write 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.
To create a new article:
- Click the create an article link.
- By default, the issue summary becomes the new article's title, you can edit this.
- Choose either the How-To or Troubleshooting template.
- Follow the prompts to create the article, then Publish.
- Check how it 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 your knowledge base becomes self-organizing over time.
You can also create articles from the sidebar, then Knowledge base 
> Create article.
How to share articles
There are two ways you can share articles with customers:
- Hover over an article to share it as a comment on a request:
- Share links from a knowledge base article that you access via Knowledge base in the sidebar.
When customers click 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
To recommend articles for certain request types, go to Project settings > Knowledge base > Auto-search on request types, then in the Search KB column, choose Yes:
You can restrict the search to articles with a certain label. To make life easier for yourself, use a label similar to the name of the request form.
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 one by going to Administration > Applications > Application links.
Other important information
- Knowledge base vs. request type search: The knowledge base search and the request type search are independent of each other.
- Request type search: The request type search will display a maximum of 5 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 request's Summary field.
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 search help
When you link a Confluence knowledge base to your service project, a Search help link appears below the search field.
When you click 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.