Survey & Vote Server - User Guide

Overview

Survey and Vote Macros contains 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 a 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. 


Survey macro

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

  1. In the editor, choose Survey macro from the list of macros. (Or type {Survey to select it directly.)
  2. 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
  3. 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.
  4. Publish the page.
  5. 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.

  1. In the editor, choose Vote macro from the list of macros. (Or type {Vote to select it directly.)
  2. 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
  3. 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:
  4. Publish the page.
  5. 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


PermissionDescriptionDefault
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
EditWho 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

(warning) List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functions

Page Viewers with Attach File permissions

(warning) 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:

  1. The macro editor -  Access to lock/unlock through the macro editor cannot be restricted beyond page editor permissions.
  2. 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

(warning) 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

(warning) List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functions

Page Viewers

(warning) 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:

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

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

(star) Required - Indicates this is a required field for that macro

FieldDefaultSurveyVoteDescription
Survey/Ballot Titlenone(tick)

(tick)

(star) Required

Currently, in the Survey macro, the title is optional but the Actions dropdown will not be available if the title is not configured.

(warning) 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 title2(tick)(tick)

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 choices5-Outstanding, 4-More Than Satisfactory, 3-Satisfactory, 2-Less Than Satisfactory, 1-Unsatisfactory(tick)(error)

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 votesfalse(tick)(tick)

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 locationTop(tick)(error)

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

(tick)(tick)Allow users to comment on choices
Value of the last choice1(tick)(error)

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 step1(tick)(error)

Surveys only

If you have updated Override defaults choices, make certain this field matches that configuration.

Examples:

  1. Default order
    5, 4, 3, 2, 1 uses an Iteration step of 1
  2. 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 groupsall groups(tick)(error)

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 managersall users(tick)(error)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 groupsall groups(tick)(tick)This is a comma-separated list of GROUPS who are allowed to cast a vote. See Permissions for more details.
List of votersall users(tick)(tick)This is a comma-separated list of USERS who are allowed to cast a vote. See Permissions for more details.
List of result viewer groupsall groups(tick)(tick)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 viewersall users(tick)(tick)This is a comma-separated list of USERS who are allowed to see the summary table results. See Permissions for more details.
Always show resultsfalse(tick)(tick)Show results immediately, ignoring the list of result viewers and the need to have voted first.
Show list of users who votedfalse(tick)(tick)Shows the list of users who have voted.
Pending votersfalse(tick)(tick)

Show the list of users who still need to vote.

(warning) Requirement: either one of these must be set in order for Pending voters to be displayed:

  • List of Voters
  • List of Voter Groups
Username styleplain login name(tick)(tick)

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:

  1. plain login name - This is just the username of the user. Example: asmith
  2. linked login name - This is the username, but linked to their profile.
  3. plain user name - This is the full name of the user. Example: Alice Smith
  4. linked user name - This is the full name of the user, but also linked to their profile. Recommended
Email delimiter,(tick)(tick)

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 viewfalse(tick)(error)

Surveys only

Each question is one row of a table. Many other features are disabled including comments, list of voted users and statistics

Lockedfalse(tick)(tick)

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.