QTM4J: Link Bugs to Test Case Execution
qtm4j_link_bugs_to_test_case_executionLink Jira bugs to a test case execution by resolving bug keys automatically. Supports single or bulk linking using explicit defect IDs or a JQL filter.
Instructions
Link Jira bug keys to a test case execution. Looks up testCaseExecutionId from testCycleKey and testCaseKey; resolves bug keys to numeric defect IDs automatically.
Toolset: Test Executions
Parameters:
testCycleKey (string) required: Test cycle key in the format '{PROJECT_KEY}-TR-{number}', e.g. 'SCRUM-TR-101'. Used directly as the API path parameter.
testCaseKey (string) required: Test case key in the format '{PROJECT_KEY}-TC-{number}', e.g. 'SCRUM-TC-145'.
defectIDs (any): Jira issue keys of the bugs to link (e.g. ['PROJ-456', 'PROJ-789']). Pass Jira keys — not numeric IDs. Required if filter.jql is not provided; duplicates removed automatically.
filter (object): JQL filter to select which bugs should be linked. Use instead of or in addition to defectIDs.
returnLinkedDefectCount (boolean): When true, the response includes linkedDefectCount (the number of bugs linked). Defaults to true. (default: true)
Output Description: Confirmation object with testCycleKey, testCaseKey, linked: true, and linkedDefectCount (by default). warningMessages is included when the server reports per-bug issues.
Use Cases: 1. Link one or more Jira bugs to a test case execution in a single request, supporting both single and bulk linking operations.
Examples:
Link two bugs to a test case execution
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"defectIDs": [
"PROJ-456",
"PROJ-789"
]
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true, linkedDefectCount: 2 }
Link a bug and suppress defect count in response
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"defectIDs": [
"PROJ-456"
],
"returnLinkedDefectCount": false
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true }
Link bugs using a JQL filter
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"filter": {
"jql": "project = PROJ AND issuetype = Bug AND status = 'To Do'"
}
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true, linkedDefectCount: 5 }
Hints: 1. Call set_project_context before this tool. 2. An execution must already be started for the test case before bugs can be linked. 3. If the user provides a JQL expression, pass it as the filter.jql field. Correct or normalize JQL before calling this tool if needed — the handler passes it through unchanged.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | JQL filter to select which bugs should be linked. Use instead of or in addition to defectIDs. | |
| defectIDs | No | Jira issue keys of the bugs to link (e.g. ['PROJ-456', 'PROJ-789']). Pass Jira keys — not numeric IDs. Required if filter.jql is not provided; duplicates removed automatically. | |
| testCaseKey | Yes | Test case key in the format '{PROJECT_KEY}-TC-{number}', e.g. 'SCRUM-TC-145'. | |
| testCycleKey | Yes | Test cycle key in the format '{PROJECT_KEY}-TR-{number}', e.g. 'SCRUM-TR-101'. Used directly as the API path parameter. | |
| returnLinkedDefectCount | No | When true, the response includes linkedDefectCount (the number of bugs linked). Defaults to true. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| linked | Yes | True — confirms the link request was accepted. | |
| testCaseKey | Yes | Test case key of the execution the bugs were linked to (e.g. 'SCRUM-TC-145'). | |
| testCycleKey | Yes | Test cycle Key of the execution the bugs were linked to (e.g. 'SCRUM-TR-101'). | |
| warningMessages | No | Per-bug warnings reported by the server (e.g. a bug key not accessible in Jira). Present only when issues occurred; the remaining bugs are still linked. | |
| linkedDefectCount | No | Number of bugs successfully linked. Present when returnLinkedDefectCount is true (default). |