Skip to end of metadata
Go to start of metadata

Survey Plugin Structure

The Survey plugin stores survey and response data via the Bandana storage mechanism within the Confluence database. Each time a survey is viewed/edited/responded, the data is retrieved from Bandana and the appropriate screen is generated dynamically with this data. Hence, surveys or their responses are not stored as pages within Confluence as the concept of a page does translate to the nature of a survey. Surveys can be embedded into a wiki page via the survey macros. The report views (individual and aggregated) are also generated dynamically and individual charts can be embedded into wiki pages.


Top of page

Global Survey Management

A Global Survey Management screen is presented that allows manipulation of all survey data within the system (not just within a specific space). The Global Survey Management section is accessible from the Administration screen within the Administration section. The following actions can be executed here:

  • Delete All Survey Data – all surveys and all responses in all spaces will be deleted.

Top of page

Creating and Managing Surveys

Surveys are also associated with the space they are created in. The survey listing screen will only display surveys created within that specific space. However, the Global Survey Management operations affect all surveys within the system.

Creating a Survey

The quick steps to creating a survey are:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.






  2. Click on the 'Create' icon (green plus image).
  3. Add a suitable title for the survey.
  4. Add a suitable description for the survey. The description can be used to describe the goal of the survey. At present, the description is only presented in the survey list.
  5. Configure the response options as required.
  6. Add a suitable Completion Message. This message is displayed to the end user once they have completed a survey.
  7. Click the "Create" button to create the survey with the supplied details.
  8. The browser will direct to the Manage Sections screen in order to allow new sections be added to the survey.

You can use wiki markup and macros in the 'title', 'description', and 'completion message' fields

Response Options

The Survey plugin allows configuration of how users can interact with a survey.

End Date

By specifying an End Date, the survey will not accept responses after this date. Users are presented with an appropriate message if they attempt to progress through or submit a response once the End Date has passed.

Limit Responses and Max Responses

By default, there are no limits on how many responses a survey will accept. By enabling Limit Responses, it is possible to specify the number of responses the survey will accept in the Max Responses input box. Users are presented with an appropriate message if they attempt to progress through or submit a response once the maximum number of responses has been received.

Allow Multiple Responses per User

By default, a survey will only accept one response from a specific user. By enabling this option, the survey will allow multiple responses from any user. This option is automatically enabled once a survey is set to accept Anonymous responses.

Anonymous

By default, a survey response records the username of the respondent and date of submission, along with the answer data provided by the respondent. By enabling this option, responses will only record the answer data. Usernames and submission dates are not recorded. Enabling this option will also enable Multiple Responses per User. Once a survey is set to be Anonymous, it is not possible to reset the survey to record/display username and submission date data.

Sections

Along with the survey details, a survey consists of a number of sections. At present, the Survey plugin provides the following section types:

  • Page – surveys consist of at least one page, and each page may contain any number of other section types
  • Text Question – a text input box for the response
  • Single-select Question – a radio style option element for the response
  • Multi-select Question – a check-box style option element for the response
  • Drop-Down Question – a check-box style option element for the response
  • Instructional Section – a text only element for conveying information to the respondent (does not provide any response element)
  • Section Group – groups contain other sections, like Instructional Sections they do not contribute to the responses.

Adding A Section To A Survey

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Manage Sections" icon (cog). Upon creating a new survey, the browser will automatically present this screen also.
  3. Locate the Page or Question Group to which you wish to add the section to.
  4. Select the Section type from the list in the drop-down next to the 'Add Section' button
  5. Click 'Add Section'

Editing a Section

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Manage Sections" icon (cog). Upon creating a new survey, the browser will automatically present this screen also.
  3. Click the "Edit Section" icon associated with the section to be edited.
  4. The section is now editable and all labels, options and validators can be updated.

Configuring Section Types

Sections can be configured either when they are created or by editing the section as described above. Each section type has different configuration options; all sections, with the exception of pages and question groups, have a 'label' field which is often the question text itself.
The label field can contain wiki markup and macros. However, note that all macros must be closed otherwise unexpected errors may occur when displaying the survey.

Text Questions

  1. Add a suitable label for the question. This label is presented to the user as the question.

Single-Select Questions

  1. Add a suitable label for the question. This label is presented to the user as the question.
  2. Add an option within the Options section and click the "Add" button.
  3. Add the appropriate number of options and click the "Save" button to complete the operation.

Multi-Select Questions

  1. Add a suitable label for the question. This label is presented to the user as the question.
  2. Add an option within the Options section and click the "Add" button.
  3. Add the appropriate number of options and click the "Save" button to complete the operation.

Drop-Down-Select Questions

  1. Add a suitable label for the question. This label is presented to the user as the question.
  2. Add an option within the Options section and click the "Add" button.
  3. Add the appropriate number of options and click the "Save" button to complete the operation.

