Survey & Vote Server and Data Center - 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.
- 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.
- Title - Recommended - The survey macro does not require a title, but the Actions dropdown menu will not be displayed without it.
- Additional options are detailed below in Fields.
- Click Save
- Title - Recommended - The survey macro does not require a title, but the Actions dropdown menu will not be displayed without it.
- 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.
- Title - Required
- Additional options are detailed below in Fields.
- Click Save
- Title - Required
- 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?
| Page Viewers (logged in only) |
| View Results | Who can see the results summary table? To change this setting update either one of these parameters:
| 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:
To restrict these functions to a list of users or groups, update either one of these parameters:
| Page Viewers with Attach File permissions
|
| Lock/Unlock | Who can Lock or Unlock a macro? Lock/Unlock can be accessed in two places:
To restrict visibility of the Actions dropdown to a list of users or groups, update either one of these parameters:
| 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:
| Page Viewers
|
List of Managers/Manager Groups affects: Export, Lock/Unlock, and Clear all Votes functionsFields
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 | Survey | Vote | Description |
|---|---|---|---|---|
| Survey/Ballot Title | none | |
| Currently, in the Survey macro, the title is optional but the Actions dropdown will not be available if the title is not configured.
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
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:
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 |
| 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.
|
| 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:
|
| 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. 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.
Related Articles
General Articles