en-US/about_JiraPS_CustomFields.help.txt
|
TOPIC
about_jiraps_customfields SHORT DESCRIPTION Jira has fields of all possible types. Strings, text boxes, numbers, dropdown menus, lists, aso. This article explains how to pass the desired value for each of them. LONG DESCRIPTION Many of JiraPS's functions contain convenience parameters for issue fields that are commonly used. These parameters take care of translating PowerShell to the correct JSON format when working with Jira's API. However, not every standard Jira field is implemented via a parameter, and most Jira instances also contain custom fields to allow your organization to tailor its Jira instance to your own requirements. To allow JiraPS to work with fields that do not have named parameters, these functions support a generic `-Fields` parameter. Using -Fields Basically, `-Fields` uses a hashtable that looks something like this: $fields = @{ fieldName = @{ value = 'New Value' } fieldID = @{ id = 'ID of new value or item' } } Set-JiraIssue -Fields $fields > This isn't a super easy syntax - and the module authors are always open to ideas for ways to improve this. There are two easy ways to know more about a specific field: - use the `Get-JiraField` function. This can tell you a lot about what to pass in the Fields hashtable. - use the `Get-JiraIssue | Format-List *` function on an issue that has the value you are looking for. SOME KNOWN FIELD FORMATS Here are some notes on specific fields that have come up in the past. TEXT FIELD A text field is a single line of text that requires the value to be a string. Examples are: - Summary $fields = @{ summary = "This is an example" } TEXT AREA A text field with multiple lines of text that requires the value to be a string. Examples are: - Description $fields = @{ description = @" This is an example with multiple lines of text "@ # this uses the here-string to pass a multiline value } NUMBER A number field requires the value to be an Integer. $fields = @{ customfield_11444 = 123 } ARRAY A custom field that is an array of strings. Examples are: - Labels $fields = @{ labels = @( "nameOfTheLabel" ) } SINGLE-SELECT A custom field that allows you to select a single value from a defined list of values. You can address them by 'value' or by 'id'. $fields = @{ customfield_11449 = { value = "option3" } # or: customfield_11449 = { id = 10112 } } MULTI-SELECT Multi-value fields require the value to be an array, even if you're only defining one value. Examples are: - Component/s $fields = @{ components = @( @{ name = 'Component 1' } ) } DATE PICKER A date is passed as a string in the 'YYYY-MM-DD' format. Examples are: - DueDate $fields = @{ duedate = "2017-12-31" } DATETIME PICKER A custom field that is a datetime in ISO 8601 `YYYY-MM-DDThh:mm:ss.sTZD` format. $fields = @{ customfield_11442 = "2015-11-18T14:39:00.000+1100" } # or (the automated way of using a [DateTime] object): $date = Get-Date $fields = @{ customfield_11442 = $date.ToString("o") -replace "\.(\d{3})\d*([\+\-]\d{2}):", ".`$1`$2" } > The "automated way of using a [DateTime] object" mentioned above is needed, as Powershell's `Get-Date -format "o"` differs from what Jira supports: > PoSh: `2015-11-18T14:39:00.0000000+11:00` > Jira: `2015-11-18T14:39:00.000+1100` CHECKBOX A custom field that allows you to select a multiple values from a defined list of values. You can address them by 'value' or by 'id'. $fields = @{ customfield_11440 = @( @{ value = "Text of the first checkbox" } @{ value = "Text of the third checkbox" } ) # or: customfield_11440 = @( @{ id = 10112} # id of the first checkbox @{ id = 10114} # id of the third checkbox ) } RADIO BUTTON A custom field that allows you to select a single value from a defined list of values. You can address them by 'value' or by 'id'. $fields = @{ customfield_11445 = @{ "value" = "Text of the option" } # or: customfield_11445 = @{ "id" = 10112 } # id of the option } USER PICKER A custom field that allows a single user to be selected. The user is identifies by the username. $fields = @{ customfield_11453 = @{ name = "tommytomtomahawk" } } MULTI-USER PICKER A custom field that allows multiple users to be selected. The user is identifies by the username. $fields = @{ customfield_11458 = @( @{ name = "inigomontoya" } @{ name = "tommytomtomahawk" } ) } CASCADING PICKER A custom field that allows you to select a multiple values from a defined list of values. You can address them by 'value' or by 'id'. $fields = @{ customfield_11447 = @{ value = "parent_option1" child = @{ value = "p1_child1" } } # or: customfield_11447 = @{ id = 10112 child = @{ id = 10115 } } } FINDING ALLOWED VALUES Use `Get-JiraField` and look for the AllowedValues property. This will give you both an ID and a value for each "item" your field is allowed to be. (Get-JiraField "Urgency").AllowedValues Then, use this syntax described above. EXAMPLES The following extensive example contains several types of custom fields as input for a new Jira issue. $fields = @{ project = "TV" issuetype = "bug" summary = "Important Issue" description = "This Issue is *very* important\n\n really!?" Assignee = "admin" Reporter = "admin" Priority = 1 Fields = @{ labels = @("important", "notreally") fixVersion = @( @{ name = "Release 1.1"} ) customfield_10001 = @{ name = "item from a dropdown" } duedate = "2020-01-01" } } NOTE If you run into any additional fields that you'd like to see documented, feel free to let me know in a GitHub issue - or submit a PR to this page with the field! SEE ALSO Jira REST Api - Field input formats KEYWORDS - customfield |