Run Macro - 6.x

Overview:

The run macro allows you to easily enter data on a page by automating the input process. Configure the user from using the macro to enable the user to enter values on a confluence page. The run macro will render the newly entered values and replace the old values with the new.

Description

Provides a user form with input fields before rendering the body of the macro. Form fields will be used to replace variables in the body prior to rendering. Field values can be provided by user interaction, pre-defined variables, or request parameters. Any text in the macro body that begins with $ immediately followed by a key found in the replace parameter list (see Field types for details) will be replaced by the value. Usually, values will be provided by a user submitting a form from the page based on the replace parameter. Default values can be specified.

This macro may have restricted use for security reasons. See Macro Security for Confluence and consult with your administrator for details.

The run macro provides a form with specified input fields, settings, and parameters that you define within the editor. The values input into the form fields will be used to replace variables in the body of the Confluence page before it is rendered. Form values can be provided as:

1. User interaction - a user inputs data into the fields you've defined.
2. By using Pre-defined variables.
3. By including request parameters (from the URL).

Any text in the body of the run macro will be replaced by:

• the value when the text begins with '$' immediately followed by a key found in the replace parameter list  (see Field types for details). Typically, values will be provided by a user submitting a form from the page based on the replace parameter. When defining field types, default values may be specified.
• dynamic text using any Field key parameters that begin with '$' followed by a Field key. 

Insert the run macro on a Confluence page

Create a Confluence page that will eventually contain the form you would like presented to users within your organization.

1. Create a page named Incredible Form in a space accessible to the desired audience.
2. Click Save to save the new page.
3. Edit the Incredible Form page.
4. Select Other macros from the top menu.

5. In the search box type 'Run' and select Run with a user form and parameters from the macro suggestions.

6. Click the Run macro from the list of available macros.
7. Click Save settings.

Work with field settings

With the run macro on our Confluence page, it's time to explore adding fields to a form.

Examples:

1. Horizontal radio button - gender:M:Gender:radio::M:Male:F:Female
2. Single select with 12 lines - month:12:Month:select:12:1:Jan:2:Feb:3:Mar:4:Apr:5:May:6:Jun:7:July:8:Aug:9:Sept:10:Oct:11:Nov:12:Dec
3. Checkbox (value same as text) - day::Day of$nbsp;week:checkbox-required:7:Sunday::Monday::Tuesday::Wednesday::Thursday::Friday::Saturday

Export

The HTML, representing the rendered body of the macro, can be exported to a page attachment or to the file system. This enables the dynamic content to be captured at a point in time for later viewing. An attachment or file created by this type of export can be used on a page by including it in the body of a html macro. For example: {html:script=^bobs.html} {html}. If exportVersion=keep is used, the referenced attachment is already there, and the HTML macro is authorized for use on the page, then the macro body will not be rendered and the attachment will be included instead. This enables caching and automation capabilities.

Recursive use

When using wiki markup, identical macros run, run1, and run2 are provided to enable recursive use of the macro.

Request parameters

Request parameters are case sensitive. Look at the URL after pressing the run button or after an autorun. This url can be used as a link. Usually, the URL contains the page title. If the page title contains special characters or you wish to have a more persistent link (that survives page renames or moves), then Confluence's alternate page view URL can be used: .../pages/viewpage.action?pageId=......... The view URL can be constructed by looking at the URL after going to Tools->Info. Tiny links cannot be used (CONF-11594   ). Each parameter is represented by a request parameter composed of _ separated elements:

• run - constant
• id - id associated with this run instance - see the id parameter
• parameter key - the first component of the key:value:description triple

An example is: run_1_gender=M. An example of the run action is: run_1=run, this causes the action to run. Exclude this from the link if you just want the parameters filled in, but want the user to press the button.

The group pseudo field type does not result in a requestParameter. The request parameter representation can be controlled using the requestPrefix and requestAction parameters.

Fields that allow multiple selections

Checkbox and multi-select fields allow multiple selections and are more complex. Special considerations are:

• If the initial value needs to be specified with more than one selection, the value must be a single quoted, comma-separated list of choice values.
• The replacement value for such a field is a single quoted, comma-separated list of single-quoted selected values.
• Checkbox and multi-select entries appear multiple times as a request parameter with a value matching values that have been selected.
• Embedded single quotes are doubled.

Translation

Text visible to form users (field titles, parameter descriptions, and choice text) can be provided so that it is translatable by using @ followed by a key to the translatable resource. This means that the form will show text specific to the user language setting.

• Any valid i18n key defined in Confluence can be used (example: @dashboard.name)
• Custom keys (beta - subject to change based on user feedback)
  • Can be defined and accessed via @custom.example.key.
  • This requires customization that requires your system administrator. Custom keys must be added to a property file named org.swift.confluence.run.custom.properties. Appropriate language translations property files named after the language abbreviation (example: org.swift.confluence.run.custom_fr.properties) and inserted into the add-on jar under i18n directory.

Usage

The following examples are given in wiki markup format so it is easy to copy and paste. Use Insert → Markup in your Confluence editor to paste in the examples.

Run example:

Run a script

{run:replace=greeting:Hello,who:Bob}
{beanshell}
 out.println("$greeting $who");
{beanshell}
{run}

Run a SQL query

{run:replace=first:Bob:First name|exportFile=^bobs.html|titleExport=Archive result}
{sql:datasource=NameDS}
select * from NAMES where first='$first'
{sql}
{run}