/
Smart Questions and Answers for Confluence Server and Data Center

Smart Questions and Answers for Confluence Server and Data Center

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.

Legal and policy documents

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.

  • Template for new questions: you can specify any template or blueprint available in the current space as template for a new questions. The default is "Smart QA default" which is basically an empty page with some instructional text. Please refer to the section [Using templates](https://bitbucket.org/apurde/simple-qa/wiki/Home#markdown-header-using-templates) below to learn how to correctly set-up a template.

  • Start question extract after: in case you are using templates it might be useful to specify a string after which the extract shown in the overview starts. Please refer to the section [Using templates](https://bitbucket.org/apurde/simple-qa/wiki/Home#markdown-header-using-templates) below to get more details.

  • Approval reminder: please enter the number of hours (e.g. 36) after which the author of a question is reminded to check whether his/her question has been answered. The hours count from the last activity on the question. In case you don't want a reminder leave the field empty. Please note that the reminder is only sent once in case there are no further activities after the last reminder. The check whether a reminder is due is triggered every time the question is viewed and whenever the reminder task is executed (default: once every day).

  • Always notify asker: when set the asker (creator of a question) will always be notified about new responses regardless of any notification channel defined.

  • Custom instructional message title: you can override the default instructional message title by providing your title here.

  • Custom instructional message body: you can override the default instructional message body by providing your body in [Confluence storage format]https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html) here.

You can customize all messages send by the app, including notifications about new questions and answers. The description below each field names all placeholders you can use.

  • Exclude words: comma-separated list of words to exclude when searching for similar questions. Define such words might help to narrow down the search.

  • Special features: you may enter comma-separated special features here. Special features are features outside the main features of the app. Currently the following special features exist:

    • hide-ask-button: hide the "Ask Question" button

    • hide-watch-menu: hide the watch-topic link

    • hide-asker: hide the person who asked in the overview

    • bypass-edit-restriction: allow users to create questions which do not have a add/edit permission in the space (please open a support ticket to get the necessary details)

    • similarQuestionsBasedOnLabelsOnly: determine similar questions based on labels only

    • allow-private-questions: allow the asker to create a private question and make it public later. This might be helpful in case you want to answer your own question right away.

    • skipWatcherNotification: do not notify watchers of a question page about new answers. This can be useful in case you want to avoid double notification by the app and Confluence itself.

    • like-container-after-title: show the like section right below the title not under the question

    • use-like-icons: use like icons rather rather then chevrons to up- and down-voting of answers

    • hide-page-tree: hide all questions except the current one in the page tree on the left

    • sort-labels-by-name: sort the labels by name rather than relevance in the label overview

    • restrict-to-author: restrict the edit permission of a question page to the creator of a question

    • approved-answer-first: show the approved answer before all other answers

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:

Don’t forget to let an admin allow the connection in Confluence’s Allowlist

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.

Don’t forget to let an admin allow the connection in Confluence’s Allowlist

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

Define your own template for questions

Define your own question template

You can use any template or blueprint available in the current space for a new question. Per default Smart QA uses a very simple template for a new question (called "Smart QA default" in the selection list).

As Confluence does not export comments (or answers in our case) to e.g. PDF you have to include the Smart QA Export View macro at the end of your template in case you want answers to be exported. You have two possibilities to do so:

  1. Include it via the macro browser.

  2. (recommended) Use a source editor (e.g. Confluence Source Editor). We recommend this approach as you can hide the Smart QA Export View macro in the editor and avoid user confusion. To do so please insert the following lines at the end of your template using a source editor:

<p class="simple-qa-hide"> <ac:structured-macro ac:name="simple-qa-export-view" ac:schema-version="1"/> </p>

Not all blueprints respect the title you specified when asking a new question. You might need to type it again in the dialog.

Define at which point the question extract should start

When using templates you will most likely run into a different challenge. Per default the Smart QA Overview macro shows an excerpt of the question which starts at the beginning of the page. With the parameter "Start question extract after" you can specify a string after which the extract starts. In the example of a template below you should enter "Details" under "Start question extract after".

Different position of the boxes (navigation links and similar questions) needed?

In case you need the boxes for similar questions and the links to appear at a different location you can create a user macro (no body) with the content below and in include at the desired location of your template.

## @noparams <div class="simple-qa-custom-box-location"></div>

Getting some statistics

The Smart QA statistics macro can be used to show some basic indicators of your questions and answers topic. You have to specify the page holding the Smart QA overview macro (your topic). You can decide whether you want to show the top askers and respondents in the statistics and whether you want to include the topic title in the statistics. Whether you can show the top askers and respondents is configurable on system- and space-level.

The following special features exist:

  • first-level-questions-only: only use first level questions in the statistic (some users use cascaded questions topics and requested this feature)

The Smart QA statistics macro can be embedded in any page including the corresponding topic page holding the overview macro.

Define side content in the "Community style"

In case you are using the "Community style" in the Smart QA Overview macro you can define one or more blocks of side content shown on the right side of the questions. Just include one Smart QA Side Content macro for one block on the same page as the Smart QA Overview macro and put the content in the body of the macro.

Get a list of question topics

Use the Smart QA Topic List macro to get a list of topics.

Get all questions in a space or the entire instance

Use the Smart QA Collection macro to get all questions of the current space or the entire Confluence instance. Please note that you can't raise questions from the Smart QA Collection macro.

Show the collection in community style and add a Smart QA side Content macro with the Smart QA Topic List macro inside the side content to get nice overview of your all your questions.

Prevent isolated pages from being rated as a question

Smart Questions and Answers interprets all pages below a topic page as question. You may exclude isolates pages from being rated as question by setting the label "smart-qa-no-question" on that page.

Using the REST interface

The following table shows all REST endpoints which can be used by you. The topicPageId parameter is the Id of the page holding the the topic (the Smart QA Overview macro).

REST call and type

Description

Example

REST call and type

Description

Example

/rest/simpleqa/1.0/{topicPageId}/forcereminder PUT

Enforce a reminder messages to eventually accept the correct answer to be send out now.

./.

/rest/simpleqa/1.0/addquestion PUT

Add a question including answers/comments to a defined topic. This call is typically used when importing questions from other tools like Confluence Questions. The data payload is of this PUT request is the text representation of the JSON format in the next column. Beside "date" also "dateLong" is supported which takes the date as long value.

{ topicPageId: 20905989, title: "Title of the question", name: "fritz", date: "2019-01-01", body: "<p>Body of the question</p>", answers : [ { name: "sophie", date: "2019-03-01", body: "<p>Answer 1</p>", approved: false, comments : [ { name: "sophie", date: "2019-03-01", body: "<p>Comment to the answer</p>" } ] }, { name: "john", date: "2019-03-02", body: "<p>Answer 2</p>", approved: true, comments : [] } ], comments: [ { name: "sophie", date: "2019-03-01", body: "<p>Comment to the question</p>" } ], labels : [ { name: "test_label" } ] }

/rest/simpleqa/1.0/{topicPageId}/export GET

Export the entire topic (all questions, its answers and top-level-comments and all first-child comments to answers and top-level comments). This REST endpoint is intended for a data migration to Cloud.

You can only export questions for which you have a view permission.

./.

/rest/simpleqa/1.0/{topicPageId}/export2 GET

Same as above but for very large topics which can result in a time out.

This call returns an ID and two links (url to view and download to download) to collect the results once they are ready - please note that the results are deleted once you collected them successfully.

./.

/rest/simpleqa/1.0/exportAll GET

Export all questions of the Confluence instance.

This call returns an ID and two link url to view and download to download) to collect the results once they are ready - please note that the results are deleted once you collected them successfully.

