Smart Questions and Answers for Confluence Cloud

This is the documentation for the Cloud version of Smart Questions and Answers. The documentation of the Server / Data Center version is here.

 

What is it?

The Smart Questions and Answers plug-in brings flexible question and answer functionality to Confluence Cloud. Unlike the alternatives this app uses pages as questions. This approach allows you to use all features of Confluence (including all your plug-ins) to be used when raising questions. Furthermore it allows you to define your own template for questions.

In case you want to know what has been changed in the past: https://purde-software.atlassian.net/wiki/spaces/PLUG/pages/2120548374

Getting started

Understanding the idea

Smart Questions and Answers uses normal Confluence pages as questions. Unlike the server version of this app comments are not used as answers however they shown separately on each question page.

A topic is a page holding the Smart QA question overview macro. The child pages of that topic page are the questions. Due to this setup you can define as many topics as you like even in a single space. With the permission system of Confluence you can easily protect certain topics.

Creating you first topic

The easiest way to create a new topic is to navigate to the space in which you would like to create the topic and click on the Questions icon in the side bar:

The side bar

The page which opens then lists all accessible topics in the space and the instance and allow all users with space administration permissions to create a new question topic using the “Create a new topic” button.

Topic overview

The dialog box which opens explains the way how to manually create a topic (as you already learned by simply adding the Smart QA question overview macro to any page) or you select a parent page in this dialog and click “Create from template”. The app will now create a draft page which you can modify to your needs, save it and you are all set.

Configuring a topic

Smart Questions and Answers allows you to configure each topic individually with the parameters of the Smart QA question overview macro which is embedded in your topic page.

Configuring a question overview

The following parameters are configurable:

Overview tab

  • Page size: The number of results shown on one overview page.

  • Initial filter: The initial filter (when you open the topic page) to apply.

  • Initial sort: The initial sorting to apply.

  • Statistics Show a basic statistic (number of questions, answers etc.) below the label list.

  • User-ranking: Show a user ranking either based on contributions or a more complex system.

Situation

Points given when ranking is based on contributions

Points given when ranking is based on the “more complex system”

Situation

Points given when ranking is based on contributions

Points given when ranking is based on the “more complex system”

User raises a question

1

-

User gives an answer

2

1

User provided an answer which has been accepted by the question owner

-

5

User provided an answer which has been votes up by a user

-

2

User provided an answer which has been voted doen by a user

-

-1

Questions tab

  • Allow down-vote: allow down-voting of answers

  • Exclude words: a list of comma separated words which is excluded in the search for similar questions.

  • Score cut off: in case you see to many “similar questions” which are not similar try to increase the value such that those results are not shown any more.

Question template tab

  • Question template: select the Smart QA default template for new questions or any other global of space template.

  • Extract after: in case you have a template which contains content before the real questions you can define an expression here. All text prior to this expression (including the expression) is removed when shoring the question extract in the overview page.

  • Create new questions as full width page: when checked new questions are created as full width pages.

Permissions tab

  • Content managers: a list of persons having content manager permissions. Content managers can accept answers on behalf of the owner, can remove answers or comments and can view and delete other persons notifications.

  • Allowed to ask: a list of Confluence user groups allowed to ask questions.Please note that this is only a very week protection. Smart Questions and Answers just removes the “Ask question” button.

  • Allowed to respond: a list of Confluence user groups allowed to respond on questions.

Ensure content manager permissions

  • Content managers should have the permission to delete Answers, Notifications and Comments on the space level. Otherwise some delete actions might fail.

  • We recommend restricting the edit permissions of a topic page to the content managers. Otherwise other people could make themselves content managers.

Notifications tab

  • Send page comments via the channels: if selected page comments (in our case comments to questions) are also send via the notification channels defined by you.
    In general we do not recommend using page (question) comments.

  • General notifications by email: those notifications are sent out by email regardless of any notification channel you define in the corresponding dialog. Please note that those notification apply to all users - no user can opt-out.

  • Notification templates: you can define your message templates as you like including the placeholders listed at the bottom of the tab.

Working with the overview

The image below shows the output of the Smart QA question overview macro.

Question overview

We hope that the UI is self explaining. In case it is not some hints:

  • The title of the page (here QM questions) is the topic.

  • Search within this topic will search for the expression in questions and answers.
    Please note that the search is a little different to the Advanced Confluence search. In case you type term1 term2 the search will try to find all questions/answers which contain both terms (term1 and term2). In case you want to search for questions/answers containing term1 or term2 type term1 OR term2.

  • When you click on a label like “audit” only questions containing this label are shown.

  • The cross symbol will reset the search.

  • The “Ask question” button is used to create new questions.

  • Use the eye symbol to manage notifications (next release).

  • The line “All”, “Answered”, … are the filters you can apply.

  • In the sorting dropdown you can select how your questions should be sorted in the overview.

  • The used labels section on the right shows all labels used in this topic. When you click on a label only questions with this label are displayed.

