Automating TFS to Jira: Preserving Test Hierarchy and Data Integrity with Python
Moving from on-premise TFS to Jira is rarely a clean lift-and-shift. Standard tools flatten your data. We break down the Python scripts we used to export Tasks via WIQL and, crucially, crawl Test Plans recursively to preserve folder hierarchy.

Migrations are rarely clean. When moving from legacy on-premise Team Foundation Server (TFS) or Azure DevOps (ADO) to Jira, the data transfer is the easy part. The real challenge is context. Most out-of-the-box export tools flatten your data, turning a carefully organized tree of Test Plans and Suites into a chaotic list of disconnected tickets.
For an enterprise application, losing that hierarchy means losing years of organizational knowledge. At Deviqon Labs, we prioritize data integrity. When faced with a migration involving thousands of tasks and test cases nested in deep folder structures, we didn't resort to manual reorganization. We engineered two distinct Python solutions.
The Two-Pronged Approach
A "one-size-fits-all" script rarely works because Tasks and Test Cases in ADO behave differently. Tasks are flat; they live in a backlog. Test Cases live in a hierarchy of Plans and Suites. To handle this, we split our logic:
- For Tasks & Bugs: A fast WIQL (Work Item Query Language) extractor.
- For Test Cases: A recursive folder crawler that maps the tree structure.
Part 1: The Tasks (WIQL Extraction)
For standard work items, speed is key. We utilized ADO’s WIQL endpoint to fetch IDs in bulk, then iterated through them to download attachments and history. The critical component here is handling the rate limiting and timeouts common with older on-premise servers.
1def get_all_work_item_ids():2 # WIQL allows us to grab thousands of IDs efficiently3 query = {"query": "Select [System.Id] From WorkItems Where [System.TeamProject] = @project Order By [System.Id] Desc"}4 try:5 r = requests.post(f"{ADO_BASE_URL}/_apis/wit/wiql?api-version=6.0", json=query, headers=headers)6 r.raise_for_status()7 return [item['id'] for item in r.json()['workItems']]8 except Exception as e:9 logger.critical(f"Connection Failed: {e}")10 exit()
This script generates a flat list of JSON files, ready for mapping to Jira Issue Types.
Part 2: The Test Plans (Recursive Crawling)
This is where standard tools fail. We needed to replicate the folder structure on our local machine exactly as it appeared in TFS. This required a recursive function to walk the Test Plan tree.
1. Solving the "On-Prem" Connectivity Issue
Legacy TFS servers often have resolution issues (e.g., internal DNS failures or port blocking). Before attempting to crawl thousands of items, our script runs a diagnostic check using Python's socket library. This prevents the script from crashing mid-execution due to a blip in the VPN or internal network.
1def check_connection():2 parsed = urlparse(ADO_BASE_URL)3 hostname = parsed.hostname4 port = parsed.port or 8056 print(f"--- DIAGNOSTIC: Checking connection to '{hostname}' ---")7 try:8 # verify DNS resolution9 ip = socket.gethostbyname(hostname)10 print(f"[OK] DNS Resolved '{hostname}' to {ip}")1112 # verify TCP socket connection13 sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)14 sock.settimeout(5)15 result = sock.connect_ex((hostname, port))16 if result == 0:17 return True18 except Exception as e:19 print(f"[FATAL] Connection check error: {e}")20 return False
Handling this level of environmental instability is a common challenge in the enterprise modernization projects our teams at Deviqon Labs focus on.
2. The Recursive Mapper
We fetch a Plan, then find its Suites. If a Suite contains children, the function calls itself, building a directory path string (e.g., /Plan A/Regression/Payment Module).
1def get_suites_for_plan(plan_id, plan_name):2 url = f"{ADO_BASE_URL}/_apis/test/plans/{plan_id}/suites?api-version=6.0"3 resp = safe_api_request(url)4 suites = resp.json()['value']56 # Map Children to Parents7 children_map = {}8 root_suite = None910 for s in suites:11 if 'parentSuite' in s:12 pid = s['parentSuite']['id']13 children_map.setdefault(pid, []).append(s)14 else:15 root_suite = s1617 final_paths = []1819 # Recursive path builder20 def traverse(current_suite, current_path):21 s_name = clean_filename(current_suite['name'])22 full_path = os.path.join(current_path, s_name)2324 final_paths.append((current_suite['id'], full_path))2526 children = children_map.get(current_suite['id'], [])27 for child in children:28 traverse(child, full_path)2930 if root_suite:31 traverse(root_suite, "")3233 return final_paths
3. Parsing XML Steps
Finally, ADO stores test steps in a verbose XML format (`Microsoft.VSTS.TCM.Steps`). We strip the HTML tags and structure the data into clean JSON arrays for the Jira description field.
1def parse_ado_steps(xml_string):2 if not xml_string: return []3 steps_data = []4 try:5 # Wrap in root to handle fragment errors6 root = ET.fromstring(f"{xml_string}")7 for i, step in enumerate(root.findall('.//step'), 1):8 params = step.findall('parameterizedString')9 # Custom clean_html regex function applied here10 action = clean_html(params[0].text)11 expected = clean_html(params[1].text)12 steps_data.append({"index": i, "action": action, "expected": expected})13 except:14 return [{"index": 1, "action": "XML Error", "expected_result": "Could not parse"}]15 return steps_data
The Result
By running these scripts, we generate a local "Mirror" of the TFS instance. Tasks are flattened for the backlog, while Test Cases sit in folders mirroring their exact Test Plan hierarchy. This allows us to validate assets, check attachment sizes, and clean data before we ever touch the Jira API.
Bridging the Gap to Jira
Once we have this clean local mirror, the upload logic is straightforward. We map the folder paths to Jira Components (or Xray Test Repositories), ensuring that when a Test Case is created in Jira, it automatically lands in the correct organizational bucket. This transforms a blind data dump into a structured import.
From Theory to Practice
The concepts in this article, robust error handling, recursive crawling, and protocol diagnostics, are foundational for maintaining data integrity during system migrations. If you are exploring how these techniques apply to your own legacy systems, or if you are facing a unique technical hurdle, our senior specialists are available for a technical discussion.
Contact Deviqon Labs to discuss your project.
About the Author
Teodor Cosma is a Software Engineer at Deviqon Labs with 3 years of experience in frontend development and tooling automation. .


