Clone wiki

User Custom Fields Add-on / Home

Project Team for Jira Cloud Add-on

On this page:

What the add-on does?

Project Team for Jira Cloud is an add-on for Jira Cloud that: 1) allows extending the profiles of the user by adding custom fields, 2) generates and displays organizational charts and 3) displays the team of your projects as described below.

The user profiles can be extended by adding custom attributes like Phone Number, Bio or Skills. Once defined, the custom fields become available on the user profile page on a new tab named Additional Attributes.

Extended user profile

With this add-on you can generate and display org charts based on your Jira users and their hierarchical relationships. The org charts are automatically generated based on those custom fields (and their values) that indicate the hierarchical relationship between the Jira users.

The Org Chart gadget

Also this add-on makes visible the team of the project by displaying its members and their roles in a tab named “Project Team” added to the project dashboard.

The Project Team tab of the project dashboard

Adding user custom fields

The Jira administrators can add, edit or delete the user custom fields on the Profile Custom Fields page located in Jira Administration area user Add-Ons > Project Team for Jira Cloud Add-On section.

Adding a user custom field

To add a new user custom field:

  • Log on as a Jira admin
  • Navigate to Jira Administration > Add-Ons > Project Team Add-on > Profile Custom Fields page
  • Click the Add Custom Field button

Adding a user custom field

  • Select the Type of the new field
  • Enter a Name for the new custom field
  • Optionally, type a Description
  • If you choose to add a Multi Line Text field, you can add one or more items that represent the possible values of the field.
  • Click Save

Modifying a user custom field

To modify the attributes of a user custom field:

  • Log on as a Jira admin
  • Navigate to Jira Administration > Add-Ons > Project Team Add-on > Profile Custom Fields page
  • In the table with available fields, locate the custom field that you want to modify and click its Edit icon
  • Modify the field's attributes as you want
  • Click Save

Deleting a user custom field

To delete a user custom field:

  • Log on as a Jira admin
  • Navigate to Jira Administration > Add-Ons > Project Team Add-on > Profile Custom Fields page
  • In the table with available fields, locate the custom field that you want to modify and click its Delete icon
  • If you are really sure that you want to delete the custom field, click Delete in the confirmation window

Configuring edit permissions

You can allow specific Jira users or groups to edit the custom fields of the users. For instance, a manager or your HR department. Follow thse steps to grant edit permissions to a user or group:

  • Log on as a Jira admin
  • Navigate to Jira Administration > Add-Ons > Project Team Add-on > Permissions page
  • Add the group or user to the list
  • Click Save

Setting edit permissions

NOTE: Regardless these settings, the Jira users are allowed to edit the custom fields of their own profile. Also, the Jira administrators can edit the custom fields of any Jira user.

Editing the user custom field values

The value of the custom fields of a specific user profile can be set by the user herself or by the Jira administrators on the Additional Attributes tab of that profile by clicking the Edit icon of the field.

Setting the value of a user custom field

Displaying Org Charts

The org charts can be displayed on your Jira dashboards by using the Org Chart gadget. For the org chart to be generated, you must have a user custom field of type User Picker representing the hierarchical relationship between your Jira users. Also, the fields must be properly set on the user profiles. See "Adding a user custom field" above for how to add such field.

Assuming that you already have a dashboard created and at least one User Picker custom field defined and set on user profiles, follow these steps to display the org chart:

  • Go to your Jira dashboard and click Add gadget
  • Search for the org chart gadget and add it

Adding the Org Chart gadget

  • Enter the gadgets settings as described in the table below

Setting-up the Org Chart gadget

SettingDescription
Gadget TitleChoose what to display in the title bar of the gadget.
Top-down Relationship FieldThe user custom field defined in the add-on settings representing the hierarchical relationship between the Jira users.
Diagram RootRepresents the Jira user that will be displayed on the top-level of the chart. In case of a company org chart, this is usually the CEO. Use the Search user and then select the user.
Field representing the person's titleIs a user custom field of type Text defined in the add-on settings that usually represents the job title of the person. The value of this field will be displayed in the org chart under the user's full name.
Limit Diagram to ? levelsIndicates the max number of levels the org chart can have.
Show AvatarIndicates if the user avatars will be displayed in the org chart.
  • Click Save. The org chart will be generated and displayed on your dashboard.

The Org Chart gadget

Displaying the Project Team

The Project Team tab of a project displays those Jira users that have a role in that specific project.

The Project Team tab of the project dashboard

Go to Project Settings > People and assign the users on project roles so that they can be displayed on the Project Team tab. In case you don't have the project roles created, new project roles can be added in Jira Administration > Project Roles.

REST API

Retrieving the custom fields values for the users

The value of the custom field for a specific Jira user can be retrieved programmatically by using the REST API method below.

Request URL

The request URL takes the following form:
https:/ /MY_Jira_BASE_URL/rest/api/2/user/properties/CUSTOM_FIELD_ID?userKey=USER_KEY&jsonValue=true
Replace "http:/ /MY_Jira_BASE_URL" with the base URL of your Jira server and the parameters as described below.

Parameters

You have to specify the following parameters:

ParameterDescription
CUSTOM_FIELD_IDThe ID of the user custom field for which you want to retrieve the value. See "Determining the ID of a custom field" below for how to determine the ID of the field.
USER_KEYThe key (username) of the Jira user for which you want to retrieve the value.

An example of the request URL with parameters is as follows:

https:/ /myJiraserver.atlassian.com/rest/api/2/user/properties/1499867425717?userKey=john&jsonValue=true
In this example the value of field with id "1499867425717" of the user "john" is retrieved.

A successful response

An HTTP 200 status response indicates a successful request. The following data about the matching documents is returned in json format:

{"key":"1499867425717","value":{"value":"Programmer","customFieldId":1499867425717,"userKey":"john"}}

Error Response

If the REST call fails, the service returns one of the following HTTP statuses:

HTTP Status CodeDescription
400Returned if the user key or id is invalid.
401Returned if the calling user is not authenticated.
403Returned if the calling user does not have permission to browse the user.
404Returned if the user with given key does not exist or if the specified field ID does not exists.

Determining the ID of a custom field

To determine the ID of a user custom field:

  • Open Google Chrome
  • Log on as a Jira admin
  • Navigate to Jira Administration > Add-Ons > Project Team Add-on > Profile Custom Fields page
  • In the table with available fields, locate the custom field that you want to modify
  • Right click on the field name and then click Inspect.

Inspect element with Google Chrome

  • Identify the ID of the field. The prefix "row_" is not part of the field ID, so please ignore it.

Identifying the field's ID

Updated