Ordering Options for Single, Multi, and Drop-Down Select Questions Using the icons to the right of each option you can move an option to the top of the list, up one position, down one position, or to the bottom of the list. You can also remove an option by clicking the remove, or trashcan, icon.

Instructional sections

  1. Add an appropriate label for the section. This label will be presented to the respondent with no input element.
  2. Click the "Save" button to complete the operation.

Question Group

  1. You can enter wiki markup you would like to appear before and after the questions in this group. Note you may span macros across the 'before' and 'after' fields, e.g a panel macro can be used thus:
markupBefore
{panel:title=This is a group of questions inside a panel}
markupAfter
{panel}

 

  1. Click the "Save" button to complete the operation.

 

 

You can then add question to the question group, or move existing questions in to it:

Pages

  1. Click the 'Add Page' button at the bottom of the screen

Question Validators

The Survey plugin allows for the specification of validators to be associated with specific questions. These validators are executed when a user attempts to progress through a paged survey or submit a completed response. The validator will return a suitable error message if the answer for a specific question is invalid. The user must reformat the answer in order to progress/submit the survey.
There are currently two types of validator:

  • Required – an answer must be provided for this question
  • Text Length – the text answer must be within a specified length

In order to add a Required validator to a question:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click "Manage Sections" icon (cog).
  3. Click the "Edit Section" icon for the question requiring a validator.
  4. In the Validation section, check the Required checkbox.
  5. Click "Save" to confirm the validator settings.
  6. It is also possible to delete the validator by unchecking the "Required" checkbox and clicking "Save".

Text Length Validator Applicable Question Types Currently only text questions support the Text Length validator. Since all other question types do not permit "free-text" style input text length is not a meaningful criteria. However, there is nothing to exclude question types developed in the future from utilising this validator.
In order to add a Text Length validator to a question:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click "Manage Sections" icon (cog).
  3. Click the "Edit Section" icon for the question requiring a validator.
  4. In the Validation section, check the Text Length checkbox.
  5. Specify appropriate values for the Min and Max length.
  6. Click "Save" to confirm the validator settings.
  7. It is also possible to delete the validator by unchecking the checkbox and saving the section again.

Conditional Criteria for Sections