Working with notifications channels

In the Smart QA question overview macro you can define “General notifications by mail” which work independent of any channel defined here.

When clicking on the eye symbol right of the “Ask question” button a dialog opens which allows you add or remove your notification channels or, in case you are a content manager (see above under Permissions tab), also delete other notifications. Currently Smart Questions and Answers supports the following notifications:

  • Slack

  • Microsoft Teams (via a webhook)

  • Google Chat (via a webhook)

  • Email to your personal mail account

Manage notifications dialog

All notification channels will notify on new questions and answers (an email notification however is not send out for to you for your own questions and answers). When setting up a notification you can decide whether you want to receive a notification for all questions and answers or only those which contain at least one of the defined labels (in the example above Andreas Purde and QM Team only receive notifications in case the question contains the audit label).

No view permission = no notification

For security reasons no notification is sent out in case the creator of a notification does not have the permission to view the content. Please keep this in mind in case a colleague leaves the company who created a Slack or Teams notification.

Private channels in Slack

In case you want to connect to private channels in Slack you have to connect the Smart Q&A app to your private channel before you connect to the channel in Slack:

Step

Image

Description

Step

Image

Description

1

Click on “Connect an app”

2

Add the Smart Q&A app to your private channel

Configuring a Microsoft Teams webhook

In order to get notifications to Microsoft Teams you have to configure a webhook as explained here for example and insert the webhook URL into the notification.

Configuring a Google Chat webhook

In order to get notifications to Google Chat you have to configure a webhook as explained here. You have to copy the webhook URL into the notification.

Please note that you need a paid Google Workspace account to create a webhook as explained here.

Working with questions and their answers

The question and its answers

As questions are normal Confluence pages there is not much to say apart from the fact that a question page needs to embed at least the Smart QA answer container macro. Otherwise there won’t be any answers. Embedding the Smart QA side container is optional but allows you to show some useful navigation links as well as similar questions.

The default template contains both containers.

Compared to Confluence Server and Data Center the interaction of an app with Confluence Cloud is very limited. We simply can’t override comments to be answers.

The answer section looks as follows (here including one answer):

Answer section

You can vote up or down (if configured) answers and (in case you are the owner of a question or content manager) accept an answer. You can also comment on answers.

The answer editor

General information

The editor for answers is not the current Confluence Cloud editor but the Tiny editor which you might still know from previous Confluence Cloud versions and the Server version. It contains most features you would expect from an editor and the following additional ones.

Use the link symbol to link to web or Confluence content (e.g. pages or attachments) and the image icon to embed web or Confluence images.

Insert code snippets

Use the code snippet symbol to insert code snippets. The app supports syntax highlighting for various languages.

Mentions

Just type @ and keep on typing until you find the name you are searching for.

You need to type at least one letter after the @ sign before the search starts.

Using mentions

Creating your own question template

In case you want to show up questions in your company’s look and feel just create your own template for questions. Please insert at least the Smart QA answer container macro to show the answers and optionally the Smart QA side container macro into the template to show the links and similar questions. Once you have created your template select in the Smart QA question overview macro.

Other things to know

Cloud apps have some specialties which we wood like to highlight here:

  • We store answers and notifications as custom content within your Confluence Cloud instance. We do not hold any data on our servers.

  • We store some properties (e.g. number of answers, view count) as content properties in your Confluence Cloud instance. Again we do not hold any data on our servers.

  • Custom content and content properties follow regular Confluence permissions. However this also means that technically advanced users might misuse this fact and e.g. manipulate and answer. Yes, it will be traceable but an app can’t hinder this.

Need help?

Frequent support cases and peculiarities

Observation

Explanation

Observation

Explanation

My new question does not show up in the overview right away.

The app uses Confluence search to find questions. The search index however needs some time (based on our experience up to 30 seconds, sometimes even more) to catch changes including new questions.

Solution: perform a reload after approx. 30 seconds.

The pagination sections shows strange results like “showing result 0 to 0 of 1”

The app uses Confluence search endpoints to find questions. To get the questions and the overall count of matching questions we need to perform two search requests which might be handled by different nodes of Confluence Cloud. Those kind of glitches happen because one node already knows e.g. the presence of a new question while the other one doesn’t.

Solution: perform a reload after approx. 30 seconds.

I liked a question but this is not reflected in the overview.

The app extracts likes when opening a question and closing it by navigating somewhere else. In case you close the tab however no extraction happens.

Solution: open the question again to start the like extraction.

The advanced search contains a Questions type. However no results are returned.

The app uses the Questions type only to show the questions icon in the side bar (this was needed as the described method to show an icon in the side bar is not working as described). As questions are pages there is no real Questions type.

Solution: ignore the Questions type. It will be removed once Atlassian solved the bug.

Getting support

Please use our ticketing system to create a support ticket regardless whether you found a bug, have a feature request or questions.