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.
Required apps | Who can see the knowledge base on your Refined site | |
|---|---|---|
Solution 1. |
| All users, or only logged-in users from your team. |
Solution 2. |
| All logged-in users, or only logged-in users from your team. Anonymous access isn’t possible due to Atlassian limitations (scroll down to learn more). |
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
Combine Refined Sites for Confluence with Refined Sites for JSM.
Visible to all users or only to logged-in users from your team.
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.
To also show suggested articles when users create a request, implement solution 2 as well: scroll down for instructions.
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.
Space permission | When the permission is set to “View”, these users can see the space |
|---|---|
Internal licensed users | Logged-in users from your team. |
Guest users | Logged-in guest users to whom you’ve granted access to the space. |
Anonymous access | Anyone: logged-in or not. Read more. |
Add the knowledge base
Go to the site structure.
Click Add New > Confluence space.
Use the search bar to find the desired Confluence space.
Customize the appearance of the space home using modules and other tools.
For a full in-depth guide, read this article: Build a documentation site/knowledge base
Solution 2. Add Confluence spaces as knowledge bases to the project in native JSM
Combine native Confluence with Refined Sites for JSM.
Visible to all logged-in users, or only logged-in users from your team. Anonymous access isn’t possible.
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.
Setting in “Who can view” | When selected, these users can see the knowledge base on your Refined site |
|---|---|
Only Confluence users | Logged-in users from your team who have access to the space (which you set up in Confluence). |
All logged-in users | Logged-in users, regardless if they’re from your team or not. Logged-in users who aren’t licensed users in your team are JSM customers. In Confluence, they're also referred to as unlicensed users from Jira Service Management. |
Anyone | Logged-in users, regardless if they’re from your team or not. Due to Atlassian limitations, users always have to log in to see a portal on a Refined site (even on public sites). To keep track of this issue or vote and comment on it, click here. |
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.
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.
Go to the Refined Administration.
Click Sites in the left-hand menu.
Select the site that features the JSM project with the knowledge base.
Click the Audience Features tab.
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.
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.
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.
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.
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.