Conditions can be added to any question type including Question Groups. There are however a few criteria that must be met in order to add a Condition to a question:

  1. Conditions can not be added to any question on the first page of a survey
  2. A Condition can only depend on the answer of Single Select, Multi-Select, and Drop-Down questions
  3. A Condition can only be applied to a question that follows all the questions it depends on (i.e if question D should only be shown if questions A, B, and C have particular answers, then question D must not appear on or before any page containing A, B or C.

Configuring a Condition for a question is easy:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click "Manage Sections" icon (cog).
  3. Click the "Edit Section" icon for the question requiring a validator.
  4. In the Conditionals_ section, select the Question whose answer you wish to depend on.
  5. Click "Get possible values".
  6. Select the answer that will cause this conditional to be true, i.e show the question
  7. Click "Save Condition" to confirm the validator settings.
  8. It is also possible to delete the condition by editing the question and clicking the remove icon next to the condition.

Sorting Questions with Conditionals!Conditionals are not updated during re-ordering of sections or pages, the consequence is that previously valid conditionals now violate one of the criteria for Conditionals listed above. This is indicated by an error message on any question with an invalid conditional. However, you must correct any error messages otherwise unpredictable results and response data may result when taking the survey.

Section Ordering

It is possible to re-order survey sections. Sections can be moved to the top or bottom of the list, up or down one position or to a specific position within the list.

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Manage Sections" icon (cog). Upon creating a new survey, the browser will automatically present this screen also.
  3. To move the section:
    1. Click on the required move icon (top, up, down, bottom) at the right hand side of the question/page or
    2. "Drag and Drop" the question, question group, or page in to the position you desire (this work in the same way drag and drop works on your win/mac desktop)

Copying a Survey

It is possible to create a copy of a survey within the same space as the original survey. This is a complete clone of the original survey, including sections, response options, and status however the responses are not copied as part of this operation.

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Copy Survey" icon (two pages).
  3. Specify a new title for the copy of the survey.
  4. Click the "Copy" button to complete the operation.

Inviting Respondents and Limiting Access

The Survey plugin provides the ability to invite specific users and/or groups to participate in a survey.
It is possible to specify a list of users and groups to be invited to a survey. An email invitation will be sent to all invitees with a link to the survey. The survey invite screen will display the list of invitees, and, for non-anonymous surveys, indicate who has responded to the survey.
The survey invitation screen also allows configuration of access to the survey. It is possible to allow all users access to the survey or only those who have been invited.
In order to invite a user/group to a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Manage Invites" icon (people).
  3. Add the required user names and/or group names of the users/groups that are to be invited to the survey.
  4. Click the "Send Invites" button.
  5. The current list of invited users and groups should be updated with the new invitees. For non-anonymous surveys, the list will indicate if a response is recorded for the invitee.

In order to specify the access level for the survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the "Manage Invites" icon (people).
  3. Select the option "Unrestricted" to allow access to all users. Select the option "By invitation" to limit access to only invited users.
  4. Click the "Update" button to confirm the selection.

Survey Status

A survey can be in a number of states, affecting if users can respond and various informational messages displayed to users if no responses are being accepted.
The current states include:

  • Edit
  • Live
  • Locked
  • Expired
  • In Review
  • Closed
  • Archived

At present, the survey will only accept responses if it is in the Edit or Live states. All other states will not allow a user respond and present an appropriate message as to why the survey is not accepting responses.
The state can be set by editing the survey details. The functionality associated with survey states will be expanded on in future releases.

Export a Survey

It is possible to export a backup of a survey in zipped XML format. The backup contains all survey details and section information. It does not include the responses to the survey.
An export can also be imported into another space.
In order to export a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click on the 'Export Survey' icon for the survey to be exported.
  3. The survey details and section information will be exported in a zipped XML file. The file can be downloaded and saved by clicking on the download link presented in the next screen.

Import a Survey

It is possible to import a previously exported survey into a space. The survey should have been export via the plugin as a zipped XML file. The survey can be imported into the original space from which it came, or it can be imported into any other space.
In order to import a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'Import Survey' icon at the top of the screen.
  3. Provide a suitable title for the survey to be imported.
  4. Select the zipped XML export file in the 'Survey Upload Path' file input.
  5. Click the 'Import' button.
  6. The survey will imported into the system, using the new title specified.

Delete a Survey

In order to delete a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'Delete Survey' icon associated with the survey to be deleted.
  3. A confirmation screen will be displayed, noting how many responses have been received for the survey to be deleted. All survey data (details and sections) including all survey responses for the survey will be deleted. This action cannot be undone.
  4. Click the 'Delete' button to complete the deletion process.

 

Top of page

Viewing and managing response data


Viewing Individual Responses

It is possible to review individual responses to a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'View Individual Responses' icon associated with the survey to be reviewed.
  3. The next screen presents the details of the survey with a list of the individual responses.
  4. An individual response can be reviewed by clicking the 'View Response' icon associated with the response to be reviewed.
  5. Once the response has been reviewed, return to the response list by clicking the 'Return to Responses List' link.

Deleting an Individual Response

It is possible to delete an individual response to a survey:

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'View Individual Responses' icon associated with the survey to be reviewed.
  3. The next screen presents the details of the survey with a list of the individual responses.
  4. An individual response can be deleted by clicking the 'Delete Response' icon associated with the response to be deleted.

Viewing Aggregated Responses

An aggregated view of the responses to a survey can be viewed. Responses to text questions are displayed with aggregate counts for each unique answer supplied. Responses to single and multi-select questions are displayed in pie-chart format with details of each option selected in all responses.

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'View Aggregated Responses' icon associated with the survey to be reviewed.
  3. The aggregate report will be generated and presented on the next screen.

Export Reponses in CSV format

The Survey plugin provides the ability to export responses for a survey in Comma Separated Valuses (CSV) format. This allows for further inspection/report generation/manipulation of the response data in third party CSV/Spreadsheet applications.

  1. Navigate to the 'Manage Surveys' tab within the 'Browse Space' screens.
  2. Click the 'Export CSV Results' icon associated with the survey to be reviewed.
  3. The survey responses will be exported in a zipped CSV file. The file can be downloaded and saved by clicking on the download link presented in the next screen.

The CSV export includes the survey title, space key and time/date of export in the first row. The next row presents all the questions from the survey. Subsequent rows present the user name of the user (in the case of non-anonymous surveys) who responded, followed with the response submitted for each question.


Top of page

Macro Parameters

Simple Survey Macros

These macros output pre-formatted content which does not require further styling, they are useful for quickly and easily displaying Survey's and their results on a wiki page.

{survey-link} Macro

In order to allow users access a survey and complete a response, the survey-link macro can be placed on a page. This macro will be rendered as a link to start the survey:
{survey-link:spaceKey=TST|surveyId=mfl45d4xAPwT2nS|linkText=Survey Link}

Parameter

Required

Description

spaceKey

 

The space key of the space containing the survey to be taken

surveyId

(tick)

The ID of the syrvey to be taken

linkText

 

The text of the link as presented to the user

It is also possible to retrieve this macro markup by clicking on the Generate Survey Link Code icon within the Manage Surveys screen for the required survey. This link will present a pop-up from which the survey-link macro code can be copied and added to a page.

{survey-results} Macro

Rather than viewing the result of the survey through the Manage Surveys interface the survey-results macro allows you to render the results on any wiki page.

Parameter

Required

Default Value

Description

surveyId

(tick)

n/a

the id of the survey to link to. This is available from the 'Manage Surveys' screen.

spaceKey

 

current Space

The space key of the space which contains the survey

{survey-default-view} Macro

Using the {survey-default-view} macro you can display the survey within a wiki page and allow users to input and submit their responses. This macro works even if you have multiple pages within your survey. This macro is equivalent to using several of the more advanced survey layout macros described below and is a convenient method, particularly for single page surveys, of displaying the output on a wiki page while more complex surveys or layouts should use the advanced macros directly.

Parameter

Required

Default Value

Description

surveyId

(tick)

n/a

the id of the survey to link to. This is available from the 'Manage Surveys' screen.

spaceKey

 

current Space

The space key of the space which contains the survey

Advanced Survey Macros

Often the simple macros are more than enough, however sometimes a more control over the formatting of the survey is desired and so the following macros have been provided which allow you far greater control over the layout of the survey and can be used in conjunction with other formatting plugins such as Theme Builder 4 Plugin.

{survey-render} Macro

The survey macro does not output any content itself but is required so that the other macros, such as the {survey-body} and {survey-info} macros, know which survey to display sections and information from.

Parameter

Required

Default Value

Description

surveyId

(tick)

n/a

the id of the survey to link to. This is available from the 'Manage Surveys' screen.

spaceKey

 

current Space

The space key of the space which contains the survey, if no space key is specified the space key of the current page is used.

{survey-info} Macro

The survey-info macro allows various fields of the Survey to be displayed in the wiki page. This macro can be used repeatedly on the page and therefore is useful in generating 'headers' and 'footers' via wiki markup in custom layouts. Note: this macro can only be used inside a {survey} macro.

Parameter

Required

Default Value

Description

default

(tick)

n/a

The information type to display, options are:

  • title – the survey title
  • description – the survey description
  • questionCount – the total number of questions including conditional questions
  • pageCount – the number of pages in the survey
  • currentPage – the current page displayed
  • endDate – the closing date for the survey if one is set

{survey-body} Macro

This macro is required within a {survey} macro as it outputs the questions for the current page. Additional wiki markup can be placed around this macro however it is not possible to inject custom markup around each section at this time. Note: this macro can only be used inside a {survey} macro.

{survey-button} Macro

So that users can progress through the form and submit it, perhaps going back a page to correct a field, several types of button can be displayed allowing access to these actions. Any button can appear multiple times on a wiki page, but each but must appear at least once in order to ensure that users can properly interact with the survey. Note: this macro can only be used inside a {survey} macro.

Parameter

Required

Default Value

Description

default

(tick)

n/a

Displays the form buttons, note you must have at least once instance of each button on the wiki page:

  • previous – go back one page in the survey, this is not displayed if no previous page exists.
  • next – advance to the next page in the survey, this is not displayed if no further pages exist.
  • cancel – cancel taking the survey and return to the space homepage
  • submit – submit the completed survey

{survey-question-results} Macro

Show results of a survey question as a table

Parameter

Type

Required

Default Value

Description

surveyId

string

(tick)

 

 

question

string

(tick)

 

 

spaceKey

spacekey

 

 

 

{survey-default-view} Macro

Renders a survey in a standard default view.

Parameter

Type

Required

Default Value

Description

surveyId

string

(tick)

 

 

spaceKey

spacekey

 

 

 

{survey-question-result-chart} Macro

Renders the result of a question in a pie chart.

Parameter

Type

Required

Default Value

Description

spaceKey

spacekey

 

 

 

surveyId

string

(tick)

 

 

question

string

 

 

 

title

string

 

 

 

legend

boolean

 

true

 

pieSectionLabel

string

 

 

 

3D

boolean

 

false

 

width

int

 

300

 

height

int

 

300

 

colors

color

 

 

 

subTitle

string

 

 

 

dataDisplay

enum

 

false

false, true, after, before

bgColor

color

 

#ffffff

 

borderColor

color

 

 

 

Top of page

Recipes

Example Survey Embedded within a Confluence Page

 


{survey-render:surveyId=xxxxxxxx}
h2. {survey-info:title}

|| Description | {survey-info:description} |
|| *Closing Date* | {survey-info:endDate} |
|| *Total Questions* | {survey-info:questionCount} |

_Page {survey-info:currentPage} of {survey-info:pageCount}_

{survey-body}

{survey-button:previous} {survey-button:next} {survey-button:cancel} {survey-button:submit}

{survey-render}

 

 

Top of page

 

  • No labels