As an administrator, you can set up Form IDs which can be used when creating forms, helping to simplify the creation and use of forms. Form IDs are reusable and editable, making it easier when you want to bulk edit the behavior of several forms.Form IDs are created in the Form administration section and provide a number of benefits such as:

  • Control the behavior of the responses to a form
  • Track the usage of a Form ID
  • Update several forms that use the same ID at the same time
  • Link the responses to a Form to the Form ID Internal Database.

It's not necessary to use Form IDs and you can set a direct destinations in the Forms for Confluence macro, however the Form ID is a powerful mechanism used to administer and manage the use of Forms for Confluence more easily and is a good option when creating forms that are designed to be more permanent.

Form IDs can be configured to manage responses using either the Internal Database or specific email addresses.

Prerequisites

  • Install Forms for Confluence
  • Login in as an Administrator

If setting up a Form ID for ScriptRunner:

Create Form IDs for Email Relay

Form IDs with the collector type set to Email Relay will send responses to a form to an email address.

Instructions

  1. Navigate to the Administrator console.
  2. Select Forms Administration from the left navigation panel.
  3. Click Add a New Form Configuration.
  4. Complete the Create New Form ID Configuration fields.
    1. Provide a unique identifier in the Form ID field.
    2. Set Destination type to Email Relay.
    3. Enter the email address(es) to receive results from the configuration.
      1. Optional: Select the Single Submission checkbox, if you want to send an email only once to the provided email addresses.
      2. Optional: Check the Submission Override checkbox, if you want to allow the user to override previous submissions.
      3. Optional: Provide information about this configuration in the Description field.
      4. Optional: Provide a message to be displayed to senders after submitting their form, in the Success HTML field.
  5. Click Save, to create the new Form ID Configuration.


    The new Form ID will appear in your list. You can now use this form mail as a parameter for the Forms for Confluence macro.

Creating Form IDs for Internal Database

Form IDs with the collector type set to Internal Database will store responses from a form in the Forms for Confluence Internal Database. Responses can be viewed, managed and exported directly in Confluence.

Instructions

  1. Navigate to the Administrator console.
  2. Select Forms Administration from the left navigation panel.
  3. Click Add a New Form Configuration.
  4. Complete the Form ID Configuration.

    1. Provide a unique identifier in the Form ID field.

    2. Select Internal Database as Destination type.

    3. Select desired specifications in the Form Response Macro Permission field.

      1. Optional: Select the Scheduled checkbox in the Notifications section to receive periodic responses.

        Notification preference is personal to the user editing the form configuration, and will not influence other users notification preferences. Notifications may be disabled for the user editing the form configuration.
      2. Optional: Deselect the checkbox option for Single Submission, if allowing multiple submissions from a single user is desired.

      3. Optional: Check the Submission Override checkbox option if you want to allow the user to override previous submissions.

      4. Optional: Provide information about the configuration in the Description field.

      5. Optional: Provide a message to be displayed to senders after having submitted their form in the Success HTML field. 

  5. Click Save to create your Form ID Configuration.
    The new Form ID will appear in your list. You can now use this form mail as a parameter for the Forms for Confluence macro.

Creating Form IDs for ScriptRunner for Jira

Instructions

  1. Navigate to Confluence Administration > General configuration > Forms for Confluence.
  2. Click Add a New Form Configuration.
  3. Complete the Create New Form ID Configuration fields.
    1. Provide a unique identifier in the Form ID field.
    2. Set Destination type to Email Relay.
    3. Enter the email address(es) to receive results from the configuration.
    4. Select the Jira Application Link that will be associated with the Form ID from the available Jira Application Links shown in the drop-down list. See the Atlassian documentation for instructions on setting up an application link between Confluence and Jira.
    5. The ScriptRunner Endpoint, identifies the specific endpoint (contact point) configured using ScriptRunner REST endpoints in Jira. This is simply the exact point to where the form will be sent. The ScriptRunner REST endpoint will be responsible for processing the submitted form. One form can be submitted to multiple Jira instances, and each Jira instance can have several endpoints. See the ScriptRunner documentation for setting up a REST endpoint. 
      1. Optional: Select the Single Submission checkbox, if you want to send an email only once to the provided email addresses.
      2. Optional: Check the Submission Override checkbox, if you want to allow the user to override his submission.
      3. Optional: Provide a message to users after the form has been submitted in the Additional Information HTML field. This might be useful if the form submitted was used to created an issue in Jira. The message received could contain a link to the newly created issue or any other information deemed useful. 

        Provide a message

        "Info Html" in ScriptRunner Form Configuration is customizable and at present Info Html supports the following placeholders:

        $endpoint: Input value of the "ScriptRunner Endpoint" text box.

        $formID: Input value of the "Form ID" text box.

        $response: Received response of a successful call.

  4. Click Save, to create the Form ID Configuration.

    The new Form ID will appear in the Form Configuration list.


    The Form ID can now be used as a parameter in the Forms for Confluence macro.

Check out our example use cases for more information.