Demo

Features 

Create custom input forms for your users to submit data using the Easy Forms macro.  View submitted data with the Easy Forms Report macro.

• Drag and drop to rearrange fields
• Fast editing of forms and updates
• Users can go back and update forms when settings allow
• The ability to control who can edit a form via Confluence page permissions.
• A dynamic up to date report on form submissions.
• Email notification of form submissions
• Confluence notifications of form submissions
• The ability to export form submissions in
  • XML
  • JSON
  • CSV
  • XLS
• Easily remove submissions from a report
• Allow for single or multiple submissions per user.
• Now offers HipChat integration
• Predefined form field types including:
  • Text
  • Paragraph
  • Multiple Checkbox
  • Multiple Choice
  • Drop Down
  • Date
  • Time
  • Number
  • Website Address
  • Email Address
  • Mailing Address
  • Section Titles
  
  

User Guide 

Creating an Easy Form 

1. Add an Easy Form Macro to the page and publish the page
   
   

   Form name

   The form name is a page-unique key to the form data. Changing it after form data has been submitted will sever the connection to the data. The data connection can be restored by restoring the name to its original value.
2. Click the "Edit" button on your form (in page view mode), drag and drop fields to quickly create your form
   
   

3. Click Save
   
   

Custom Input Validation

Fields of type “Text” allow configuration of custom validation using a regular expression when "Custom validation with regular expressions" is enabled in the admin configuration tool:

For example, you could use the regular expression ^(\d{3}-?\d{2}-?\d{4}|XXX-XX-XXXX)$ to validate that the user is inputting a valid US Social Security Number like 123-45-6789:

You can configure a custom validation failure message that will be displayed when a user's input fails validation:

Creating a Report 

Simply add an EasyForm Report Macro to any page indicating the Page Location and the Form Name to see the results

Report Permissions

To view an Easy Form Report on a page the user must have edit access on the page that contains the Easy Form (in addition to view access for the page that the report is on).

Users who can access the page that the report is on but do not have access to the report will see an informational message:

Users who can view the report can export the form data from links at the bottom of the form:

To bypass the permission check for a form report the form can be edited in the Easy Form macro editor to set "Unrestricted reports":

An unrestricted report is viewable by anonymous users.  Best practice for unrestricted reports would be to put them on a page that is not accessible to anonymous users so that all of your logged in users can see the report but not anyone else.  If you do open up the report to anonymous users then be aware that the report export ability is disabled for anonymous users even if the report is unrestricted.

Export Report from Admin Tool

An admin user can use the Easy Form admin tool to export reports as JSON, XML, XLS, or CSV data.  The tool is under "Easy Forms" in the Confluence general configuration admin tools:

Reports for Easy Forms in other spaces 

In the Easy Form Report macro editor, type the page name into the input for "Page with form" and auto-completion will render that page in the dropdown list of matching page names. If the page is in another space then the selecting it will populate the input by prepending that space key to the page name, separated by a colon.  e.g. TestSp: Test Easy Form Page

Pagination in Reports

In version 1.11.7 and later the Easy Form Report macro has a setting for controlling pagination:  "Max rows for client-side pagination".  The default is 10,000 rows:

When the number of rows in the report is less than or equal to the number in this setting then client-side pagination is used in the report table. Else, server-side pagination is used.

Client-side pagination loads all rows of the report into memory in the browser (and on your server) and this makes sorting and search filtering fast.  The tradeoff is that it uses more memory than server-side pagination and, when the number of pages is very large, it can bog down your server or your browser.

Server-side pagination loads only one page of data into memory in the browser (and on your server).  It is a bit slower for sort/search but performs well for very large datasets (reports with many submissions).

You can tune this parameter for your report macro adjusting the number lower to give a preference to server-side pagination or higher to give a preference to client-side pagination.  Set it to 0 to always use server-side pagination.

Server-side pagination has some limitations in sort/filter operations due to limitations imposed by SQL and the database schema for reports. 

• For sever-side pagination you cannot sort by submission value at the same time you are searching by submission value.  For that case, you must sort by another field, like updated date, and then search by submission value.  
• Cannot sort multi-valued submission fields (checkboxes)
• Cannot sort or search by user
• Sort and search are case-sensitive

Email Notifications 

Notification Configuration 

To control email notifications for form submissions navigate to Administration -> Easy Forms -> Configuration

Server Configuration 

For email notifications to work your Confluence server must also have an outgoing mail SMTP server successfully configured:

Confluence Workbox Notification Integration 

Confluence users can be notified for form submissions via Confluence Workbox notifications:

Notifications are sent to user's workboxes as shown:

Anonymous Forms

Single Responses

To restrict the votes on a form to a single response the user will need to be logged in and "Annonymous form" selected in the Macro editor.

When forms are specified as "Anonymous form" in the macro editor then submittals are anonymous. 

The Report macro will not include the user for each row because the user is not persisted for anonymous form submissions.

Unlimited Responses

You can also add anonymous responses on a page that allows anonymous view access and the Macro has "one submission per user" left unchecked

Responses will be shown as anonymous, but anyone can respond as many times as they like. All they have to do is refresh the form. 

Webhook Notification Integration

The Easy form admin tool has a setting for enabling a webhook integration:

You can set this to the URL of a resource that will accept a HTTP POST containing a JSON string containing the submission data for a form submittal.

The JSON object includes the formId, formName, and formTitle.  The submitted values are included in 2 arrays: a columns array that defines the title and type of each field in the form and a rows array that contains the field values.

For example:

{
    "formId": "28",
    "formName": "EasyFormWebHookTest",
    "formTitle": "Test Form",
    "formCreated": "2020-06-19T22:09Z",
    "formUpdated": "2020-06-19T22:10Z",
    "pageId": 1245427,
    "rowsTotal": 1,
    "rowsOffset": 0,
    "rowsLimit": 1,
    "columns": [
        {
            "uid": "c2YmFmL",
            "title": "Favorite Color",
            "type": "radio",
            "created": "2020-06-19T22:10Z",
            "updated": "2020-06-19T22:10Z",
            "deleted": false
        },
        {
            "uid": "c6RtagW",
            "title": "Favorite Animal",
            "type": "text",
            "created": "2020-06-19T22:10Z",
            "updated": "2020-06-19T22:10Z",
            "deleted": false
        }
    ],
    "rows": [
        {
            "id": 32,
            "userKey": "2c9_ThisIsFake_2016e234a15ad0000",
            "userName": "John Doe",
            "created": "2020-06-19T22:10Z",
            "updated": "2020-06-19T22:10Z",
            "fields": [
                {
                    "uid": "c2YmFmL",
                    "values": [
                        "blue"
                    ]
                },
                {
                    "uid": "c6RtagW",
                    "values": [
                        "Blue Whale"
                    ]
                }
            ]
        }
    ]
}

HipChat Notification Integration (Deprecated)

Note that Atlassian's Hipchat reached end of life on Feb. 15, 2019.  Easy Form's Hipchat integration is deprecated and will be removed in a future version.

1. Scroll to the bottom of the Insert Easy Form Macro popup box
2. Enter your HipChat Room Token to integrate HipChat 

Form Copying 

You can copy paste a form from page to page in the Confluence page's edit mode using Confluence's Copy Page feature

Page templates containing a form can be created simply by creating/editing a template and pasting in the EasyForm macro copied from a page in edit mode

Database

Easy Forms uses Active Objects to persist data in your Confluence Server's database.  This document has details of all of the DB tables used by this app and can be used for DB backup operation in addition to migrating the data between servers: Migrating Easy Form Data between Instances

FAQs 

Release Notes