Description

The run macro provides a user form with specified input fields. Form fields will be used to replace variables in the body before rendering. Form values can be provided as follows:

1. User interaction - a user inputs data into the fields 
2. Using Pre-defined variables
3. Including 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. 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.

Parameters

Field Types

See Field types.

Advanced capabilities

Examples:

• Horizontal radio button - gender:M:Gender:radio::M:Male:F:Female
• 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
• 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 an 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 - 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 request parameter with 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}