en-US/about_JiraPS_CustomFields.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
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