| Info |
|---|
|
This routine is available starting with SIL Engine™ 4.6.3.| Table plus |
|---|
| applyColStyleToCell | true |
|---|
| heading | 0 |
|---|
| columnTypes | s,s,s,s |
|---|
| multiple | false |
|---|
| columnAttributes | style="background:#e5e7ea;font-weight:bold,,style="background:#e5e7ea;font-weight:bold, |
|---|
| enableSorting | false |
|---|
|
Syntax | admUpdateCustomFieldOptions(fieldName, pathToFile, charset, actionForOldFieldValues, actionForExistingFieldValues, projectKeys, issueTypes, useDefaultScheme, reorder, updateExistingOptionsValues, applyActionsOnParentOptions) | Package | | Alias | | Pkg Usage | | |
Description
| Excerpt |
|---|
|
| Updates custom field options for the specified context. If the context does not exist, it will be created. |
Updates custom field options for the specified context. If the context does not exist, it will be created. If the project keys and issue types are not specified (empty arrays), the option will be added to the global context.
This routine only handles custom fields of the following types: single select, multi select, radio buttons, checkboxes and checkboxes and cascading selects.
Parameters
| Table plus |
|---|
| applyColStyleToCell | true |
|---|
| columnTypes | s,s,s,s |
|---|
| heading | 0 |
|---|
| multiple | false |
|---|
| enableSorting | false |
|---|
|
Parameter name | Type | Required | Description |
|---|
fieldName | |
...
String | Yes | Name of custom field. | pathToFile |
|
...
String | No | The path to a file to read options from. If this parameter is empty, an empty list of options will be considered. | Note |
|---|
| The file should contain one custom field option on a separate line. |
| Note |
|---|
| To handle cascading select custom fields children options, prefix them with a space or a tab and they will be considered as children of the closest option from above that isn't prefixed with a space or tab. |
| charset |
|
...
String | No | The character set to use when reading from file. |
|
...
If this parameter is empty, then the default system charset will be used. | actionForOldFieldValues |
|
...
String | No | The action to take for the field values (options) that are present in the current field options but are not present in the input options. |
|
...
Possible values: "NONE", "DISABLE", "ENABLE", "DELETE". |
|
...
If this parameter is empty, the value "NONE" will be used. | actionForExistingFieldValues |
|
...
String | No | The action to take for the field values (options) that are present in the current field options and are also present in the input options. |
|
...
Possible values: "NONE", "DISABLE", "ENABLE", "DELETE". |
|
...
If this parameter is empty, the value "NONE" will be used. | projectKeys |
|
...
String [] | No | Project keys. | issueTypes |
|
...
String [] | No | Issue types. | useDefaultScheme |
|
...
Boolean (true/false) | Yes | Specify if you want to use the default configuration scheme (or context) of this custom field. | reorder |
|
...
Boolean (true/false) | Yes | Specify if you want to reorder the options as they are given in the input file. | updateExistingOptionsValues |
|
...
Boolean (true/false) | Yes | Specify if you want to update the existing options with the values provided in the input file. This option is needed because Jira considers for example that the option "ABC" is the same as "abc". This option allows you to rename the options. |
|
...
| applyActionsOnParentOptions |
|
...
Boolean (true/false) | Yes | Specify if you want the actionForOldFieldValues and actionForExistingFieldValues to also be applied to parent options, or just child options. | Note |
|---|
If this parameter is false and the custom field's type is not cascading select, then the actions will not apply (since only the cascading select custom field can have children displayed in the UI). |
|
|
Return
...
Type
boolean Boolean (true/false)
Returns 'true' if the options were successfully updated and 'false' otherwise. If returned 'false' check the log for a detailed reason on why it failed.
...
.
Examples
Example 1 - Updating a Cascading Select Custom Field
For Example 1.1 and and Example 1.2 we we will consider as a starting point, the following already existing options of the custom field:
| Code Block |
|---|
Parent1
Child1
Child2
Parent2
Child4
|
and as an input file, "updateoptions.txt", that has the following contents:
| Code Block |
|---|
PARENT1
Child3
Child2
CHILD1
Parent2
Child5
Parent3
NewChild |
|
Example 1.1. - Updating a Cascading Select Custom Field - Delete missing input options, rename existing input
...
| Code Block |
|---|
admUpdateCustomFieldOptions("CF_CASCADE", "updateoptions.txt", "", "DELETE", "NONE", {}, {}, false, false, true, false);
|
...
options
...
...
PARENT1
CHILD1
Child2
Child3
Parent2
Child5
Parent3
NewChild
Option "Parent2 - Child4" is going to be removed, because the the actionForOldFieldValues parameter is "DELETE".
Option "Parent1 - Child1" will be renamed to "PARENT1 - CHILD1" because the parameter parameter updateExistingOptionsValues is set to true.
The new option "PARENT1 - Child3" is added at the end of the existing options because the parameter parameter reorder was set to false.
Example 1.2. - Updating a Cascading Select Custom Field - Disable existing options and add the others
| Code Block |
|---|
admUpdateCustomFieldOptions("CF _CASCADE", "updateoptions .txt", " ", "NONEDELETE", "DISABLENONE", {}, {}, false, false, falsetrue, truefalse);
|
The resulted field options will now be:
| Code Block |
|---|
Parent3
NewChild |
...
Example 1 - Updating a Cascading Select Custom Field
For Example 1.1 and Example 1.2 we will consider as a starting point, the following already existing options of the custom field:
| Code Block |
|---|
Parent1(disabled)
Child1(disabled)
Child2(disabled)
Child3
Parent2(disabled)
Child4
Child5
Parent3
NewChild |
| Note |
|---|
The disabled options are still visible on the issues where the custom field value has been set before the DISABLE operation took place. They will not show anymore on the new issues or issues that have ENABLED values set in the custom field. |
Example 2 - Updating other custom fields
Updating custom fields with types different than cascading select, works exactly the same, except the fact that the applyActionsOnParentOptions parameter should always be set to true.
This is because these types of fields only use parent options (no child options).
...
and as an input file, "updateoptions.txt" could look something like this, for cascading select:, that has the following contents:
| Code Block |
|---|
Option 1
Child option 1
Child option 2
Option 2
Child option 3
Child option 4 |
and something like this for the other supported types (single select, multi select, radio buttons and checkboxes):
| Code Block |
|---|
Option 1
Option 2
Option 3
|
Updating custom fields with types different than cascading select, works exactly the same, except the fact that the applyActionsOnParentOptions parameter should always be set to true.
See also
| Filter by label (Content by label) |
|---|
| showLabels | false |
|---|
| max | 25 |
|---|
| showSpace | false |
|---|
| cql | label = "jiracustomfield_fieldadmin_routine" and space = currentSpace ( ) |
|---|
| labels | jiraarray_attachment_routineroutines |
|---|
|