Merge branch 'bugfix/fix-user-picker' into fix-user-picker

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,11 +6,22 @@ labels: ''
 assignees: ''
 ---
 
+# Read this before submitting your support ticket/bug report
+
+- [ ] Make sure that you have searched for your problem in the **FAQ**: <https://github.com/solidify/jira-azuredevops-migrator/blob/master/docs/faq.md>
+- [ ] Make sure that you have searched for your problem in the **issue board** (you can search for keywords in the **filters** search bar): <https://github.com/solidify/jira-azuredevops-migrator/issues?q=is%3Aissue+>
+- [ ] Fill in the issue template below (starting with **Describe the problem**)
+- [ ] Delete this section but keep the issue template
+---
+
 **Describe the problem**
+
 A clear and concise description of what the problem/bug is.
 
 **To Reproduce**
+
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'

docs/Samples/config-agile.json

@@ -29,6 +29,10 @@
         "source": "Parent",
         "target": "System.LinkTypes.Hierarchy-Reverse"
       },
+      {
+        "source": "Child",
+        "target": "System.LinkTypes.Hierarchy-Forward"
+      },
       {
         "source": "Relates",
         "target": "System.LinkTypes.Related"
@@ -75,6 +79,12 @@
         "target": "System.AssignedTo",
         "mapper": "MapUser"
       },
+      {
+        "source": "Sprint",
+        "source-type": "name",
+        "target": "System.IterationPath",
+        "mapper": "MapSprint"
+      },
       {
         "source": "description",
         "target": "System.Description",

docs/Samples/config-basic.json

@@ -29,6 +29,10 @@
         "source": "Parent",
         "target": "System.LinkTypes.Hierarchy-Reverse"
       },
+      {
+        "source": "Child",
+        "target": "System.LinkTypes.Hierarchy-Forward"
+      },
       {
         "source": "Relates",
         "target": "System.LinkTypes.Related"
@@ -71,6 +75,12 @@
         "target": "System.AssignedTo",
         "mapper": "MapUser"
       },
+      {
+        "source": "Sprint",
+        "source-type": "name",
+        "target": "System.IterationPath",
+        "mapper": "MapSprint"
+      },
       {
         "source": "description",
         "target": "System.Description",

docs/Samples/config-cmmi.json

@@ -103,6 +103,12 @@
                 "target": "System.AssignedTo",
                 "mapper": "MapUser"
             },
+            {
+                "source": "Sprint",
+                "source-type": "name",
+                "target": "System.IterationPath",
+                "mapper": "MapSprint"
+            },
             {
                 "source": "description",
                 "target": "System.Description",

docs/Samples/config-scrum.json

@@ -29,6 +29,10 @@
         "source": "Parent",
         "target": "System.LinkTypes.Hierarchy-Reverse"
       },
+      {
+        "source": "Child",
+        "target": "System.LinkTypes.Hierarchy-Forward"
+      },
       {
         "source": "Relates",
         "target": "System.LinkTypes.Related"
@@ -227,8 +231,9 @@
       {
         "source": "description",
         "target": "Microsoft.VSTS.TCM.ReproSteps",
-        "for": "Bug"
+        "for": "Bug",
+        "mapper": "MapRendered"
       }
     ]
   }
-}
+}

docs/faq.md

@@ -33,14 +33,15 @@ If you are still not able to authenticate. Try and run the tool as another user.
 
 - To map a custom field by value we have to add a mapping in the configuration file, using the custom field name:
 
-    ```
+```json
     {
         "source": "Custom Field Name Jira",
         "source-type": "name",
-        "target": "Custom.CustomFieldNameADO"
+        "target": "Custom.TargetField"
     },
+```
 
-- Alternatively, we can map the filed kay instead of the name. Inspect the REST API response to find the **field key** for your custom field. This is usually something like **customfield_12345**.
+- Alternatively, we can map the field key instead of the name. Inspect the REST API response to find the **field key** for your custom field. This is usually something like **customfield_12345**.
 
 Example:
 
@@ -51,7 +52,53 @@ Example:
 }
 ```
 
