Advanced settings for custom fields

You can use eazyBI advanced settings (available only to Jira system administrators and eazyBI admins) to add support for additional Jira custom fields as well as modify import options for standard custom fields.

eazyBI advanced settings are defined using the TOML format.

On this page:

Additional custom fields

If you would like to import in eazyBI additional Jira custom field with a custom field type that is not supported by default, then you can add a definition of how this custom field should be imported. Also, if some default custom field settings should be changed, then it can be done with adding necessary custom field configuration parameters.

At first, you need to find out Jira custom field ID. You can see custom field ID in the URL when entering Configuration screen of this field. For example, if the end of the URL is ...admin/ConfigureCustomField!default.jspa?customFieldId=10100, the field ID is 10100.

Then add the following line to advanced settings:

[jira.customfield_NNNNN]

where NNNNN is custom field ID. This will start the block of configuration parameters for the NNNNN custom field. After that line, specify the data type of this field:

data_type = "string"

By default, the string maximum length is 255 characters. If there is a need to import longer string values, then use additional limit setting and specify the maximum length.
Other available types are text, integerdecimal, datedatetime.

If you use the decimal data type, then by default the precision (maximum number of digits) is 15 and the scale (digits after the decimal point) is 2. You can change these defaults with additional precision and scale settings.

If you would like to import custom field as additional dimension then add

dimension = true

If the custom field can contain multiple values for a single issue then add

multiple_values = true

If the custom field returns string with comma separated values (see example definition of calculated text field) which should be imported as multiple values then add also

split_by = ","

If you would like to import custom field as a measure then add

measure = true

Here is example of custom string type dimension definition:

[jira.customfield_10100]
data_type = "string"
dimension = true 

Add additional custom field definitions as needed in advanced settings text area field and then click Update advanced settings.

Multi-Level custom field import

For the custom field that is created using Multi-Level Cascading Select plugin, please add the following advanced options

[jira.customfield_NNNNN]
data_type = "string"
dimension = true
levels = ["Level 1", "Level 2"]

In levels setting, list all levels that are defined in the multi-level cascading select custom field configuration (use your level names instead of "Level 1", "Level 2"). Level names should be unique.

In addition, the following option can be added if the (none) member should be created at all parent levels. By default, this option is set to false and only one (none) member is created at the first highest level. 

none_member_all_levels = true

Interval dimension

You can import a numeric custom field as an interval dimension. For example, if you would like to import the "Story Points" dimension that groups issues by story points intervals, then add the following advanced settings (where NNNNN is the Story points custom field ID) :

[jira.customfield_NNNNN]
dimension = true
intervals = "/5"

The above specifies that Story points custom field should be imported as an interval dimension and should group Story point values in the intervals or ranges of 5. This is the default interval, after import it can be edited from "All Hierarchy level members" in the new Story Points dimension.

Import changes of custom field dimensions

By default, you can enable changes of the standard Transition Status and Assignee dimensions as well as the changes of Jira Agile Sprint dimension to be imported. See the documentation how to enable and use Issues history and other measures that can be used to get the historical issue status.

Option 'Import issue change history' should be enabled prior to enabling value change import for any custom field dimension.

It is possible to import changes also of other single value custom field dimensions. Please add additional separate_table and changes advanced settings for these custom fields:

[jira.customfield_NNNNN]
data_type = "string"
dimension = true
separate_table = true
changes = true

After that in Jira import options you will be able to select Import as dimension and Import value changes option for this custom field. After the import you can use Issues history measure with this dimension and Time dimension to see how many issues had the historical custom field value at the end of the corresponding Time period. Or use hidden Transitions to measure to analyze transitions and see the historical value of this custom field at the time when the transition was performed. 

Please import value changes only for the custom field dimensions where it is really necessary. Import of each additional custom field dimension value changes increases the size of the eazyBI database.

Value change import of calculated custom fields (i.e. Jira Misc, ScriptRunner calculated custom fields) is not available in eazyBI because value changes of those custom fields are not represented in issues history.

Import changelog string value

Some additional custom field types store just an ID of the selected value and then use additional lookup functionality to show a display value that corresponds to this ID value. If you have added such custom field in the advanced settings and after the import in the eazyBI you see just an ID value, then this could be the cause for that. In this case please check in the Jira issue page History tab if you see the display value of this custom field when the change is made. If yes, then add get_changelog_string option in the advanced settings and re-import this custom field in eazyBI and now the custom field display values should be imported in eazyBI.

[jira.customfield_NNNNN]
data_type = "string"
dimension = true
get_changelog_string = true

List of all settings

Here is the list of all available custom field advanced settings:

Setting Available values Default value Description
changes true or false  false Specify true for the single value string data type separate table dimensions (see separate_table below) if you would like to see the historical custom field value with Issues history measure. Please also select Import issue change history option when doing the Jira import.
check_calculated_value true or false false Can be used for import of calculated custom fields which can return a different value even when the updated date and time of the issue has not changed. By default, the incremental import will re-import only those issues which are created or updated since the last import. If you set this setting to true, then for all issues this custom field value will be checked if it has not changed since the last import and will re-import this field value if it is changed. Enabling of this setting for calculated custom fields can make the import slower as during the import the calculation will be performed for all issues.
csv_dimension true or false false

