QTM4J: Link Bugs to Test Step Execution
qtm4j_link_bugs_to_test_step_executionLinks Jira bugs to a specific test step execution by looking up the step from test cycle, test case, and sequence number. Supports single or bulk linking with optional JQL filter.
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). |