-## 4. How to migrate custom fields having dropdown lists?
+### (Troubleshooting) My custom field is not migrated correctly/not migrated at all.
+
+If your custom field is not imported correctly into Azure DevOps, please go through the following checklist and ensure that every step has been followed:
+
+1. Ensure that the field is created in the correct Azure DevOps process model, and that the field is existing on the correct work item type.
+2. Ensure that the `target` of your field mapping is set to the **Field reference name** of the ADO field, not the **Field name** (Observe that these two are different!!!)
+
+    For example, if the **field name** is `MyField`, the **field reference name** is usually something like `Custom.MyField` (for ADO Services) or `MyCompany.MyField` (for ADO Server). Spaces are not allowed in the **field reference name**.
+
+    Here is a reference sheet with all of the default fields: https://learn.microsoft.com/en-us/azure/devops/boards/work-items/guidance/work-item-field?view=azure-devops (click each field to open up the documentation page and view the field reference name).
+
+### (Troubleshooting) I receive errors like: **VS403691: Update to work item 165 had two or more updates for field with reference name 'Custom.XXX'. A field cannot be updated more than once in the same update."**
+
+This error is usually indicative of incorrect configuration on the user's side. Please follow the checklist [here](https://github.com/solidify/jira-azuredevops-migrator/blob/master/docs/faq.md#troubleshooting-my-custom-field-is-not-migrated-correctlynot-migrated-at-all) (the section above this one, in the same document) to ensure that you do not have any issues with your `config.json` file.
+
+## 4. Guideline for migrating multiple projects
+
+### Scenario 1: Single project
+
+When migrating a single project, you may have issues with links to other issues that are in other projects or otherwise not captured by the JQL query.
+
+You can include such linked issues (all parents, epic links and sub items) by setting the following property in the configuration file:
+
+```json
+  "download-options": 7
+```
+
+See <https://github.com/solidify/jira-azuredevops-migrator/blob/master/docs/config.md#download-options> for more information on the `download-options` property.
+
+### Scenario 2: Multiple projects
+
+When migrating multiple project, one after another (or otherwise running several migrations with different queries in a serial fashion), you may get duplicate issues if you have enabled the *include-linked-issues-not-captured-by-query* flag.
+
+The recommendation is thus to turn off all linked issues (parents, epic links and sub items) by setting the following property in the configuration file:
+
+```json
+  "download-options": 0
+```
+
+See <https://github.com/solidify/jira-azuredevops-migrator/blob/master/docs/config.md#download-options> for more information on the `download-options` property.
+
+When running multiple migrations, one after another, we recommend following the below guidelines:
+
+- Use one separate `workspace` folder per migration.
+- For every completed migration, locate the `itemsJournal.txt` file inside your `workspace` folder. Copy this file to the workspace folder of the next migration. Then proceed with the net migration. This will ensure that you do not get duplicates, and any cross-project or cross-query links will be intact.
+
+## 5. How to migrate custom fields having dropdown lists?
 
 - To map a custom field which is an dropdown list you can use MapArray mapper to get in a better way.
 Also take a look at the other possible [Mappers](config.md#mappers) to use.
@@ -68,7 +115,7 @@ Example:
 }
 ```
 
-## 5. How to migrate correct user from Jira to Azure DevOps and assign to the new work items?
+## 6. How to migrate correct user from Jira to Azure DevOps and assign to the new work items?
 
 - User mapping differs between Jira Cloud and Jira Server. To migrate users and assign the new work items in Azure DevOps to the same user as the original task had in Jira, we need to add a text file in the root that would look something like this:
 
@@ -108,7 +155,7 @@ Example:
     [email protected][email protected]
     ```
 
-## 6. How to migrate the Work Log (Time Spent, Remaining Estimate fields)?
+## 7. How to migrate the Work Log (Time Spent, Remaining Estimate fields)?
 
 You can migrate the logged and remaining time using the following field mappings.
 
