Working with Jira Service Management (JSM) and utilising the unlicensed user feature from Atlassian where Service Desk users can access Confluence pages as articles, there are a few things that are good to know when adding Refined to the mix.
Refined is a great tool for highlighting content from Confluence on your site, getting that self-service set up. Read on to learn more about what to consider when setting up a knowledge base.
Introduction to the concept: https://refined.com/blog/how-to-add-a-confluence-knowledge-base-to-your-refined-for-jira-support-site/
How Refined works
When it comes to access and licensing, Refined works in the same way as Confluence and Jira: any user’s permission and access will be determined by their license set on the Atlassian side of things.
This means that a user cannot access content in Confluence or JSM via Refined that they can’t access via Confluence or JSM itself.
Guidance for building your knowledge base site
As mentioned in the blog above, there are two ways of building your knowledge base on a Refined site using Confluence:
using the JSM knowledge base connection
surfacing Confluence spaces on your site
Before building out your site, make sure you have considered the full scope of licenses, permission and access when it comes to Confluence.
What licensing are you working with in Confluence?
For a user to get access to content in Confluence, there are three ways you can set this up:
Unlicensed users
Confluence licensed users
Anonymous users
Unlicensed users
When setting up on or several spaces as knowledge base spaces via a JSM project, unlicensed users are the ones that have access to a service desk that has a Confluence space connected as a knowledge base. The unlicensed users can view content in Confluence on a per article level, meaning they can access content in Confluence via the portal as articles, but they cannot go directly to Confluence to view content.
When this is applied in Atlassian cloud, it is reflected in Refined.
| Info |
|---|
|
Content from Confluence can be viewed on an article basis, as a popup.
...
Confluence licensed users
Confluence licensed users will have access to content in Confluence as per their permissions on a space level. This is reflected in Refined. When you have this option you open up for adding Confluence spaces to a Refined site, giving any user with a license opportunity to browser the content, view the page tree and access activity streams and blog feeds.
...
Anonymous users
Having your Confluence open for anonymous users means that the content is publicly available. Since from the point-of-view of permissions this means read permissions in Confluence you get the same options as in the case of users have Confluence licenses above, and you can add in spaces to your Refined site unlocking all the nice features here.
| Info |
|---|
Setting up anonymous content in Confluence: https://support.atlassian.com/confluence-cloud/docs/set-up-public-access/ |
What Refined apps do you have installed?
When using Refined for Atlassian cloud, what you can do depends on what Refined apps you’ve added to your Atlassian cloud.
Refined for Jira
With Refined for Jira Cloud you have access to the knowledge base shown as popups on an article per article basis, either via link or via search.
Refined for Confluence
With Refined for Confluence Cloud you open up for adding Confluence spaces to your Refined sites. Users who have read permissions in these spaces can browse the spaces from the Refined site, and you can highlight content.
What Confluence content in the search on a Refined site?
The search in a Refined site shows the content based on what is added to the site and what the searching user has access to see.
Refined for Jira
With Refined for Jira Cloud, when you have a Confluence space linked as a knowledge base to a JSM portal, and that project is added to your Refined sites, when a user searches they will see search results as articles.
Refined for Confluence
With Refined for Confluence Cloud, when Confluence spaces have beed added to your Refined sites, the search for content will show up as pages.
For any user that have access to both the Confluence content (via a Confluence license, or if the content is anonymously available), and the knowledge base content (by being a user on a JSM portal that has a knowledge base linked) both results will show up, one as a page and one as an article.
...
Extending articles with links on Refined
While an unlicensed user cannot freely browse content on your site as they only have a per-article way of viewing it, you can use links to create a library for users.
...
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.
| Widget Connector | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
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.
| Info |
|---|
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.
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.
| ||
Anyone | Logged-in users, regardless if they’re from your team or not.
|
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.