Run macro

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. Normally, 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.

Parameters

Field Types

See Field types.

Advanced capabilities

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 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 plugin jar under i18n directory.

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.

Usage

Run example

Run a script

{run:replace=greeting:Hello,who:Bob}
{beanshell}
System.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}