This is an automated email from the ASF dual-hosted git repository. yumeng pushed a commit to branch docs-yumeng in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 27f5760229f8aa50c912f0468cb592495abe0a9b Author: yumengwang03 <[email protected]> AuthorDate: Wed Apr 26 17:15:25 2023 +0800 docs: updated Jira configuration images and text --- docs/Configuration/Jira.md | 55 +++++++++++++-------- .../images/jira-create-a-connection.png | Bin 0 -> 251873 bytes docs/Configuration/images/jira-set-data-scope.png | Bin 0 -> 145731 bytes .../images/jira-set-transformation1.png | Bin 0 -> 88605 bytes .../images/jira-set-transformation2.png | Bin 0 -> 246495 bytes .../images/jira-set-transformation3.png | Bin 0 -> 63077 bytes 6 files changed, 34 insertions(+), 21 deletions(-) diff --git a/docs/Configuration/Jira.md b/docs/Configuration/Jira.md index 099063172f..bbb538e38d 100644 --- a/docs/Configuration/Jira.md +++ b/docs/Configuration/Jira.md @@ -4,50 +4,60 @@ sidebar_position: 4 description: Config UI instruction for Jira --- -Visit config-ui: `http://localhost:4000`. +Visit Config UI at: `http://localhost:4000`. ### Step 1 - Add Data Connections - + #### Connection Name -Name your connection. +Give your connection a unique name to help you identify it in the future. -#### Endpoint URL +#### Jira Version +Select if you use Jira Cloud or Jira Server. Jira Cloud has only one authentication method by using the API token, while Jira Server supports two ways of authentication: using basic authentication or Personal Access Token. -This should be a valid REST API endpoint +#### Endpoint URL +This should be a valid REST API endpoint. -- If you are using Jira Cloud, the endpoint will be `https://<mydomain>.atlassian.net/rest/` -- If you are self-hosting Jira v7+ or v8+, the endpoint may look like `https://jira.<mydomain>.com/rest/` - The endpoint url should end with `/`. +- Jira Cloud: the endpoint will be `https://<mydomain>.atlassian.net/rest/` +- Jira Server: the endpoint will be `https://jira.<mydomain>.com/rest/` + +Please note: the endpoint url should end with `/`. -#### Username / Email +#### E-mail +For Jira Cloud only: please enter the e-mail of your Jira account. -Input the username or email of your Jira account. +#### Username +For Jira Server only: please enter the username of your Jira account. #### Password +For Jira Server only: please enter the password of your Jira account. -- If you are using Jira Cloud, please input the [Jira personal access token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html). -- If you are using Jira Server v7+ or v8+, please input the password of your Jira account. +#### API Token +For Jira Cloud only: learn about [how to create an API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). -#### Auth Token +Please note: Jira API token and Personal Access Token are two different tokens. -When accessing Jira API using a Jira Auth Token, users may encounter access restrictions if their token does not have sufficient permissions. This is typically caused by insufficient scope or role settings for the Jira Auth Token. +#### Personal Access Token +For Jira Server only: learn about [how to create a Personal Access Token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html). + +#### Token Permissions +For both Jira Cloud and Jira Server, when accessing Jira API, users may encounter access restrictions if their token does not have sufficient permissions. This is typically caused by insufficient scope or role settings for the Jira token. To solve this issue, users can take the following steps: - Checking User Permissions -Users can confirm whether they have sufficient permissions by checking their permissions in Jira. For cloud users, they can view their global and project permissions through the "Permissions" tab on the "Profile" page. For server users, they can log in to Jira as an administrator and view user permissions on the "User Management" page. +Users can confirm whether they have sufficient permissions by checking their permissions in Jira. For Cloud users, they can view their global and project permissions through the "Permissions" tab on the "Profile" page. For Server users, they can log in to Jira as an administrator and view user permissions on the "User Management" page. - Ensuring Sufficient Permissions -Before using Jira API, users need to ensure that their account has at least the necessary project or global permissions. Global permissions include various Jira system settings and management operations, while project permissions control specific operations and configurations for each Jira project. Users can assign roles such as `Project Administrator`, `Project Lead`, `Developer`, etc. for the corresponding projects, or assign global permissions such as `Jira Administrators`, `Jira Soft [...] +Before using the Jira API, users need to ensure that their account has at least the necessary project or global permissions. Global permissions include various Jira system settings and management operations, while project permissions control specific operations and configurations for each Jira project. Users can assign roles such as `Project Administrator`, `Project Lead`, `Developer`, etc. for the corresponding projects, or assign global permissions such as `Jira Administrators`, `Jira [...] - Solving Access Restrictions -To solve access restrictions caused by insufficient Jira Auth Token permissions, users should check the token's permission settings to ensure the correct scope and role are set. If the permission settings are correct but the required API is still inaccessible, consider using other authentication methods, such as authenticating with a username and password. If the issue persists, contact the Jira administrator for further assistance. +To solve access restrictions caused by insufficient Jira token permissions, users should check the token's permission settings to ensure the correct scope and role are set. If the permission settings are correct but the required API is still inaccessible, consider using other authentication methods, such as authenticating with a username and password. If the issue persists, contact the Jira administrator for further assistance. #### Proxy URL (Optional) @@ -65,9 +75,9 @@ Click `Test Connection`, if the connection is successful, click `Save Connection ### Step 2 - Setting Data Scope - + -#### Projects +#### Boards Choose the Jira boards to collect. @@ -79,14 +89,17 @@ Usually, you don't have to modify this part. However, if you don't want to colle - Cross Domain: Jira accounts, etc. ### Step 3 - Adding Transformation Rules (Optional) +Adding transforamtion to the Jira data you wish to collect can help standardize the data to view more metrics, such as [Requirement Lead Time](https://devlake.apache.org/docs/Metrics/RequirementLeadTime), [Bug Age](https://devlake.apache.org/docs/Metrics/BugAge) and DORA - [Median Time to Restore Service](https://devlake.apache.org/docs/Metrics/MTTR). + + + + - Without adding transformation rules, you can not view all charts in "Jira" or "Engineering Throughput and Cycle Time" dashboards.<br/> Each Jira board has at most ONE set of transformation rules. - #### Issue Tracking diff --git a/docs/Configuration/images/jira-create-a-connection.png b/docs/Configuration/images/jira-create-a-connection.png new file mode 100644 index 0000000000..68fb73bc6b Binary files /dev/null and b/docs/Configuration/images/jira-create-a-connection.png differ diff --git a/docs/Configuration/images/jira-set-data-scope.png b/docs/Configuration/images/jira-set-data-scope.png new file mode 100644 index 0000000000..27dd8b1edb Binary files /dev/null and b/docs/Configuration/images/jira-set-data-scope.png differ diff --git a/docs/Configuration/images/jira-set-transformation1.png b/docs/Configuration/images/jira-set-transformation1.png new file mode 100644 index 0000000000..b0e4804368 Binary files /dev/null and b/docs/Configuration/images/jira-set-transformation1.png differ diff --git a/docs/Configuration/images/jira-set-transformation2.png b/docs/Configuration/images/jira-set-transformation2.png new file mode 100644 index 0000000000..3e43beaa92 Binary files /dev/null and b/docs/Configuration/images/jira-set-transformation2.png differ diff --git a/docs/Configuration/images/jira-set-transformation3.png b/docs/Configuration/images/jira-set-transformation3.png new file mode 100644 index 0000000000..bbfd891fba Binary files /dev/null and b/docs/Configuration/images/jira-set-transformation3.png differ