You can only export questions for which you have a view permission.

This call is only suitable for Cloud migration when using Smart Questions and Answers Server/DC 3.11.3 or above

./.

/rest/simpleqa/1.0/{topicPageId}/notification/add PUT

Add a notification for you or another user (if you are a content manager for this topic). The data payload is of this PUT request is the text representation of the JSON format in the next column.

Example 1: add an email notification for user sophie limited to questions holding the audit label.

{ type: "mail", userName: "sophie", labelText: "audit", details: { } }

Example 2: add a MS Teams notification as the current user - no label limitation.

{ type: "teams", labelText: "", details: { title: "All employees", webhook: "https://xyz" } }

Importing from Questions for Confluence

In case you want to import questions from Atlassian's Questions for Confluence please refer to this page.

View a question topic elsewhere

You can view a question topic also elsewhere (e.g. on another page) in your Confluence instance. Just use the page include macro and refer to the topic page.

Create a hierarchical topic tree

Smart Questions and Answers allows the creation of hierarchical or cascaded topics like the following example:

  • Development questions

    • Hardware related questions

    • Software related questions

      • Java questions

      • C# questions

For details please refer to this page.

Migration to Cloud

In case you want to migrate Smart Questions and Answers to Cloud please refer to this page.

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.

Looking for labels? They can now be found in the details panel on the floating action bar.

Related content