Refined for Jira lets you create help sites with Jira Service Management that deliver a modern, user-friendly experience for internal or external customers. Combine it with Refined for Confluence to add a knowledge base and feature self-help resources, FAQs and more on your site.
Step 1: Prepare a content strategy
If your organisation needs multiple support sites, it’s worth taking the time to figure out how they all fit into an overarching strategy before you start building: this blog can help you decide on a structure that works for your organisation.
Once you have this sorted, devise a roadmap for creating, publishing, organising and managing the content that comprises the support site(s) you’ll build. A good starting point is to ask yourself who the site’s target audience is and what support resources they need:
JSM service desks: Make a list of the JSM projects you already have, or create new ones specifically for your support site.
Confluence knowledge bases: One of the easiest ways to cut down on JSM support tickets is to help users help themselves. Confluence is a great tool to integrate content that answers common questions directly into the support environment. For the best user experience, use Refined for Confluence in addition to Refined for Jira. This lets you take full advantage of Refined’s user-friendly browse and search experience, which includes:
Page tree menus on landing pages and in the left-hand menu of the Confluence space.
Embedding request types directly on Confluence pages.
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.
If you use only Refined for Jira, it’s possible to show users knowledge base articles in a pop-up, on a per-article basis. However, this alternative comes with a range of limitations. Check out this guide to see which solution works for your organisation and how to implement it.
Step 2: Create a site
When you have your strategy fleshed out, it’s time to turn your content into a site.
Go to Refined Administration > Sites and create a new site by clicking the + button.
Give the site a catchy name and subdomain. While you are welcome to keep this URL (formatted as example.refined.site), you can also set up a custom domain later. Changing the domain to help.yoursite.com, for example, clearly communicates the site’s purpose.
Head over to the Permissions tab to set your site access permissions.
Internal support sites should be set to Private, so only logged-in users from your organisation can see it.
External support sites should be set to Public, so everyone can view them, or to Support so that only JSM customers and logged-in users from your organisation can see it.
Step 3: Add content and structure
Go to the Site Builder tab to add content and structure to your site. The structure is reflected in the site’s navigation menu.
Add content
Most sites consist of a mix of these building blocks, which you add with the + Add Content button.
When you add a JSM project, you create a customisable landing page for the project. Users can create and view requests on this page. Landing pages are customisable – we’ll get into that later on in this guide.
When you add a Confluence space, you create a landing page for the space. Through this page, users can access the Confluence space’s pages and blogs.
A Refined Page is a customisable landing page. Although it is not connected to any specific Confluence or Jira content itself, you can use it to display content from the spaces and projects that you group underneath it in the Site Builder. Any item that you nest below a Refined Page appears in a dropdown list in your site’s navigation menu.
Menu Folders also let you create dropdown lists in the navigation menu. As opposed to a Refined Page, a Menu Folder doesn’t have a landing page.
Links let you direct users to any page you want, on or off your site, straight from your site’s navigation menu.
Add structure
Simply drag and drop items in the Site Builder to arrange them into a hierarchy. Group items underneath Refined Pages and Menu folders to create dropdown lists in the site navigation menu.
Step 4: Create user-friendly landing pages
Landing pages help users navigate your site. You can customise your site’s homepage, as well as the landing pages for Refined Pages, JSM projects, a d Confluence spaces.
You shape your pages in the Page Builder with the help of building blocks called modules. For example, on a JSM project page you can add:
A Request Types module to make it easy for users to send tickets.
A My Requests module to give users a handy overview of their tickets.
Icons with quick links to relevant pages on your site — for example to point users to the Frequently Asked Questions section in your knowledge base.
Three tips for landing page success:
To create uniformity across your help site, export and import page layouts. This way you easily standardise the looks of similar types of landing pages. For example, on help.refined.com we have similar looking landing pages for our Cloud, Data Center and Server help desks.
Need inspiration? The Page Builder includes a range of templates, including ones for navigation, documentation, and support. A template is merely a starting point – after applying it, you can further adjust the page.
Users will be more likely to effectively use your support site if the content is relevant to them when they arrive. For example:
Use the text variable $userfirstname in a module’s title to welcome users to your help site.
Apply view permissions on a landing page. For instance, on your home page you can show anonymous users a prompt to log in to file a ticket, while a logged-in user will see an overview of request types and their open tickets.
Step 5: Theme your site to match your brand
Of course, the help site should reflect your company's identity. Add logos and create themes to apply your brand’s look and feel. You can apply themes site-wide or to individual parts of the site, which gives you loads of options for customisation:
Differentiate areas of your site by applying variations of your theme. For example, when you offer one service desk per product type, you can tailor their themes to the products.
If you have multiple sites (your Refined subscription allows you to create as many as you like), apply different themes to each of your sites.
Create themes for special occasions, for example to celebrate a company anniversary.
Step 6: Set up JSM customer notification emails
In JSM you can activate customer notifications for each project, so users automatically receive an email every time someone updates their requests. All these emails contain a View Request link, which directs users to the JSM portal on Atlassian’s website – even if the user created the issue on your Refined site.
To direct users to the JSM portal on your Refined site instead:
Update the email template of every service project that you added to your Refined site.
Update the email template of each language in your service project, if you have enabled several languages.
Step 7: Seamlessly integrate JSM into Confluence pages
Available when you use Refined for Confluence.
Combine the power of JSM and Confluence on your sites by adding Request Type links to your Confluence pages. This makes it easier for your users to create tickets straight from the knowledge base section of your site. For example, if a user reads a knowledge base article about your data storage practises and has further questions, they can easily create a request and then get back to browsing the rest of the knowledge base.
Step 8: Customise Confluence pages and blog posts
Available when you use Refined for Confluence.
Use Space Settings to further improve your site’s user experience:
If your site only features short pages, you can disable the estimated read time for a cleaner look.
On the other hand, you can help users navigate long pages by adding a table of contents, which lists all headings on a page and moves along with the user as they scroll down the page.
If your space contains many pages, help users navigate it by adding a search field to the space’s left-hand side menu.
You have full control over the settings of each space: use global space settings to decide the default look of your spaces, and customise specific spaces with custom space settings.
Step 9: Grant admin permissions for streamlined collaboration
Jira/Confluence administrators often aren’t the ones in charge of creating and maintaining the content that lives on their Refined sites. With this in mind, your can delegate Refined administrator permissions to any Jira/Confluence user in your organisation, regardless of their Jira/Confluence permissions.
Step 10: Add a cookie dialog
If you need to, add a Cookie Dialog to help users understand what kind of cookies you want to collect, and why you want to do so. You can create a custom dialog for each of your sites to comply with your organisation’s policies and with laws such as GDPR and CCPA.
Step 11: Keep your content up to date and relevant
Building the help site is just the start - keep fine-tuning it to make sure the content stays relevant:
Do you often receive tickets on a topic, even though that information can be found on your site? This may indicate that the relevant page is hard to find. The promoted search results functionality lets you place a page at the top of search results when a user looks for specific search terms.
Gather feedback from logged-in users to improve your site (available when you use Refined for Confluence). Use Space Settings to enable a Give Feedback button on Confluence pages and blog posts.
Communicate important information to your users by adding an announcement banner to the top of your site. For example, a banner can inform users of scheduled maintenance.
What will you build next?
Your Refined subscription includes an unlimited number of sites. Build an intranet for employees, a documentation site for customers, and a portal for your partner network—all from the same Confluence and Jira instances.
We’re always happy to help if you have any questions: reach out to support.