Wiki
Clone wikiProject Team / Cloud
Project Team for Jira Cloud
On this page:
- Project Team for Jira Cloud
- What this app does?
- Adding user custom fields
- Configuring edit permissions
- Viewing and editing the user custom field values on the Advanced Profile page
- Displaying Organizational Charts
- Visualizing the Project Team
- Displaying the Team Members Info on Jira dashboards
- REST API
- Migrating app data from Connect to Forge
- Migration from Jira Server / Data Center to Jira Cloud
What this app does?
Project Team for Jira Cloud is an app for Jira Cloud that allows extending the profiles by adding custom attributes like Phone Number, Bio or Skills. Once defined, the custom fields become visible on an Advanced Profile page for each user and in the issue screen from Jira.
The Jira issue screen displays the advanced attributes of the issue's reporter and assignee.
Also, this app 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. From this page you can access the Advanced Profile page of each user for visualizing and editing their custom fields.
With this app you also can generate and display organizational charts based on your Jira users and their hierarchical relationships. The organizational charts are automatically generated based on those custom fields (and their values) that indicate the hierarchical relationship between the Jira users.
Adding user custom fields
The Jira administrators can add, edit or delete the user custom fields on the Profile Custom Fields page located in the Jira Settings area under Apps > PROJECT TEAM section.
Adding a user custom field
To add a new user custom field:
- Log on as a Jira admin
- Navigate to Jira Settings > Apps > PROJECT TEAM > Profile Custom Fields page
- Click the Add Custom Field button
- 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.
- Choose where the new field to be displayed. If you check Show on User Advanced Profile, it will be displayed on the User Advanced Profile page of every user. If you check Show on View Issue Screen, the field will be displayed on "User additional attributes" section from the View screen of the Jira issues, but only if the field has a value.
NOTE: The User Advanced Profile page displays all the fields, regardless their Show on User Advanced Profile setting, to the users that have permissions for editing the field values.
- 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 Settings > Apps > PROJECT TEAM > 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 Settings > Apps > PROJECT TEAM > 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 Yes 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 these steps to grant edit permissions to a user or group:
- Log on as a Jira admin
- Navigate to Jira Settings > Apps > PROJECT TEAM > Permissions page
- Add the group or user to the list
- Click Save
NOTE: Regardless of these settings, the Jira users are allowed to edit the custom fields of their own Advanced Profile page. Also, the Jira administrators can edit the custom fields of any Jira user.
Viewing and editing the user custom field values on the Advanced Profile page
The value of the custom fields of a specific user profile can be visualized and set on the Advanced Profile page of that user.
Any Jira user can access his own Advanced Profile page by clicking the Apps>User Advanced profile menu-option of the Jira top menu bar.
The Advanced Profile page of another user can be opened from the Project Team tab of the Jira project the user belongs to, by clicking the user's display name.
Or, if you are on the view issue screen and the user is the issue's reporter or assignee, you can click the Advanced Profile link from the User additional attributes area of that user.
Once you reached the field to be edited, click its edit icon and change its value as you want.
The users can set their own custom field values. Special permissions are required to set the custom field values of the other users (see "Configuring edit permissions").
Displaying Organizational Charts
The organizational charts can be displayed on your Jira dashboards by using the Organizational Chart gadget. For the organizational chart to be generated, you must have a user custom field of type User Picker representing the hierarchical relationship between the Jira users. Also, the fields must be properly set on the user's Advanced Profile page. 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 the user Advanced Profile page, follow these steps to display the organizational chart:
- Go to your Jira dashboard and click Add gadget
- Search for the org chart gadget and add it
- Enter the gadget settings as described in the table below
Setting | Description |
---|---|
Top-down Relationship Field | The user custom field defined in the app settings representing the hierarchical relationship between the Jira users. |
Diagram Root | Represents 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 title | Is a user custom field of type Text defined in the app 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 ? levels | Indicates the max number of levels the org chart can have. |
Show Avatar | Indicates if the user avatars will be displayed in the org chart. |
- Click Save. The organizational chart will be generated and displayed on your dashboard.
Visualizing the Project Team
The Project Team tab of a project displays those Jira users that have a role in that specific project.
Go to Project Settings > People and assign the users to project roles, so that they can be displayed on the Project Team tab of the project. In case you don't have the project roles created, new project roles can be added in Jira Settings > System > Project Roles.
Displaying the Team Members Info on Jira dashboards
You can also display the team of a project on your Jira dashboards by using the Team Members Info gadget.
Assuming that you already have a dashboard, follow these steps to display the project team on it:
- Go to your Jira dashboard and click Edit
- Search for the Team Members Info gadget and add it
- Enter the gadget settings as described in the table below
Setting | Description |
---|---|
Project | The Jira project for which the team will be displayed. |
Columns to display | The user attributes to be displayed in the gadget as columns. The user custom fields defined in the app can be also selected. You can change the display order of the fields by moving them up or down. |
Avatar size | The size of the avatars displayed in the gadget. |
- Click Save. The team of the selected project is now displayed on your dashboard.
REST API
Retrieving the custom field values for the users
The value of the custom fields 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/3/user/properties/CUSTOM_FIELD_ID?accountId=USER_ACCOUNT_ID&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:
Parameter | Description |
---|---|
CUSTOM_FIELD_ID | The 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_ACCOUNT_ID | The accountId of the Jira user for which you want to retrieve the value. |
An example of the request URL with parameters is as follows:
https:/ /myjira.atlassian.net/rest/api/3/user/properties/1667729115557?accountId=557058%3A682699a7-c8dd-4c7a-bc1f-00972ca096c4&jsonValue=true
In this example the value of field with id "1667729115557" of the user with account id 557058%3A682699a7-c8dd-4c7a-bc1f-00972ca096c4 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":"1667729115557","value":{"value":"Programmer","customFieldId":1667729115557}}
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
400 | Returned if the user key or id is invalid. |
401 | Returned if the calling user is not authenticated. |
403 | Returned if the calling user does not have permission to browse the user. |
404 | Returned if the user with given key does not exist or if the specified field ID does not exist. |
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 Settings > Apps > PROJECT TEAM > Profile Custom Fields page
- In the table with the available fields, hover the mouse cursor over the field. The field id is displayed in a tooltip.
Migrating app data from Connect to Forge
Project Team has been recently ported to Forge - the Atlassian's brand-new platform for apps development on Jira and Confluence Cloud. Initially, the app was created on top of the Atlassian Connect platform, which will be deprecated in the future.
After upgrading Project Team from a Connect-based version (1.2.x) to a Forge-based version (3.x or newer), the old app data consisting in the user custom fields and edit permissions is not visible in the new app until a data migration is performed.
Follow these steps to perform the app data migration from Connect to Forge:
- Log in to Jira Cloud as an admin
- Navigate to Jira Settings > Apps > PROJECT TEAM > Migration page
- If the migration was not performed yet, click Migrate
- Check the migration progress and status. In case of any errors, try again. If the errors persist, please contact StonikByte Support (support@stonikbyte.com) for assistance.
Migration from Jira Server / Data Center to Jira Cloud
There is currently no migration path from Jira Server / Data Center to Jira Cloud. The only method is to recreate the data manually.
Please also note that there are significant differences in functionality/features between the Server/Data Center and the Cloud version of Project Team.
Functionality / Feature | Availability on Server/Data Center | Availability on Cloud |
Project Team tab on each Jira project | Yes | Yes |
Project Team tab displayed by project members | Yes | Yes |
Project Team tab displayed by project roles | Yes | No |
Project Team tab displays the user advanced attributes (user custom fields) | Yes | No |
User custom fields of type "Single Line Text" | Yes | Yes |
User custom fields of type "Multi Line Text" | Yes | Yes |
User custom fields of type "Multi Value Picker" | Yes | Yes |
User custom fields of type "User Picker" | Yes | Yes |
Display of user advanced attributes (user custom fields) on Jira User Profile page | Yes | No - Instead, it introduces a separate page called Advanced User Profile, where advanced attributes are displayed. |
Custom fields for displaying the advanced attributes of issue's reporter/assignee on the Jira issue screens and issue search results | Yes | No - Instead, it displays the advanced attributes of the reporter/assignee in the right pane of the Jira issue screen. |
JQL function getUsersByAdditionalAttribute | Yes | No |
Options for configuring where the user custom fields are displayed | Yes | Yes |
Options for configuring the display order of the user custom fields | Yes | No |
Project Team dashboard gadget | Yes | Yes |
Organizational Chart dashboard gadget | Yes | Yes |
Global Permissions settings | Yes | Yes |
Project Team REST API | Yes | No - Retrieving Jira user custom field values is possible through the Jira REST API. |
Updated