Run macro

Description

Allows user input of parameters before rendering the body of the macro. Parameters will be used to replace variables in the body prior to rendering. Parameters 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 of comma separated key:value:description triplets 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. The default value is specified in the key:value:description triplet.

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

Parameters

• id - Optional. Can be specified as the default parameter. A way to specify a unique id to identify this instance of the run macro. By default, a numeric id is automatically assigned based on the order of the macro on the page. When using legacy wiki markup, you must assign a unique id if there are more than one run macros on the same page.
• replace - A comma separated list of key:value:description triplets. Any entry containing a comma (,) or colon (\:) must be enclosed in single quotes (') - example: x:1:'It''s an example: 1, 2, or 3'. Keys, values, and descriptions are case sensitive. More advanced capabilities are available and documented in the next section.
  • key is the parameter name. It must not be blank or contain blanks. Avoid special characters.
  • value is the initial replacement value. If not provided, blank will be used.
  • description is descriptive text used to provide prompt text for the parameter. If not provided, the key will be used. Line breaks with leading space ( <br>) and required spaces (&nbsp;) are supported.
• width - Width of the parameter entry table in percent(%) or pixels. Default is blank (default table format).
• inputSize - Size of the value text entry fields. Default is 95% of table width.
• autoRun - Default is false. Set to true to automatically render the macro body with the default parameter values.
• help - Help page link. If this is specified and is a valid and authorized page reference, a help icon will appear at the top right of the parameter area that links to the help page. In addition, any parameter whose description begins with ? will generate a help icon and link to an anchor on the page specified. The anchor will be identified by the replacement parameter key. A link to a anchor not defined on the help page will show the top of the help page. A page can be referenced by title or spacekey:title. Special values of @self, @parent, and @home are valid.
• anchor - Anchor title for positioning after button press. This is the title used on an anchor macro somewhere on the current page. Normally, the anchor would be placed before the run macro or at the top of the run macro body so that the results are shown at the top of the page. If there are parameter validation conditions, errors from user input may not be visible if the anchor is after the form.
• focus - Input parameter name to receive focus when page is initially displayed to allow typing or selection immediately. Themes or other page content may override this setting. It may also be browser dependent. Since 3.1.0.
• heading - Heading that appears before the buttons. Default is blank. Line breaks with leading space ( <br>) and required spaces (&nbsp;) are supported.
• prompt - Prompt text that appears above the parameters. Default is blank. Line breaks with leading space ( <br>) and required spaces (&nbsp;) are supported.
• titleRun - Title for the run button. Default is Run or equivalent translation.
• titleExport - Title for the export button. Default is Export or equivalent translation. Exportfile parameter is required before the export button will show.
• titleExportFile - Title for the export file input field. Default is Name: or equivalent translation. This will only be shown if exportfile parameter value starts with a question mark (?).
• titleAttachmentComment - Title for the attachment comment input field. Default is Comment: or equivalent translation. This will only be shown if attachmentComment parameter value starts with a question mark (?).
• hideParameters - Hide the parameters. Default is false.
• hideColumnHeadings - Hide column headings in the parameter table. Default is <b>false</b>.
• hideRun - Hide the Run button. Default is false.
• hideExport - Hide the Export button. Default is true unless exportFile is non-blank.
• showMore - Show fields with the more attribute on initial display. Default is false. The _more request parameter will override this setting.
• exportFile - Location of the export partial html file representing the rendered macro body. For export to an attachment, the user must be authorized to add attachments to the page specified.
  • ^attachment - The rendered html is exported as an attachment to the current page.
  • page^attachment - The rendered html is exported as an attachment to the page name provided.
  • space:page^attachment - The rendered html exported as an attachment to the page name provided in the space indicated.
  • filename - The rendered html is exported as a file located in confluence home directory/script/filename. Subdirectories can be specified.
    Replacement keys are allowed in this field and will be replaced with values.
• exportVersion - Defines the the version mechanism for exported reports.
  • new - (default) Creates new version of the attachment. For file based exports 'new' has the same effect as 'keep'.
  • replace - Replace (overwrites) existing rendered html and, for attachments, removes all previous versions! To replace an existing attachment, the user must be authorized to remove attachments for the page specified.
  • keep - Only creates an new export if an existing export of the same name does not exist. An existing attachment will not be changed and an existing file will not be updated.
• attachmentComment - Comment used for an exported attachment. If it begins with a question mark (?) then an entry field with this value will appear next to the export button. Replacement keys are allowed in this field and will be replaced with values.
• autoExport - Default is false. Set to true to have the rendered macro body automatically exported.
• showKey - Show the key. The key is shown after the value entry field. Default is false.
• suppressQuote - Suppress quoting of multi-select values. Default is false. Normally, a multi-select value is represented as a comma separated list of single quoted values. Set suppressQuote=true to have a multi-select value represented as a comma separated list of values. The user must ensure that no values contain commas to prevent unpredictable results.
• dateFormat - Date format to use for replacement of $current_time. Default is server date format. See Date Format for how to specify this value.
• requestPrefix - Default is run_id_ where id is the value of the id parameter. The prefix is appended with the parameter name to form the request parameter key on the url.
• requestAction - Default is run_id where id is the value of the id parameter. This represents the request parameter key for the action to perform (run or export).
• keepRequestParameters - Default is false. Set to true to keep existing request parameters on the url after button is pressed. Normally used for recursive use or when there are multiple run commands on the same page so that the results of one run macro are retained when the second is run. All requests parameters will be retained if keepRequestIds is not specified. Otherwise, non-run macro request parameters and those references by the keepRequestIds parameter will be retained.
• keepRequestIds - List of run macro ids whose request parameters should be retained on the url after button is pressed. Use of this parameter or keepRequestParameters parameter is required for recursive use of this macro. This works only for default request prefix values.
• parameterInput - For advanced customization of the display of the parameter input table. This requires velocity programming and Confluence system administrator privileges to add and update the customized velocity file. This is a velocity include reference relative to the Confluence web app and replaces the table portion of the velocity file embedded in the plugin.

Advanced capabilities

Entry fields

By default, parameter entry fields are text fields. By providing additional information, other entry fields are possible. The entry field type and other options for a replacement parameter are specified on the replace parameter as additional portions of the replacement parameter entry - key:value:description:type:number:... . The first 3 parts are described above. The additional parts are described next:

type

• text - value is displayed in a text box. (default)
• textarea - value is displayed in a multi-line text area.
• radio - values are displayed as radio buttons.
• checkbox - values are displayed as checkboxes.
• select - values are displayed as a select list.
• select-multi - values are displayed as a multiple select list.
• integer - value is displayed in a short text box. Integer values are long integers.
• integer-select - value is displayed in a select list with automatically generated values based on lower and upper bounds. Difference must be less than 10000.
• float - value is displayed in a short text box. Float values are double floats.
• date - value is displayed in a short text box.
• output - value is displayed as output text.
• hidden - value is hidden - the field does not show up in the parameter table.
• group - pseudo field used for grouping of other fields so they display as a single row. A group field indicates the start of fields included in the group. Groups are automatically ended by the next group field or append -end to the type field for the last field in the group.

Append -required to the field type to ensure a non-blank value is selected or specified.
Append -disabled to the field type to disable input on the field.
Append -end to the field type to end a group previously started with the group type.
Append -more to the field type to initially hide the parameter until the user requests to view more parameters. This allows for basic and advanced parameters to be on the same form with display under user control.
Unrecognized types are ignored.

The remaining colon (:) separated entries are interpreted in a type specific manner.

• text type
  • input size - Default is inputSize parameter. This allows for individual text fields to have a different value.
• textarea type
  • number of rows - Default is 5 rows to display.
  • number of columns - Default is to be as large as the containing area allows.
• radio, checkbox, select, and select-multi types
  • number of rows - used to control the display for some field types that can span multiple rows. The default is 1 except for a default of 5 for select-multi type. A negative value will be interpreted as the number of entries per line for radio and checkbox field types.
  • value:text - Subsequent pairs represent entry values and entry text for options needed for radio, checkbox, and select field types. The value becomes the replacement value for the option. The text is what appears to the user. If the text is blank, the value will be used. Note when specifying the initial value for this parameter, use the choice value and not the text. For select fields, select groups can be specified using special value:text pairs indicated by @group:text and @end:text where text is the group name. If text is blank, the group will not be named and a line will be drawn instead.
• integer and float types
  • lowerBound:upperBound - if a bound is not specified, no check will be done. Bounds must be valid integer or float values. Bounds are inclusive (less than or equal). Both bounds must be specified for integer-select.
• date type
  • lowerBound:upperBound:dateFormat - if a bound is not specified, no check will be done. Bounds must be valid date values. Bounds are inclusive (less than or equal). Date format defaults to the dateFormat parameter. See Date Format for how to specify this value.
• group type
  • width - Width of the group area in percent(%) or pixels. Default is to use as much space as needed by group elements.

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

Three identical macros run, run1, and run2 are provided to enable recursive use of the macro.
Request parameters
Parameters are passed as request parameters on the URL, enabling automatic running of content based on the incoming parameters.

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}