QTM4J: Link Bugs to Test Step Execution
qtm4j_link_bugs_to_test_step_executionLinks Jira bug keys to a specific test step execution by identifying the execution through cycle, test case, and step sequence, then resolves and attaches the selected defects automatically.
Instructions
Link Jira bug keys to a test step execution. Looks up testStepExecutionId from testCycleKey, testCaseKey, and step sequence number; 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'.
testStepSeqNo (number) required: sequence number of the test step within the test case (e.g. 2 = the second step).
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 specific test step execution in a single request, supporting both single and bulk linking operations.
Examples:
Link a bug to step 2 of a test case execution
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"testStepSeqNo": 2,
"defectIDs": [
"PROJ-456"
]
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true, linkedDefectCount: 1 }
Link multiple bugs to step 3 and suppress defect count
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"testStepSeqNo": 3,
"defectIDs": [
"PROJ-456",
"PROJ-789"
],
"returnLinkedDefectCount": false
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true }
Link bugs to a step using a JQL filter
{
"testCycleKey": "PROJ-TR-101",
"testCaseKey": "PROJ-TC-42",
"testStepSeqNo": 1,
"filter": {
"jql": "project = PROJ AND status = Open"
}
}Expected Output: { testCycleKey: 'PROJ-TR-101', testCaseKey: 'PROJ-TC-42', linked: true, linkedDefectCount: 2 }
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 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. | |
| testStepSeqNo | Yes | sequence number of the test step within the test case (e.g. 2 = the second step). | |
| 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). |