Introduction
User Property Manager introduces two new custom field types to your JIRA system that can be used to display and edit user property information on JIRA issues.
- Text User Property Value
- Select List User Property Value
Adding Fields
UPM custom fields are added to JIRA just like any other custom field. To add new fields, navigate to Administration >> Issues >> Custom Fields and click on Add Custom Field. This should display a Custom Field Create Wizard which will include your new UPM fields.
- Text User Property Field is a simple text field that displays and edits user properties on JIRA issues. Any valid property text value can be used with this field.
- Select List User Property Field works much like a JIRA Select List. It displays the current property value in view screens but when editing it allows the user to select from a predefined set of values.
Configuring Fields
In order to display user properties on JIRA issues, the new fields must be configured first.
To get to configuration pages of a field
- Navigate to Administration >> Issues >> Custom Fields
- Locate the UPM field in the list.
- Click the cog icon next to the custom field and select Configure.
- In the Configure Custom Field page that opens, click on "Edit Text User Property Field" link or "Edit Select List User Property Field" link, depending on the type of your custom field.
- When clicked one of the two screens shown below should appear, depending on the custom field type.
User Property Text Field Configuration
User Property Select List Field Configuration
UPM custom fields have the parameters listed below that need to be configured:
Reference User Custom Field
This drop down box lists all the single-user picker fields in the system and sets the field from which the owner of the property will be taken from. In other words, your UPM field will display the user property of the user set in this field.
It also contains options to select assignee or reporter fields as reference fields.
This field should not be left blank as it is required for your UPM custom field to function properly.
Property Name
You should enter the exact property name which you want to display on your UPM field.
Be careful when entering this value because JIRA does not contain a master list of properties. If you enter an incorrect name, UPM field will not complain and try to display and edit a property with that name. If it cannot find a property with that name, it sure will create one for the user.
This field should not be left blank as it is required for your UPM custom field to function properly.
Options
This field is available only for Select List User Property Field and sets the possible options for the user property.
You should enter a comma separated string of values to this field to define the options. Ex:
Red, Green, Blue, Yellow
You can also start with a comma to enter an empty value to the option list. Ex:
, Red, Green, Blue, Yellow
You can define an empty value as explained above when you need to configure this field as a required field. The empty value will fail the "Required" condition of Field Configurations. The empty value will also fail field required validator functions provided by most Jira apps.
If options list is left completely blank, this field will display the existing user property value on JIRA issues. When editing, it will display a list with only one options, which is the existing value.
Issue View Screen
UPM Custom Fields are added to JIRA issue screens just like any other custom field. On JIRA View screens, the fields will display the values of the set Property Name for the user in the Reference User Field.
If the user does not have the property, the field will just not appear on the issue.
Issue Navigator
You can also add UPM fields to JIRA Issue Navigator screen as columns. They will display the user property values and also will show values in CSV or XML exports.
UPM Fields do not yet support JQL searches by user property values.
Issue Edit Screen
When added to the edit screen, UPM Fields will display editors to change user property values.
Text User Property Field will display a text box for editing. Select List Property Field will display a drop down list for editing.
If you remove the value from a UPM field (delete the text in Text UPM field or select the empty option in Select List UPM field.) the property value will be removed from the user.
You can display the fields in edit screen or transition screens to let end-users edit property values.
In order to limit who can change user property values through UPM fields, you should remove UPM fields from Edit screen of your issue and use transition screens to edit values of these fields. Since you can set conditions for transitions, this will effectively act as a permission set for editing property values. (Please note that you can define transitions from a status to the same status, which in practice serves as a controlled Edit screen)
Please note that when editing, UPM fields operate according to the latest value in the Reference User Field. This means if you change both the property values and the reference user field value on the same screen, the property updates will be performed on user that is the new value of the reference user field.