Can be used with custom fields that have dimension and multiple_values enabled. If enabled then additional Custom field CSV dimension will be created where used combinations of values (as comma separated string) will be imported.

For example, if an issue has custom field with values one and two, then in the multiple values dimension Custom field two separate members (one and two) will be created and the corresponding measure values for this issue will be stored for each of these members. If csv_dimension is enabled, then in Custom field CSV dimension one member with comma separated values (one, two) will be created and the corresponding measure values will be stored for this member. You can use this additional CSV dimension if you want to filter measure values for issues who have both values in the custom field.

data_type

"string"
"text"
"integer"
"decimal"
"date"
"datetime" 


Specify the data type of the custom field value and that should be stored in eazyBI. Use string for limited length strings (the default limit is 255) or text for large text properties (do not use text when enabling dimension).

Use integer and decimal for numeric values. Specify precision (default 15) and scale (default 2) for decimals if you want to change the defaults.

Use date for date values without time and datetime for dates with time.

dimension true or false false Enable custom field import as a dimension. Enable only for list-of-values custom field types and not for custom fields which have unique values for each issue.
get_changelog_string true or false  false Some custom fields return numeric ID values as their default values, but you would like to import the corresponding string display value in eazyBI. In these cases quite often custom fields also provide string representation which is stored in the issue changelog (check in Jira if you see the string values in the issue history when you change this custom field value). If the changelog string value is available for this custom field then enable import of this string value in eazyBI.
intervals String with default interval ranges
If you want to import ranges of numeric values as an interval dimension, then specify the default intervals (for example, "/10").
interval_unit

"seconds"
"minutes"
"hours"
"days"


If the custom field returns a time interval value, then specify the default time unit for the intervals range (for example, if "days" is specified then intervals with the value "/10" means that time intervals for each 10 days should be created).
javascript_code  
If you create a new JavaScript calculated custom field, then specify the JavaScript code in this setting.
levels Array with strings

If the custom field should be imported as a multi-level dimension then specify and array with level names (for example, ["Level 1", "Level 2"]). The custom field value should be an array with values for each level. If the custom field value is a concatenated string, then specify split_by that should be used to split a string into an array of strings. See also the none_member_all_levels setting.

See the Multi-Level custom field import example above as well as the Jira Misc Calculated Field example.

limit Integer limit value 255 for strings Increase the string data type limit if needed.
measure true or false false

Enable custom field import as a measure. Please enable only for integer, decimal, date, or datetime data types.

See Custom Fields for more information about numeric and date custom fields import as measures.

multiple_dates true or false false

Enable custom measure import with numeric values for several dates. Custom field should return multiple lines where each line is in the format YYYY-MM-DD,numeric_value.

See the numeric measure with multiple dates example.

multiple_dimensions Array with dimension names.

Enable custom measure import with numeric values for several dimension combinations. Specify the list of dimension names that each line will return (for example, ["Time", "Assignee"]). Each line of the custom field value should be in the format dimension1_key,...,dimensionN_key,numeric_value (for example, 2015-09-27,john.smith,123 for the previous dimension names list example).

If you want to use custom field dimensions then only single-value separate_table dimensions (see below) can be used.

multiple_values true or false false Enable with If the custom field returns no one value for one issue but several values for one issue (an array of values). If the custom field value is a concatenated string, then specify split_by that should be used to split a string into an array of strings.
name String with a custom field name
Specify the custom field name when defining a new JavaScript calculated custom field.
none_member_all_levels true or false false Enable the (none) member creation at all parent levels of a custom dimension with several levels. By default, only one (none) member is created at the first highest level.
precision Integer precision value 15 for decimals Specify the precision (total max number of digits) of the decimal data type.
scale Integer scale value 2 for decimals Specify the scale (max number of digits after the decimal point) of the decimal data type.
separate_table true or false false By default, single-value custom dimensions are stored in the Jira issues table in the eazyBI database. If you want to upload additional measures for these custom dimensions or if you want to use it in the list of multiple_dimensions names, then enable this setting and re-import Jira issues into eazyBI. After that, a separate dimension table with the dimension members values will be created in the eazyBI database.
split_by String separator value
When levels or multiple_values settings are enabled, but the custom field returns a concatenated string then specify the separator that should be used to split the string value into an array. For example, if split_by is set to "," then the custom field value "a,b,c" is split into the array ["a","b","c"].
time_interval

"age"
"duration" 


If the interval dimension is for a duration, then specify "duration" and the custom field value should be the difference between two dates in time_unit.

If the interval dimension is for an age, then specify "age" and the custom field value should be a Unix timestamp (number of time_unit since January 1, 1970).

time_unit "seconds" 
"minutes" 
"hours" 
"days" 

If the custom field returns a time interval value, then specify the time unit for this value. This time unit will be used to convert the time value into the corresponding interval_unit and then to find the corresponding intervals range.

See the example of custom calculated field as an interval dimension.