Smart Questions and Answers for Confluence Cloud

What is it?

The Smart Questions and Answers app 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 apps) 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: Smart Questions and Answers change log

Legal and policy documents

The following legal documents apply for all of our apps:

• End user license agreement (EULA)

• Source code license agreement

• Service level agreement

• Privacy policy

• Cybersecurity policy

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 are 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.

Ensure proper permissions

As it is NOT ensured that Confluence adds the necessary space permissions to create Answers, Comments to Answers and Notifications you should check that the intended users/groups (not necessarily the app) have the necessary permissions.

Example of a permission set

Open

 

Configure the app

In the app’s configuration screen (reachable via Manage Apps | Smart Questions and Answers | Configure) you can change the following settings:

• Define user groups to which are allowed to use the “Create a new topic” button in the topic overview

• Configure the appearance of the “All questions” view (reachable via the sidebar).

• Define a custom SMTP server for notifications

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 sidebar:

Open

The sidebar

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

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

Basic configuration

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.

Overview tab

• Look and feel: Select a look and feel option of the overview

• 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.

Questions tab

• Show accepted answer before all others: show the accepted answer before all other answers regardless of the answer’s votes

• Voting: select how voting of answers shall happen

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

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

• AI answer support EXPERIMENTAL : You can define that users get the possibility to use an AI to suggest an answer to the given question.
  Please consider potential data privacy concerns before using this feature as the service provider will get the question title and body.

Question template tab

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

• Extract cell: the cell of the question template which contains the actual question text (start counting at the top from left to right). Please note that also a full width section is counted as one cell even though Confluence does not draw a border around it.

• 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 showing the question extract in the overview page.

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

Please check this section below on defining templates

Permissions tab

• Content managers: a list of persons having content manager permissions. Content managers have the same permissions as the creator of a question and can additionally lock and feature questions.

• Allowed to ask: a list of Confluence user groups allowed to ask questions.
  Please note that this is only a very weak 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.

• Restrict the edit permission of a question to the creator: restrict the edit permission of newly created questions to the creator of the question. Please note that the Smart QA app must have the permission to edit content in the space and to set restrictions.

Notifications tab

• Send page comments via the channels: if selected, page comments (in our case comments to questions) are also sent 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 notifications 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. In case you do not want receive certain notifications please simply delete the entry in the input field.

Customization tab

The customization tab allows you some changes to the look and feel of UI (overview and questions). You can use one of the following commands (one per line):

Hints

• Please use your browser's DOM inspector to find the class names or IDs of the elements you want to change

• Due to security reasons selector, text and value can only contain the following characters: 0-9, a-z, A-Z and the following special characters: .#_-!:

Additional configuration

Page comments - on or off?

We know that some users might have difficulties picking the new answer field in case they want to answer and picking a comment field in case they want to comment on the question. Starting 2021-12-05 Smart Questions and Answers uses a dedicated content type for comments to answers (not questions). This allows you to disable page comments by removing the relevant permission for the space. Please that this has the following side effects:

• You can’t comment on other pages the same space anymore

• Old comments to answers can’t be edited anymore

Working with the overview

The classical overview

The image below shows the output of the Smart QA question overview macro in the classical format:

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

• The title of the page (here Quality management 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.

• 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.

The table like overview

The image below shows the output of the Smart QA question overview macro in the table like format:

The table like overview is a little different from the classical overview. The main differences are:

• The filters are shown in a dropdown not a tab line

• In case you only want to show questions having a certain label please select the label from the “Label” dropdown

• The last activity is shown in minutes (m), hours (h) or weeks (w) from the current date - older dates are shown in a short format like Jan-22

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

All notification channels will notify on new questions and answers (an email notification however is not sent 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).

Details for Slack notifications

Connecting to Slack (step-by-step)

Receiving notifications in private channels

To receive notifications in Slack private channels you must integrate the Smart Questions and Answers Slack app into the private channel. Only after this action you will find the private channel in the channel selection list.

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.

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

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.

Insert links and images

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.

You can also upload attachments here.

Insert Confluence Content (pages or excerpts) or iFrames

Use this icon to embed Confluence content (an entire page or an excerpt) or an iFrame.

To embed an iFrame use the “Web content” tab, for a page or excerpt includes the “Confluence content” tab. Use @page as excerpt name in case you want to include the entire page.

Please note that the embedding of Confluence content has its limits: the look and feel is slightly different, images might not have the correct size, dynamic content macros are not embedded etc. This is unfortunately outside of our control.

Pasting images

You can paste images into the editor. Please note that those images are currently directly embedded in the answer rather than uploaded as attachment.

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.

Locking and featuring questions

The defined content managers 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.

It might take up to 45 seconds (sometimes even longer) before Confluence updates its index and a featured questions really shows up before all other ones.

Advanced use cases

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.

1. Create a page template as usual either globally or in the space - for details refer to Atlassian’s documentation.

2. 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.

3. Once you have created your template select it in the Smart QA question overview macro. In case the question body is not in the first cell please ensure to select to proper cell which contains the question (this is needed for the question extract in the overview and the AI support).

Cell counting example for the standard template

Creating a hierarchical topic tree

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

Please refer to this page for details.

Additional view on a topic elsewhere

You can use Confluence’s page include macro to embed a view on a topic elsewhere.

Migrating from Server to Cloud

In case you are migrating from Server or Data Center to Cloud please follow this guidance. We are sorry that this process requires a little bit of manual work.

Other things to know

Cloud apps have some specialties which we would 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

Getting support

Please use our ticketing system to create a support ticket regardless of whether you found a bug, have a feature request or questions. You can email us using support@purde.de.