Configuring Power Custom Fields

Owned by Jonathan Muse
Last updated: Oct 11, 2024 by Shane Smith
5 min read

Adding a Power Custom Field

Follow these steps to add a Power Custom Field:

  1. Log into your Jira instance as Admin.

  2. Go to Administration > Issues > Custom Fields page.

  3. Click Add custom field and select one of the available PCF custom fields.
    Ensure that you select the project screens that you want them to be on.

You can select one of the following types to learn more about a specific field:

Configuring PCF custom fields

After you create the field, go to the corresponding Configure link and complete and configure the fields on that page. See the following field specifics.

image-20240212-111826.png

Default value

To set the default value, click Edit Default value.

NOTE: For the PCF - SIL User Picker, the default value is set by clicking Edit Field data settings.

NOTE: If your option provider data source (described below) relies on an issue/issue key, the default value selection will not work, since there’s no issue context in the field’s configuration page.

Template configuration

To improve the usability of the app, we added a template for each option type:

image-20240212-113458.png

You don't have to configure any other settings for these Power Custom Fields. Just select a template and the required properties are set automatically.

For the components and versions in the templates, edit the SIL script so it uses your project key.

You can find the script in the field’s configuration page or the silprograms folder and under the custom field ID or field config ID sub-folder.

Data Source Types

The data source is used to obtain the values which populate the custom field. You select the data source type in the corresponding field.

A script used as a data source can return either a string or an option array. If a string array is returned, its elements are saved as pairs (value, value). If an option array is returned, the elements will be saved in a KPOption structure.

Predefined structure types

Name

Field

Type

Name

Field

Type

KPOption

label

string

value

string

The data source script is also invoked when JQL search is going.

For more information about data source types, see SIL Data Source and SQL Data Source. You can find examples of data sources in our Examples for Power Custom Fields section.

Option Type

For the types of option that you want to use, click the Edit Option Type link. The default option type is rendered as a string.

For in formation about other types, see Option types.

Validation Strategy and Execution

You can select the type of validation for the custom fields values that you set by editing them in the field’s configuration.

  • Validation Strategy

    • No Validation – the options set to custom field won't be validated

    • Datasource Options – the options set to custom field will be checked by the datasource generated list

    • Datasource Options with query – the options set to custom field will be validated by the datasource which is queried with each label of the selected values. We recommend this option for autocomplete type custom fields.

  • Force script execution – When the radio button is on, the script will be executed even if the value of the field does not change. If the radio button is off, the script is not be executed if the value is not changed.

Select Script

The SIL Script you select in the field configuration page is used to populate the field’s options and will run each time you modify the custom field. You can select another script at any time by clicking the pencil icon in the the Pick a SIL Script as data source section under Data source.

When you change a custom field value, either using inline edit or using the edit issue screen and saving the changes, the argv value changes. The argv contains the old value and new value of the custom field.

Autocomplete settings

The Autocomplete settings tab in the configuration page helps you configure the autocomplete settings for the custom fields that have the autocomplete functionality.

  • Use the Minimum characters option to set the minimum number of characters that can be used for the autocomplete.

  • Use the Maximum results option to set the number of the results that can result from autocomplete. In the example above, the script will show a maximum of 50 results.

  • The Filtering Strategy provides the following options:

    • Implicit - this option filters the values by the label

    • Datasource - This option calls the datasource to decide what filter should be applied based on the query. This option doesn’t use implicit filtering.

Dependencies

To use the screen values for a field in the data source, you have to add it as a dependent field.

When the value of the dependent field is changed, the current fields' values will be recalculated, according to the new value of the dependent field.

You can find a dependent fields example here.

After you add the power custom fields, see the User Guide for additional details on how to use them.

Additional information