Support for Atlassian Server Products is ending in February 2024. Consider migrating to Survey and Vote Macros’ Data Center version. Contact our support team if you have any questions.

Overview

Survey and Vote Macros contain two different macros that can be used to gather information from your customers or colleagues.

Survey macro allows you to offer a list of questions or topics that can then be ranked.

Vote macro is great for offering a set of distinct choices. Voters can then select one option.

Results are displayed in a summary and can be exported to a CSV.

Both macros can be locked by page editors or custom groups so that the results can be finalized.

Features

Gather information from customers, colleagues, and your user-base by offering choices that can be ranked (survey), or a one-choice-one vote style ballot (vote).
Customize macros to allow or disallow changing of votes
Lock completed surveys or vote so that the results can be finalized
Export survey results to a CSV file
Allow a survey to be restarted by clearing all data (Note: this cannot be undone)
Control which users or groups can vote or see results. For surveys, control which users or groups can manage surveys.
Surveys have an optional condensed view which both takes up less space and hides commenting features.
Configure ranking choices in surveys
Show lists of voters who have (or haven't) voted yet.

Get Survey and Vote

Get Survey and Vote from the Atlassian Marketplace!

Table of Contents

Survey macro

Survey macro allows you to offer a list of questions or topics that can then be ranked and commented on.

In the editor, choose Survey macro from the list of macros. (Or type {Survey to select it directly.)
Survey macro has many optional configuration parameters. To configure them, click on the body of the macro, and select the Edit button.
1. Title - Recommended - The survey macro does not require a title, but the Actions dropdown menu will not be displayed without it.
2. Additional options are detailed below in Fields.
3. Click Save
Back in the main editor and within the body of the macro, configure the questions/options you wish users to rank/comment on:
The format of each question is "title - description" and the description is optional. Separate each question with a newline. These questions will render with 5 choices to rank the user's response. By default, 5 is outstanding and 1 is unsatisfactory. You can add custom responses by editing the macro's Fields.
Publish the page.
You should now see your survey as configured. After voting you will see the Summary which is rendered at the top of the survey by default. (For more details on who sees the results summary table, see Permissions.)

Vote Macro

Vote macro is great for offering a set of distinct choices. Voters can then select one option.

In the editor, choose Vote macro from the list of macros. (Or type {Vote to select it directly.)
The Macro editor will automatically be launched because the title parameter is required. Vote macro also has many optional configuration parameters. If you decide to update them in the future, simply edit the page, click on the body of the macro, and select the Edit button.
1. Title - Required
2. Additional options are detailed below in Fields.
3. Click Save
Back in the main editor and within the body of the macro, configure the options you wish users to choose between. Separate each choice with a newline:
Publish the page.
You should now see your vote macro as configured:

Usage

Information on interacting with the macros in Page View mode.

Voting

For Vote macro and the default view of Survey macro, votes can be triggered by clicking a selection in the Your Vote column of the macro:

The Condensed view of the survey macro is more like a grid:

Actions Dropdown

In Survey macros with titles, survey managers will have an Actions dropdown which will offer Export, Clear all Vote, and Lock/Unlock options directly from the Page View.

Link to a Macro or Survey Question

The titles of Vote and Survey macros, and the Questions in the default view of a Survey macro are clickable. If you click a question header, or a macro title, a link to that spot will be copied to your clipboard:

Permissions

Permission	Description	Default
Vote	Who can vote? To change this setting update either one of these parameters: List of Voters List of Voter Groups	Page Viewers (logged in only)
View Results	Who can see the results summary table? To change this setting update either one of these parameters: List of Result Viewers List of Result Viewer Groups	Page Viewers
Edit	Who can edit macro parameters in the macro editor?	Page Editors
Export Survey	Who can export a survey? In order to export a survey, viewers must have: Attach Files space permissions To restrict these functions to a list of users or groups, update either one of these parameters: List of Managers List of Manager Groups List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functions	Page Viewers with Attach File permissions Export can only be accessed if Survey has a title
Lock/Unlock	Who can Lock or Unlock a macro? Lock/Unlock can be accessed in two places: The macro editor - Access to lock/unlock through the macro editor cannot be restricted beyond page editor permissions. For Survey macros with titles: the Actions dropdown To restrict visibility of the Actions dropdown to a list of users or groups, update either one of these parameters: List of Managers List of Manager Groups List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functions	Page Editors
Clear all Votes	Who can clear all vote data from a survey macro? To restrict these functions to a list of users or groups, update either one of these parameters: List of Managers List of Manager Groups List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functions	Page Viewers Clear all Votes can only be accessed if Survey has a title

Fields

Configurable parameters can be updated in the macro editor: Edit the page, click the macro you wish to update, then click the Edit button to launch the Macro editor.

Survey/Vote columns:

If checked, indicates availability in either/both Survey or Vote macros

If crossed out, indicates field is not available for either Survey or Vote macro, depending on the column

Required - Indicates this is a required field for that macro

Field	Default	Vote	Description
Survey/Ballot Title	none	Required	Currently, in the Survey macro, the title is optional but the Actions dropdown will not be available if the title is not configured. Titles must be unique across multiple uses of the macros on the same page. Failure to maintain unique titles may result in unexpected behavior. In the future, surveys without titles may not be supported.
HTML header level for title	2		The HTML header level of the title. 1 for h2, 2 for h2, etc. 0 renders as regular text, and will not show up in the TOC macro that uses HTML headers for TOC items.
Override default choices	5-Outstanding, 4-More Than Satisfactory, 3-Satisfactory, 2-Less Than Satisfactory, 1-Unsatisfactory		Surveys only. This is a comma-separated list of choices that will override the defaults. Each choice must indicate a number value and name, separated by a hyphen. Example: 5-Best The numerical part should be in ascending OR descending order. You must also set the "Value of the last choice" and "Iteration step" fields to match. For example: to use the order 1, 2, 3, 4, 5 instead of 5, 4, 3, 2, 1 Use Iteration step: -1 and "Value of the last choice": 5. The default order of 5, 4, 3, 2, 1 uses an Iteration step of 1 and a "Value of the last choice" of 1.
Changeable votes	false		If true this will allow the users to change their responses until the survey is locked. Recommended, as this will improve voter experience: (No one likes accidentally clicking the wrong choice and not being able to change it.)
Summary location	Top		Surveys only. Where the location of the results summary table will appear. Top: Above the choices Bottom: Below the choices None: No results displayed!
Allow/Show comments	Survey: true Vote: false		Allow users to comment on choices
Value of the last choice	1		Surveys only If you have updated Override defaults choices, make certain this field matches that configuration. Example: for the default series of choices with numerical values: 5,4,3,2,1, the Value of the Last Choice should be set to: 1
Iteration step	1		Surveys only If you have updated Override defaults choices, make certain this field matches that configuration. Examples: Default order 5, 4, 3, 2, 1 uses an Iteration step of 1 For the alternative order 1, 2, 3, 4, 5 Set the Iteration step to -1 The purpose of iteration step is to support calculation for the summary average numbers. As the first options in surveys usually are the highest priority the calculation is reversed.
List of manager groups	all groups		Surveys only A comma-separated list of GROUPS who are allowed to manage survey operations (exporting, locking, resetting). See Permissions for more details.
List of managers	all users		Surveys only A comma-separated list of USERS who are allowed to manage survey operations (exporting, locking, resetting). See Permissions for more details.
List of voter groups	all groups		This is a comma-separated list of GROUPS who are allowed to cast a vote. See Permissions for more details.
List of voters	all users		This is a comma-separated list of USERS who are allowed to cast a vote. See Permissions for more details.
List of result viewer groups	all groups		This is a comma-separated list of GROUPS who are allowed to see the summary table results. See Permissions for more details.
List of result viewers	all users		This is a comma-separated list of USERS who are allowed to see the summary table results. See Permissions for more details.
Always show results	false		Show results immediately, ignoring the list of result viewers and the need to have voted first.
Show list of users who voted	false		Shows the list of users who have voted.
Pending voters	false		Show the list of users who still need to vote. Requirement: either one of these must be set in order for Pending voters to be displayed: List of Voters List of Voter Groups
Username style	plain login name		When users are listed (pending voters list, show list of users who voted, commenting interface, etc), they can be rendered in one of 4 ways: plain login name - This is just the username of the user. Example: asmith linked login name - This is the username, but linked to their profile. plain user name - This is the full name of the user. Example: Alice Smith linked user name - This is the full name of the user, but also linked to their profile. Recommended
Email delimiter	,		Some features offer email buttons. Example: pending voters will provide an email button to facilitate reminding users that haven't voted yet. Some email clients will handle different delimiters more gracefully than others. The default is comma: `,` Outlook may behave better with semi-colon, so if you're organization requires the use of Outlook for internal emails, configure this field to semi-colon: `;`
Condensed view	false		Surveys only Each question is one row of a table. Many other features are disabled including comments, list of voted users and statistics
Locked	false		Locks the macro, and no further votes may be submitted. For survey macros, Clear all Votes is not available when the survey is locked. Locking can be undone at any time. Either uncheck the Locked parameter in the macro editor. Or, for surveys with titles, survey managers will be allowed to Lock or Unlock the survey from the Actions dropdown. See Permissions for more details.

Database Persistence and Migration

These details are for admins who need to know where the data is for this plugin because they are migrating their space or pages from one instance to another.

The global settings, as configured by an admin user in the "Survey and Vote" admin tool, are persisted as a CLOB of JSON in the database table AO_ECDDDB_CONFIGURATION_DAO. This data is for global admin settings and is scoped to your entire Confluence instance. It is not per-space.
- There are only a few settings so the easiest approach for migration is probably to set the settings to whatever you want on the new instance if you are not migrating the AO_ECDDDB_CONFIGURATION_DAO table in your database.
The definition/structure of a survey/vote macro (the questions and/or choices) are in the macro parameters, which are in the Confluence Storage Format for a page.
- Therefore, there is no additional migration necessary for survey/vote definitions other than migrating the page itself.
Votes and comments are persisted using Confluence content properties and are scoped to the page that the survey/vote macro is on. The data can be found in the OS_PROPERTYENTRY table with the ENTITY_ID column being the ID of the page that the macro is on and the ENTITY_KEY being a string that starts with "vote." or "survey."
- Confluence migrates the values in the OS_PROPERTYENTRY table when you migrate a page.

Migrate to Polls for Confluence cloud:

You can now migrate to Polls for Confluence cloud easily.

On migration, all Vote macros are converted to polls of type Choice or Regular, and Survey macros to polls of type Survey. The macro conversion happens when the page with the macro(s) is loaded in cloud for the first time. After the migration and loading of pages is completed, you can view the macros in the polls list under Polls Administration (app configuration) with type "Regular" or "Survey", and can perform actions with certain limitations.

Though all macros on all pages are migrated to the cloud, it is recommended that administrators look through the pages to ensure there are no errors after migration. Refer to the Polls for Confluence Migration guide to understand the migration.

Survey and Vote

User Guide