@@ -133,7 +180,7 @@ The history of the **logged time** and **remaining time** will be preserved on e
 }
 ```
 
-## 7. How to map custom userpicker fields
+## 8. How to map custom userpicker fields
 
 Here is how we have successfully mapped userpicker fields in the past. `source` should be the field name:
 
@@ -146,7 +193,7 @@ Here is how we have successfully mapped userpicker fields in the past. `source`
 },
 ```
 
-## 8. How to map datetime fields
+## 9. How to map datetime fields
 
 Here is how we can map datetime fields like ResolvedDate:
 
@@ -158,7 +205,7 @@ Here is how we can map datetime fields like ResolvedDate:
 }
 ```
 
-## 9. How to migrate an issue fields to a comment
+## 10. How to migrate an issue fields to a comment
 
 Through some manual intervention, we can migrate every historical value of an **issue field** to a **Work Item Comments**. Simply do the following:
 
@@ -179,3 +226,47 @@ Through some manual intervention, we can migrate every historical value of an **
    - `5397700c-5bc3-4efe-b1e9-d626929b89ca` > `System.History`
    - `e0cd3eb0-d8b7-4e62-ba35-c24d06d7f667` > `System.History`
 1. Run `WiImport` as usual.
+
+## 11. How to omit the Jira issue ID/key in the work item title
+
+By default, the field mapping for `System.Title` will be set up so that the title is prefixed with the Issue key. This can be prevented by omitting the **MapTitle mapper** from the field map in the configuration:
+
+```json
+  {
+    "source": "summary",
+    "target": "System.Title"
+  }
+```
+
+Instead of the default:
+
+```json
+  {
+    "source": "summary",
+    "target": "System.Title",
+    "mapper": "MapTitle"
+  }
+```
+
+## 12. I get https response code 400 and a System.Aggregate Exception with the warning "Failed to get item count using query ...", and no items are exported.
+
+The issue is usually a malformed query. Make sure that you have tried all of the following solutions:
+
+- Ensure that the `query` property in your `config.json` file follows correct [JQL syntax](https://www.atlassian.com/software/jira/guides/jql/overview)
+  - You can set up the corresponding JQL query in the issues view in your Jira project to debug the query.
+- Ensure that you don't have any issues with [authorization](https://github.com/solidify/jira-azuredevops-migrator/blob/master/docs/faq.md#2-why-i-am-getting-unauthorized-exception-when-running-the-export).
+- In the `project` clause of your query, try both the prject name, project key and project ID
+
+If all of the aboce suggestions fail, verifu that you are able to reach the issue search rest API endpoint outside of the Exporter. Try to see if you can set up a Rest query in [postman](https://www.postman.com/) or similar, with the same JQL query as you are trying in your config.json-file, with the same user + API token/password and let me know the result of that.
+
+Here is an example in curl:
+
+```txt
+curl -D- 
+  -u johnie:johnie 
+  -X POST 
+  -H "Content-Type: application/json" 
+  --data '{"jql":"project = QA","startAt":0,"maxResults":2,"fields":["id","key"]}' 
+
+ "http://johnie:8081/rest/api/2/search"
+```

docs/jira-export.md

@@ -5,18 +5,27 @@ Work item migration tool that assists with moving Jira items to Azure DevOps or
 ```txt
 Usage: jira-export [options]
 ```
-
+ authe
 |Argument|Required|Description|
 |---|---|---|
 |-? \| -h \| --help|False|Show help information|
 |-u \<username>|True|Username for authentication|
 |-p \<password>|True|Password for authentication|
+|-t \<token>|False|OAuth 2.0 token (leave empty unless authenticating with OAuth)|
 |--url \<jiraul>|True|Url of the Jira organization|
 |--config \<configurationfilename>|True|Export the work items based on this configuration file|
 |--force|False|Force execution from start (instead of continuing from previous run)|
 
-## Example
+## Examples
+
+### Usage, authentication with username + password
 
 ```bash
 jira-export -u myUser -p myPassword --url https://myorganization.atlassian.net --config config.json --force
 ```
+
+### Usage, authentication with OAuth2 token
+
+```bash
+jira-export -u myUser -p myPassword -t myToken --url https://myorganization.atlassian.net --config config.json --force
+```

readme.md

@@ -86,7 +86,7 @@ Please refer to [Contribution guidelines](docs/CONTRIBUTING.md) and the [Code of
 
 ## Supported versions of ADO/Jira
 
-The Jira to Azure DevOps work item migration tool is offically supported on the following platforms:
+The Jira to Azure DevOps work item migration tool is officially supported on the following platforms:
 
 - Atlassian Jira Cloud
 - Atlassian Jira Server

src/WorkItemMigrator.Extension/PRICING.md

@@ -0,0 +1,19 @@
+### Jira Azure DevOps Migrator PRO, price plan
+
+#### Included features
+
+* Jira Azure DevOps Migrator PRO + bootstrapper utility
+* Support for a limited number of Jira organizations/servers
+* Support for an unlimited number of Azure DevOps organizations/servers
+* Support over email
+
+#### Price
+
+$1000 / Jira organization (or server) / month
+
+</br>
+
+The extension can be evaluated during a 30 days period.
+All prices excl. VAT.
+
+[Contact us](mailto:[email protected]) for more information.

src/WorkItemMigrator.Extension/README.md

@@ -28,12 +28,38 @@ The tools are provided as-is and will require detailed understanding of how to m
 * Read the article [Jira to VSTS migration: migrating work items](https://solidify.se/blog/jira-to-vsts-migration-work-items) for more context of the process.
 * Read the article [Jira to Azure DevOps (VSTS or TFS) migration](https://solidify.se/blog/jira-azure-devops-migration) for a complete step-by-step walkthrough on a migration.
 
-# Tested with
+# Jira Azure DevOps Migrator PRO
 
-The Jira to Azure DevOps work item migration tool has been tested on the following configurations:
+The **Jira Azure DevOps Migrator PRO offering** from Solidify offers more features and utilities to further increase your migration capabilities and streamline the migration workflow. [Contact us for more information](mailto:[email protected])
+
+## Features
+
+**Jira Azure DevOps Migrator PRO** contains all the features in the **Community Edition**, plus the following additional functionality:
+
+- Priority support
+- Composite field mapper (consolidate multiple Jira fields into a single ADO field)
+- Migrate **Releases** and the **fixes version** field
+- Migrate **Remote Links** (Web links) to Work Item hyperlinks.
+- Correct any **Embedded Links to Jira Issues** in text fields such as Description, Repro Steps and comments, so that they point to the correct Work Item in Azure DevOps.
+- Select any property for **object**- and **array**-type fields for mapping. This allows for:
+  - More possibilities when mapping the **fixes version** and **components** fields.
+  - Support for mapping **custom user picker** fields.
+- Utilities for automating user mapping between Jira and Azure DevOps
+- Utilities for automatically generating the Jira Azure DevOps Migrator configuration file, thus enabling you to get started migrating faster
+- Utilities for viewing the Jira workflow and assisting with field and state mapping
+
+# Supported versions of ADO/Jira
+
+The Jira to Azure DevOps work item migration tool is officially supported on the following platforms:
 
 - Atlassian Jira Cloud
-- Atlassian Jira Server 7.0.0
+- Atlassian Jira Server
+  - 7.x
+  - 8.x
+  - 9.x
 - Azure DevOps Services
-- Azure DevOps Server ("TFS 2019")
+- Azure DevOps Server
+  - 2022
+  - 2020
+  - 2019
 - Team Foundation Server 2018 update 3

src/WorkItemMigrator.Extension/vss-extension.json

@@ -1,7 +1,7 @@
 {
     "manifestVersion": 1,
     "id": "jira-devops-migration",
-    "name": "Jira to Azure DevOps/TFS work item migration tool",
+    "name": "Jira to Azure DevOps/TFS work item migration tool (FREE)",
     "version": "0.0.1",
     "public": false,
     "publisher": "solidify",
@@ -57,6 +57,9 @@
       },
       "privacypolicy": {
         "path": "PRIVACY.md"
+      },
+      "pricing": {
+        "path": "PRICING.md"
       }
     }
   }