QMetry: Create Defect or Issue

Create a new defect/issue internally in QMetry.

Toolset: Issues

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• issueType (number) required: Issue type ID (e.g. Bug, Enhancement, etc.)

• issuePriority (number) required: Issue priority ID (e.g. High, Medium, Low, etc.)

• summary (string) required: Summary or title of the defect/issue

• description (string): Detailed description of the defect/issue

• sync_with (string): External system to sync with (e.g. JIRA, QMetry, etc.)

• issueOwner (number): Owner/user ID for the issue

• component (array): Component IDs associated with the issue

• affectedRelease (array): Release IDs affected by this issue

• affectedCycles (array): Cycle IDs affected by this issue

• tcRunID (number): Test Case Run ID to link this defect/issue to a test execution (optional)

• environment (string): Environment where the issue was found (e.g. 'Chrome', 'Firefox', 'Production'). Free-text string — no ID lookup needed.

• issueState (number): Issue status ID. Optional by default — QMetry allows admins to make this mandatory at the project level. Get valid IDs from project info → customListObjs.issueState[index].id. Common values: Open, Reopened, Resolved, Closed.

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

Output Description: JSON object containing the new create issue with id, dfid(defectID).

Use Cases: 1. Create a basic defect/issue with just a summary 2. Set issueType, issueOwner, component (labels), environment, and affectedRelease using valid IDs from project info 3. Create defects/issues with UDF values (hobby, destination, custom fields) 4. Link defects/issues to specific test case runs using tcRunID

Examples:

1. Create an issue with summary 'Login Issue'

{
  "name": "Login Issue",
  "issuePriority": 2231988,
  "issueType": 2231983
}

Expected Output: Issue created in summary details

2. Create an issue with Major priority and Bug type to Bug with summary 'Login Issue'

{
  "name": "Login Issue",
  "issuePriority": 2231988,
  "issueType": 2231983
}

Expected Output: Issue created in summary details with priority and Bug type

3. Create an issue with summary 'Login Issue' and set issueOwner to 'John Doe'

{
  "name": "Login Issue",
  "issueOwner": 15112,
  "issuePriority": 2231988,
  "issueType": 2231983
}

Expected Output: Issue created in summary details with owner, priority and Bug type

4. Create an issue with summary 'Login Issue' and link it to test case run ID 567890

{
  "name": "Login Issue",
  "issueOwner": 15112,
  "issuePriority": 2231988,
  "issueType": 2231983,
  "tcRunID": 567890
}

Expected Output: Issue created in summary details and linked to test case run ID 567890

5. Create an issue with summary 'Login Issue' and set description to 'User is unable to login' and owner to 'John Doe' and link it to test case run ID 567890

{
  "name": "Login Issue",
  "issueOwner": 15112,
  "issuePriority": 2231988,
  "issueType": 2231983,
  "tcRunID": 567890,
  "description": "User is unable to login"
}

Expected Output: Issue created in summary details with description, owner, priority, Bug type and linked to test case run ID 567890

6. Create an issue with summary 'Login Issue' and set release to 'Release 1.0' and its associated all cycles and owner to 'John Doe'

{
  "name": "Login Issue",
  "issueOwner": 15112,
  "issuePriority": 2231988,
  "issueType": 2231983,
  "affectedRelease": [
    111840
  ],
  "affectedCycles": [
    112345,
    112346
  ]
}

Expected Output: Issue created in summary details with release and associated all cycles, owner

7. Create an issue with summary 'Login Issue' and set release to 'Release 1.0' and its associated all cycle 'Cycle 1.0.1', 'Cycle 1.0.2'

{
  "name": "Login Issue",
  "issuePriority": 2231988,
  "issueType": 2231983,
  "affectedRelease": [
    111840
  ],
  "affectedCycles": [
    112345,
    112346
  ]
}

Expected Output: Issue created in summary details with release and cycles

