You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by zk...@apache.org on 2023/07/20 15:48:56 UTC
[incubator-devlake-website] branch main updated: docs: updated jira config doc (#597)
This is an automated email from the ASF dual-hosted git repository.
zky pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 49df5f19c5 docs: updated jira config doc (#597)
49df5f19c5 is described below
commit 49df5f19c50cbbdc5dbbc0f4fdecf786db58785d
Author: Yumeng Wang <yu...@merico.dev>
AuthorDate: Thu Jul 20 23:48:51 2023 +0800
docs: updated jira config doc (#597)
---
docs/Configuration/Jira.md | 87 +++++++++++++--------
.../images/add-a-connection-project.png | Bin 0 -> 76516 bytes
docs/Configuration/images/collect-data.png | Bin 0 -> 74240 bytes
docs/Configuration/images/create-a-project.png | Bin 0 -> 93626 bytes
docs/Configuration/images/jira-add-data-scopes.png | Bin 0 -> 107464 bytes
docs/Configuration/images/sync-policy.png | Bin 0 -> 57804 bytes
6 files changed, 53 insertions(+), 34 deletions(-)
diff --git a/docs/Configuration/Jira.md b/docs/Configuration/Jira.md
index 627e82d4f1..088028e485 100644
--- a/docs/Configuration/Jira.md
+++ b/docs/Configuration/Jira.md
@@ -8,49 +8,51 @@ Visit Config UI at: `http://localhost:4000`.
## Step 1 - Add Data Connections
+On the Connections page, you can select Jira and create a new connection or it.
+
+### Stept 1.1 - Authentication
+

-### Connection Name
+#### Connection Name
Give your connection a unique name to help you identify it in the future.
---------
-
-The configuration for the endpoint and authentication for your Jira connection depends on your Jira version, Jira Cloud or Server/Data Center.
+Please note: the following configuration for the endpoint and authentication for your Jira connection depends on your Jira version, Jira Cloud or Server/Data Center.
-### Jira Cloud
-#### Endpoint URL
+#### Jira Cloud
+##### Endpoint URL
This should be a valid REST API endpoint: `https://<mydomain>.atlassian.net/rest/`
Please note: the endpoint url should end with `/`.
-#### E-mail
+##### E-mail
Please enter the e-mail of your Jira account.
-#### API Token
+##### API Token
Learn about [how to create an API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
Please note: Jira API token and Personal Access Token are two different tokens.
-### Jira Server/Data Center
-#### Endpoint URL
+#### Jira Server/Data Center
+##### Endpoint URL
This should be a valid REST API endpoint: `https://jira.<mydomain>.com/rest/`
Please note: the endpoint url should end with `/`.
-#### Authentication Method
+##### Authentication Method
Jira Server supports two ways of authentication: using basic authentication or Personal Access Token.
-#### Username
+##### Username
Please enter the username of your Jira account.
-#### Password
+##### Password
Please enter the password of your Jira account.
-#### Personal Access Token
+##### Personal Access Token
Learn about [how to create a Personal Access Token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).
-### Token Permissions
+#### 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:
@@ -67,44 +69,40 @@ Before using the Jira API, users need to ensure that their account has at least
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)
+#### Proxy URL (Optional)
If you are behind a corporate firewall or VPN you may need to utilize a proxy server. Enter a valid proxy server address on your network, e.g. `http://your-proxy-server.com:1080`
-#### Fixed Rate Limit (Optional)
+##### Fixed Rate Limit (Optional)
DevLake uses a dynamic rate limit to collect Jira data. You can adjust the rate limit if you want to increase or lower the speed. If you encounter a 403 error during data collection, please lower the rate limit.
Jira(Cloud) uses a dynamic rate limit and has no clear rate limit. For Jira Server's rate limiting, please contact your Jira Server admin to [get or set the maximum rate limit](https://repository.prace-ri.eu/git/help/security/rate_limits.md) of your Jira instance. Please do not use a rate that exceeds this number.
-### Test and Save Connection
+#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save Connection` to add the connection.
-## Step 2 - Setting Data Scope
+### Step 1.2 - Add Data Scopes
-
-
-### Boards
+#### Boards
Choose the Jira boards to collect.
-### Data Entities
-
-Usually, you don't have to modify this part. However, if you don't want to collect certain Jira entities, you can unselect some entities to accerlerate the collection speed.
+
-- Issue Tracking: Jira issues, issue comments, issue labels, etc.
-- Cross Domain: Jira accounts, etc.
-## Step 3 - Adding Scope Config (Optional)
+### Step 1.3 - Add Scope Config (Optional)
Scope config contains two parts:
-- The entities of which domain you wish to collect
+- The entities of which domain you wish to collect: Usually, you don't have to modify this part. However, if you don't want to collect certain Jira entities, you can unselect some entities to accerlerate the collection speed.
+ - Issue Tracking: Jira issues, issue comments, issue labels, etc.
+ - Cross Domain: Jira accounts, etc.
- The transformations on the Jira data you are going to collect
- Issue Type: Standardize the issue types to DevLake's pre-defined three issue types: REQUIREMENT, BUG, and INCIDENT.
- Story Points: Map the custom field that represents story_point in your Jira to DevLake's issue story point.
- Cross-domain: Get the commit(s) associated with Jira issues from Jira issues' remote links or development panels.
-Although this configuration is an optional, some of above transformations are required to measure metrics such as [Requirement Lead Time](https://devlake.apache.org/docs/Metrics/RequirementLeadTime), [Bug Age](https://devlake.apache.org/docs/Metrics/BugAge) or [DORA - Median Time to Restore Service](https://devlake.apache.org/docs/Metrics/MTTR) in the built-in Grafana dashboards.
+Although this configuration is optional, some of the above transformations are required to measure metrics such as [Requirement Lead Time](https://devlake.apache.org/docs/Metrics/RequirementLeadTime), [Bug Age](https://devlake.apache.org/docs/Metrics/BugAge) or [DORA - Median Time to Restore Service](https://devlake.apache.org/docs/Metrics/MTTR) in the built-in Grafana dashboards.


@@ -116,7 +114,7 @@ Without adding transformation rules, you can not view all charts in "Jira" or "E
Each Jira board has at most ONE set of transformation rules.
-### Issue Tracking
+#### Issue Tracking
- Requirement: choose the issue types to be transformed to "REQUIREMENT".
- Bug: choose the issue types to be transformed to "BUG".
@@ -124,13 +122,34 @@ Each Jira board has at most ONE set of transformation rules.
- Epic Key: choose the custom field that represents Epic key. In most cases, it is "Epic Link".
- Story Point: choose the custom field that represents story points. In most cases, it is "Story Points".
-### Additional Settings
+#### Additional Settings
- Remotelink Commit SHA: parse the commits from an issue's remote links by the given regular expression so that the relationship between `issues` and `commits` can be created. You can directly use the regular expression `/commit/([0-9a-f]{40})$`.
-## Step 4 - Setting Sync Frequency
+## Step 2 - Collect Data in a Project
+### Step 2.1 - Create a Project
+Collecing Jira data reuiqres creating a project first. You can visit the Project page from the side menu and create a new project by following the instructions on the user interface.
+
+
+
+### Step 2.2 - Add a Jira Connection
+You can add a previously configured Jira connection to the project and select the boards for which you wish to collect the data for.
+Please note: if you don't see the boards you are looking for, please check if you have added them to the connection first.
+
+
+
+### Step 2.3 - Set the Sync Policy
+There are three settings for Sync Policy:
+- Data Time Range: You can select the time range of the data you wish to collect. The default is set to the past six months.
+- Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your prefered schedule.
+- Skip Failed Tasks: sometime a few tasks may fail in a long pipeline; you can choose to skip them to avoid spending more time in running the pipeline all over again.
+
+
+
+### Step 2.4 - Start Data Collection
+Click on "Collect Data" to start collecting data for the whole project. You can check the status in the Status tab on the same page.
+
-You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your prefered schedule.
## Troubleshooting
diff --git a/docs/Configuration/images/add-a-connection-project.png b/docs/Configuration/images/add-a-connection-project.png
new file mode 100644
index 0000000000..2e619b6bf7
Binary files /dev/null and b/docs/Configuration/images/add-a-connection-project.png differ
diff --git a/docs/Configuration/images/collect-data.png b/docs/Configuration/images/collect-data.png
new file mode 100644
index 0000000000..962cb164ad
Binary files /dev/null and b/docs/Configuration/images/collect-data.png differ
diff --git a/docs/Configuration/images/create-a-project.png b/docs/Configuration/images/create-a-project.png
new file mode 100644
index 0000000000..7d95a9b822
Binary files /dev/null and b/docs/Configuration/images/create-a-project.png differ
diff --git a/docs/Configuration/images/jira-add-data-scopes.png b/docs/Configuration/images/jira-add-data-scopes.png
new file mode 100644
index 0000000000..a85fd7045a
Binary files /dev/null and b/docs/Configuration/images/jira-add-data-scopes.png differ
diff --git a/docs/Configuration/images/sync-policy.png b/docs/Configuration/images/sync-policy.png
new file mode 100644
index 0000000000..1147e41377
Binary files /dev/null and b/docs/Configuration/images/sync-policy.png differ