Smart Questions and Answers for Confluence Server and Data Center

Owned by Andreas Purde
Last updated: Aug 08, 2023
16 min read

This is the documentation of the Server and Data Center version of Smart Questions and Answers version 3.x.x. The documentation of the Cloud version is here the documentation of version 2.x.x is here.

 

What is it?

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

The following legal documents apply for all of our apps:

Getting started

Understanding the idea

Smart Questions and Answers uses normal Confluence pages as questions and comment as answers.

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.

Configuration

Basic configuration

Smart Questions and Answers has the following parameters which can be configured on the system- and/or space-level.

Settings on the space-level always overwrite the settings on the system-level.

  • Page used for system- or space-wide questions and answers: if you configure a page here a link from the header bar with the title "Questions" will be shown which links to the specified page.

  • Allow nested Smart Questions and Answers topics: if checked users may create their own nested topics on pages as before. When not checked the Smart-QA Overview macro will not render if the page is not the system- or space-wide questions and answers page.

  • Show top askers and respondents: when checked the statistics macro is allowed to show the top-10 askers and respondents. As this might be a workers council concern we decided to allow a disabling here.

Figure: Smart Questions and Answers settings on the space level

Anonymous access

Smart Questions and Answers supports anonymous questions and answers in case open the space and page to the public. Please note that anonymous users can't vote an can't approve an answer. Of course they also don't receive any notifications. Please refer to the Confluence documentation on how to setup public access. You may wan't to consider granting the following for your public space:

  • All - view

  • Pages - add (to ask questions)

  • Comments - add (to give answers)

Due the Confluence's rights management an anonymous user can always change the questions of other other anonymous users

Create your first topic

Include the Smart QA Overview macro on any page with no child pages (why: child pages are questions). When done you will see a search field, a button to create a new question a row of filter tabs and most likely the information that there are no questions (yet).

Figure: UI of the Smart QA Overview macro

Configure your topic

The Smart QA Overview macro has a couple of parameters you can configure. Please note that some of those parameters won't change the overview's behavior or look and feel itself but the way the app handles the questions and answers under this overview.

  • Show label overview: shows all used labels starting with the most frequent one. You can filter for the label by clicking on it or watch/unwatch a label by clicking on the eye-symbol next to it.

  • Community style overview: show the overview in a style comparable to the Atlassian Community.

  • Initial filter and sort: per default Smart Questions and Answers shows all questions in the overview sorted by their last activity. In case you want to change this you can fill this field. To do so please leave the editor and bring the overview in the state you want to have (apply filter, sort and search as needed). Now copy the URL from your browser's address bar and paste it in this field. The field may look something like this: `https://example.com/display/QM/QM+questions?simpleqafilter=simple-qa-filter-all&simpleqasearch=&simpleqasort=0,1&simpleqapage=1`.

  • Allow down-vote: if activated down-voting of an answer is also possible. This option was implemented as some workers councils might not like down-voting.

  • Show similar questions: show similar questions on each question page. Remark: the plug-in identifies similar questions based on used labels and the title of the question compared to other questions (title, question and answers).

  • Show links: when set each question page contains a set of links to show the instructions (see further below) to go back to main topic page and to ask another questions.

  • Show instructions as pop-up: when set instructions are shown as pop-up on each question page explaining how to contribute.

  • Hide create buttons: when set the Confluence own create buttons are hidden on question pages. You may want to activate this in case users are trying to create new questions via those buttons.

  • Alternative position for answers: when set answers may use the space left to the similar questions. This feature is only effective when "Show similar questions" is selected and the width of the browser window is sufficient.

  • Show comments below answers: show comments below answers rather than above them.

  • Content manager: a list of users having additional permissions such as: accepting answer in addition to the creator of a question, switching comments to answers and vice versa and locking questions.

  • User group allowed to ask: leave empty if all users are allowed to ask questions. Otherwise type all user groups allowed to ask as a comma-separated list.

  • User group allowed to respond: leave empty if all users are allowed to respond to a question. Otherwise type all user groups allowed to respond as a comma-separated list.

Working with the overview

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

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

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 (via a webhook)

  • Microsoft Teams (via a webhook)

  • Email to your personal mail account

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.

Configuring a Slack webhook

In contrast to the Cloud version of this app the Server and Data Center version only connects to Slack via webhooks. In order to configure a webhook you have two options:

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.

Working with questions and their answers

Basics

As you already know a question is a regular Confluence page which is enriched (depending on the settings by certain UI elements).

UI element

What the UI element does

UI element

What the UI element does

The navigation links allow a quick navigation to the instructions (which you can customize) to the overview page (main page) and to ask a new question.

 

The section with similar questions allows a quick navigation to questions which are rated similar based on the search results.

The comment section is enriched by UI elements allowing to use comments as answers.

UI element

What the UI element does

UI element

What the UI element does

An answer is enriched by UI elements to vote the answer up and down (if activated). In case you are the owner of the question or a content manager you may also accept the answer.

Below the answer the owner of the answer or any content manager may convert an answer to a comment or vice versa.

Locking and featuring questions

The defined content manager for a topic have the possibility to lock or feature a question. A locked question does not accept further responses, a featured questions always shows up in front of all other questions in the overview. The UI for locking and featuring is located on the question page:

Advanced use cases

Trouble shooting

Frequent support cases

No current ones

Known limitations

The plug-in has the following known limitations:

  • For temporary limitations please refer to the issue tracker.

  • One overview page for one topic: Smart Questions and Answers only allows one overview page for one topic.

  • Confluence mobile view is only partly supported (read only).

  • Due to limitation in the Confluence API Smart Questions and Answers needs at least one user in the confluence-administrators group to extract the likes. In case you are not using the group you may alternative add a user to the group smart-qa-liker-extractor-group. This user should be allowed to view all questions in your instance.

Getting support

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