Hints: 1. ╔══════════════════════════════════════════════════════════════════╗ 2. ║ STEP 0 — NON-NEGOTIABLE: Call 'Fetch UDF Layout' BEFORE create ║ 3. ╚══════════════════════════════════════════════════════════════════╝ 4. NEVER call 'Create Defect or Issue' without first calling 'Fetch UDF Layout' with entityType='IS', pageName='ADD'. 5. Skipping this step WILL cause 400 errors (CO.MANDATORY_FIELDS_MISSING) because mandatory fields and defaults are unknown. 6. This rule has NO exceptions — not even when the user only provided a name and nothing else. 7. 8. === MANDATORY PRE-CREATE CHECK (ALWAYS DO THIS FIRST) === 9. Before creating any issue, call 'Fetch UDF Layout' with entityType='IS', pageName='ADD'. 10. Response keys use 'IS' — same structure as TC but scoped to issue module. 11. 12. SYSTEM FIELDS mandatory check — use 'systemFields' array (from qmSDF.IS in newlayout): 13. Each entry: { name, label, fieldTypeName, isMandatory } 14. isMandatory=true (allowBlank=false) means field MUST have a value before creating. 15. 16. UDF FIELDS mandatory check — use 'fields' array (from qmUDF.IS in newlayout): 17. Each entry: { name, label, fieldTypeName, isMandatory, listName? } 18. isMandatory=true means field MUST have a value. 19. 20. DEFAULT VALUES — use 'defaultValues' object (from qmDefaultValue.IS in newlayout): 21. Shape: { fieldName: defaultValueId } e.g. { 'str1': 'Tony Stark', 'lookup19': 5232630, 'component': 5232632 } 22. IMPORTANT: defaultValues can contain BOTH system field defaults AND UDF field defaults — handle each differently: 23. → SYSTEM field defaults (fields in qmSDF.IS, e.g. component/Labels, issueType, issuePriority): route to TOP-LEVEL params, NOT to udfFields. 24. - MULTILOOKUPLIST system fields (e.g. component): default is a single ID — wrap in array: component: [5232632]. 25. - LOOKUPLIST system fields (e.g. issueType, issuePriority): default is a single ID — use directly: issueType: 5232517. 26. → UDF field defaults (fields in qmUDF.IS, e.g. str1, lookup19, age19): route to udfFields param. 27. IMPORTANT: QMetry's API sometimes returns 'defaultValues: {}' (empty) even when defaults exist in QMetry settings. 28. If 'defaultValues' is empty, you cannot auto-apply — ask user for mandatory fields without defaults. 29. RULE: isMandatory=true AND defaultValues[field.name] exists → auto-use default, do NOT ask user. 30. RULE: isMandatory=true AND no defaultValues entry → MUST ask user before creating. 31. RULE: isMandatory=false AND defaultValues entry exists → auto-apply if user didn't specify. 32. 33. SYSTEM FIELDS mandatory check — additional caveat: 34. IMPORTANT: QMetry's API sometimes returns 'systemFields: []' (empty) even when system fields ARE mandatory. 35. If 'systemFields' is empty, treat the following as always mandatory: summary, issueType, issuePriority. 36. For issueType/issuePriority defaults: check 'customListObjs.issueType' / 'customListObjs.issuePriority' from Fetch Project Info — use first non-archived entry as fallback. 37. 38. ╔══════════════════════════════════════════════════════════════════════════╗ 39. ║ PRE-FLIGHT DEFAULT SWEEP — MANDATORY STEP BEFORE EVERY CREATE CALL ║ 40. ╚══════════════════════════════════════════════════════════════════════════╝ 41. After resolving mandatory fields, sweep ALL defaultValues entries: 42. For EACH key in defaultValues: 43. IF the user did not explicitly provide that field → add it to the payload using the default value. 44. This applies regardless of isMandatory — non-mandatory defaults MUST also be auto-applied. 45. Route correctly: system fields → top-level params, UDF fields → udfFields. 46. MULTILOOKUPLIST system fields (e.g. component): wrap single default ID in array → component: [id]. 47. Example: defaultValues = { str1: 'Tony Stark', lookup19: 5232630, component: 5232632 } 48. → user only said 'create an issue named X' 49. → payload MUST include: udfFields.str1='Tony Stark', udfFields.lookup19=5232630, component=[5232632] 50. → WRONG to put component in udfFields — it is a system field and must be a top-level array param. 51. → WRONG to omit component just because it is not mandatory — it has a default. 52. Skipping this sweep = missing fields in the created record = user-visible data loss. 53. ╚══════════════════════════════════════════════════════════════════════════╝ 54. 55. DECISION MATRIX: 56. | isMandatory | Has default | Action | 57. |-------------|-------------|-------------------------------------| 58. | true | YES | Auto-fill with default, no ask | 59. | true | NO | Ask user before creating | 60. | false | YES | Auto-fill with default — REQUIRED | 61. | false | NO | Skip if user didn't provide | 62. Only after ALL mandatory fields resolved AND default sweep complete → proceed with create. 63. === END MANDATORY PRE-CREATE CHECK === 64. 65. === ERROR RECOVERY: CO.MANDATORY_FIELDS_MISSING === 66. If create fails with error code 'CO.MANDATORY_FIELDS_MISSING', DO NOT give up. Auto-recover: 67. 1. Parse the 'MISSING_FIELDS' list from the error response (comma-separated field labels). 68. 2. Match each label against 'fields[].label' and 'systemFields[].label' from the Fetch UDF Layout response. 69. 3. For matched UDF fields: check 'listOptions[field.listName]' for valid option IDs. 70. 4. For matched system fields (e.g. 'Priority'): check 'customListObjs.issuePriority' from project info. 71. 5. If the field has a 'defaultValues' entry: auto-fill it silently. 72. 6. If no default exists: ask the user ONLY for the missing fields by label. 73. 7. Retry create with the resolved values added to the payload. 74. NEVER ask user to 'try again' manually — resolve and retry automatically. 75. === END ERROR RECOVERY === 76. 77. === DATE FORMAT CHECK (MANDATORY — EVERY CREATE REQUEST) === 78. ALWAYS call 'Fetch QMetry Project Info' before every create request — not only when the user explicitly mentions a date. 79. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 80. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 81. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 82. STEP 3: unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 83. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 84. STEP 4: For EVERY DATETIMEPICKER field in the payload: parse any user-provided date and re-format it using the active unique_value pattern before sending. 85. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 86. === END DATE FORMAT CHECK === 87. 88. CRITICAL: summary, issueType, issuePriority are REQUIRED fields to create an issue 89. OPTIONAL SYSTEM FIELDS: issueOwner, component, affectedRelease, affectedCycles, description, environment, tcRunID 90. SYSTEM FIELD ID RESOLUTION — fetch project info, then use these mappings: 91. - issueType: customListObjs.issueType[].id 92. - issuePriority: customListObjs.issuePriority[].id 93. - issueOwner / owner: customListObjs.users[].id (match by name) 94. - component / labels: customListObjs.component[].id (component acts as labels — pass array of IDs) 95. - environment: free-text string (e.g. 'Chrome', 'Firefox', 'Production') — pass directly as top-level field, no ID lookup needed 96. - sync_with: customListObjs.component[].igConfigurationID or internalTrackerId 97. - tcRunID: data[].tcRunID (from 'Execution/Fetch Testcase Run ID') 98. If the user provides a issuePriority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.issuePriority[index].name, and use its ID in the payload. If the name is not found, skip the issuePriority field and show a user-friendly message: 'Defect/issue created without issuePriority, as given issuePriority is not available in the current project.' 99. If the user provides an issueOwner name, fetch project info, find the matching issueOwner in customListObjs.users[index].name, and use its ID in the payload as issueOwner. If the name is not found, skip the issueOwner field and show a user-friendly message: 'Defect/issue created without issueOwner, as given issueOwner is not available in the current project.' 100. If the user provides an issue type name, fetch project info, find the matching type in customListObjs.issueType[index].name, and use its ID in the payload as issueType. If the name is not found, skip the issueType field and show a user-friendly message: 'Defect/issue created without issue type, as given type is not available in the current project.' 101. 102. === RELEASE/CYCLE ID RESOLUTION (MANDATORY WHEN USER PROVIDES RELEASE OR CYCLE) === 103. ALWAYS call 'Fetch Releases and Cycles' tool (FETCH_RELEASES_AND_CYCLES) to resolve release and cycle IDs — do NOT guess IDs from project info. 104. Fetch Releases and Cycles response structure: 105. releases[].releaseID → use as affectedRelease value (wrap in array: [releaseID]) 106. releases[].name → release display name to match against user input 107. releases[].builds[].buildID → use as affectedCycles value (wrap in array: [buildID]) 108. releases[].builds[].name → cycle display name to match against user input 109. PAYLOAD FORMAT: both affectedRelease and affectedCycles MUST be arrays of numeric IDs: 110. affectedRelease: [releaseID] e.g. affectedRelease: [92112] 111. affectedCycles: [buildID] e.g. affectedCycles: [130831] 112. affectedCycles: [buildID1, buildID2] multiple cycles allowed 113. WORKFLOW when user provides release/cycle name or ID: 114. 1. Call FETCH_RELEASES_AND_CYCLES to get all releases and their nested cycles (builds). 115. 2. Match user's release name/ID → extract releases[].releaseID. 116. 3. Match user's cycle name/ID within that release → extract releases[].builds[].buildID. 117. 4. Set affectedRelease: [releaseID] and affectedCycles: [buildID] in payload. 118. VALIDATION: If the release or cycle name/ID is not found in FETCH_RELEASES_AND_CYCLES response, skip both fields and show: 'Issue created without release/cycle association, as given release/cycle is not available in the current project.' 119. NEVER pass a single number for affectedRelease or affectedCycles — always wrap in array even for one ID. 120. === END RELEASE/CYCLE ID RESOLUTION === 121. 122. Ensure all IDs used are valid for the current QMetry project context 123. This tool is essential for defect management and test execution linkage 124. Helps maintain traceability between test executions and reported issues 125. Critical for quality assurance and defect lifecycle management 126. Use for creating issues directly from test execution contexts 127. 128. UDF (User Defined Fields) WORKFLOW FOR CREATE: 129. 1. Call 'Fetch UDF Layout' with entityType='IS', pageName='ADD' to discover field names, types, and list option IDs. 130. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 131. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 132. 3. For MULTILOOKUPLIST fields: pick an array of IDs. 133. 4. For CASCADINGLIST fields: pick parent ID, then call 'Fetch Cascade Child Values' for child ID. Pass { parent: parentId, child: childId }. 134. 5. Pass all UDF values via 'udfFields' param: { fieldName: value }. 135. 6. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail.