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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
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