Add a knowledge base to your site

One of the easiest ways to cut down on support tickets is to help users help themselves. A great way to do this on your Refined site is by adding a knowledge base: a self-serve online library of information about a product, service, department, or topic. There are two ways to do this – choose one or combine them, depending on your apps and audience.

To illustrate: help.refined.com features both options. You’re now in the Refined Sites for Confluence documentation/knowledge base space (solution 1). If you go to the Cloud support page and file a request, you’ll see knowledge base articles suggested once you start typing in the summary field (solution 2). If you’re logged in, you can also see knowledge base articles in the search results when you search the site.

To determine which solution to go for on your own site, read on or watch this video.

Solution 1. Add Confluence spaces as knowledge bases to the Refined site

By using Refined Sites for Confluence in addition to Refined Sites for JSM, you give your users the best self-help experience. It lets you take full advantage of Refined Sites’ user-friendly browse and search experience, which includes:

• Page tree menus on landing pages and in the left-hand menu of the Confluence space.

• A search field in the left-hand menu of the Confluence space, which only shows results from that space.

• The possibility to embed JSM Request Type links on Confluence pages. These are visible in-line in the text, as well as when the use clicks the support icon at the top of the page (see the images below - click to enlarge).

• Confluence modules on your landing pages, which for example let you highlight the latest news from your blogs and show the most recently updated pages.

• The knowledge base articles listed as Pages when a user searches the site.

Open

Request types show up neatly on the page: as a button at the top right-hand side, and clearly formatted inline.

Open

The user creates the request directly on-page. So once it’s sent, they can carry on with reading the same employee handbook page.

Set up who can read the knowledge base articles

The space permissions you set up in Confluence determine who can see the space on the Refined site.

Add the knowledge base

1. Go to the site structure.

2. Click Add New > Confluence space. 

3. Use the search bar to find the desired Confluence space.

4. Set up the space.

5. Customize the appearance of the space home using modules and other tools.

Solution 2. Add Confluence spaces as knowledge bases to the project in native JSM

This more limited solution includes:

• Suggested knowledge base articles when a user creates a request, based on the keywords the user writes in the summary field. When they click the article, they see it in a popup.

• The knowledge base articles listed as Articles when a user searches the site.

Limitations

• When a user reads a knowledge base article and clicks a link to go to another knowledge base article, they’re directed to the native JSM portal. We can’t direct them to the article on the Refined site, because the knowledge base articles are rendered in an iFrame. Please vote and comment on this active Atlassian ticket.

• Some macros and other content or formatting aren’t supported in the popup, because the knowledge base articles are rendered in an iFrame. If you prefer, you can direct users to the page in native Confluence by adding a link to the bottom of the popup: scroll down for instructions. Please vote and comment on this active Atlassian ticket.

• Users can only read articles one-by-one: there's no page tree or other browsing functionality in the popups.

Set up who can read the knowledge base articles

The project’s knowledge base settings that you set up in native JSM determine who can see the project’s knowledge base on your Refined sites.

Add the knowledge base

Atlassian provides some great resources on how to set up a knowledge base in native JSM. Once added to the JSM project, the knowledge base also become available on your Refined site.

• Using Confluence and Jira Service Management together

• 5 steps to setting up a knowledge base in Jira Service Management

• Set up a knowledge base so customers can serve themselves

Optional: add a link to native Confluence

You can direct users to the page in native Confluence by adding a link to the bottom of the popup. This can help users, for example when the original Confluence page includes macros that are not supported in the popup on the Refined site.

1. Go to the Refined Administration.

2. Click Sites in the left-hand menu.

3. Select the site that features the JSM project with the knowledge base.

4. Click the Audience Features tab.

5. Scroll to the Jira Service Management heading and enable Article link.

Optional: highlight singular knowledge base articles as popups on your site’s landing pages

As mentioned in the limitations, users can only read articles one-by-one: there is no browsing functionality in the popups. But because it’s possible to access these popups with direct links, you can build landing pages that feature links to the most important articles.

1. Choose which page to add the links to. Use the landing page of the JSM project on your site, or add a Refined Page to your site structure.

2. Go to the page and open the Page Builder. Create the module that you want to link to the knowledge base article. For example, use an Icon module, Links module or an Image module.

3. In another tab, go to your Refined site and search for a knowledge base article using the search in the navigation menu. Click the article to open the popup and copy the URL.

4. Go to the tab where you have the Page Builder open. Click the module and add the URL in the module’s settings or in the module’s text. Don’t shorten the URL – it should be this format: domain.com/portal/{id}/article/{id}/{title}. For example: exampledomain.refined.com/portal/2/article/39026710/Payment

_{These instructions originally appeared on the Refined blog.}