Fetch QMetry projects list including projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• params (object) required

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object containing list of projects details

Use Cases: 1. Get project list to check user how many project access to particular apikey 2. Retrieve available fields of each project list including projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations 3. Validate project access and permissions

Examples:

1. Get list of project available to user

{
  "params": {
    "showArchive": false
  }
}

Expected Output: Project active/non archived list including some important fields like projectID, name, projectKey, isArchived, viewIds and folderPath needed for other operations

2. Get projects with custom pagination

{
  "params": {
    "showArchive": false
  },
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of projects with custom pagination settings

3. Get not active/archived projects

{
  "params": {
    "showArchive": true
  }
}

Expected Output: List of all projects including archived ones (showArchive: true sent in payload)

4. Filter projects by name

{
  "filter": "[{\"value\":\"MAC\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of projects matching the name criteria

5. Filter projects by project key

{
  "filter": "[{\"value\":\"MAC\",\"type\":\"string\",\"field\":\"projectKey\"}]"
}

Expected Output: List of projects filtered by project key (e.g. 'MAC', 'UT', etc.)

Hints: 1. Fetch list of projects available to user 2. Use 'default' project key when user doesn't specify one 3. Use params.showArchive: true/false to get archived/non-archived projects, default is false when not provided 4. Pagination supported for large result sets (start, page, limit parameters) 5. Filter parameter should be a JSON string with filter criteria 6. Common filter fields: 'name' (string), 'projectKey' (string)

Set current QMetry project for your account

Toolset: Projects

Parameters:

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

Output Description: JSON object containing project configuration details, confirmation of project switch, and available project metadata

Use Cases: 1. Switch to a specific project before performing test case operations 2. Set project context for batch operations on test cases 3. Configure the default project for the current session 4. Validate access to a specific project before proceeding with operations

Examples:

1. Set default project as active

{
  "projectKey": "default"
}

Expected Output: Project context set to 'default' with confirmation of project details

2. Switch to UT project

{
  "projectKey": "UT"
}

Expected Output: Project context switched to 'UT' project with available configurations

3. Set MAC project as active for test case operations

{
  "projectKey": "MAC"
}

Expected Output: Project context set to 'MAC' with viewIds and folder structure

Hints: 1. Always set the project context before performing test case operations in multi-project environments 2. Use the same project key that you'll use in subsequent test case operations 3. Common project keys include 'default', 'UT', 'MAC', 'VT' - check with your QMetry admin for available projects 4. This operation must be performed before fetching test cases if working with non-default projects 5. The project context persists for the current session until changed again

Fetch QMetry project information including viewId and folderPath needed for other operations

Toolset: Projects

Parameters:

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

Output Description: JSON object containing project details, viewIds, folderPaths, project configuration, 'dateTimeFormatID' (active date format ID), and 'dateTimeFormatNew' array (each entry: { id, name, unique_value } — use unique_value of the matching entry as the date format pattern for all API date fields).

Use Cases: 1. Get project configuration before fetching test cases 2. Retrieve available viewIds for test case listing 3. Get folderPath information for project navigation 4. Validate project access and permissions

Examples:

1. Get default project info

{}

Expected Output: Project configuration with viewIds, folderPaths, and project details

2. Get specific project info

{
  "projectKey": "MAC"
}

Expected Output: MAC project configuration with available views and folders

Hints: 1. Always call this first when user doesn't provide viewId or folderPath 2. Use 'default' project key when user doesn't specify one 3. Extract viewId from latestViews.TC.viewId for test case operations 4. Use empty string '' as folderPath for root directory 5. DATE FORMAT — IMPORTANT: response contains 'dateTimeFormatID' (number) and 'dateTimeFormatNew' (array). 6. dateTimeFormatID = active format ID for this project. 7. dateTimeFormatNew = [{ id, name, unique_value }] — find entry where id === dateTimeFormatID. 8. unique_value is the authoritative date format pattern using Java/QMetry conventions: 9. yyyy = 4-digit year | MM = 2-digit month (01-12) | dd = 2-digit day | MMM = 3-letter month (Jan/Feb/...) 10. Example mappings: 11. unique_value 'MM-dd-yyyy' → format: 12-25-2024 12. unique_value 'dd-MM-yyyy' → format: 25-12-2024 13. unique_value 'yyyy-MM-dd' → format: 2024-12-25 14. unique_value 'dd-MMM-yyyy' → format: 25-Dec-2024 15. Always use this format when sending date values in any create/update payload. 16. Always parse user-provided dates and reformat them to this pattern before sending to API.

Fetch QMetry releases and cycles from the current project

Toolset: Projects

Parameters:

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

• showArchive (boolean): Whether to include archived records in the results. When true, returns both active and archived items. When false, returns only active (non-archived) items. Applies to any entity type being fetched (test cases, requirements, releases, cycles, builds, platforms, etc.).

Output Description: JSON object with project hierarchy containing releases and their associated cycles

Use Cases: 1. Fetch associated releases and cycles of current project 2. Fetch available releases and cycles of current project 3. Get release and cycle information for test planning 4. List all releases and cycles in a project 5. Search for specific releases using release name or ID 6. Fetch cycle lists based on release ID 7. Search for specific cycles using cycle name or ID 8. Get project structure for test planning and execution 9. Retrieve release hierarchy for reporting purposes

Examples:

1. Get active releases and cycles (default behavior)

{}

Expected Output: List of active releases and cycles excluding archived ones (showArchive: false sent in payload)

2. Get active/unarchived releases and cycles explicitly

{
  "showArchive": false
}

Expected Output: List of active releases and cycles excluding archived ones (showArchive: false sent in payload)

3. Get not active/archived releases and cycles

{
  "showArchive": true
}

Expected Output: List of all releases and cycles including archived ones (showArchive: true sent in payload)

Hints: 1. Use 'default' project key when user doesn't specify one 2. PAYLOAD SCENARIOS: 3. - No showArchive parameter → payload: {showArchive: false} → Returns only active releases/cycles 4. - showArchive: false → payload: {showArchive: false} → Returns only active/non-archived releases/cycles 5. - showArchive: true → payload: {showArchive: true} → Returns all releases/cycles including archived ones 6. Default behavior always excludes archived items unless explicitly requested 7. Releases contain cycles - use this hierarchy for test execution planning 8. Each release can have multiple cycles representing different testing phases

Fetch QMetry builds from the current project

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with builds list and pagination metadata

Use Cases: 1. Fetch all from the current project 2. Fetch all available builds for test execution planning 3. Get build metadata for test run assignments 4. List builds for reporting and analytics 5. Filter builds by name or archive status 6. Get paginated build results for large projects 7. Retrieve build information for CI/CD integration 8. Search for specific builds using filters 9. Get build details for test execution history

Examples:

1. Get all builds (default behavior)

{}

Expected Output: List of all builds with default pagination (10 items per page)

2. Get builds with custom pagination

{
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of builds with custom pagination settings

3. Filter builds by name

{
  "filter": "[{\"value\":\"Build 1.0\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of builds matching the name criteria

4. Filter builds by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of builds filtered by archive status (archived and non-archived)

Hints: 1. Use 'default' project key when user doesn't specify one 2. Default pagination: start=0, page=1, limit=10 3. Filter parameter should be a JSON string with filter criteria 4. Common filter fields: 'name' (string), 'isArchived' (list of 0,1) 5. Empty payload {} is sent when no parameters are provided 6. Builds are also known as 'drops' in QMetry terminology 7. Use builds for associating test executions with specific software versions

Fetch QMetry platforms from the current project

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• sort (string): Sort criteria as JSON string (default '[{"property":"platformID","direction":"DESC"}]') (default: "[{"property":"platformID","direction":"DESC"}]")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with platforms list and pagination metadata

Use Cases: 1. Fetch all platforms from the current project 2. Get platform metadata for test execution planning 3. List platforms for test environment selection 4. Filter platforms by name or properties 5. Get paginated platform results for large projects 6. Retrieve platform information for cross-platform testing 7. Search for specific platforms using filters 8. Get platform details for test execution assignment

Examples:

1. Get all platforms (default behavior)

{}

Expected Output: List of all platforms with default pagination (10 items per page)

2. Get platforms with custom pagination

{
  "page": 1,
  "limit": 10,
  "start": 0
}

Expected Output: List of platforms with custom pagination settings

3. Filter platforms by name

{
  "filter": "[{\"value\":\"Chrome\",\"type\":\"string\",\"field\":\"name\"}]"
}

Expected Output: Filtered list of platforms matching the name criteria

4. Filter platforms by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of platforms filtered by archive status (archived and non-archived)

5. Get only archived platforms

{
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only archived platforms

6. Get only active/non-archived platforms

{
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only active/non-archived platforms

7. Get platforms with custom sorting

{
  "sort": "[{\"property\":\"name\",\"direction\":\"ASC\"}]"
}

Expected Output: List of platforms sorted by name in ascending order

Hints: 1. Use 'default' project key when user doesn't specify one 2. Default pagination: start=0, page=1, limit=10 3. Filter parameter should be a JSON string with filter criteria 4. Sort parameter should be a JSON string with sort criteria 5. Default sort: platformID descending 6. Common filter fields: 'name' (string), 'isArchived' (list of 0,1) for archive status 7. IMPORTANT: Always use 'isArchived' field for filtering by archive status, even though response shows 'isPlatformArchived' 8. Archive status values: 0 = active/non-archived, 1 = archived 9. Empty payload {} is sent when no parameters are provided 10. Use platforms for cross-platform testing and environment selection

Create a new release in QMetry with optional cycle for test planning and execution tracking

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• release (object) required

• cycle (object): Optional cycle to create within the release

Output Description: JSON object containing the created release ID, release details, and cycle information if provided

Use Cases: 1. Create a new release for a major product version (e.g., v2.0, Q1 Release) 2. Create a release with an initial cycle for immediate test planning 3. Set up release dates for sprint planning and milestone tracking 4. Organize test execution by product versions and cycles 5. Create release hierarchy for better test planning and reporting 6. Establish test execution phases with releases and cycles

Examples:

1. Create a basic release with just a name

{
  "release": {
    "name": "Release 2.0"
  }
}

Expected Output: Release 'Release 2.0' created successfully with generated release ID

2. Create a release with description and dates

{
  "release": {
    "name": "Q1 2024 Release",
    "description": "First quarter release for 2024",
    "startDate": "01-01-2024",
    "targetDate": "31-03-2024"
  }
}

Expected Output: Release 'Q1 2024 Release' created with start date 01-01-2024 and target date 31-03-2024

3. Create a release with an initial cycle

{
  "release": {
    "name": "Release 3.0",
    "description": "Major product update"
  },
  "cycle": {
    "name": "Sprint 1",
    "isLocked": false,
    "isArchived": false
  }
}

Expected Output: Release 'Release 3.0' created with cycle 'Sprint 1' for test execution planning

4. Create a release with all details

{
  "release": {
    "name": "Summer 2024 Release",
    "description": "Summer product release with new features",
    "startDate": "01-06-2024",
    "targetDate": "31-08-2024"
  },
  "cycle": {
    "name": "Beta Testing Cycle",
    "isLocked": false
  }
}

Expected Output: Release 'Summer 2024 Release' created with dates and 'Beta Testing Cycle' for test execution

Hints: 1. CRITICAL: release.name is REQUIRED - must provide a name for the release 2. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 3. Check your QMetry instance settings to determine the correct date format 4. If dates are in wrong format, QMetry will return an error - verify format with admin 5. projectID is optional in the release object - it will be auto-resolved from the project key if not provided 6. To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID 7. cycle parameter is completely optional - omit it if you only want to create a release 8. If providing cycle, cycle.name is REQUIRED 9. cycle.isLocked defaults to false if not provided - set to true to prevent modifications 10. cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare) 11. Releases can have multiple cycles added later using other tools 12. Use descriptive release names like 'Release 2.0', 'Q1 2024', 'Sprint 15' for better organization 13. startDate and targetDate help with sprint planning and milestone tracking 14. Creating a release with a cycle is useful for immediate test planning after release creation 15. Release hierarchy: Project → Release → Cycle → Test Execution 16. After creating a release, you can associate test suites and test cases with it 17. Use FETCH_RELEASES_CYCLES tool after creation to verify the release was created successfully

Create a new cycle within an existing release in QMetry for test execution planning

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• cycle (object) required

Output Description: JSON object containing the created cycle ID, cycle details, and association with the release

Use Cases: 1. Create a new test cycle for a sprint within an existing release 2. Add additional testing phases to an existing release 3. Set up regression testing cycles for a specific release 4. Organize test execution by sprints, phases, or iterations 5. Create cycles with specific date ranges for milestone tracking 6. Establish test execution phases within release planning

Examples:

1. Create a basic cycle with just a name in a release

{
  "cycle": {
    "name": "Sprint 2",
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Sprint 2' created successfully in release ID 12345

2. Create a cycle with description and dates

{
  "cycle": {
    "name": "Regression Testing Cycle",
    "description": "Full regression testing for release 2.0",
    "startDate": "15-01-2024",
    "targetDate": "31-01-2024",
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Regression Testing Cycle' created with start date 15-01-2024 and target date 31-01-2024 in release 12345

3. Create a locked cycle to prevent modifications

{
  "cycle": {
    "name": "Final QA Cycle",
    "description": "Locked cycle for final QA testing",
    "isLocked": true,
    "isArchived": false,
    "releaseID": 12345
  }
}

Expected Output: Locked cycle 'Final QA Cycle' created in release 12345 to prevent modifications

4. Create a cycle with all details including project ID and dates

{
  "cycle": {
    "name": "Sprint 3 - Feature Testing",
    "description": "Testing new features for Sprint 3",
    "startDate": "01-02-2024",
    "targetDate": "15-02-2024",
    "isLocked": false,
    "isArchived": false,
    "projectID": 67890,
    "releaseID": 12345
  }
}

Expected Output: Cycle 'Sprint 3 - Feature Testing' created with dates and project context in release 12345

Hints: 1. CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to associate this cycle with 2. CRITICAL: cycle.name is REQUIRED - must provide a name for the cycle 3. HOW TO GET releaseID: 4. 1. Call FETCH_RELEASES_CYCLES tool to get all releases and their IDs 5. 2. From the response, get value from projects.releases[].releaseID 6. 3. Use that numeric releaseID in the cycle.releaseID parameter 7. Example: Release 'Q1 2024' might have releaseID: 12345 8. CRITICAL WORKFLOW - IF USER PROVIDES RELEASE NAME: 9. 1. User says: 'Create cycle Sprint 2 in release Q1 2024' 10. 2. You MUST first call FETCH_RELEASES_CYCLES tool to get all releases 11. 3. Search the response for release with name 'Q1 2024' 12. 4. Extract projects.releases[].releaseID from matching release 13. 5. Use that releaseID in cycle.releaseID parameter 14. 6. If release name not found, inform user and list available releases 15. Example workflow: 16. - User request: 'Create cycle Sprint 2 in Release 2.0' 17. - Step 1: Call FETCH_RELEASES_CYCLES 18. - Step 2: Find release where name = 'Release 2.0', get its releaseID (e.g., 12345) 19. - Step 3: Call CREATE_CYCLE with cycle.releaseID = 12345 20. RELEASE NAME RESOLUTION: 21. - NEVER assume or guess release IDs - always fetch from API 22. - Release names are user-defined strings (e.g., 'Q1 2024', 'Release 2.0', 'Sprint 15') 23. - Release IDs are numeric identifiers assigned by QMetry (e.g., 12345, 67890) 24. - Match release names case-insensitively when searching 25. - If multiple releases match the name, ask user to clarify or use the most recent one 26. - FETCH_RELEASES_CYCLES returns: projects.releases[] array with name and releaseID fields 27. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 28. Check your QMetry instance settings to determine the correct date format 29. If dates are in wrong format, QMetry will return an error - verify format with admin 30. projectID is optional in the cycle object - it will be auto-resolved from the project key if not provided 31. To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID 32. cycle.isLocked defaults to false if not provided - set to true to prevent modifications 33. cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare) 34. Use descriptive cycle names like 'Sprint 2', 'Regression Cycle', 'Alpha Testing' for better organization 35. startDate and targetDate help with sprint planning and milestone tracking 36. Cycle hierarchy: Project → Release → Cycle → Test Execution 37. After creating a cycle, you can associate test suites and test cases with it 38. Use FETCH_RELEASES_CYCLES tool after creation to verify the cycle was created successfully 39. DIFFERENCE FROM CREATE_RELEASE: This tool creates a cycle in an EXISTING release, while CREATE_RELEASE can create a release with an optional cycle 40. If you need to create both a release and a cycle together, use CREATE_RELEASE tool instead 41. If release doesn't exist yet, create it first with CREATE_RELEASE, then add more cycles with this tool

Update an existing cycle in QMetry for test execution planning

Toolset: Projects

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• cycle (object) required

Output Description: JSON object containing the updated cycle details and confirmation of update

Use Cases: 1. Update cycle name for better organization 2. Modify cycle dates to reflect schedule changes 3. Adjust testing phase timelines within a release 4. Update cycle metadata for sprint tracking 5. Revise milestone dates for test execution planning 6. Rename cycles to match updated sprint naming conventions

Examples:

1. Update cycle name

{
  "cycle": {
    "name": "Alpha_v1_Updated",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle updated successfully with new name 'Alpha_v1_Updated'

2. Update cycle dates

{
  "cycle": {
    "startDate": "10-10-2018",
    "targetDate": "11-11-2018",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle dates updated successfully with new start date 10-10-2018 and target date 11-11-2018

3. Update cycle name and dates together

{
  "cycle": {
    "name": "Sprint 2 - Updated",
    "startDate": "15-01-2024",
    "targetDate": "31-01-2024",
    "buildID": 1494,
    "releaseID": 3729
  }
}

Expected Output: Cycle updated with new name and dates successfully

Hints: 1. CRITICAL: cycle.buildID is REQUIRED - must provide the build ID to identify the cycle to update 2. CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to identify the cycle to update 3. HOW TO GET buildID and releaseID: 4. 1. Call FETCH_RELEASES_CYCLES tool (API: 'Cycle/List') to get all cycles 5. 2. From the response, get buildID from projects.releases[].builds[].buildID 6. 3. From the response, get releaseID from projects.releases[].releaseID 7. 4. Use those numeric IDs in cycle.buildID and cycle.releaseID parameters 8. Example: Cycle 'Sprint 2' might have buildID: 1494 and releaseID: 3729 9. CRITICAL WORKFLOW - IF USER PROVIDES CYCLE NAME: 10. 1. User says: 'Update cycle Sprint 2 to change dates' 11. 2. You MUST first call FETCH_RELEASES_CYCLES tool to get all cycles 12. 3. Search the response for cycle with matching name 'Sprint 2' 13. 4. Extract buildID and releaseID from the matching cycle 14. 5. Use those IDs in cycle.buildID and cycle.releaseID parameters 15. 6. If cycle name not found, inform user and list available cycles 16. Example workflow: 17. - User request: 'Update cycle Alpha_v1 name to Alpha_v1_Updated' 18. - Step 1: Call FETCH_RELEASES_CYCLES 19. - Step 2: Find cycle where name = 'Alpha_v1', get its buildID (e.g., 1494) and releaseID (e.g., 3729) 20. - Step 3: Call UPDATE_CYCLE with cycle.buildID = 1494 and cycle.releaseID = 3729 21. CYCLE IDENTIFICATION: 22. - NEVER assume or guess buildID or releaseID - always fetch from API 23. - Cycle names are user-defined strings (e.g., 'Sprint 2', 'Alpha_v1', 'Regression Cycle') 24. - buildID and releaseID are numeric identifiers assigned by QMetry 25. - Match cycle names case-insensitively when searching 26. - If multiple cycles match the name, ask user to clarify or use the most recent one 27. - FETCH_RELEASES_CYCLES returns: projects.releases[].builds[] array with name, buildID, and releaseID 28. Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY 29. Check your QMetry instance settings to determine the correct date format 30. NOTE: To verify/update the Date Format - Go to QMetry -> User Profile 31. If dates are in wrong format, QMetry will return an error - verify format with admin 32. You can update name, startDate, or targetDate independently or together 33. Only include the fields you want to update - other fields will remain unchanged 34. startDate and targetDate help with sprint planning and milestone tracking 35. Cycle hierarchy: Project → Release → Cycle → Test Execution 36. After updating a cycle, you can verify changes using FETCH_RELEASES_CYCLES tool 37. DIFFERENCE FROM CREATE_CYCLE: This tool updates an EXISTING cycle, while CREATE_CYCLE creates a new one

Create a new test case in QMetry with steps, metadata, and release/cycle mapping.

Toolset: Test Cases

Parameters:

• tcFolderID (string): Test Case folder ID - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TC.id automatically. Manual folder ID only needed if you want to target a specific sub-folder.

• steps (array): STEPS INCLUSION RULE — read before deciding whether to include this field:

DEFAULT BEHAVIOR: OMIT 'steps' entirely from the payload. Do NOT include steps: [] (empty array). A test case without steps is valid and is the normal case when the user did not mention steps.

INCLUDE 'steps' ONLY in these two scenarios: SCENARIO 1 — User explicitly mentions steps in their prompt. Examples: 'create test case with steps', 'step 1: open browser, step 2: click login', 'add these steps: ...', 'include steps', 'create with following steps'. When user provides step text, parse each step into { orderId, description, inputData?, expectedOutcome? }.

SCENARIO 2 — Any field in 'stepSystemFields' OR 'stepFields' from Fetch UDF Layout has isMandatory=true. stepSystemFields = built-in step fields (description, expectedOutcome, etc.). stepFields = step-level UDF fields (custom fields configured per project). If EITHER array has isMandatory=true on any entry, the backend REQUIRES at least 1 step. In this case you MUST include at least 1 step even if the user did not mention steps. Also fill mandatory step UDF fields from stepFields in step.UDF — use stepDefaultValues if defaults exist, else placeholder. Ask the user for step content OR create a placeholder step with description='Step 1'.

NEVER include 'steps' in any other scenario — omitting it keeps the payload clean and avoids BE errors. NEVER send steps: [] (empty array) — either omit the field or send at least 1 valid step object.

Step object fields: orderId (required): sequential integer starting at 1 description (required): step action text inputData (optional): test data for this step expectedOutcome (optional): what should happen after this step UDF (optional): step-level custom fields tcStepID (omit on create — only used when updating existing steps)

• name (string) required

• priority (number)

• component (array)

• testcaseOwner (number)

• testCaseState (number)

• testCaseType (number)

• estimatedTime (number): Estimated execution time in SECONDS (e.g. 3600 = 1 hour, 36000 = 10 hours). NOT minutes.

• testingType (number)

• description (string)

• associateRelCyc (boolean)

• releaseCycleMapping (array): Release/cycle mapping. Set associateRelCyc=true when providing this. version field defaults to 1 if not specified.

• 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 test case ID, summary, and creation metadata.

Use Cases: 1. Create a basic test case with just a name and folder 2. Add detailed steps with custom fields (UDFs) to a test case 3. Associate test case with specific release/cycle for planning 4. Set priority, owner, component, and other metadata using valid IDs from project info 5. Create test cases for automation or manual testing types 6. Add test case to a specific folder using tcFolderID 7. Include estimated execution time and description 8. Map test case to multiple cycles/releases

Examples:

1. MOST COMMON: Create test case with name only — NO steps (user did not mention steps). Steps field is OMITTED from payload.

{
  "name": "Login Test Case"
}

Expected Output: Test case created without steps. Steps field omitted entirely from payload — do NOT add steps: [].

2. Create test case with metadata only — no steps (user did not mention steps)

{
  "tcFolderID": "102653",
  "name": "Login Test Case",
  "priority": 2025268,
  "testCaseState": 2025271,
  "estimatedTime": 3600,
  "description": "Verifies login flow"
}

Expected Output: Test case created with metadata, no steps. Steps omitted from payload.

3. SCENARIO 1: User explicitly asked for steps — 'create test case with step 1 - Go to login page, step 2 - enter credentials'

{
  "tcFolderID": "102653",
  "name": "Login Flow Test",
  "steps": [
    {
      "orderId": 1,
      "description": "Go to login page"
    },
    {
      "orderId": 2,
      "description": "Enter credentials"
    }
  ]
}

Expected Output: Test case created with 2 steps because user explicitly mentioned steps in prompt.

4. SCENARIO 1: User provided steps with full metadata (steps explicitly mentioned in prompt)

{
  "tcFolderID": "102653",
  "name": "Test Case 1",
  "steps": [
    {
      "orderId": 1,
      "description": "First Step",
      "inputData": "First Data",
      "expectedOutcome": "First Outcome",
      "UDF": {
        "customField1": "Custom Field Data A",
        "customField2": "Custom Field Data B"
      }
    }
  ],
  "priority": 2025268,
  "component": [
    2025328
  ],
  "testcaseOwner": 1467,
  "testCaseState": 2025271,
  "testCaseType": 2025282,
  "estimatedTime": 10,
  "description": "Description",
  "testingType": 2025275,
  "associateRelCyc": true,
  "releaseCycleMapping": [
    {
      "release": 14239,
      "cycle": [
        21395
      ],
      "version": 1
    }
  ]
}

Expected Output: Test case created with steps because user explicitly requested steps. All metadata populated.

5. SCENARIO 2: stepSystemFields has isMandatory=true — backend requires at least 1 step even though user did not ask for steps

{
  "name": "Mandatory Step Test Case",
  "steps": [
    {
      "orderId": 1,
      "description": "Step 1"
    }
  ]
}

Expected Output: Test case created with 1 mandatory step because stepSystemFields from Fetch UDF Layout had isMandatory=true. User was not prompted for step details — a minimal step was included to satisfy backend requirement.

Hints: 1. ╔══════════════════════════════════════════════════════════════════════════════╗ 2. ║ STEPS DECISION RULE — APPLY BEFORE EVERY CREATE CALL (NO EXCEPTIONS) ║ 3. ╚══════════════════════════════════════════════════════════════════════════════╝ 4. 5. DEFAULT: OMIT 'steps' from payload. Do NOT include steps: [] (empty array). 6. Test cases without steps are fully valid. The backend does NOT require steps unless noted below. 7. 8. INCLUDE 'steps' ONLY in exactly 2 scenarios: 9. 10. SCENARIO 1 — User explicitly mentions steps in their prompt. 11. Trigger phrases: 'with steps', 'step 1 -', 'add steps', 'include steps', 'following steps', 'these steps'. 12. Action: Parse the user's step text into { orderId, description, inputData?, expectedOutcome? } objects. 13. Example: 'create test case, step 1 - open browser, step 2 - click login' 14. → steps: [{ orderId: 1, description: 'open browser' }, { orderId: 2, description: 'click login' }] 15. 16. SCENARIO 2 — Fetch UDF Layout returns stepSystemFields[] OR stepFields[] with isMandatory=true on any entry. 17. Trigger: stepSystemFields (built-in step fields) OR stepFields (step-level UDFs) has at least 1 field where isMandatory=true. 18. Action: MUST include at least 1 step. If user gave no step text, use description='Step 1' as placeholder. 19. Also fill mandatory step UDF fields (from stepFields) in step.UDF — use stepDefaultValues if defaults exist, else a placeholder value. 20. IMPORTANT: Inform the user that a step was required by the backend configuration. 21. 22. NEVER include steps in any other case — including when the user only says 'create test case named X'. 23. NEVER send steps: [] — either omit the key entirely OR send array with at least 1 valid step. 24. 25. QUICK DECISION TABLE: 26. | User mentioned steps? | stepSystemFields OR stepFields mandatory? | Action | 27. |-----------------------|------------------------------------------|---------------------------------------------------------------| 28. | NO | NO | OMIT steps entirely (most common case) | 29. | YES | NO | Include steps from user's prompt | 30. | NO | YES | Include 1 placeholder step + fill mandatory step UDFs, inform user | 31. | YES | YES | Include steps from user's prompt + fill mandatory step UDFs | 32. 33. ╚══════════════════════════════════════════════════════════════════════════════╝ 34. 35. ╔══════════════════════════════════════════════════════════════════╗ 36. ║ STEP 0 — NON-NEGOTIABLE: Call 'Fetch UDF Layout' BEFORE create ║ 37. ╚══════════════════════════════════════════════════════════════════╝ 38. NEVER call 'Create Test Case' without first calling 'Fetch UDF Layout' with entityType='TC', pageName='ADD'. 39. Skipping this step WILL cause 400 errors (CO.MANDATORY_FIELDS_MISSING) because mandatory fields and defaults are unknown. 40. This rule has NO exceptions — not even when the user only provided a name and nothing else. 41. 42. === MANDATORY PRE-CREATE CHECK === 43. 44. SYSTEM FIELDS mandatory check — use 'systemFields' array from Fetch UDF Layout: 45. Each entry: { name, label, fieldTypeName, isMandatory } 46. isMandatory=true (allowBlank=false in QMetry) means the field MUST have a value. 47. IMPORTANT: QMetry's API sometimes returns 'systemFields: []' (empty) even when system fields ARE mandatory. 48. If 'systemFields' is empty, treat the following as always mandatory: name (Summary), testCaseState (Status). 49. For testCaseState default: check 'customListObjs.testCaseState' from Fetch Project Info — use first non-archived entry as fallback. 50. 51. UDF FIELDS mandatory check — use 'fields' array from Fetch UDF Layout: 52. Each entry: { name, label, fieldTypeName, isMandatory, listName? } 53. IMPORTANT: QMetry's API sometimes returns isMandatory=false for fields that ARE enforced as mandatory. 54. The 'isMandatory' flag is a hint, not a guarantee. Trust the actual API error over this flag. 55. When isMandatory=true: field MUST have a value. 56. 57. DEFAULT VALUES — use 'defaultValues' object from Fetch UDF Layout: 58. Shape: { fieldName: defaultValueId } e.g. { 'lookup19': 5232630, 'estimatedTime': 18305.0, 'priority': 5232497 } 59. These are pre-configured QMetry defaults. ALWAYS auto-apply them — even when user did not mention the field. 60. IMPORTANT: QMetry's API sometimes returns 'defaultValues: {}' (empty) even when defaults exist in QMetry settings. 61. If 'defaultValues' is empty, you cannot auto-apply — ask user for mandatory fields without defaults. 62. RULE: if isMandatory=true AND defaultValues[field.name] exists → use default, do NOT ask user. 63. RULE: if isMandatory=true AND NO defaultValues[field.name] → MUST ask user before creating. 64. RULE: if isMandatory=false AND defaultValues[field.name] exists → auto-apply default if user didn't specify. 65. RULE: if isMandatory=false AND no default → skip if user didn't provide. 66. 67. ╔══════════════════════════════════════════════════════════════════════════╗ 68. ║ PRE-FLIGHT DEFAULT SWEEP — MANDATORY STEP BEFORE EVERY CREATE CALL ║ 69. ╚══════════════════════════════════════════════════════════════════════════╝ 70. After resolving mandatory fields, do a full sweep of ALL defaultValues entries: 71. For EACH key in defaultValues: 72. IF the user did not explicitly provide that field → add it to the payload using the default value. 73. This applies regardless of isMandatory — non-mandatory defaults MUST also be auto-applied. 74. Example: defaultValues = { lookup19: 5232630, estimatedTime: 18305, priority: 5232497 } 75. → user only said 'create a test case named X' 76. → payload MUST include: lookup19=5232630, estimatedTime=18305, priority=5232497 77. → WRONG to omit priority/estimatedTime just because they are not mandatory — they have defaults. 78. Skipping this sweep = missing fields in the created record = user-visible data loss. 79. ╚══════════════════════════════════════════════════════════════════════════╝ 80. 81. TEST CASE STEPS mandatory check — use BOTH 'stepSystemFields' AND 'stepFields' arrays from Fetch UDF Layout: 82. stepSystemFields: built-in step fields { name, label, fieldTypeName, isMandatory } 83. stepFields: step-level UDF fields { name, label, fieldTypeName, isMandatory, listName? } 84. If ANY field in EITHER array has isMandatory=true → SCENARIO 2 triggered → MUST include at least 1 step. 85. Mandatory stepFields UDFs must be filled in step.UDF — use stepDefaultValues for defaults, else placeholder. 86. If NO field in EITHER array has isMandatory=true AND user did not mention steps → OMIT steps from payload. 87. Step defaults: use 'stepDefaultValues' object — same auto-fill logic as defaultValues. 88. 89. DECISION MATRIX: 90. | isMandatory | Has default | Action | 91. |-------------|-------------|-------------------------------------| 92. | true | YES | Auto-fill with default, no ask | 93. | true | NO | Ask user before creating | 94. | false | YES | Auto-fill with default — REQUIRED | 95. | false | NO | Skip if user didn't provide | 96. 97. Only after ALL mandatory fields are resolved AND default sweep is complete → proceed with create. 98. === END MANDATORY PRE-CREATE CHECK === 99. 100. === ERROR RECOVERY: CO.MANDATORY_FIELDS_MISSING === 101. If create fails with error code 'CO.MANDATORY_FIELDS_MISSING', DO NOT give up. Auto-recover: 102. 1. Parse the 'MISSING_FIELDS' list from the error response (comma-separated field labels). 103. 2. Match each label against 'fields[].label' and 'systemFields[].label' from the Fetch UDF Layout response. 104. 3. For matched UDF fields: check 'listOptions[field.listName]' for valid option IDs. 105. 4. For matched system fields (e.g. 'Status'): check 'customListObjs.testCaseState' from project info. 106. 5. If the field has a 'defaultValues' entry: auto-fill it silently. 107. 6. If no default exists: ask the user ONLY for the missing fields by label. 108. 7. Retry create with the resolved values added to the payload. 109. NEVER ask user to 'try again' manually — resolve and retry automatically. 110. === END ERROR RECOVERY === 111. 112. === DATE FORMAT CHECK (MANDATORY — EVERY CREATE REQUEST) === 113. ALWAYS call 'Fetch QMetry Project Info' before every create request — not only when the user explicitly mentions a date. 114. 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). 115. Project info response contains 'dateTimeFormatID' and 'dateTimeFormatNew' array. 116. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 117. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 118. STEP 3: unique_value is the Java/QMetry format pattern. Mapping: 119. yyyy = 4-digit year | MM = 2-digit month (01-12) | dd = 2-digit day | MMM = 3-letter month (Jan/Feb/...) 120. 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' 121. STEP 4: For EVERY DATETIMEPICKER field in the payload (user-provided OR from defaultValues): 122. - Parse the date regardless of what format the user typed 123. - Re-format it using the active unique_value pattern 124. - Send the re-formatted string to the API 125. Examples with unique_value='yyyy-MM-dd': 126. User says '25 Dec 2024' → send '2024-12-25' 127. User says '12/25/2024' → send '2024-12-25' 128. Default value is a date string '2024-12-25' → already correct, keep it 129. NEVER send a date in a format different from the project's active dateTimeFormatID format. 130. Fetch project info ONCE per create/update operation and reuse dateTimeFormatID for all date fields. 131. === END DATE FORMAT CHECK === 132. 133. If tcFolderID is not provided, it will be auto-resolved to the root test case folder using project info (rootFolders.TC.id). 134. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 135. STALE / NOT-FOUND ID RECOVERY (applies to ALL system fields — priority, component/label, owner, status, testCaseType, testingType, release, cycle): If the user references a value by name and it is NOT found in your current cached project info data, DO NOT give up or skip the field immediately. Instead: call 'Fetch QMetry Project Info' fresh (no arguments needed) to get the latest snapshot, then re-scan the relevant customListObjs list. This is mandatory when: (a) the user just added a new label/priority/status/user in QMetry UI, or (b) the cached info is from an earlier turn. Only skip + show a friendly message if the value is still missing AFTER the fresh fetch. 136. FOLDER ID RESOLUTION (tcFolderID): Project info only exposes the ROOT folder ID (rootFolders.TC.id). Sub-folder IDs are NOT returned by project info. If the user specifies a sub-folder (e.g. 'Folder 1'), use this resolution order: 1. Check if the user already provided the numeric folder ID — use it directly. 2. Try fetching test cases with folderPath='' and scope='folder' — if a TC exists there, its folder context confirms the path, but the ID is still needed from the UI. 3. If still unresolved, ask the user: 'Please provide the numeric folder ID for "". You can find it in the QMetry URL when browsing that folder (look for folderId=XXXXX).' NEVER silently fall back to root folder when the user explicitly named a sub-folder — always ask first. 137. If the user provides a priority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.priority[index].name, and use its ID in the payload. If the name is not found after a fresh fetch, skip the priority field (it is not required) and show a user-friendly message: 'Test case created without priority, as given priority is not available in the current project.' 138. If the user provides a component name, fetch project info, find the matching component in customListObjs.component[index].name, and use its ID in the payload. If the name is not found, skip the component field (it is not required) and show a user-friendly message: 'Test case created without component, as given component is not available in the current project.' 139. If the user provides an owner name, fetch project info, find the matching owner in customListObjs.owner[index].name, and use its ID in the payload as testcaseOwner. If the name is not found, skip the testcaseOwner field (it is not required) and show a user-friendly message: 'Test case created without owner, as given owner is not available in the current project.' 140. If the user provides a test case state name, fetch project info, find the matching state in customListObjs.testCaseState[index].name, and use its ID in the payload as testCaseState. If the name is not found, skip the testCaseState field (it is not required) and show a user-friendly message: 'Test case created without test case state, as given state is not available in the current project.' 141. If the user provides a test case type name, fetch project info, find the matching type in customListObjs.testCaseType[index].name, and use its ID in the payload as testCaseType. If the name is not found, skip the testCaseType field (it is not required) and show a user-friendly message: 'Test case created without test case type, as given type is not available in the current project.' 142. If the user provides a testing type name, fetch project info, find the matching type in customListObjs.testingType[index].name, and use its ID in the payload as testingType. If the name is not found, skip the testingType field (it is not required) and show a user-friendly message: 'Test case created without testing type, as given testing type is not available in the current project.' 143. Example: If user says 'Create test case with title "High priority test case" and set priority to "Blocker"', first call project info, map 'Blocker' to its ID, and use that ID for the priority field in the create payload. If user says 'set priority to "Urgent"' and 'Urgent' is not found, skip the priority field and show: 'Test case created without priority, as given priority is not available in the current project.' 144. tcFolderID is required; use the root folder ID from project info or a specific folder. 145. STEPS: Omit steps from payload by default. Only include steps when user explicitly mentions them (SCENARIO 1) or stepSystemFields/stepFields has isMandatory=true (SCENARIO 2). See STEPS DECISION RULE at top of hints. 146. If the user provides a prompt like 'create test case with steps as step 1 - Go to login page, step 2 - give credential, step 3 - go to test case page, step 4 - create test case', LLM should parse each step and convert it into the steps payload array, mapping each step to an object with orderId, description, and optionally inputData and expectedOutcome. 147. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 148. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 149. Demo steps payload: steps: [ { orderId: 1, description: 'First Step', inputData: 'First Data', expectedOutcome: 'First Outcome', UDF: { customField1: 'Custom Field Data A', customField2: 'Custom Field Data B' } }, ... ] 150. UDF fields in steps must match your QMetry custom field configuration. 151. Release/cycle mapping is optional but useful for planning. 152. If the user wants to link or associate a release and cycle to the test case, set associateRelCyc: true in the payload. 153. If the user provides a release ID, map it from projects.releases[index].releaseID in the project info response, and use that ID in releaseCycleMapping. 154. If the user provides both release and cycle IDs, validate both against the current project's releases and cycles; if valid, use them in releaseCycleMapping. 155. When adding releaseCycleMapping, always include the 'version' field (usually set to 1) in each mapping object. The correct format is: { release: , cycle: [], version: 1 }. If 'version' is missing, the request will fail. 156. If the user provides a release name, map it to its ID from project info; if a cycle name is provided, map it to its ID from the associated release's builds list. 157. Example payload: releaseCycleMapping: [ { release: , cycle: [], version: 1 } ] 158. LLM should ensure that provided release/cycle names or IDs exist in the current project before using them in the payload. If not found, skip and show a user-friendly message: 'Test case created without release/cycle association, as given release/cycle is not available in the current project.' 159. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 160. If a custom field is mandatory, include it in the UDF object. 161. estimatedTime is in SECONDS (e.g. 3600 = 1 hour, 36000 = 10 hours). NOT minutes. 162. Description and testingType are optional but recommended for clarity. 163. 164. UDF (User Defined Fields) WORKFLOW FOR CREATE: 165. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='ADD' to discover field names, types, list option IDs, and udfmID (projectUserFieldID). 166. 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. 167. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 168. 3. For MULTILOOKUPLIST fields: pick an array of IDs from listOptions[field.listName][].id. 169. 4. For CASCADINGLIST fields (ROOT-LEVEL UDF — MANDATORY STEPS): 170. a. MUST call 'Fetch Cascade Child Values' with parentId to get available child options (do NOT skip this step). 171. b. Pass the cascade value as: { parent: parentId, child: childId } in udfFields. 172. Example: udfFields: { project19: { parent: 5232623, child: 5232625 } } 173. 5. For STRING/LARGETEXT/NUMBER/DATETIMEPICKER: pass value directly. 174. 6. Pass all UDF values via 'udfFields' param: { fieldName: value }. 175. 7. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail. 176. 177. STEP UDFs: Pass step UDF values in each step's 'UDF' object. 178. Call 'Fetch UDF Layout' for stepFields to discover field names, types, and udfmID (projectUserFieldID). 179. Step UDF field types follow same rules as root UDF EXCEPT for CASCADINGLIST — step cascade requires a DIFFERENT format: 180. 181. STEP CASCADINGLIST UDF FORMAT (critical — different from root cascade): 182. For a cascade field named 'project19' with udfmID=2637584, parent={id:5232626, value:'React'}, child={id:5232628, value:'Redux'}: 183. You MUST include THREE keys inside the step's UDF object: 184. 1. fieldName: { parent: parentId, child: childId } 185. e.g. project19: { parent: 5232626, child: 5232628 } 186. 2. fieldName_value: [{ FieldID: 'fieldName', FieldValue: [{ id: parentId, value: 'parentLabel', child: { id: childId, value: 'childLabel' } }], type: 'CASCADINGLIST' }] 187. e.g. project19_value: [{ FieldID: 'project19', FieldValue: [{ id: 5232626, value: 'React', child: { id: 5232628, value: 'Redux' } }], type: 'CASCADINGLIST' }] 188. 3. fieldName_selectedList: { id: udfmID, name: 'fieldName', type: 'CASCADINGLIST' } 189. e.g. project19_selectedList: { id: 2637584, name: 'project19', type: 'CASCADINGLIST' } 190. To get parentLabel and childLabel: call 'Fetch Cascade Child Values' — it returns option labels alongside IDs. 191. udfmID comes from Fetch UDF Layout stepFields[].projectUserFieldID. 192. NEVER omit _value or _selectedList for step cascade fields — the API silently ignores cascade data without them.

Update an existing QMetry test case OR create a new version by tcID and tcVersionID, with auto-resolution from entityKey.

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• tcVersionID (number) required: Test Case version number. This is the internal numeric identifier for the version.

• tcVersion (number): Test Case version number (required when withVersion=true for creating new version). This is the current version number from which a new version will be created.

• withVersion (boolean): Pass 'true' if you want to create a new version of the test case with incremented version number. When true, a new version is created (e.g., if current version is 2, new version 3 is created). When false or omitted, updates the existing version specified by tcVersionID. IMPORTANT: Always send proper tcVersionID to identify which version the request is for.

• versionComment (string): Comment or description for the new version (used only when withVersion=true). Helps track what changed in this new version. Example: 'Updated test steps for new requirements'

• notruncurrent (boolean): Flag to control execution behavior for current version when creating a new version. Used in conjunction with withVersion=true.

• notrunall (boolean): Flag to control execution behavior for all versions when creating a new version. Used in conjunction with withVersion=true.

• folderPath (string): Folder path for test suites - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• isStepUpdated (boolean): Set to true when steps are being added, updated, or removed. Required when including 'steps' or 'removeSteps' arrays.

• steps (array)

• removeSteps (array)

• name (string)

• priority (number)

• component (array)

• owner (number)

• testCaseState (number)

• testCaseType (number)

• estimatedTime (number): Estimated execution time in seconds. Example: 7200 for 2 hours

• executionMinutes (number)

• testingType (number)

• description (string)

• updateOnlyMetadata (boolean): Set to true to update only metadata fields without touching test steps. When true, steps and removeSteps are ignored.

• 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.

• UDF (record<string, object>): UDF wrapper required for update operations. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value. Also set matching flat key in udfFields for the LOOKUPLIST Alias display. Example: { custom_text: { fieldID: 1001, value: 'new value' } }

Output Description: JSON object containing the test case ID, version ID, summary, update/creation metadata. When withVersion=true (version creation), response includes new version number and version ID. When withVersion=false/omitted (existing version update), response includes updated fields confirmation.

Use Cases: 1. Update test case summary (name) 2. Change priority, owner, or state of a test case 3. Edit, add, or remove test steps 4. Update only metadata (no steps) 5. Create a new version of a test case (withVersion=true) 6. Update a specific version of a test case (without withVersion flag) 7. Bulk update using entityKey auto-resolution 8. Modify test case description or estimated time 9. Change test case type or component 10. Update testing type or custom fields 11. Update, add and remove test case steps 12. Version control for test case evolution tracking

Examples:

1. Update test case summary (existing version update)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "name": "MAC Test11"
}

Expected Output: Test case summary updated. tcID and tcVersionID auto-resolved from entityKey. Only 'name' field changed. Version remains the same.

2. Create NEW VERSION with updated summary and description

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "description": "Test Description version 2",
  "withVersion": true,
  "versionComment": "version 2 comment add",
  "notruncurrent": true,
  "notrunall": true
}

Expected Output: New version created (version 2). Test case now has incremental version with updated summary and description. Original version 1 remains unchanged.

3. Create NEW VERSION with all metadata fields (release, cycle, priority, owner, etc.)

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Facebook Login Validation Failed update from MCP V2",
  "description": "Existing description V2",
  "priority": 2355751,
  "testcaseOwner": 6963,
  "testCaseState": 2355753,
  "testCaseType": 2355762,
  "estimatedTime": 7200,
  "withVersion": true,
  "versionComment": "Created version 2 with updated metadata",
  "notruncurrent": true,
  "notrunall": true,
  "folderPath": 602290,
  "scope": "project"
}

Expected Output: New test case version 2 created with updated summary, description, priority (High), owner (umang.savaliya), state, type, and estimated time (2 hours). Version comment added for tracking.

4. Update EXISTING VERSION 2 (not creating new version)

{
  "tcID": 4572654,
  "tcVersionID": 5514385,
  "name": "Updated version 2 name",
  "priority": 2355752
}

Expected Output: Version 2 updated with new name and priority. No new version created because withVersion flag is not set. This is a normal update of existing version.

5. Update priority to High and owner to john.doe (existing version)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "priority": 505015,
  "testcaseOwner": 6963
}

Expected Output: Priority and owner updated. Field IDs auto-resolved from project info. tcID/tcVersionID resolved from entityKey. Existing version modified.

6. Update steps (edit, add, remove) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "steps": [
    {
      "orderId": 1,
      "description": "Step 22",
      "inputData": "Input 22",
      "expectedOutcome": "Outcome 22",
      "tcStepID": 3014032
    },
    {
      "orderId": 2,
      "description": "Step3",
      "inputData": "Input 3",
      "expectedOutcome": "Outcome 3"
    }
  ],
  "removeSteps": [
    {
      "tcStepID": 3014031,
      "description": "Step 1",
      "orderId": 1
    }
  ],
  "isStepUpdated": true
}

Expected Output: Steps updated: Step 22 edited (tcStepID preserved), Step3 added (no tcStepID), Step 1 removed. tcID/tcVersionID auto-resolved. Existing version modified.

7. Create NEW VERSION with updated steps

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "steps": [
    {
      "orderId": 1,
      "description": "I and u have a calculator",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001791
    },
    {
      "orderId": 2,
      "description": "I add 41 and 31",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001793
    },
    {
      "orderId": 3,
      "description": "the result should be 72",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001792
    }
  ],
  "withVersion": true,
  "versionComment": "version 2 with preserved steps",
  "notruncurrent": true,
  "notrunall": true,
  "isStepUpdated": true
}

Expected Output: New version 2 created with all steps from version 1 preserved. Steps carry forward with their tcStepID values. Version comment added for tracking.

8. Update only metadata (no steps) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "updateOnlyMetadata": true,
  "name": "New Name"
}

Expected Output: Metadata updated only. Steps unchanged. tcID/tcVersionID auto-resolved. Existing version modified.

9. Create NEW VERSION from existing version 2 with updated steps (working payload for linked test cases)

{
  "tcID": 4594145,
  "tcVersionID": 5536706,
  "tcVersion": 2,
  "name": "Mock Test Case - E-commerce Checkout Flow - v3",
  "steps": [
    {
      "orderId": 1,
      "description": "Open browser and navigate to e-commerce website",
      "expectedOutcome": "Homepage loads successfully with product catalog",
      "inputData": "URL: https://example-shop.com",
      "tcStepID": 38129471
    },
    {
      "orderId": 2,
      "description": "Search for product",
      "expectedOutcome": "Search results display relevant products",
      "inputData": "Search term: 'wireless headphones'",
      "tcStepID": 38129475
    },
    {
      "orderId": 3,
      "description": "Select product and add to cart",
      "expectedOutcome": "Product added to cart, cart counter increments",
      "inputData": "Click 'Add to Cart' button",
      "tcStepID": 38129472
    },
    {
      "orderId": 4,
      "description": "Proceed to checkout",
      "expectedOutcome": "Checkout page displays with cart summary",
      "inputData": "Click cart icon and 'Proceed to Checkout'",
      "tcStepID": 38129473
    },
    {
      "orderId": 5,
      "description": "Complete payment",
      "expectedOutcome": "Order confirmation page displayed",
      "inputData": "Fill payment details and submit",
      "tcStepID": 38129474
    },
    {
      "orderId": 6,
      "description": "Verify order confirmation email received",
      "expectedOutcome": "Email with order details received in inbox",
      "inputData": "Check email account for confirmation"
    },
    {
      "orderId": 7,
      "description": "Check order status in account dashboard",
      "expectedOutcome": "Order status shows as 'Processing' with tracking information",
      "inputData": "Navigate to My Orders section"
    }
  ],
  "withVersion": true,
  "versionComment": "Created version 3: Added 2 new verification steps (email and order status check)",
  "notrunall": false,
  "notruncurrent": false,
  "scope": "project"
}

Expected Output: New version 3 created successfully from version 2. Test case now has 7 steps (5 preserved + 2 new). Key: tcVersion=2 was used because version 2 already existed in system. notrunall and notruncurrent both false (not true). Result shows tcVersion: 3 in response with new tcVersionID.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout): { fieldName: defaultValueId } — sweep ALL entries. 4. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload with the default value. 5. This applies to non-mandatory fields too (e.g. priority, estimatedTime). Omitting them = data loss. 6. === END DEFAULT VALUES === 7. 8. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 9. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 10. 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). 11. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 12. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 13. 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/...). 14. 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' 15. 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. 16. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 17. === END DATE FORMAT CHECK === 18. 19. CRITICAL - VERSION CREATION vs UPDATE DISTINCTION: 20. This tool supports TWO MODES using the SAME API endpoint: 21. 22. MODE 1: CREATE NEW VERSION (withVersion=true) 23. - Purpose: Create an incremental version of the test case (e.g., v1 → v2, v2 → v3) 24. - When to use: User explicitly asks to 'create new version', 'create version 2', 'increment version' 25. - Required fields: tcID, tcVersionID (of source version), tcVersion (current version number), withVersion=true 26. - Optional but recommended: versionComment (track what changed), notruncurrent, notrunall 27. - Behavior: Creates a NEW test case version with incremented version number. Source version remains unchanged. 28. - Example: If current version is 1, setting withVersion=true creates version 2 29. - Use cases: Updating test case for new requirements, creating variants for different scenarios, version control 30. 31. MODE 2: UPDATE EXISTING VERSION (withVersion=false or omitted) 32. - Purpose: Modify fields of an EXISTING version without creating a new version 33. - When to use: User asks to 'update test case', 'modify version X', 'change summary' (without mentioning new version) 34. - Required fields: tcID, tcVersionID (of version to update) 35. - Do NOT include: withVersion flag, versionComment, tcVersion 36. - Behavior: Updates the specified version in-place. No new version is created. 37. - Example: Updating version 2's summary - only version 2 is modified, no version 3 is created 38. - Use cases: Fixing typos, updating metadata, modifying steps in existing version 39. 40. CRITICAL FIELD UNDERSTANDING: 41. - tcVersionID: The VERSION ID (numeric identifier) of the version you're working with 42. - tcVersion: The VERSION NUMBER (1, 2, 3, etc.) - only needed when withVersion=true 43. - tcID: The TEST CASE ID (remains same across all versions) 44. - Example: Test case VKMCP-TC-10 (tcID: 4572654) has version 1 (tcVersionID: 5514384, tcVersion: 1) 45. - When creating version 2 from version 1: Send tcVersionID=5514384 (source), tcVersion=1 (current), withVersion=true 46. 47. HOW TO DETERMINE WHICH MODE: 48. - User says 'create new version' → MODE 1 (withVersion=true) 49. - User says 'create version 2' → MODE 1 (withVersion=true) 50. - User says 'update test case with new version' → MODE 1 (withVersion=true) 51. - User says 'update test case VKMCP-TC-10 summary' → MODE 2 (no withVersion, update existing version) 52. - User says 'update version 2 summary' → MODE 2 (no withVersion, update existing version 2) 53. - User says 'change priority of version 1' → MODE 2 (no withVersion, update version 1) 54. - If ambiguous, ask user: 'Do you want to create a new version or update the existing version?' 55. 56. VERSION CREATION WORKFLOW (withVersion=true): 57. Step 1: Fetch test case details to get current tcID, tcVersionID, and tcVersion 58. Step 2: Optionally fetch current steps if they need to be preserved/modified 59. Step 3: Prepare payload with: 60. - tcID (test case ID) 61. - tcVersionID (source version ID to create from) 62. - tcVersion (current version number) 63. - withVersion: true (CRITICAL flag) 64. - versionComment (recommended: describe what changed) 65. - Updated fields (name, description, priority, steps, etc.) 66. - notruncurrent: true (recommended) 67. - notrunall: true (recommended) 68. Step 4: Call update API - a new version will be created with incremented version number 69. Step 5: New version inherits all fields from source version, with your specified updates applied 70. 71. EXISTING VERSION UPDATE WORKFLOW (no withVersion): 72. Step 1: Fetch test case details to get tcID and tcVersionID of the version to update 73. Step 2: Prepare payload with: 74. - tcID (test case ID) 75. - tcVersionID (version ID to update) 76. - DO NOT include withVersion, versionComment, or tcVersion 77. - Only include fields you want to change 78. Step 3: Call update API - specified version is updated in-place 79. Step 4: No new version is created, only specified fields are modified 80. 81. FIELD MAPPING FOR VERSION CREATION: 82. When creating a new version, include ALL fields you want the new version to have: 83. - name: Test case summary (required if different from source) 84. - description: Test case description (required if different from source) 85. - priority: Priority ID (get from project info customListObjs.priority[index].id) 86. - testcaseOwner: Owner ID (get from project info customListObjs.owner[index].id) 87. - testCaseState: State ID (get from project info customListObjs.testCaseState[index].id) 88. - testCaseType: Type ID (get from project info customListObjs.testCaseType[index].id) 89. - testingType: Testing type ID (get from project info customListObjs.testingType[index].id) 90. - component: Array of component IDs (get from project info customListObjs.component[index].id) 91. - estimatedTime: Time in seconds (e.g., 7200 for 2 hours) 92. - steps: Array of step objects (include tcStepID from source version to preserve steps) 93. - folderPath: Folder path or folder ID 94. - scope: Usually 'project' 95. 96. STEPS HANDLING IN VERSION CREATION: 97. When creating a new version WITH steps: 98. - To PRESERVE existing steps: Include them with their original tcStepID values 99. - To ADD new steps: Include them WITHOUT tcStepID 100. - To MODIFY steps: Include them with tcStepID and updated description/data 101. - To REMOVE steps: Include them in removeSteps array 102. - Set isStepUpdated: true if any steps are modified, added, or removed 103. - If no steps are included, new version may inherit steps from source (verify with QMetry docs) 104. 105. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with a filter on entityKeyId to resolve the tcID and tcVersionID. 106. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 107. If the user provides a priority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.priority[index].name, and use its ID in the payload. If the name is not found, skip the priority field (it is not required) and show a user-friendly message: 'Test case updated without priority, as given priority is not available in the current project.' 108. If the user provides a component name, fetch project info, find the matching component in customListObjs.component[index].name, and use its ID in the payload. If the name is not found, skip the component field (it is not required) and show a user-friendly message: 'Test case updated without component, as given component is not available in the current project.' 109. If the user provides an owner name, fetch project info, find the matching owner in customListObjs.owner[index].name, and use its ID in the payload as testcaseOwner. If the name is not found, skip the testcaseOwner field (it is not required) and show a user-friendly message: 'Test case updated without owner, as given owner is not available in the current project.' 110. If the user provides a test case state name, fetch project info, find the matching state in customListObjs.testCaseState[index].name, and use its ID in the payload as testCaseState. If the name is not found, skip the testCaseState field (it is not required) and show a user-friendly message: 'Test case updated without test case state, as given state is not available in the current project.' 111. If the user provides a test case type name, fetch project info, find the matching type in customListObjs.testCaseType[index].name, and use its ID in the payload as testCaseType. If the name is not found, skip the testCaseType field (it is not required) and show a user-friendly message: 'Test case updated without test case type, as given type is not available in the current project.' 112. If the user provides a testing type name, fetch project info, find the matching type in customListObjs.testingType[index].name, and use its ID in the payload as testingType. If the name is not found, skip the testingType field (it is not required) and show a user-friendly message: 'Test case updated without testing type, as given testing type is not available in the current project.' 113. Example: If user says 'Update test case with title "High priority test case" and set priority to "Blocker"', first call project info, map 'Blocker' to its ID, and use that ID for the priority field in the update payload. If user says 'set priority to "Urgent"' and 'Urgent' is not found, skip the priority field and show: 'Test case updated without priority, as given priority is not available in the current project.' 114. CRITICAL: To update test case steps without Duplication, use the following rules: 115. - ANTI-DUPLICATION RULE: The tcStepID field is THE KEY to prevent duplication: 116. * WITH tcStepID = UPDATE existing step (QMetry modifies the existing step in place) 117. * WITHOUT tcStepID = CREATE new step (QMetry adds a brand new step) 118. - For steps to be UPDATED: ALWAYS fetch existing steps first using FETCH_TEST_CASE_STEPS, then include the tcStepID in the step object. 119. - For steps to be ADDED: omit tcStepID completely in the step object. 120. - For steps to be REMOVED: add a full removeSteps object for each step to be deleted, matching the removeTestCaseStep interface. 121. - CRITICAL WARNING - DO NOT ADD UNSOLICITED STEPS: 122. * ONLY add, edit, or remove steps that the user EXPLICITLY requested 123. * DO NOT invent, create, or add extra steps based on assumptions or best practices 124. * DO NOT add 'helpful' steps that the user did not ask for 125. * When user says 'remove step 1', the result should have (N-1) steps, not N steps with extras 126. * When user says 'add 1 step', ONLY add that 1 step, nothing more 127. * When user says 'update step 2', ONLY update step 2, do not add or modify other steps 128. * If unsure what user wants, ASK first rather than adding steps autonomously 129. - WORKFLOW TO AVOID DUPLICATION: 130. 1. Call FETCH_TEST_CASE_STEPS to get all existing steps with their tcStepID values 131. 2. For steps you want to KEEP/UPDATE: Include them in steps[] WITH their original tcStepID 132. 3. For steps you want to ADD: Include them in steps[] WITHOUT tcStepID (ONLY if user requested) 133. 4. For steps you want to REMOVE: Include them in removeSteps[] with full details 134. 5. Always set isStepUpdated: true if steps are added, updated, or removed 135. 6. VERIFY your steps array matches user's explicit request (count and content) 136. - Example: If user says 'Edit step 1 to say ...', FIRST fetch steps to get tcStepID for step 1, THEN include it in the steps array with updated fields and the ORIGINAL tcStepID. 137. - Example: If user says 'Add a new step after step 2', add EXACTLY ONE new object to steps array with no tcStepID (not multiple steps). 138. - Example: If user says 'Remove step 3', add the full step object to removeSteps array, including tcStepID and all required fields. Do NOT add replacement steps. 139. - Example: If test case has 3 steps and user says 'remove step 1', result should have 2 steps (step 2 and step 3 with updated orderIds), NOT 3 steps with extras. 140. - Example: If user says 'add one mock step', add EXACTLY ONE step (not 2 or 3 steps even if they seem related). 141. - COMPLETE PAYLOAD EXAMPLE: { tcID: 123, tcVersionID: 456, steps: [{tcStepID: 1001, orderId: 1, description: 'Updated'}, {orderId: 2, description: 'New'}], removeSteps: [{tcStepID: 1002, orderId: 3, ...}], isStepUpdated: true } 142. - If only metadata is updated (no steps), set updateOnlyMetadata: true and do not include steps/removeSteps. 143. - Always preserve orderId sequence for proper step ordering. 144. - If user prompt is ambiguous, ask for clarification or show a user-friendly error. 145. - WARNING: Omitting tcStepID for existing steps will cause DUPLICATION - the API will create duplicates instead of updating! 146. - FINAL VERIFICATION BEFORE SENDING REQUEST: 147. * Count steps in your payload vs what user requested 148. * If user said 'add 1 step', steps array should have (existing_count + 1) items total 149. * If user said 'remove 1 step', steps array should have (existing_count - 1) items total, removeSteps should have 1 item 150. * If user said 'update step X', steps array should have same count as before, with step X's tcStepID preserved 151. * NEVER include steps the user did not explicitly mention or request 152. Steps are optional but recommended for manual test cases. 153. If the user provides a prompt like 'update test case with steps as step 1 - Go to login page, step 2 - give credential, step 3 - go to test case page, step 4 - create test case', LLM should parse each step and convert it into the steps payload array, mapping each step to an object with orderId, description, and optionally inputData and expectedOutcome. 154. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 155. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 156. Demo steps payload: steps: [ { orderId: 1, description: 'First Step', inputData: 'First Data', expectedOutcome: 'First Outcome', UDF: { customField1: 'Custom Field Data A', customField2: 'Custom Field Data B' } }, ... ] 157. UDF fields in steps must match your QMetry custom field configuration. 158. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 159. If a custom field is mandatory, include it in the UDF object. 160. 161. ADDITIONAL VERSION CREATION GUIDANCE: 162. - versionComment field: STRONGLY RECOMMENDED when withVersion=true. Helps track why version was created. 163. Example comments: 'Updated for Sprint 5 requirements', 'Fixed test steps based on code review', 'Version 2 for production environment' 164. - notruncurrent and notrunall flags: Control execution behavior when creating versions. Set both to true as best practice. 165. - folderPath: Can be string path or numeric folder ID. Usually inherited from source version if not specified. 166. - attachments: Use ADD/REMOVE arrays to manage attachments when creating new version or updating existing version. 167. - estimatedTime vs executionMinutes: Use estimatedTime (in seconds) for version creation. executionMinutes (in minutes) is legacy field. 168. 169. REAL-WORLD VERSION CREATION EXAMPLES: 170. Example 1: User says 'create a new version of test case VKMCP-TC-10 with summary = "Facebook Login Validation Failed update from MCP V2", description = used existing description by at last add V2 text, release = default, cycle = default' 171. → Workflow: 172. 1. Fetch VKMCP-TC-10 details to get tcID, tcVersionID, tcVersion, current description 173. 2. Fetch project info to get default release ID and cycle ID 174. 3. Append ' V2' to current description 175. 4. Send payload with: tcID, tcVersionID (source), tcVersion (current), withVersion=true, name='...V2', description='...V2', versionComment='Created version 2', release/cycle IDs 176. → Result: New incremental version created (e.g., version 1 → version 2) with updated summary, modified description, associated with default release/cycle 177. 178. Example 2: User says 'update version 2 summary, release, cycle, priority' 179. → Workflow: 180. 1. Fetch test case details to get version 2's tcVersionID 181. 2. Fetch project info to get priority, release, cycle IDs 182. 3. Send payload with: tcID, tcVersionID (of version 2), WITHOUT withVersion flag, with updated summary, release, cycle, priority 183. → Result: Version 2 updated in-place. No new version created. Only specified fields modified. 184. 185. COMMON PITFALLS TO AVOID: 186. - Pitfall 1: Setting withVersion=true when user wants to update existing version → Creates unwanted new version 187. - Pitfall 2: Omitting versionComment when creating new version → Lost tracking of why version was created 188. - Pitfall 3: Not fetching current tcVersionID before update → Updating wrong version or causing error 189. - Pitfall 4: Using tcVersion for normal updates → tcVersion only needed when withVersion=true 190. - Pitfall 5: Not including tcStepID for steps when creating version → Steps may duplicate instead of preserving 191. - Pitfall 6: Confusing tcVersionID (version identifier) with tcVersion (version number) → Wrong API payload 192. 193. CRITICAL ERROR HANDLING: TC.VERSION_NOT_SYNCED FOR LINKED TEST CASES 194. 195. PROBLEM: Test cases linked to test suites or with existing executions cannot be updated directly 196. TRIGGERS: 197. ✓ Test case is linked to one or more test suites 198. ✓ Test case has execution history (test runs exist) 199. ✓ Test case is part of a release/cycle with test runs 200. ✓ Any step modification when test case has associations 201. 202. ERROR CODE: TC.VERSION_NOT_SYNCED 203. ERROR MESSAGE: 'This Test Case has been associated. Create a new version to save modifications.' 204. 205. AUTOMATIC RETRY STRATEGY (IMPLEMENT THIS PATTERN): 206. When you receive TC.VERSION_NOT_SYNCED error, AUTOMATICALLY retry with version creation: 207. DO NOT ask user for confirmation - this is expected behavior for associated test cases 208. 209. 1. FIRST ATTEMPT (Normal Update): 210. - Try updating with isStepUpdated=true (for step changes) or without withVersion flag 211. - If error code is TC.VERSION_NOT_SYNCED, proceed to step 2 212. - If error is different, report the error to user 213. 214. 2. AUTOMATIC RETRY (Version Creation): 215. - Use the SAME tcID, tcVersionID, and steps array from first attempt 216. - Add these flags to payload: 217. * withVersion: true (CRITICAL - enables version creation) 218. * tcVersion: (get from test case details or executions) 219. * notrunall: false (use false, not true) 220. * notruncurrent: false (use false, not true) 221. * scope: 'project' (always required) 222. * versionComment: 'Auto-created version due to test suite association' (or custom message) 223. - Set isStepUpdated: true whenever you modify steps (including when withVersion=true) 224. - IMPORTANT: Include ALL existing steps with tcStepID + new steps without tcStepID 225. 226. 3. VERIFICATION: 227. - Check response for new tcVersionID (will be different from source) 228. - Verify tcVersion incremented (e.g., 1→2, 2→3) 229. - Confirm success message: 'Test Case updated successfully' 230. 231. UI BEHAVIOR COMPARISON: 232. QMetry UI shows a popup: 'Save as new version?' with optional comment field 233. API equivalent: Automatic retry with withVersion=true after detecting TC.VERSION_NOT_SYNCED 234. 235. REAL-WORLD EXAMPLE FROM UI PAYLOADS: 236. 237. First Attempt (FAILS with TC.VERSION_NOT_SYNCED): 238. pseudo 239. { 240. "tcID": 4594140, 241. "tcVersionID": 5536696, 242. "withVersion": false, 243. "notrunall": false, 244. "steps": [ 245. // ... 5 existing steps with tcStepID ... 246. // ... 1 new step without tcStepID (orderId: 6) ... 247. ], 248. "removeSteps": [], 249. "isStepUpdated": true 250. } 251. 252. Response: 400 - TC.VERSION_NOT_SYNCED error 253. 254. Second Attempt (SUCCEEDS - Creates Version 2): 255. pseudo 256. { 257. "withVersion": true, // NEW: Version creation flag 258. "notrunall": false, 259. "notruncurrent": false, 260. "steps": [ 261. // SAME steps array as first attempt 262. // ... 5 existing steps with tcStepID ... 263. // ... 1 new step without tcStepID ... 264. ], 265. "removeSteps": [], 266. "scope": "project", 267. "tcID": 4594140, // SAME tcID 268. "tcVersion": 1, // NEW: Current version number 269. "tcVersionID": 5536696, // SAME tcVersionID (source version) 270. "versionComment": "test", // NEW: Version comment (optional) 271. // NOTE: isStepUpdated field is NOT included when withVersion=true 272. } 273. 274. Response: 200 - Success, new tcVersionID created (e.g., 5536697), tcVersion=2 275. 276. IMPLEMENTATION PSEUDO-CODE: 277. typescript 278. try { 279. // First attempt: Normal update 280. const response = await updateTestCase({ 281. tcID, tcVersionID, steps, isStepUpdated: true 282. }); 283. } catch (error) { 284. if (error.code === 'TC.VERSION_NOT_SYNCED') { 285. // Automatic retry with version creation 286. const testCaseDetails = await fetchTestCaseDetails(tcID); 287. // CRITICAL: Use the LATEST version number from system 288. const latestVersion = testCaseDetails.tcVersion; // e.g., 2 if v2 exists 289. const response = await updateTestCase({ 290. tcID, 291. tcVersionID, // Same source version 292. tcVersion: latestVersion, // Use latest version number (not always 1!) 293. steps, // Same steps array 294. // DO NOT include isStepUpdated when withVersion=true 295. withVersion: true, // Enable version creation 296. notrunall: false, // Use false (verified working value) 297. notruncurrent: false, // Use false (verified working value) 298. scope: 'project', // Always required 299. versionComment: 'Auto-created version due to test suite association' 300. }); 301. } else { 302. throw error; // Different error, report to user 303. } 304. } 305. 306. 307. KEY INSIGHTS: 308. - DO NOT ask user for confirmation - auto-retry is expected behavior 309. - Use SAME tcVersionID in both attempts (source version for creation) 310. - Second attempt creates NEW version (tcVersionID changes in response) 311. - Steps array is IDENTICAL in both attempts 312. - tcVersion parameter is ONLY in second attempt (withVersion=true) 313. - This matches QMetry UI behavior where popup auto-triggers version creation 314. 315. CRITICAL: INCREMENTAL tcVersion SELECTION RULE 316. 317. PROBLEM: When multiple versions exist, which tcVersion should you use? 318. SOLUTION: Use the VERSION NUMBER of the version you are creating FROM (the latest existing version) 319. 320. RULE: When creating a new version, tcVersion must equal the CURRENT LATEST VERSION in the system 321. 322. EXAMPLES: 323. - If only version 1 exists: Use tcVersion: 1 (creates version 2 from v1) 324. - If version 1 and 2 exist: Use tcVersion: 2 (creates version 3 from v2) 325. - If version 1, 2, and 3 exist: Use tcVersion: 3 (creates version 4 from v3) 326. 327. WORKFLOW TO DETERMINE CORRECT tcVersion: 328. 1. Call FETCH_TEST_CASE_DETAILS or FETCH_TEST_CASE_EXECUTIONS 329. 2. Check the highest tcVersion number in the system 330. 3. Use that number as your tcVersion parameter in the update payload 331. 4. This ensures you're creating from the latest version, not an old one 332. 333. REAL-WORLD SCENARIO: 334. Scenario: Test case VKMCP-TC-43 has version 2 already created in UI 335. Wrong Approach (will fail): tcVersion: 1, withVersion: true → TC.VERSION_NOT_SYNCED error 336. Correct Approach (will succeed): tcVersion: 2, withVersion: true → Creates version 3 successfully 337. 338. VERIFIED WORKING PAYLOAD (from user's Postman testing): 339. json 340. { 341. "notrunall": false, 342. "notruncurrent": false, 343. "scope": "project", 344. "tcID": 4594145, 345. "tcVersion": 2, // KEY: Use version 2 because v2 already exists 346. "tcVersionID": 5536706, // Source version ID (stays same) 347. "versionComment": "Added new steps", // Describes what changed 348. "withVersion": true, // Enable version creation 349. "steps": [ 350. // 5 existing steps with tcStepID (preserved from source) 351. // 2 new steps without tcStepID (to be added) 352. ] 353. } 354. 355. Result: New version 3 created successfully with 7 total steps 356. 357. DEFAULT VALUES FOR TC.VERSION_NOT_SYNCED RETRIES (THIS PATTERN): 358. - notrunall: false - For this retry pattern, override any usual true default 359. - notruncurrent: false - For this retry pattern, override any usual true default 360. - scope: "project" - Always use this 361. - withVersion: true - Required when creating a new version (both initial and retries) 362. 363. WHEN TO APPLY THIS PATTERN: 364. ✓ Adding steps to test case linked to test suite 365. ✓ Editing steps in test case with existing executions 366. ✓ Removing steps from associated test case 367. ✓ Any modification to steps when TC.VERSION_NOT_SYNCED occurs 368. ✓ When creating new versions from existing versions (always check latest version number) 369. 370. WHEN NOT TO APPLY: 371. ✗ Test case is NOT linked to test suite (normal update works) 372. ✗ Only updating metadata (name, priority, etc.) without steps 373. ✗ Different error codes (handle appropriately) 374. 375. BENEFITS OF THIS APPROACH: 376. 1. Seamless UX - LLM handles version creation automatically 377. 2. Matches UI behavior - no manual intervention needed 378. 3. Preserves test history - creates proper version trail 379. 4. Maintains test suite linkage - version creation preserves associations 380. 5. Handles incremental versions correctly - uses latest version as source 381. 382. 🎯 GRACEFUL HANDLING SUMMARY: 383. 384. When adding/editing/removing steps from test cases: 385. 1. Always TRY normal update first (without withVersion flag) 386. 2. If TC.VERSION_NOT_SYNCED error received: 387. - Fetch latest version number from test case details/executions 388. - Automatically retry with withVersion=true + correct tcVersion 389. - Use notrunall=false, notruncurrent=false, scope='project' 390. - Include version comment describing the changes 391. 3. Report success with new version details to user 392. 4. NEVER ask for confirmation - handle it transparently 393. 394. This ensures test cases with executions or suite associations are handled gracefully 395. without user intervention, matching the QMetry UI experience exactly. 396. 397. executionMinutes time is in minutes (legacy field). 398. estimatedTime is in seconds (preferred for version creation). 399. Description and testingType are optional but recommended for clarity. 400. 401. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 402. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 403. 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. 404. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 405. 3. For MULTILOOKUPLIST fields: pick an array of IDs; also pass the alias flat key (e.g., fieldNameAlias: 'Option Label'). 406. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 407. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 408. Example: udfFields: { custom_text: 'new value' }, UDF: { custom_text: { fieldID: 1001, value: 'new value' } } 409. 6. Mandatory UDF fields (isMandatory=true) MUST be included. 410. STEP UDFs for update: Use same step UDF field names from 'Fetch UDF Layout' stepFields. Pass in each step's 'UDF' object. 411. For MULTILOOKUPLIST step UDFs in update: use { ADD: [id1, id2], REMOVE: [id3] } format.

Fetch QMetry test cases - automatically handles viewId resolution based on project

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• viewId (number): ViewId for test cases - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TC.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• folderPath (string): Folder path for test cases - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• folderID (number): Folder ID - unique numeric identifier for the specific folder. Use this to target a specific folder within the project hierarchy. Applies to any entity type (test cases, requirements, test suites, etc.).

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• showRootOnly (boolean): Whether to show only root folders.

• getSubEntities (boolean): Whether to include sub-entities.

• hideEmptyFolders (boolean): Whether to hide empty folders.

• folderSortColumn (string): Folder sort column (default 'name')

• restoreDefaultColumns (boolean): Whether to restore default columns (default 'false')

• folderSortOrder (string): Folder sort order (ASC or DESC)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

Output Description: JSON object with 'data' array containing test cases and pagination info

Use Cases: 1. List all test cases in a project (without filters) 2. Browse test cases in specific folders for bulk operations 3. Get paginated test case results for reporting 4. Export multiple test cases at once

Examples:

1. Get all test cases from default project - system will auto-fetch viewId

{}

Expected Output: List of test cases from default project with auto-resolved viewId

2. Get all test cases from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of test cases from UT project using UT's specific TC viewId

3. Get test cases with manual viewId (skip auto-resolution)

{
  "projectKey": "MAC",
  "viewId": 167136,
  "folderPath": ""
}

Expected Output: Test cases using manually specified viewId 167136

4. List test cases from specific project (ex: project key can be anything (VT, UT, PROJ1, TEST9)

{
  "projectKey": "use specific given project key",
  "viewId": "fetch specific project given projectKey Test Case ViewId",
  "folderPath": ""
}

Expected Output: Test cases using manually specified viewId 167136 or projectKey

5. Get test cases by release/cycle filter

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Test cases associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

6. Get test cases by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All test cases associated with Release 8.12 (ID: 55178)

7. Get test cases by cycle only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: All test cases associated with Cycle 8.12.1 (ID: 111577)

8. Search for specific test case by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test cases matching the entity key criteria

9. Search for multiple test cases by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684,MAC-TC-1685,MAC-TC-1686\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test cases matching any of the specified entity keys

Hints: 1. CRITICAL - FILTER PERSISTENCE WARNING: 2. DO NOT use this API with filters to fetch a single test case by ID, entityKey, or name! 3. Filters applied to this API persist in the production UI and cause only filtered records to be visible to users. 4. This creates a major UX problem where users see incomplete data in their QMetry portal. 5. 6. CORRECT APPROACH FOR SINGLE TEST CASE: 7. When user asks to 'fetch test case VKMCP-TC-5' or 'get test case by ID 123' or 'find test case named X': 8. 1. Ask user for the numeric test case ID (tcID) if not provided 9. 2. Use 'Fetch Test Case Details' tool with the numeric tcID parameter 10. 3. NEVER use 'Fetch Test Cases' with entityKeyId filter for single test case lookup 11. 12. WHEN TO USE THIS TOOL: 13. Only use this tool when user explicitly asks for: 14. - 'List all test cases' 15. - 'Show me test cases in folder X' 16. - 'Get all test cases' (without specifying a single test case) 17. - 'Export test cases' (for bulk operations) 18. 19. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and test case fetching 20. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 21. Step 2: Get project info using that projectKey, extract latestViews.TC.viewId 22. Step 3: Use the SAME projectKey and the extracted TC viewId for fetching test cases 23. Step 4: If user doesn't specify projectKey, use 'default' for both project info and test case fetching 24. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 25. DEPRECATED: Do not use filter with entityKeyId for single test case - use 'Fetch Test Case Details' instead 26. RELEASE/CYCLE FILTERING: Use release and cycle IDs, not names, for filtering 27. For release filter: '[{"value":[releaseId],"type":"list","field":"release"}]' 28. For cycle filter: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 29. For combined release+cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 30. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 31. FILTER FIELDS: entityKeyId, priorityAlias, createdByAlias, updatedByAlias, testCaseStateAlias, testingTypeAlias, testCaseTypeAlias, componentAlias, owner, release, cycle 32. SORT FIELDS: entityKey, name, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, testCaseStateAlias, testingTypeAlias, executionMinutes 33. For multiple entity keys, use comma-separated values in filter 34. Use empty string '' as folderPath for root directory

Get detailed information for a specific QMetry test case by numeric ID - USE THIS for single test case lookup

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with test case details including ID, key, summary, description, and metadata

Use Cases: 1. Get test case details by numeric ID (PREFERRED for single test case) 2. Fetch test case when user provides entityKey (e.g., 'VKMCP-TC-5') 3. Retrieve test case metadata for a specific test case 4. Get test case summary and properties for display or editing 5. Fetch test case details before accessing steps or version details 6. Lookup test case by name or ID without affecting UI filters

Examples:

1. Get test case details by numeric ID

{
  "tcID": 4468020
}

Expected Output: Detailed test case information including summary, description, status

Hints: 1. USE THIS TOOL when user asks to 'fetch test case VKMCP-TC-5' or 'get test case by ID' or 'find test case X' 2. This API requires a numeric tcID parameter 3. CRITICAL: If user provides entityKey (e.g., MAC-TC-1684), you have TWO options: 4. Option 1 (RECOMMENDED): Ask user for the numeric test case ID 5. Option 2: If you must resolve entityKey, use FETCH_TEST_CASES with filter ONLY ONCE, then immediately use this tool 6. After resolving entityKey → tcID, always use THIS tool (FETCH_TEST_CASE_DETAILS) for subsequent lookups 7. This tool provides metadata and properties; use FETCH_TEST_CASE_STEPS for step-level details 8. This tool does NOT persist filters in UI - safe for single test case lookups 9. ALWAYS prefer this tool over FETCH_TEST_CASES with filters for single test case operations

Get QMetry test case details for a specific version by numeric ID

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• id (number) required: Test Case numeric ID (required for fetching steps or version details). Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results.

• version (number) required: Test Case version number. This is the internal numeric identifier for the version.

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

Output Description: JSON object with version-specific test case details

Use Cases: 1. Get specific version details of a test case 2. Compare different versions of a test case 3. Retrieve version history information 4. Audit changes made across test case versions

Examples:

1. Get version 2 details for test case ID 123

{
  "id": 123,
  "version": 2
}

Expected Output: Version 2 details for test case 123

Hints: 1. Requires numeric ID, not entityKey 2. If user provides entityKey (e.g., MAC-TC-1684), first resolve it to numeric ID using FETCH_TEST_CASES 3. Version defaults to 1 if not specified 4. Provides version-specific metadata and history

Get detailed test case steps for a specific test case by numeric ID

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• id (number) required: Test Case numeric ID (required for fetching steps or version details). Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results.

• version (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with array of test steps including step description, expected result, and order

Use Cases: 1. Get step-by-step instructions with expected results 2. Retrieve test case execution procedure for manual runs 3. Export or display detailed test steps for documentation 4. Fetch steps before automation mapping

Examples:

1. Get steps for test case ID 123

{
  "id": 123
}

Expected Output: Detailed steps with actions and expected results for test case 123

Hints: 1. Requires numeric ID, not entityKey 2. If user provides entityKey (e.g., MAC-TC-1684), resolve it first via FETCH_TEST_CASES to get the numeric ID 3. Version defaults to 1 if not specified 4. Use pagination for test cases with many steps

Get execution records for a specific test case by numeric ID, including Test Run UDF values. ALWAYS present results as a unified table: Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label columns…>. NEVER show a separate type+value UDF breakdown — always combine identification fields and UDF values in one table per execution row.

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcid (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• tcversion (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with executions array. Each execution record ALWAYS contains these mandatory identification fields: 'tsEntityKey' (Test Suite Key, e.g. 'MAC-TS-42'), 'testsuiteName' (Test Suite Name), 'releaseName' (Release), 'cycleName' (Cycle), 'platform' (Platform/environment), 'executedVersion' (Executed Version of the test case), 'executionStatus' (Execution Status label), 'tcRunID' (numeric Test Run ID), and 'testRunUdfs' (array of objects each with name, label, fieldID, fieldType, value — use 'label' for display headers, null if not set). ALL project-defined UDF fields are always included, even those with no value. Top-level 'hasTcRunUdf' flag indicates whether the project has Test Run UDFs configured. When false, a 'testRunUdfNote' field provides a professional explanation instead.

Use Cases: 1. Get execution history for a specific test case 2. Retrieve test case execution results for reporting 3. Filter executions by test suite, platform, or execution status 4. Get execution data for test case analysis 5. Monitor test case execution trends over time 6. Filter executions by release, cycle, or execution date 7. Get execution details for specific test case versions 8. Audit test execution history for compliance 9. Analyze test case execution performance across different environments 10. Track test execution by specific users or teams 11. Fetch Test Run UDF values for a specific test case's execution records 12. Inspect custom metadata captured during test execution via Test Run UDFs 13. Check whether the project has Test Run UDFs configured (hasTcRunUdf flag)

Examples:

1. Get all executions for test case ID 1223922

{
  "tcid": 1223922
}

Expected Output: Present as ONE unified table — never as a separate type+value UDF breakdown. Example: | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | | MAC-TS-42 | Regression Suite | R1 | Sprint1| Chrome | v1 | Passed | varis | chrome, edge, safari | Functional | | MAC-TS-42 | Regression Suite | R1 | Sprint1| Firefox | v2 | Failed | john | firefox | Regression | Columns in order: Test Suite Key (tsEntityKey) | Test Suite Name (testsuiteName) | Release (releaseName) | Cycle (cycleName) | Platform (platform) | Executed Version (executedVersion) | Execution Status | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

2. Get executions for specific test case version

{
  "tcid": 1223922,
  "tcversion": 2
}

Expected Output: Execution records for version 2 of the test case

3. Filter executions by test suite and platform

{
  "tcid": 1223922,
  "filter": "[{\"value\":\"Sample Test Suite\",\"type\":\"string\",\"field\":\"testSuiteName\"},{\"value\":[12345],\"type\":\"list\",\"field\":\"platformID\"}]"
}

Expected Output: Filtered execution records matching test suite and platform criteria

4. Filter executions by execution status

{
  "tcid": 1223922,
  "filter": "[{\"value\":[\"PASS\"],\"type\":\"list\",\"field\":\"executionStatus\"}]"
}

Expected Output: Execution records with PASS status only

5. Filter executions by release and cycle

{
  "tcid": 1223922,
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Execution records filtered by specific release and cycle

6. Filter executions by date range

{
  "tcid": 1223922,
  "filter": "[{\"value\":\"2024-01-01\",\"type\":\"date\",\"field\":\"executedDate\",\"comparison\":\"gt\"},{\"value\":\"2024-12-31\",\"type\":\"date\",\"field\":\"executedDate\",\"comparison\":\"lt\"}]"
}

Expected Output: Execution records within the specified date range

7. Filter executions by user

{
  "tcid": 1223922,
  "filter": "[{\"value\":[\"john.doe\"],\"type\":\"list\",\"field\":\"executedBy\"}]"
}

Expected Output: Execution records executed by specific user

8. Fetch Test Run UDF values for all executions of test case ID 41571999

{
  "tcid": 41571999
}

Expected Output: Present as ONE unified table combining identification fields and UDF values — never a separate type+value breakdown. Example: | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | Country | | MAC-TS-42 | Login Suite | R1 | Sprint1 | Chrome | v1 | Passed | varis | chrome, edge, safari | Functional | India > i3 | UDF column headers use the UDF 'label' (not raw field key). Null values shown as '-'.

9. Check if project has Test Run UDFs — response includes hasTcRunUdf flag

{
  "tcid": 1223922
}

Expected Output: Response contains hasTcRunUdf: true (UDFs present, testRunUdfs populated) or hasTcRunUdf: false (no UDFs configured, testRunUdfNote explains this)

Hints: 1. === MANDATORY RESPONSE FORMAT — READ THIS BEFORE RENDERING ANY OUTPUT === 2. 3. PIVOT RULE — CRITICAL: 4. The 'testRunUdfs' field on each execution is an array of { name, label, fieldID, fieldType, value }. 5. You MUST pivot this array into TABLE COLUMNS — do NOT render it as rows. 6. → Each testRunUdfs[i].label = a column header in the unified table 7. → Each testRunUdfs[i].value = the cell value for that execution's row 8. → testRunUdfs[i].fieldType = INTERNAL METADATA — NEVER show this as a column 9. → testRunUdfs[i].fieldID = INTERNAL METADATA — NEVER show this as a column 10. 11. FORBIDDEN PATTERNS — NEVER do any of these: 12. ❌ Do NOT render a separate sub-table (UDF Label | Type | Value) per execution 13. ❌ Do NOT show 'Type' or 'fieldType' as a visible column 14. ❌ Do NOT group output by tcRunID with individual breakdowns beneath each 15. ❌ Do NOT show raw UDF field keys (e.g. 'TRString', '8260LUP') as headers — use 'label' 16. 17. REQUIRED OUTPUT — ONE unified table, all executions as rows: 18. | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label 1> | <UDF Label 2> | ... | 19. |----------------|-----------------|---------|-------|----------|------------------|------------------|---------------|---------------|-----| 20. | MAC-TS-42 | Login Suite | R1 | S1 | Chrome | v1 | Passed | varis | chrome, edge | ... | 21. 22. MANDATORY COLUMNS (always first, in this order): 23. 1. Test Suite Key → tsEntityKey (e.g. 'MAC-TS-42') 24. 2. Test Suite Name → testsuiteName (test suite display name) 25. 3. Release → releaseName 26. 4. Cycle → cycleName 27. 5. Platform → platform 28. 6. Executed Version → executedVersion 29. 7. Execution Status → executionStatus 30. 8. Tested By → testedBy/executedBy when present 31. 9+. One column per UDF field — use testRunUdfs[i].label as header, testRunUdfs[i].value as cell. 32. 33. Null UDF values → show as '-'. If hasTcRunUdf is false, show columns 1-8 only. 34. UDF DATA SOURCE — THIS TOOL IS SELF-CONTAINED: 35. This tool automatically calls Test Run UDF metadata once (project-wide) and parses the udfjson field from each execution row. 36. The 'testRunUdfs' array in every execution record already contains ALL configured UDF fields — including fields with no value (null). 37. DO NOT call 'Fetch Test Run UDF Values' after this tool for test case executions — that tool uses GET_TESTCASE_RUNS_BY_TESTSUITE_RUN which is for test suite runs, not test case executions. 38. NEVER chain 'Fetch Test Run UDF Values' when the user asks for UDF values of test case executions — use testRunUdfs from THIS response directly. 39. === END MANDATORY RESPONSE FORMAT === 40. 41. This API requires a numeric tcid parameter, not entity key 42. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with filter on entityKeyId to resolve the tcid 43. After resolving entityKey → tcid, call this tool with the resolved numeric tcid 44. tcversion parameter is optional - omit to get executions for all versions 45. 46. CRITICAL WORKFLOW FOR LINKED ISSUES: When user asks 'fetch linked issues of test case [ID]' or 'linked issues of execution': 47. YOU MUST FIRST get the execution data using this tool to extract tcRunID before fetching issues! 48. 49. COMPLETE WORKFLOW FOR TEST CASE → LINKED ISSUES: 50. STEP 1: Resolve Test Case ID (if needed) - Use FETCH_TEST_CASES if user provides entity key 51. STEP 2: Fetch Test Case Executions (THIS TOOL) - Input: tcid, Extract: data[].tcRunID values 52. STEP 3: Fetch Linked Issues - Tool: FETCH_LINKED_ISSUES_BY_TESTCASE_RUN, Input: entityId = tcRunID 53. 54. ID MAPPING CRITICAL UNDERSTANDING: 55. - tcid/tcID = Test Case ID (for getting execution data with this tool) 56. - tcRunID = Test Case Run/Execution ID (THIS is entityId for linked issues API) 57. - entityId = tcRunID (what the linked issues API actually needs) 58. 59. NEVER USE tcid DIRECTLY as entityId for linked issues! 60. ALWAYS get tcRunID from executions and use THAT as entityId! 61. 62. EXAMPLE RESPONSE STRUCTURE FROM THIS TOOL: 63. { "data": [{ "tcRunID": 58312120, "testSuiteName": "Suite 1", "executionStatus": "PASS", "testRunUdfs": [...] }] } 64. → Use tcRunID (58312120) as entityId for linked issues API 65. 66. FILTER CAPABILITIES: Support extensive filtering by test suite, platform, status, user, release, cycle, dates, and archive status 67. FILTER FIELDS: testSuiteName (string), platformID (list), executionStatus (list), executedBy (list), project (list), release (list), cycle (list), executedDate (date with comparison), isPlatformArchived (list), isTestSuiteArchived (list), executedVersion (numeric) 68. DATE FILTERING: Use 'gt' (greater than) and 'lt' (less than) comparisons for executedDate field 69. EXECUTION STATUS: Common values include 'PASS', 'FAIL', 'BLOCKED', 'NOT_EXECUTED', 'WIP' (verify with your QMetry instance) 70. PLATFORM/SUITE ARCHIVE: Use [1,0] for both archived and non-archived, [1] for archived only, [0] for active only 71. Multiple filter conditions are combined with AND logic 72. Use pagination for large execution result sets (start, page, limit parameters) 73. Get platform IDs from FETCH_PLATFORMS tool and release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool 74. This tool is essential for test execution reporting, trend analysis, and compliance auditing 75. Execution data includes timestamps, user information, environment details, and test results 76. Use scope parameter to define retrieval context (project, folder, release, cycle) 77. 78. TEST RUN UDF SUPPORT: 79. This tool automatically fetches UDF metadata (project-wide, one call for all executions) and enriches each execution record. 80. ALL project-defined Test Run UDF fields are returned for every execution — including fields with no value (value: null). 81. HTML is stripped from rich text (LARGETEXT) UDF field values for clean output. 82. Each execution's 'testRunUdfs' is an array of objects: 83. testRunUdfs: [ 84. { "name": "8260LUP", "label": "Lookup Field", "fieldID": 228563, "fieldType": "LOOKUPLIST", "value": "l1" }, 85. { "name": "TRString", "label": "TR String", "fieldID": 229241, "fieldType": "STRING", "value": "dsf" }, 86. { "name": "notes_run", "label": "Notes Run", "fieldID": 229242, "fieldType": "LARGETEXT", "value": null }, 87. { "name": "cascade_vK", "label": "Cascade VK", "fieldID": 229426, "fieldType": "CASCADINGLIST", "value": { "child": "qq", "parent": "vkc" } } 88. ] 89. Use 'fieldID' from testRunUdfs entries when calling 'Bulk Update Test Run UDFs'. 90. 91. hasTcRunUdf FLAG — IMPORTANT: 92. The response contains a 'hasTcRunUdf' boolean flag at the top level. 93. hasTcRunUdf: true → Project has Test Run UDFs configured; each execution record includes 'testRunUdfs' array with all fields. 94. hasTcRunUdf: false → Project has NO Test Run UDFs configured. 95. When hasTcRunUdf is false, the response includes a 'testRunUdfNote' field with a professional explanation. 96. Inform the user: 'No Test Run UDFs are configured for this project. Contact a project administrator to set up Test Run UDF fields.' 97. NEVER attempt to read testRunUdfs from records when hasTcRunUdf is false — the field will not be present.

Fetch test case steps including UDF field values via viewColumns endpoint

Toolset: Test Cases

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• viewId (number): ViewId for test cases - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TC.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• version (number): Test Case version number (optional, defaults to 1). This is the internal numeric identifier for the version.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

Output Description: JSON object with data array (steps with UDF values), filterTemplate (UDF field definitions), columns (visible/hidden column config), total count, and viewId

Use Cases: 1. Get step UDF field values for a test case 2. Retrieve steps with custom fields before updating step UDFs 3. Inspect step-level UDF data for reporting

Examples:

1. Fetch steps with UDF values for test case ID 112768054

{
  "tcID": 112768054
}

Expected Output: Steps with UDF object containing field values, ID_ arrays for lookup IDs, UDF_ prefixed values, filterTemplate with UDF field definitions

Hints: 1. Response includes 'filterTemplate' array listing all UDF fields with their fieldType and udfmID 2. UDF values in each step row: UDF_ = display value, UDF_ID_ = numeric IDs 3. Step UDF object also has ID_ for lookup IDs 4. LOOKUPLIST: id = UDF_ID_, display = UDF_ 5. MULTILOOKUPLIST: ids = UDF_ID_ (array), display = UDF_ 6. CASCADINGLIST: parent = UDF_ID_[0], child = UDF_ID_[1] 7. viewId auto-resolved from project info if not provided

Fetch QMetry requirements - automatically handles viewId resolution based on project

Toolset: Requirements

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• viewId (number): ViewId for requirements - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.RQ.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• folderPath (string): Folder path for requirements - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• getSubEntities (boolean): Whether to include sub-entities.

• hideEmptyFolders (boolean): Whether to hide empty folders.

• folderSortColumn (string): Folder sort column (default 'name')

• folderSortOrder (string): Folder sort order (ASC or DESC)

• isJiraFilter (boolean): 'false' if using qmetry filter (default: false)

• filterType (enum): Pass 'QMETRY' or 'JIRA' (default: "QMETRY")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• sort (string): Sort Records - refer json schema, Possible property - name, entityKey, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, requirementStateAlias, linkedTcCount, linkedDfCount, attachmentCount, createdSystem, owner (default: "[{"property":"name","direction":"ASC"}]")

Output Description: JSON object with 'data' array containing requirements and pagination info

Use Cases: 1. List all requirements in a project 2. Search for specific requirements using filters 3. Browse requirements in specific folders 4. Get paginated requirement results 5. Filter requirements by name or properties 6. Get requirement metadata for test planning

Examples:

1. Get all requirements from default project - system will auto-fetch viewId

{}

Expected Output: List of requirements from default project with auto-resolved viewId

2. Get all requirements from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of requirements from UT project using UT's specific RQ viewId

3. Get requirements with manual viewId (skip auto-resolution)

{
  "projectKey": "MAC",
  "viewId": 7397,
  "folderPath": "/APIARY 88"
}

Expected Output: Requirements using manually specified viewId 7397

4. Search for specific requirements by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-123\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Filtered requirements matching the entity key criteria

5. Search for multiple requirements by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-123,MAC-RQ-456,MAC-RQ-789\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Requirements matching any of the specified entity keys

6. Filter requirements by state (e.g., Open, Approved)

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"Open\",\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Requirements with 'Open' state

7. Filter requirements by priority

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"High\",\"field\":\"priorityAlias\"}]"
}

Expected Output: Requirements with 'High' priority

8. Filter requirements by archive status

{
  "filter": "[{\"value\":[1,0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of requirements filtered by archive status (archived and non-archived)

9. Get only archived requirements

{
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of only archived requirements

10. Sort requirements by name in ascending order

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"name\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted alphabetically by name

11. Sort requirements by creation date (newest first)

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"createdDate\",\"direction\":\"DESC\"}]"
}

Expected Output: Requirements sorted by creation date, newest first

12. Sort requirements by entity key

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"entityKey\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted by entity key (MAC-RQ-1, MAC-RQ-2, etc.)

13. Sort requirements by linked test case count

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"linkedTcCount\",\"direction\":\"DESC\"}]"
}

Expected Output: Requirements sorted by number of linked test cases, highest first

14. Complex filter: Requirements by owner with specific state

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"john.doe\",\"field\":\"owner\"},{\"type\":\"string\",\"value\":\"Approved\",\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Requirements owned by john.doe with 'Approved' state

15. Multi-field sort: Priority first, then creation date

{
  "projectKey": "MAC",
  "sort": "[{\"property\":\"priorityAlias\",\"direction\":\"DESC\"},{\"property\":\"createdDate\",\"direction\":\"ASC\"}]"
}

Expected Output: Requirements sorted by priority (High to Low), then by creation date (oldest first)

16. Filter requirements by specific release and cycle

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Requirements associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

17. Filter requirements by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All requirements associated with Release 8.12 (ID: 55178)

Hints: 1. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and requirement fetching 2. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 3. Step 2: Get project info using that projectKey, extract latestViews.RQ.viewId 4. Step 3: Use the SAME projectKey and the extracted RQ viewId for fetching requirements 5. Step 4: If user doesn't specify projectKey, use 'default' for both project info and requirement fetching 6. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 7. For search by requirement key (like MAC-RQ-123), use filter: '[{"type":"string","value":"MAC-RQ-123","field":"entityKeyId"}]' 8. For multiple entity keys, use comma-separated values: '[{"type":"string","value":"MAC-RQ-123,MAC-RQ-456","field":"entityKeyId"}]' 9. Use empty string '' as folderPath for root directory 10. Filter supports QMETRY and JIRA types - default is QMETRY 11. FILTER FIELDS: entityKeyId, name, requirementStateAlias, priorityAlias, owner, createdByAlias, updatedByAlias, createdSystem 12. SORT FIELDS: name, entityKey, associatedVersion, priorityAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, requirementStateAlias, linkedTcCount, linkedDfCount, attachmentCount, createdSystem, owner 13. SORT DIRECTIONS: ASC (ascending), DESC (descending) 14. Multiple filters: Use array with multiple objects for AND conditions 15. Multiple sort criteria: Use array with multiple objects, first takes priority 16. Filter format: [{'type':'string','value':'filterValue','field':'fieldName'}] 17. Sort format: [{'property':'fieldName','direction':'ASC|DESC'}] 18. RELEASE/CYCLE FILTERING: Use release and cycle IDs from fetch_releases_and_cycles tool 19. For specific release: '[{"value":[releaseId],"type":"list","field":"release"}]' 20. For specific cycle: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 21. For release AND cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 22. Example: Release 8.12 (ID: 55178) + Cycle 8.12.1 (ID: 111577) = filter with both IDs

Get detailed information for a specific QMetry requirement by numeric ID

Toolset: Requirements

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• id (number) required: Requirement numeric ID (required for fetching specific requirement details). This is the internal numeric identifier, not the entity key like 'MAC-RQ-730'. You can get this ID from requirement search results or by using filters.

• version (number) required: Requirement version number (required for fetching specific requirement version details). This is the internal numeric identifier for the version.

Output Description: JSON object with requirement details including ID, key, summary, description, status, and all metadata

Use Cases: 1. Get requirement details by numeric ID 2. Retrieve requirement metadata for reporting 3. Get requirement summary and properties 4. Fetch requirement details before linking or updating 5. Access requirement field values and custom fields 6. Get requirement version-specific information

Examples:

1. Get requirement details by numeric ID

{
  "id": 4791316,
  "version": 1
}

Expected Output: Detailed requirement information including summary, description, status, and all fields

Hints: 1. This API requires a numeric ID parameter, not entity key 2. If user provides entityKey (e.g., MAC-RQ-730), first call FETCH_REQUIREMENTS with a filter on entityKeyId to resolve the numeric ID 3. After resolving entityKey → numeric ID, call this tool with the resolved numeric ID 4. Version parameter is required - use 1 for the latest version unless user specifies otherwise 5. This tool provides complete requirement information including all custom fields 6. Use this tool to get detailed requirement information that's not available in the list view

Link one or more requirements to a test case by entityKey and version IDs.

Toolset: Requirements

Parameters:

• tcID (string) required: EntityKey of Testcase (e.g. 'COD-TC-29')

• tcVersionId (number) required: Test Case version number. This is the internal numeric identifier for the version.

• rqVersionIds (string) required: Comma-separated values of versionId of the Requirement (e.g. '236124,236125')

Output Description: JSON object with success status and linkage details.

Use Cases: 1. Link requirements to a test case for traceability 2. Bulk link multiple requirements to a single test case 3. Automate requirement coverage mapping

Examples:

1. Link requirements to test case VT-TC-26

{
  "tcID": "VT-TC-26",
  "tcVersionId": 5448515,
  "rqVersionIds": "5009939,5009937,4970699"
}

Expected Output: Requirements linked to test case VT-TC-26 successfully.

Hints: 1. To get the tcID, call the Testcase/Fetch List for Bulk Operation API and use data[].entityKey. 2. To get the tcVersionId, call the Testcase/Fetch Versions API and use data[].tcVersionID. 3. To get the rqVersionIds, call the requirement/List Versions API and use data[].rqVersionID. 4. If user provides requirement entityKey (e.g., VT-RQ-18), first call requirements list with a filter on entityKeyId to resolve the rqVersionIds 5. If user provides testcase entityKey (e.g., VT-TC-26), first call testcase list with a filter on entityKeyId to resolve the tcVersionId and tcID. 6. rqVersionIds must be a comma-separated string of requirement version IDs.

Get test cases that are linked (or not linked) to a specific requirement in QMetry

Toolset: Requirements

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• rqID (number) required: Requirement numeric ID (required for fetching specific requirement details). This is the internal numeric identifier, not the entity key like 'MAC-RQ-730'. You can get this ID from requirement search results or by using filters.

• getLinked (boolean): True to get only test cases that are linked with this requirement, false to get test cases which are not linked with this requirement. Defaults to true (get linked test cases). (default: true)

• showEntityWithReleaseCycle (boolean): True to list only test cases which have given release and cycle, false for all test cases regardless of release/cycle association. Defaults to false (show all). (default: false)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• tcFolderPath (string): Folder path to get test cases under specific folder. Use empty string "" for root folder or specify path like "/Sample Template". (default: "")

• releaseID (string): Filter test cases by release ID. Accepts a string or number. Get release IDs from FETCH_RELEASES_AND_CYCLES tool.

• cycleID (string): Filter test cases by cycle ID. Accepts a string or number. Get cycle IDs from FETCH_RELEASES_AND_CYCLES tool.

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• getSubEntities (boolean): Allow filter of sub-entities for requirement. (default: true)

• getColumns (boolean): True to get column information in response. (default: true)

Output Description: JSON object with test cases array, traceability information, and pagination metadata

Use Cases: 1. Get all test cases linked to a specific requirement for traceability analysis 2. Find test cases that are NOT linked to a requirement (gap analysis) 3. Verify requirement coverage by checking linked test cases 4. Impact analysis - see which test cases are affected when a requirement changes 5. Generate traceability matrix between requirements and test cases 6. Filter linked test cases by release, cycle, or other criteria 7. Audit requirement-test case relationships for compliance 8. Identify orphaned test cases or requirements without proper links 9. Plan test execution based on requirement-test case associations 10. Quality assurance - ensure all requirements have adequate test coverage

Examples:

1. Get all test cases linked to requirement ID 4791316

{
  "rqID": 4791316
}

Expected Output: List of test cases that are linked to requirement MAC-RQ-1011

2. Get test cases NOT linked to requirement (gap analysis)

{
  "rqID": 4791316,
  "getLinked": false
}

Expected Output: List of test cases that are NOT linked to requirement MAC-RQ-1011

3. Get linked test cases filtered by specific release

{
  "rqID": 4791316,
  "releaseID": "55178"
}

Expected Output: Linked test cases associated with Release 8.12 (ID: 55178)

4. Get linked test cases filtered by release and cycle

{
  "rqID": 4791316,
  "releaseID": "55178",
  "cycleID": "111577",
  "showEntityWithReleaseCycle": true
}

Expected Output: Linked test cases in Release 8.12 and Cycle 8.12.1

5. Get linked test cases from specific folder

{
  "rqID": 4791316,
  "tcFolderPath": "/Sample Template"
}

Expected Output: Linked test cases located in the '/Sample Template' folder

6. Search linked test cases by entity key

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TC-1684,MAC-TC-1685\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Linked test cases matching specific entity keys

7. Filter linked test cases by priority

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"priorityAlias\"}]"
}

Expected Output: Linked test cases with High or Medium priority

8. Filter linked test cases by status

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"testCaseStateAlias\"}]"
}

Expected Output: Linked test cases with Active or Review status

9. Filter linked test cases by test case type

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"testCaseTypeAlias\"}]"
}

Expected Output: Linked functional test cases

10. Filter linked test cases by testing type (automation)

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[2],\"field\":\"testingTypeAlias\"}]"
}

Expected Output: Linked automated test cases

11. Get only parameterized linked test cases

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"isParameterized\"}]"
}

Expected Output: Linked test cases that are parameterized (data-driven)

12. Filter linked test cases by archive status

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"}]"
}

Expected Output: Active (non-archived) linked test cases

13. Search linked test cases by summary content

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"login\",\"field\":\"summary\"}]"
}

Expected Output: Linked test cases with 'login' in their summary

14. Filter linked test cases by requirement version

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"string\",\"value\":\"1\",\"field\":\"rqVersion\"}]"
}

Expected Output: Test cases linked to version 1 of the requirement

15. Complex filter: Active, high priority, automated test cases

{
  "rqID": 4791316,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"},{\"type\":\"list\",\"value\":[1],\"field\":\"priorityAlias\"},{\"type\":\"list\",\"value\":[2],\"field\":\"testingTypeAlias\"}]"
}

Expected Output: Active, high priority, automated test cases linked to requirement

Hints: 1. This API requires a numeric rqID parameter, not entity key 2. If user provides entityKey (e.g., MAC-RQ-1011), first call FETCH_REQUIREMENTS with filter on entityKeyId to resolve the numeric rqID 3. After resolving entityKey → rqID, call this tool with the resolved numeric rqID 4. TRACEABILITY WORKFLOW: Use this tool to establish requirement-test case traceability matrix 5. getLinked=true (default): Returns test cases that ARE linked to the requirement 6. getLinked=false: Returns test cases that are NOT linked to the requirement (useful for gap analysis) 7. showEntityWithReleaseCycle=true: Only show test cases that have the specified release and cycle 8. showEntityWithReleaseCycle=false (default): Show all test cases regardless of release/cycle 9. RELEASE/CYCLE FILTERING: Use string IDs, not numeric (e.g., releaseID: '55178', cycleID: '111577') 10. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 11. tcFolderPath: Use empty string '' for root folder or specific path like '/Sample Template' 12. FILTER CAPABILITIES: Support same filters as regular test case listing 13. FILTER FIELDS: summary, rqVersion, priorityAlias, testCaseStateAlias, createdByAlias, testCaseTypeAlias, testingTypeAlias, release, cycle, isArchived, isParameterized, componentAlias, entityKeyId 14. PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 15. STATUS IDs: Typically 1=Active, 2=Review, 3=Deprecated (verify with your QMetry instance) 16. TYPE IDs: Typically 1=Functional, 2=Integration, 3=System (verify with your QMetry instance) 17. TESTING TYPE IDs: Typically 1=Manual, 2=Automated (verify with your QMetry instance) 18. PARAMETERIZED: 1=Yes (parameterized), 0=No (non-parameterized) 19. ARCHIVED: 1=Archived, 0=Active (non-archived) 20. Multiple filter conditions are combined with AND logic 21. For entity key search, use comma-separated values: 'MAC-TC-1,MAC-TC-2,MAC-TC-3' 22. This tool is crucial for compliance, traceability audits, and impact analysis 23. Use getColumns=true to get column metadata for better result interpretation 24. Pagination supported for large result sets (start, page, limit parameters)

Get requirements that are linked (or not linked) to a specific test case in QMetry

Toolset: Requirements

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• getLinked (boolean): True to get only requirements that are linked with this test case, false to get requirements which are not linked with this test case. Defaults to true (get linked requirements). (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• rqFolderPath (string): Folder path for requirements - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with requirements array, traceability information, and pagination metadata

Use Cases: 1. Get all requirements linked to a specific test case for traceability analysis 2. Find requirements that are NOT linked to a test case (gap analysis) 3. Verify test case coverage by checking linked requirements 4. Impact analysis - see which requirements are affected when a test case changes 5. Generate traceability matrix between test cases and requirements 6. Filter linked requirements by various criteria 7. Audit test case-requirement relationships for compliance 8. Identify orphaned requirements or test cases without proper links 9. Plan requirement validation based on test case-requirement associations 10. Quality assurance - ensure all test cases have proper requirement coverage

Examples:

1. Get all requirements linked to test case ID 594294

{
  "tcID": 594294
}

Expected Output: List of requirements that are linked to test case MAC-TC-1684

2. Get requirements NOT linked to test case (gap analysis)

{
  "tcID": 594294,
  "getLinked": false
}

Expected Output: List of requirements that are NOT linked to test case MAC-TC-1684

3. Get linked requirements from specific folder

{
  "tcID": 594294,
  "rqFolderPath": "/CodeSnippets"
}

Expected Output: Linked requirements located in the '/CodeSnippets' folder

4. Search linked requirements by entity key

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-RQ-730,MAC-RQ-731\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Linked requirements matching specific entity keys

5. Filter linked requirements by status

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[1,2],\"field\":\"requirementStateAlias\"}]"
}

Expected Output: Linked requirements with Open or Approved status

6. Filter linked requirements by priority

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"priorityAlias\"}]"
}

Expected Output: Linked requirements with High priority

7. Filter linked requirements by archive status

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[0],\"field\":\"isArchived\"}]"
}

Expected Output: Active (non-archived) linked requirements

8. Search linked requirements by name content

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"authentication\",\"field\":\"name\"}]"
}

Expected Output: Linked requirements with 'authentication' in their name

9. Filter linked requirements by test case version

{
  "tcID": 594294,
  "filter": "[{\"type\":\"string\",\"value\":\"1\",\"field\":\"tcVersion\"}]"
}

Expected Output: Requirements linked to version 1 of the test case

10. Filter linked requirements by release and cycle

{
  "tcID": 594294,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Linked requirements in Release 8.12 and Cycle 8.12.1

Hints: 1. This API requires a numeric tcID parameter, not entity key 2. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with filter on entityKeyId to resolve the numeric tcID 3. After resolving entityKey → tcID, call this tool with the resolved numeric tcID 4. TRACEABILITY WORKFLOW: Use this tool to establish test case-requirement traceability matrix 5. getLinked=true (default): Returns requirements that ARE linked to the test case 6. getLinked=false: Returns requirements that are NOT linked to the test case (useful for gap analysis) 7. rqFolderPath: Use empty string '' for root folder or specific path like '/CodeSnippets' 8. FILTER CAPABILITIES: Support same filters as regular requirement listing 9. FILTER FIELDS: name, entityKeyId, requirementStateAlias, priorityAlias, createdByAlias, tcVersion, release, cycle, isArchived, componentAlias 10. Multiple filter conditions are combined with AND logic 11. For entity key search, use comma-separated values: 'MAC-RQ-1,MAC-RQ-2,MAC-RQ-3' 12. This tool is crucial for compliance, traceability audits, and impact analysis 13. Pagination supported for large result sets (start, page, limit parameters) 14. Use this tool to verify that test cases properly cover requirements 15. Essential for requirement validation and test case completeness analysis

Create a new test suite in QMetry with metadata and release/cycle mapping.

Toolset: Test Suites

Parameters:

• parentFolderId (string): Test Suite parent folder ID - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TS.id automatically. Manual folder ID only needed if you want to target a specific sub-folder.

• name (string) required

• isAutomatedFlag (boolean)

• description (string)

• testsuiteOwner (number)

• testSuiteState (number)

• associateRelCyc (boolean)

• releaseCycleMapping (array): Release/cycle association for the test suite. CRITICAL SHAPE DIFFERENCE vs Test Case mapping: Test Suite uses: { releaseId: number, buildID: number } Test Case uses: { release: number, cycle: number[], version: number } — DO NOT use TC shape here. Set associateRelCyc=true when providing this array. Example: [{ releaseId: 92112, buildID: 130831 }]

• 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 test suite ID, summary, and creation metadata.

Use Cases: 1. Create a basic test suite with just a name and folder 2. Add detailed metadata like description to a test suite 3. Associate test suite with specific release/cycle for planning 4. Set testsuiteOwner, testSuiteState, and other metadata using valid IDs from project info 5. Create test suites for isAutomatedFlag true or false for automated or manual types, default is false 6. Add test suite to a specific folder using parentFolderId 7. Map test suite to multiple cycles/releases and build ID

Examples:

1. Create a test suite in the root folder (auto-resolved)

{
  "name": "Demo Test Suite"
}

Expected Output: Test suite created in the root test suite folder with ID and summary details

2. Create a simple test suite in folder 102653

{
  "parentFolderId": "102653",
  "name": "Login Test Suite"
}

Expected Output: Test suite created with ID and summary details

3. Create a test suite with some details and metadata

{
  "parentFolderId": "113557",
  "isAutomatedFlag": false,
  "name": "Testsuite Summary",
  "description": "desc",
  "testsuiteOwner": 6963,
  "testSuiteState": 505035,
  "associateRelCyc": true,
  "releaseCycleMapping": [
    {
      "buildID": 18411,
      "releaseId": 10286
    }
  ]
}

Expected Output: Test suite created with details and metadata. Example uses: parentFolderId=113557 (MAC root TS folder from rootFolders.TS.id), testsuiteOwner=6963 (umang.savaliya from customListObjs.owner[index].id), testSuiteState=505035 (New from customListObjs.testSuiteState[index].id), releaseId=10286 (Air release from projects[index].releases[index].releaseID), buildID=18411 (Air Q1-19 cycle from projects[index].releases[index].builds[index].buildID)

Hints: 1. ╔══════════════════════════════════════════════════════════════════╗ 2. ║ STEP 0 — NON-NEGOTIABLE: Call 'Fetch UDF Layout' BEFORE create ║ 3. ╚══════════════════════════════════════════════════════════════════╝ 4. NEVER call 'Create Test Suite' without first calling 'Fetch UDF Layout' with entityType='TS', 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 test suite, call 'Fetch UDF Layout' with entityType='TS', pageName='ADD'. 10. Response keys use 'TS' — same structure as TC but scoped to test suite module. 11. 12. SYSTEM FIELDS mandatory check — use 'systemFields' array (from qmSDF.TS 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.TS 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.TS in newlayout): 21. Shape: { fieldName: defaultValueId } e.g. { 'priority': 5232497, 'estimatedTime': 18305 } 22. RULE: isMandatory=true AND defaultValues[field.name] exists → auto-use default, do NOT ask user. 23. RULE: isMandatory=true AND no defaultValues entry → MUST ask user before creating. 24. RULE: isMandatory=false AND defaultValues entry exists → auto-apply if user didn't specify. 25. 26. ╔══════════════════════════════════════════════════════════════════════════╗ 27. ║ PRE-FLIGHT DEFAULT SWEEP — MANDATORY STEP BEFORE EVERY CREATE CALL ║ 28. ╚══════════════════════════════════════════════════════════════════════════╝ 29. After resolving mandatory fields, sweep ALL defaultValues entries: 30. For EACH key in defaultValues: 31. IF the user did not explicitly provide that field → add it to the payload using the default value. 32. This applies regardless of isMandatory — non-mandatory defaults MUST also be auto-applied. 33. Example: defaultValues = { priority: 5232497, estimatedTime: 18305 } 34. → user only said 'create a test suite named X' 35. → payload MUST include: priority=5232497, estimatedTime=18305 36. → WRONG to omit priority/estimatedTime just because they are not mandatory — they have defaults. 37. Skipping this sweep = missing fields in the created record = user-visible data loss. 38. ╚══════════════════════════════════════════════════════════════════════════╝ 39. 40. DECISION MATRIX: 41. | isMandatory | Has default | Action | 42. |-------------|-------------|-------------------------------------| 43. | true | YES | Auto-fill with default, no ask | 44. | true | NO | Ask user before creating | 45. | false | YES | Auto-fill with default — REQUIRED | 46. | false | NO | Skip if user didn't provide | 47. Only after ALL mandatory fields resolved AND default sweep complete → proceed with create. 48. === END MANDATORY PRE-CREATE CHECK === 49. 50. === ERROR RECOVERY: CO.MANDATORY_FIELDS_MISSING === 51. If create fails with error code 'CO.MANDATORY_FIELDS_MISSING', DO NOT give up. Auto-recover: 52. 1. Parse the 'MISSING_FIELDS' list from the error response (comma-separated field labels). 53. 2. Match each label against 'fields[].label' and 'systemFields[].label' from the Fetch UDF Layout response. 54. 3. For matched UDF fields: check 'listOptions[field.listName]' for valid option IDs. 55. 4. For matched system fields (e.g. 'Status'): check 'customListObjs.testSuiteState' from project info. 56. 5. If the field has a 'defaultValues' entry: auto-fill it silently. 57. 6. If no default exists: ask the user ONLY for the missing fields by label. 58. 7. Retry create with the resolved values added to the payload. 59. NEVER ask user to 'try again' manually — resolve and retry automatically. 60. === END ERROR RECOVERY === 61. 62. === DATE FORMAT CHECK (MANDATORY — EVERY CREATE REQUEST) === 63. ALWAYS call 'Fetch QMetry Project Info' before every create request — not only when the user explicitly mentions a date. 64. 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). 65. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 66. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 67. 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/...). 68. 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' 69. 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. 70. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 71. === END DATE FORMAT CHECK === 72. 73. If parentFolderId is not provided, it will be auto-resolved to the root test suite folder using project info (rootFolders.TS.id). 74. To get valid values for testsuiteOwner, testSuiteState, etc., call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 75. CRITICAL: For testsuiteOwner mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.owner[].id. Match the user by customListObjs.owner[].name. 76. If the user provides an owner name (testsuiteOwner), fetch project info, find the matching owner in customListObjs.owner[index].name or customListObjs.owner[index].uniqueLabel, and use its ID in the payload as testsuiteOwner. If the name is not found, skip the testsuiteOwner field (it is not required) and show a user-friendly message: 'Test suite created without owner, as given owner is not available in the current project.' 77. CRITICAL: For testSuiteState mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.testSuiteState[].id. Match the state by customListObjs.testSuiteState[].name. 78. If the user provides a test suite state name(testSuiteState), fetch project info, find the matching state in customListObjs.testSuiteState[index].name, and use its ID in the payload as testSuiteState. If the name is not found, skip the testSuiteState field (it is not required) and show a user-friendly message: 'Test suite created without test suite state, as given state is not available in the current project.' 79. parentFolderId is required; use the root folder ID from project info (rootFolders.TS.id) or a specific folder. 80. Release/cycle mapping is optional but useful for planning. 81. If the user wants to link or associate a release and cycle to the test suite, set associateRelCyc: true in the payload. 82. CRITICAL: For releaseCycleMapping.releaseId - Call API 'Release/List' (or use project info projects[].releases[].releaseID), from the response get value from data[].releaseID or projects[].releases[].releaseID. Match the release by name. 83. CRITICAL: For releaseCycleMapping.buildID - Call API 'Cycle/List' (or use project info projects[].releases[].builds[].buildID), from the response get value from data[].buildID or projects[].releases[].builds[].buildID. Match the build/cycle by name. 84. If the user provides a release name, map it to its ID from projects[].releases[].releaseID in the project info response, and use that ID as releaseId in releaseCycleMapping. 85. If the user provides a build/cycle name, map it to its ID from projects[].releases[].builds[].buildID in the project info response, and use that ID as buildID in releaseCycleMapping. 86. Example payload: releaseCycleMapping: [ { releaseId: , buildID: } ] 87. Example: For 'Air' release and 'Air Q1-19' cycle in MAC project, use releaseId: 10286 and buildID: 18411 88. LLM should ensure that provided release/cycle names or IDs exist in the current project before using them in the payload. If not found, skip and show a user-friendly message: 'Test suite created without release/cycle association, as given release/cycle is not available in the current project.' 89. All IDs (testSuiteState from customListObjs.testSuiteState[index].id, testsuiteOwner from customListObjs.owner[index].id, releaseId from projects.releases[index].releaseID, buildID from projects.releases.builds[index].buildID) must be valid for your QMetry instance. 90. If a custom field is mandatory, include it in the UDF object. 91. 92. UDF (User Defined Fields) WORKFLOW FOR CREATE: 93. 1. Call 'Fetch UDF Layout' with entityType='TS', pageName='ADD' to discover field names, types, and list option IDs. 94. 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. 95. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 96. 3. For MULTILOOKUPLIST fields: pick an array of IDs. 97. 4. For CASCADINGLIST fields: pick parent ID, then call 'Fetch Cascade Child Values' for child ID. Pass { parent: parentId, child: childId }. 98. 5. Pass all UDF values via 'udfFields' param: { fieldName: value }. 99. 6. Mandatory UDF fields (isMandatory=true) MUST be included or create will fail. 100. 101. ╔══════════════════════════════════════════════════════════════════╗ 102. ║ POST-CREATE MANDATORY: Link Platform to Test Suite ║ 103. ╚══════════════════════════════════════════════════════════════════╝ 104. AFTER every successful test suite creation, ALWAYS call 'Link Platforms to Test Suite'. 105. Reason: QMetry UI enforces platform association — test suites without a linked platform 106. are invalid for execution and will show validation errors in the UI. 107. STEP 1: Call 'Fetch Platforms' to get available platforms for the project. 108. STEP 2: If the user specified a platform, match by name and use its platformID. 109. If no platform was specified, use the first available non-archived platform. 110. STEP 3: Call 'Link Platforms to Test Suite' with qmTsId= and qmPlatformId=. 111. NEVER report the test suite as successfully created without completing this platform link step. 112. ╚══════════════════════════════════════════════════════════════════╝

Update an existing QMetry test suite by id(testsuite numeric id), with auto-resolution from entityKey.

Toolset: Test Suites

Parameters:

• id (number) required: Id of Test Suite to be updated (required)

• TsFolderID (number): Folder ID where Test Suite resides - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific folder ID. System will fetch project info using the projectKey and extract rootFolders.TS.id automatically. Manual folder ID only needed if you want to override the automatic resolution.

• entityKey (string) required: Entity Key of Test Suite to be updated (required)

• name (string): Name of the Test Suite

• description (string): Description of the Test Suite

• testsuiteOwner (number): Owner ID of the Test Suite

• testSuiteState (number): State of the Test Suite

• 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.

• UDF (record<string, object>): UDF wrapper required for update. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value.

Output Description: JSON object containing the new test suite ID, summary, and creation metadata.

Use Cases: 1. Update test suite summary (name) 2. Change owner, or state of a test suite 3. Bulk update using entityKey auto-resolution 4. Modify test suite description

Examples:

1. Update test suite summary (updated name)

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "name": "MAC Test11"
}

Expected Output: Test suite summary updated. Only 'name' field changed. Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved. from the project info. info on rootFolders.TS.id.

2. Update state to Open and owner of the test suite

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "testSuiteState": 505036,
  "testsuiteOwner": 6963
}

Expected Output: State and owner updated. Example uses: testSuiteState=505036 (Open from customListObjs.testSuiteState[index].id), testsuiteOwner=6963 (umang.savaliya from customListObjs.owner[index].id). Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved from the project info rootFolders.TS.id.

3. Update only description of the test suite

{
  "id": 1505898,
  "entityKey": "VT-TS-7",
  "TsFolderID": 1644087,
  "description": "Updated description for the test suite."
}

Expected Output: description updated only. Field IDs auto-resolved from project info. id(test suite numeric id) resolved from entityKey. TsFolderID auto-resolved. from the project info. info on rootFolders.TS.id.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. ALWAYS call 'Fetch UDF Layout' with entityType='TS', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout): { fieldName: defaultValueId } — sweep ALL entries. 4. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload with the default value. 5. This applies to non-mandatory fields too (e.g. testSuiteState). Omitting them = data loss. 6. systemFields (from qmSDF.TS): isMandatory=true fields must retain a valid value after update. 7. fields/UDF (from qmUDF.TS): isMandatory=true UDF fields must be included if being changed. 8. === END DEFAULT VALUES === 9. 10. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 11. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 12. 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). 13. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 14. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 15. 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/...). 16. 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' 17. 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. 18. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 19. === END DATE FORMAT CHECK === 20. 21. If user provides entityKey (e.g., MAC-TS-7), first call Fetch Test Suites with a filter on entityKeyId to resolve the id (test suite numeric id) and TsFolderID from rootFolders.TS.id. 22. To get valid values for owner, state, etc., call the 'Admin/Get info Service' API (FETCH_PROJECT_INFO tool) and use the returned customListObjs IDs. 23. CRITICAL: For testsuiteOwner mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.owner[].id. Match the user by customListObjs.owner[].name. 24. If the user provides an owner name, fetch project info, find the matching user in customListObjs.owner[index].name, and use its ID in the payload as testsuiteOwner. If the name is not found, skip the testsuiteOwner field (it is not required) and show a user-friendly message: 'Test suite updated without owner, as given owner is not available in the current project.' 25. CRITICAL: For testSuiteState mapping - Call API 'Admin/Get info Service', from the response get value from customListObjs.testSuiteState[].id. Match the state by customListObjs.testSuiteState[].name. 26. If the user provides a test suite state name, fetch project info, find the matching state in customListObjs.testSuiteState[index].name, and use its ID in the payload as testSuiteState. If the name is not found, skip the testSuiteState field (it is not required) and show a user-friendly message: 'Test suite updated without test suite state, as given state is not available in the current project.' 27. If either owner or state is not found in project info, the update for that field will be skipped and a user-friendly message will be shown to the user. 28. UDF fields in steps must match your QMetry custom field configuration. 29. All IDs (testSuiteState from customListObjs.testSuiteState[index].id, testsuiteOwner from customListObjs.owner[index].id) must be valid for your QMetry instance. 30. If a custom field is mandatory, include it in the UDF object. 31. 32. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 33. 1. Call 'Fetch UDF Layout' with entityType='TS', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 34. 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. 35. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 36. 3. For MULTILOOKUPLIST fields: pick array of IDs; also pass alias flat key (e.g., fieldNameAlias: 'Option Label'). 37. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 38. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 39. Example: udfFields: { ts_field: 'value' }, UDF: { ts_field: { fieldID: 2001, value: 'value' } } 40. 6. Mandatory UDF fields (isMandatory=true) MUST be included.

Fetch QMetry test suites - automatically handles viewId resolution based on project

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• viewId (number): ViewId for test suites - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TS.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• folderPath (string): Folder path for test suites - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• getSubEntities (boolean): Whether to include sub-entities.

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• sort (string): Sort Records - refer json schema, Possible property - entityKey, name, testsuiteStatus, linkedPlatformCount, linkedTcCount, createdDate, createdByAlias, updatedDate, updatedByAlias, attachmentCount, owner, remExecutionTime, totalExecutionTime (default: "[{"property":"name","direction":"ASC"}]")

Output Description: JSON object with 'data' array containing test suites and pagination info

Use Cases: 1. List all test suites in a project 2. Search for specific test suites using filters 3. Browse test suites in specific folders 4. Get paginated test suite results

Examples:

1. Get all test suites from default project - system will auto-fetch viewId

{}

Expected Output: List of test suites from default project with auto-resolved viewId

2. Get all test suites from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of test suites from UT project using UT's specific TS viewId

3. Get test suites with manual viewId (skip auto-resolution)

{
  "projectKey": "MAC",
  "viewId": 103097,
  "folderPath": ""
}

Expected Output: Test suites using manually specified viewId 103097

4. List test suites from specific project (ex: project key can be anything (VT, UT, PROJ1, TEST9)

{
  "projectKey": "use specific given project key",
  "viewId": "fetch specific project given projectKey Test Suite ViewId",
  "folderPath": ""
}

Expected Output: Test suites using manually specified viewId 103097 or projectKey

5. Get test suites by release/cycle filter

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

6. Get test suites by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All test suites associated with Release 8.12 (ID: 55178)

7. Get test suites by cycle only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: All test suites associated with Cycle 8.12.1 (ID: 111577)

8. Search for specific test suite by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TS-1684\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test suites matching the entity key criteria

9. Search for multiple test suites by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-TS-1684,MAC-TS-1685,MAC-TS-1686\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Test suites matching any of the specified entity keys

Hints: 1. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and test suite fetching 2. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 3. Step 2: Get project info using that projectKey, extract latestViews.TS.viewId 4. Step 3: Use the SAME projectKey and the extracted TS viewId for fetching test suites 5. Step 4: If user doesn't specify projectKey, use 'default' for both project info and test suite fetching 6. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 7. For search by test suite key (like MAC-TS-1684), use filter: '[{"type":"string","value":"MAC-TS-1684","field":"entityKeyId"}]' 8. RELEASE/CYCLE FILTERING: Use release and cycle IDs, not names, for filtering 9. For release filter: '[{"value":[releaseId],"type":"list","field":"release"}]' 10. For cycle filter: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 11. For combined release+cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 12. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 13. FILTER FIELDS: name, release, cycle, platform, isArchived, testsuiteStatus, createdByAlias, createdDate, entityKeyId, attachmentCount, linkedPlatformCount, linkedTcCount, updatedByAlias, updatedDate, owner, remExecutionTime, and totalExecutionTime 14. SORT FIELDS: entityKey, name, testsuiteStatus, linkedPlatformCount, linkedTcCount, createdDate, createdByAlias, updatedDate, updatedByAlias, attachmentCount, remExecutionTime, and totalExecutionTime 15. For multiple entity keys, use comma-separated values in filter 16. Use empty string '' as folderPath for root directory

Get test suites that can be linked to test cases in QMetry with automatic viewId resolution

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tsFolderID (number): Test Suite folder ID. CRITICAL: the parameter name is 'tsFolderID' — do NOT use 'testSuiteFolderId', 'folderId', 'folderID', or other variants. Accepts a string or number. Get from project info response → rootFolders.TS.id. Use FETCH_PROJECT_INFO tool first if not provided by user.

• viewId (number): ViewId for test suite folders - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TSFS.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• getColumns (boolean): Whether to get column information in response. (default: true)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with test suites array and pagination metadata

Use Cases: 1. Get test suites available for linking with test cases 2. Find appropriate test suites for test case organization 3. Browse test suites in specific folders for better management 4. Filter test suites by release, cycle, or archive status 5. Organize test execution by grouping test cases into test suites 6. Plan test suite structure for comprehensive test coverage 7. Manage test case categorization for reporting purposes 8. Search for existing test suites before creating new ones 9. Get root test suite folder contents using project info

Examples:

1. Get test suites from root folder using auto-resolved viewId

{
  "tsFolderID": 113557
}

Expected Output: List of test suites available in the root test suite folder with auto-resolved viewId

2. Get test suites with custom pagination and auto-resolved viewId

{
  "tsFolderID": 113557,
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of test suites with 20 items per page

3. Filter test suites by release with auto-resolved viewId

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"}]"
}

Expected Output: Test suites associated with Release 8.12 (ID: 55178)

4. Filter test suites by cycle with auto-resolved viewId

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with Cycle 8.12.1 (ID: 111577)

5. Get only active (non-archived) test suites

{
  "tsFolderID": 113557,
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: List of active test suites (not archived)

6. Filter test suites by release and cycle

{
  "tsFolderID": 113557,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"release\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycle\"}]"
}

Expected Output: Test suites associated with both Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

7. Get test suites with column information

{
  "tsFolderID": 113557,
  "getColumns": true
}

Expected Output: Test suites list with detailed column metadata for better interpretation

8. Search test suites from specific sub-folder with manual viewId

{
  "tsFolderID": 42,
  "viewId": 104316
}

Expected Output: Test suites available in specific folder ID 42 for test case linking

Hints: 1. CRITICAL: tsFolderID is REQUIRED - Test Suite folder ID will be auto-resolved if not provided 2. viewId will be AUTOMATICALLY RESOLVED from project info if not provided 3. HOW TO GET tsFolderID: 4. 1. Call FETCH_PROJECT_INFO tool first to get project configuration 5. 2. From the response, use rootFolders.TS.id for the root test suite folder 6. 3. Example: rootFolders.TS.id = 113557 (MAC project root TS folder) 7. 4. If user doesn't specify tsFolderID, automatically use rootFolders.TS.id from project info 8. VIEWID AUTO-RESOLUTION: 9. 1. System automatically fetches project info using the projectKey 10. 2. Extracts latestViews.TSFS.viewId automatically 11. 3. Example: latestViews.TSFS.viewId = 104316 (MAC project TSFS view) 12. 4. Manual viewId only needed if you want to override the automatic resolution 13. WORKFLOW: System automatically handles project info if tsFolderID or viewId is not provided 14. PROJECT INFO STRUCTURE: clientData.rootFolders.TS.id contains the root test suite folder ID 15. PROJECT INFO STRUCTURE: latestViews.TSFS.viewId contains the test suite folder view ID 16. For sub-folders: Use specific folder IDs if you know them, or call folder listing APIs 17. FILTER CAPABILITIES: Same as other QMetry list operations 18. FILTER FIELDS: release, cycle, isArchived, name, status, priority 19. RELEASE/CYCLE FILTERING: Use numeric IDs in list format (get from FETCH_RELEASES_AND_CYCLES) 20. ARCHIVE FILTERING: 0=Active, 1=Archived 21. getColumns=true provides additional metadata for result interpretation 22. Multiple filter conditions are combined with AND logic 23. Pagination supported for large result sets (start, page, limit parameters) 24. This tool helps organize test cases into logical test suites 25. Essential for test execution planning and test case management 26. Use this before creating new test suites to check existing ones

Link test cases to a test suite in QMetry.

Toolset: Test Suites

Parameters:

• tsID (number) required: Id of Test Suite (required). CRITICAL: parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', or other variants.

• tcvdIDs (array) required: Array of Test Case Version IDs (required if fromReqs is false). CRITICAL: parameter name is 'tcvdIDs' — do NOT use 'tcVersionIds', 'testCaseVersionIds', or other variants.

• fromReqs (boolean): Link TestCases from Requirements (optional, default false)

Output Description: JSON object with linkage status and details.

Use Cases: 1. Link test cases to a test suite by entity keys 2. Bulk link multiple test cases to a suite 3. Automate test suite composition from test cases

Examples:

1. Link test cases to a test suite

{
  "tsID": 8674,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": false
}

Expected Output: Test cases QTM-TC-32 and QTM-TC-35 linked to test suite 8674.

2. Link test cases directly to test suites with test cases entityKeys VT-TC-9, VT-TC-10 to test suite id 1487397

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": false
}

Expected Output: Test cases VT-TC-9 and VT-TC-10 linked to test suite 1487397.

3. Link test case VT-TC-4, VT-TC-1,VT-TC-101, VT-TC-22 to test suite VT-TS-3

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503,
    5448505,
    5448506
  ],
  "fromReqs": false
}

Expected Output: Test cases VT-TC-4, VT-TC-1, VT-TC-101, and VT-TC-22 linked to test suite VT-TS-3.

Hints: 1. To get the tsID, call the Fetch Test Suites for Test Case API with rootFolderId otherwise if given folderid so use that and from response get the id. 2. To get the tcvdIDs by testcase entityKey, call the Testcase/Fetch Versions API and use data[].tcVersionID. 3. Set fromReqs to false to direct test case linkage.

Link test cases (including those linked to requirements) to a test suite in QMetry.

Toolset: Test Suites

Parameters:

• tsID (number) required: Id of Test Suite (required). CRITICAL: parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', or other variants.

• tcvdIDs (array) required: Array of Test Case Version IDs (required if fromReqs is true). CRITICAL: parameter name is 'tcvdIDs' — do NOT use 'tcVersionIds', 'testCaseVersionIds', or other variants.

• fromReqs (boolean): Link TestCases from Requirements (optional, default true)

Output Description: JSON object with linkage status and details.

Use Cases: 1. Link requirements linked test cases to a test suite 2. Bulk link multiple requirements linked test cases to a suite 3. Automate test suite composition from requirements linked test cases

Examples:

1. VT-RQ-18 Requirements Linked test cases to a test suite

{
  "tsID": 8674,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": true
}

Expected Output: Test cases QTM-TC-32 and QTM-TC-35 linked to test suite 8674.

2. VT-RQ-19 Requirements Linked test cases to test suites id 1487397

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503
  ],
  "fromReqs": true
}

Expected Output: Test cases VT-TC-9 and VT-TC-10 linked to test suite 1487397.

3. VT-RQ-20 Requirements Linked test case to test suite VT-TS-3

{
  "tsID": 1487397,
  "tcvdIDs": [
    5448504,
    5448503,
    5448505,
    5448506
  ],
  "fromReqs": true
}

Expected Output: Test cases VT-TC-4, VT-TC-1, VT-TC-101, and VT-TC-22 linked to test suite VT-TS-3.

Hints: 1. To get the tsID, call the Fetch Test Suites for Test Case API with rootFolderId otherwise if given folderid so use that and from response get the id. 2. To get the requirement linked tcvdIDs by requirement entityKey, call the Fetch Test Cases Linked to Requirement API by to fetch If user provides entityKey (e.g., MAC-RQ-1011), first call FETCH_REQUIREMENTS with filter on entityKeyId to resolve the numeric rqID and get the linked test cases version ids. 3. Set fromReqs to true to link requirements linked test cases instead of direct test case linkage.

Link one or more platforms to a QMetry Test Suite.

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• qmTsId (number) required: Id of Test Suite (required). CRITICAL: the parameter name is 'qmTsId' — do NOT use 'tsId', 'testSuiteId', 'tsID', or other variants. Accepts a string or number. To get the qmTsId - Call API 'Testsuite/Fetch Testsuite'. From the response, get value -> data[].id

• qmPlatformId (string) required: Comma-separated Platform IDs (required). CRITICAL: the parameter name is 'qmPlatformId' — do NOT use 'platformId', 'platformID', 'platformIds', or other variants. Accepts a number or string. To get the qmPlatformId - Call API 'Platform/List'. From the response, get value -> data[].platformID

Output Description: JSON object with linkage status, success message, and details.

Use Cases: 1. Link a single platform to a test suite 2. Link multiple platforms to a test suite for cross-platform testing 3. Define execution environments for a test suite 4. Organize test suites by supported platforms 5. Set up platform-specific test suite configurations

Examples:

1. Link single platform to a test suite

{
  "qmTsId": 1511970,
  "qmPlatformId": "63004"
}

Expected Output: Platform 63004 linked to test suite 1511970 successfully.

2. Link multiple platforms to a test suite

{
  "qmTsId": 1511970,
  "qmPlatformId": "63004,63005,63006"
}

Expected Output: Platforms 63004, 63005, 63006 linked to test suite 1511970 successfully.

Hints: 1. CRITICAL: qmTsId and qmPlatformId are REQUIRED parameters 2. To get the qmTsId (Test Suite ID): 3. 1. Call 'Testsuite/Fetch Testsuite' API 4. 2. From response, use data[].id 5. 3. Example: Test Suite 'Login Tests' might have ID 1511970 6. To get the qmPlatformId (Platform ID): 7. 1. Call 'Platform/List' API (Fetch Platforms tool) 8. 2. From response, use data[].platformID 9. 3. Example: Platform 'Chrome' might have ID 63004 10. qmPlatformId accepts comma-separated values for multiple platforms 11. Format for multiple platforms: '63004,63005,63006' 12. No spaces in the comma-separated list 13. If test suite entity key (e.g., VT-TS-12) is provided, first fetch test suites to resolve numeric ID 14. Platforms represent browsers, operating systems, devices, or custom environments 15. This tool helps organize cross-platform test execution 16. Essential for comprehensive platform coverage testing

Get test cases that are linked (or not linked) to a specific test suite in QMetry

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tsID (number) required: Test Suite numeric ID. CRITICAL: the parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', 'suiteId', or other variants. Accepts a string or number. NOTE: To get the tsID - Call API 'Testsuite/Fetch Testsuite' From the response, get value of following attribute -> data[].id

• getLinked (boolean): True to get only those issues that are linked with this Test case Run, False to get those issues which are not linked with this Test case Run. Default value true (get linked issues). (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with test cases array containing test case details, properties, and suite linkage information

Use Cases: 1. Get all test cases linked to a specific test suite for execution planning 2. Find test cases that are NOT linked to a test suite (gap analysis) 3. Analyze test suite composition and coverage 4. Filter linked test cases by various criteria 5. Plan test execution based on test suite structure 6. Generate test suite reports and documentation 7. Validate test suite contents before execution 8. Manage test case organization within test suites 9. Export test suite details for external reporting 10. Verify test case assignments in test suites

Examples:

1. Get all test cases linked to test suite ID 1497291 (default behavior)

{
  "tsID": 1497291
}

Expected Output: List of test cases linked to the test suite with test case details and metadata

2. Get all test cases linked to test suite ID 1497291 (explicit)

{
  "tsID": 1497291,
  "getLinked": true
}

Expected Output: List of test cases linked to the test suite with test case details and metadata

3. Get test cases NOT linked to test suite (gap analysis)

{
  "tsID": 1497291,
  "getLinked": false
}

Expected Output: List of test cases that are NOT linked to the test suite

4. Get linked test cases with custom pagination

{
  "tsID": 1497291,
  "getLinked": true,
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of linked test cases with 50 items per page

5. Filter linked test cases by priority (using default getLinked=true)

{
  "tsID": 1497291,
  "filter": "[{\"value\":[1,2],\"type\":\"list\",\"field\":\"priorityAlias\"}]"
}

Expected Output: High and medium priority test cases linked to the suite

6. Filter linked test cases by status

{
  "tsID": 1497291,
  "getLinked": true,
  "filter": "[{\"value\":[1],\"type\":\"list\",\"field\":\"testCaseStateAlias\"}]"
}

Expected Output: Active test cases linked to the test suite

Hints: 1. CRITICAL: tsID parameter is REQUIRED - this is the Test Suite numeric ID 2. getLinked parameter is OPTIONAL - defaults to true if not provided 3. HOW TO GET tsID: 4. 1. Call API 'Testsuite/Fetch Testsuite' to get available test suites 5. 2. From the response, get value of following attribute -> data[].id 6. 3. Example: Test Suite 'Regression Suite' might have ID 1497291 7. tsID is NOT the same as tsFolderID - tsID refers to a specific test suite, not a folder 8. getLinked=true (default): Returns test cases that ARE linked to the test suite 9. getLinked=false: Returns test cases that are NOT linked to the test suite (useful for gap analysis) 10. If getLinked is not specified, it defaults to true (linked test cases) 11. FILTER CAPABILITIES: Support filtering by test case properties 12. FILTER FIELDS: priorityAlias (list), testCaseStateAlias (list), testingTypeAlias (list), testCaseTypeAlias (list), componentAlias (list), owner (list) 13. PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 14. STATUS IDs: Typically 1=Active, 2=Review, 3=Deprecated (verify with your QMetry instance) 15. TESTING TYPE IDs: Typically 1=Manual, 2=Automated (verify with your QMetry instance) 16. TYPE IDs: Typically 1=Functional, 2=Integration, 3=System (verify with your QMetry instance) 17. Multiple filter conditions are combined with AND logic 18. Use pagination for large result sets (start, page, limit parameters) 19. This tool is essential for test suite management and execution planning 20. Helps verify test suite composition before test runs 21. Critical for understanding test coverage within specific suites 22. Use for test suite analysis and optimization

Get executions for a given test suite in QMetry

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tsID (number) required: Test Suite numeric ID. CRITICAL: the parameter name is 'tsID' — do NOT use 'testSuiteId', 'testSuiteID', 'suiteId', or other variants. Accepts a string or number. NOTE: To get the tsID - Call API 'Testsuite/Fetch Testsuite' From the response, get value of following attribute -> data[].id

• tsFolderID (number): Test Suite folder ID. CRITICAL: the parameter name is 'tsFolderID' — do NOT use 'testSuiteFolderId', 'folderId', 'folderID', or other variants. Accepts a string or number. Get from project info response → rootFolders.TS.id. Use FETCH_PROJECT_INFO tool first if not provided by user.

• gridName (string): Grid Name to be displayed (default 'TESTEXECUTIONLIST')

• viewId (number): ViewId for test execution - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TE.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with executions array containing execution details, status, platforms, releases, and execution metadata

Use Cases: 1. Get all executions for a specific test suite for reporting purposes 2. Analyze test execution results and trends within a test suite 3. Filter executions by release, cycle, platform, or automation status 4. Monitor test suite execution performance across different environments 5. Generate execution reports for specific test suites 6. Track execution history and patterns for test suite optimization 7. Validate test suite execution coverage across releases and cycles 8. Audit test execution data for compliance and quality assurance 9. Export execution data for external reporting and analytics

Examples:

1. Get all executions for test suite ID 194955

{
  "tsID": 194955
}

Expected Output: List of executions for the test suite with execution details, status, and metadata

2. Get executions with test suite folder and view ID

{
  "tsID": 194955,
  "tsFolderID": 126554,
  "viewId": 41799
}

Expected Output: Executions filtered by test suite folder and specific view configuration

3. Filter executions by release and cycle

{
  "tsID": 194955,
  "filter": "[{\"type\":\"list\",\"value\":[55178],\"field\":\"releaseID\"},{\"type\":\"list\",\"value\":[111577],\"field\":\"cycleID\"}]"
}

Expected Output: Executions filtered by specific release (55178) and cycle (111577)

4. Filter executions by platform and automation status

{
  "tsID": 194955,
  "filter": "[{\"type\":\"list\",\"value\":[12345],\"field\":\"platformID\"},{\"type\":\"boolean\",\"value\":true,\"field\":\"isAutomatedFlag\"}]"
}

Expected Output: Automated executions filtered by specific platform (12345)

5. Get only active (non-archived) executions

{
  "tsID": 194955,
  "filter": "[{\"value\":[0],\"type\":\"list\",\"field\":\"isArchived\"}]"
}

Expected Output: Active executions that are not archived

6. Get executions with custom pagination and grid name

{
  "tsID": 194955,
  "gridName": "TESTEXECUTIONLIST",
  "page": 1,
  "limit": 25
}

Expected Output: Paginated list of executions with 25 items per page using specific grid configuration

Hints: 1. !MOST IMPORTANT HOW TO GET viewId: 2. CRITICAL: Always resolve and use the correct test execution viewId for the current project when calling this tool. 3. The viewId parameter must be fetched from the active project's info (latestViews.TEL.viewId). 4. Each QMetry project may have a different test execution list viewId, so using a stale or incorrect viewId will result in incomplete or invalid executions list data by test suite id. 5. Usage workflow: 6. 1. Fetch project info for the current project (Admin/Get info Service). 7. 2. Extract latestViews.TEL.viewId from the response. 8. 3. Use this viewId in the Fetch Test Case Runs by Test Suite Run API call. 9. Example: 10. { 11. tsID: 1533730, 12. viewId: 94194, 13. gridName: 'TESTEXECUTIONLIST' 14. } 15. CRITICAL: tsID parameter is REQUIRED - this is the Test Suite numeric ID 16. HOW TO GET tsID: 17. 1. Call API 'Testsuite/Fetch Testsuite' to get available test suites 18. 2. From the response, get value of following attribute -> data[].id 19. 3. Example: Test Suite 'Regression Suite' might have ID 194955 20. HOW TO GET tsFolderID (optional): 21. 1. Call API 'Testsuite/List of folders' to get test suite folders 22. 2. From the response, get value of following attribute -> data[].id 23. 3. Example: Test Suite folder might have ID 126554 24. FILTER CAPABILITIES: Extensive filtering by execution properties 25. FILTER FIELDS: releaseID (list), cycleID (list), platformID (list), isAutomatedFlag (boolean), isArchived (list) 26. RELEASE/CYCLE FILTERING: Use numeric IDs in list format (get from FETCH_RELEASES_AND_CYCLES) 27. PLATFORM FILTERING: Use numeric platform IDs (get from FETCH_PLATFORMS) 28. AUTOMATION STATUS: Use boolean true/false for isAutomatedFlag field 29. ARCHIVE STATUS: 0=Active executions, 1=Archived executions 30. GRID NAME: Default is 'TESTEXECUTIONLIST' - used for execution list display configuration 31. VIEW ID: Optional numeric identifier for specific execution view configurations 32. Multiple filter conditions are combined with AND logic 33. Use pagination for large execution result sets (start, page, limit parameters) 34. This tool is essential for test execution analysis and reporting 35. Critical for monitoring test suite performance and execution trends 36. Use for compliance reporting and execution audit trails 37. Essential for test execution planning and resource optimization

Get test case runs under a specific test suite run execution in QMetry, including Test Run UDF values. ALWAYS present results as a unified table: Test Case Key | Test Case Summary | Executed Version | Execution Status | <UDF Label columns…>. NEVER show a separate type+value breakdown — always combine identification fields and UDF values in one table per run.

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tsrunID (string) required: Test Suite Run ID. CRITICAL: the parameter name is 'tsrunID' — do NOT use 'testSuiteRunId', 'tsRunID', 'testSuiteRunID', or any other variant. Accepts a string or number (e.g. 731600 or '731600' — both are valid). To get this value: Call 'Fetch Executions by Test Suite' → use data[].tsRunID from the response.

• viewId (number): ViewId for test execution - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.TE.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• udfFilter (string): User-defined field filter as JSON string (default '[]') (default: "[]")

• tcrUdfFilter (string): Test Case Run (TCR) UDF filter as JSON string (default '[]'). Used to filter test case runs by Test Run UDF field values. Format: '[{"type":"list","value":[,],"field":""}]'. Example: '[{"type":"list","value":[5108701,5108697],"field":"8260LUP"}]' filters runs where the UDF field '8260LUP' has those list item IDs. (default: "[]")

• showTcWithDefects (boolean): Show test case runs with linked defects (default: false)

Output Description: JSON object with test case runs array. Each row ALWAYS contains these mandatory identification fields: 'entityKey' (Test Case Key, e.g. 'MAC-TC-123'), 'summary' (Test Case Summary/name), 'latestVersion' (Executed Version, e.g. 'v1', 'v2'), 'runStatus' (Execution Status label, e.g. 'Passed', 'Failed', 'Not Run'), 'runStatusID' (numeric status ID), 'tcRunID' (numeric Test Run ID), and 'testRunUdfs' (object with Test Run UDF field keys mapped to their values, parsed from the raw 'udfjson' field; HTML stripped from rich text). UDF values can also be fetched in enriched form via FETCH_TEST_RUN_UDF_VALUES or field metadata via FETCH_TEST_RUN_UDF_METADATA. The top-level response includes 'hasTcRunUdf' (boolean), 'total' (count), and pagination metadata.

Use Cases: 1. Get all test case runs under a specific test suite run execution 2. Fetch Test Run UDF values for all test case executions in a test suite run — always show Test Case Key, Summary, and Execution Status alongside UDFs 3. Fetch Test Run UDF values for a specific test case execution by tcRunID 4. Filter test case runs by Test Run UDF field values (e.g. show only runs where dropdown UDF = specific option) 5. Analyze individual test case execution results, status, and custom UDF metadata 6. Monitor test case run performance and execution trends 7. Generate detailed test execution reports including custom UDF data 8. Track test case run history and execution patterns 9. Validate test case run coverage and execution completeness 10. Audit test case run data with UDF values for compliance and quality assurance 11. Export detailed test case run data including Test Run UDFs for external reporting 12. Retrieve paginated test case run results for large test suite executions

Examples:

1. Get all test case runs for test suite run ID '107021'

{
  "tsrunID": "107021",
  "viewId": 6887
}

Expected Output: Present as ONE unified table — never as a separate type+value breakdown. Example: | Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | Country | | MAC-TC-5 | Login - valid credential | v1 | Passed | varis | chrome, edge, safari | Functional | India > i3 | | MAC-TC-6 | Login - invalid password | v2 | Failed | john | firefox | Regression | - | Columns: Test Case Key (entityKey) | Test Case Summary (summary) | Executed Version (latestVersion) | Execution Status (runStatus) | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

2. Fetch Test Run UDF values for all executions in test suite run '728995'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "start": 0,
  "page": 1,
  "limit": 20
}

Expected Output: Present as ONE unified table combining identification fields and UDF values — never a separate type+value breakdown. Example: | Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | Environments UDF | Planned Execution Date | Execution Type | | MAC-TC-5 | Login test | v1 | Passed | varis | chrome, edge, safari | - | Functional | HTML is stripped from LARGETEXT UDF fields. Null values shown as '-'.

3. Filter by Test Run UDF list/dropdown field (single-select or multi-select lookup) — runs where UDF '8260LUP' has list item IDs 5108701 or 5108697

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5108701,5108697],\"field\":\"8260LUP\"}]"
}

Expected Output: Filtered test case runs matching the lookup list UDF values

4. Filter by Test Run UDF multi-lookup list field — runs where multi-select UDF 'PGTE_MULTILOOKUPLIST' contains list item IDs 5126503 or 5126502

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5126503,5126502],\"field\":\"PGTE_MULTILOOKUPLIST\"}]"
}

Expected Output: Filtered test case runs where multi-lookup UDF matches any of the given list item IDs

5. Filter by Test Run UDF cascading dropdown field — runs where cascading UDF 'cascade_vK' has list item IDs 5126498 or 5126499 (must set isCascading:true)

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5126498,5126499],\"field\":\"cascade_vK\",\"isCascading\":true}]"
}

Expected Output: Filtered test case runs matching the cascading dropdown UDF values

6. Filter by Test Run UDF short text field — runs where text UDF 'TRString' contains the value 'str'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"string\",\"field\":\"TRString\",\"value\":\"str\"}]"
}

Expected Output: Filtered test case runs where short text UDF matches the search string

7. Filter by Test Run UDF large text field — runs where large text UDF 'vk_large_text' contains 'this is large text'

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"string\",\"field\":\"vk_large_text\",\"value\":\"this is large text\"}]"
}

Expected Output: Filtered test case runs where large text UDF matches the search string

8. Filter by Test Run UDF date field — runs where date UDF 'PGTE_DATEPICKER' is after a specific date (comparison: gt) and before another date (comparison: lt)

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"date\",\"field\":\"PGTE_DATEPICKER\",\"comparison\":\"gt\",\"value\":\"06-01-2026\"},{\"type\":\"date\",\"field\":\"PGTE_DATEPICKER\",\"comparison\":\"lt\",\"value\":\"06-30-2026\"}]"
}

Expected Output: Filtered test case runs where date UDF falls within the specified range

9. Filter by Test Run UDF numeric field — runs where numeric UDF 'NB_number_TR' equals 2

{
  "tsrunID": "728995",
  "viewId": 79451,
  "tcrUdfFilter": "[{\"type\":\"numeric\",\"value\":2,\"field\":\"NB_number_TR\"}]"
}

Expected Output: Filtered test case runs where numeric UDF equals the specified value

10. Combine multiple Test Run UDF filters — filter by list UDF AND string UDF AND numeric UDF simultaneously

{
  "tsrunID": "728995",
  "viewId": 79451,
  "start": 0,
  "page": 1,
  "limit": 20,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5108701,5108697],\"field\":\"8260LUP\"},{\"type\":\"string\",\"field\":\"TRString\",\"value\":\"str\"},{\"type\":\"numeric\",\"value\":2,\"field\":\"NB_number_TR\"}]"
}

Expected Output: Test case runs matching ALL specified UDF filter conditions (AND logic)

11. Full filter combination — standard field filter + Test Run UDF filter + show only runs with defects

{
  "tsrunID": "728995",
  "viewId": 79451,
  "start": 0,
  "page": 1,
  "limit": 20,
  "filter": "[]",
  "udfFilter": "[]",
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5108701,5108697],\"field\":\"8260LUP\"},{\"type\":\"string\",\"field\":\"TRString\",\"value\":\"str\"},{\"type\":\"string\",\"field\":\"vk_large_text\",\"value\":\"this is large text\"},{\"type\":\"date\",\"field\":\"PGTE_DATEPICKER\",\"comparison\":\"gt\",\"value\":\"\"},{\"type\":\"date\",\"field\":\"PGTE_DATEPICKER\",\"comparison\":\"lt\",\"value\":\"\"},{\"type\":\"list\",\"value\":[5126503,5126502],\"field\":\"PGTE_MULTILOOKUPLIST\"},{\"type\":\"list\",\"value\":[5126498,5126499],\"field\":\"cascade_vK\",\"isCascading\":true},{\"type\":\"numeric\",\"value\":2,\"field\":\"NB_number_TR\"}]",
  "showTcWithDefects": false
}

Expected Output: Test case runs filtered by all 7 UDF field type conditions simultaneously

12. Get paginated test case runs with standard runStatus filter

{
  "tsrunID": "2362144",
  "viewId": 104123,
  "start": 0,
  "page": 1,
  "limit": 25,
  "filter": "[{\"type\":\"string\",\"value\":\"Failed\",\"field\":\"runStatus\"}]"
}

Expected Output: Paginated list of Failed test case runs with 25 items per page including testRunUdfs

13. Show only test case runs with linked defects, filtered by Test Run UDF list value

{
  "tsrunID": "107021",
  "viewId": 6887,
  "showTcWithDefects": true,
  "tcrUdfFilter": "[{\"type\":\"list\",\"value\":[5108701],\"field\":\"8260LUP\"}]"
}

Expected Output: Test case runs with defects where the specified Test Run UDF matches

Hints: 1. === MANDATORY RESPONSE FORMAT — READ THIS BEFORE RENDERING ANY OUTPUT === 2. 3. PIVOT RULE — CRITICAL: 4. The 'testRunUdfs' field on each row is a key-value map (object) of UDF field keys to their values. 5. You MUST pivot this into TABLE COLUMNS — do NOT render it as rows. 6. → Each key in testRunUdfs = use the UDF human-readable label as the column header 7. → Each value in testRunUdfs = the cell value for that run's row 8. → 'fieldType' / 'fieldID' = INTERNAL METADATA — NEVER show these as columns 9. 10. FORBIDDEN PATTERNS — NEVER do any of these: 11. ❌ Do NOT render a separate sub-table (Label | Type | Value) per tcRunID 12. ❌ Do NOT show 'Type' or 'fieldType' as a visible column 13. ❌ Do NOT group output by tcRunID with individual breakdowns beneath each 14. ❌ Do NOT show raw UDF field keys (e.g. 'TRString', '8260LUP') as column headers — use human-readable labels 15. 16. REQUIRED OUTPUT — ONE unified table, all runs as rows: 17. | Test Case Key | Test Case Summary | Executed Version | Execution Status | <UDF Label 1> | <UDF Label 2> | ... | 18. |---------------|-------------------|------------------|------------------|---------------|---------------|-----| 19. | VKMCP-TC-1 | Login test | v1 | Not Run | varis | chrome, edge | ... | 20. | VKMCP-TC-2 | Invalid password | v2 | Not Run | john | firefox | ... | 21. 22. MANDATORY COLUMNS (always first, in this order): 23. 1. Test Case Key → entityKey (e.g. 'VKMCP-TC-1') 24. 2. Test Case Summary → summary (test case name) 25. 3. Executed Version → latestVersion (e.g. 'v1', 'v2') 26. 4. Execution Status → runStatus (e.g. 'Not Run', 'Passed', 'Failed') 27. 5. Tested By → testedBy/executedBy when present 28. 6+. One column per UDF field — use the human-readable label as header, the value as the cell. 29. 30. Null UDF values → show as '-' in the cell. 31. If testRunUdfs is empty or hasTcRunUdf is false, still show columns 1-5. 32. CHAINING WITH FETCH TEST RUN UDF VALUES: 33. If the user explicitly asks for Test Run UDFs with these test case runs, call 'Fetch Test Run UDF Values' after this tool with sourceContext='testSuiteRun' and sourceRows=. Render that tool's unifiedTableRows as the final answer. 34. === END MANDATORY RESPONSE FORMAT === 35. 36. CRITICAL WORKFLOW FOR FETCHING ALL EXECUTIONS OF A TEST SUITE: 37. When user asks to: 38. - 'fetch all executions' 39. - 'get all test runs' 40. - 'fetch all tcRunIDs for test suite X' 41. - 'update status for all executions of test suite X' 42. STEP 1: First call FETCH_EXECUTIONS_BY_TESTSUITE tool with the test suite ID (tsID, not entityKey) 43. - This returns ALL execution records for that test suite (could be 3, 5, 9, or any number) 44. - Extract ALL tsRunID values from the response data array 45. - Example response: data: [{tsRunID: '2739237', ...}, {tsRunID: '2739236', ...}, {tsRunID: '2739235', ...}] 46. STEP 2: For EACH tsRunID from Step 1, call this tool (FETCH_TEST_CASE_RUNS_BY_TESTSUITE_RUN) 47. - This returns all test case runs (tcRunID values) for that specific execution 48. - Repeat for ALL tsRunID values discovered in Step 1 49. STEP 3: Collect all tcRunID values from all executions 50. - Now you have the complete list of test case runs across ALL executions 51. - Use these for bulk status updates or other operations 52. CRITICAL ERROR TO AVOID: 53. - NEVER assume or hard-code only 2-3 execution IDs 54. - NEVER skip Step 1 - always discover ALL executions first 55. - NEVER fetch tcRunIDs for only some executions - get ALL of them 56. - If there are 9 executions, you must fetch tcRunIDs for all 9, not just 2 57. EXAMPLE WORKFLOW: 58. User: 'Fetch all test case runs for test suite VKMCP-TS-21' 59. Step 1: Call FETCH_EXECUTIONS_BY_TESTSUITE with tsID (resolved from VKMCP-TS-21) 60. Result: Found 9 executions with tsRunIDs: 2739237, 2739236, 2739235, 2739234, 2739233, 2739232, 2739231, 2739230, 2739229 61. Step 2: Call this tool 9 times (once for each tsRunID) 62. Call 1: tsrunID='2739237' -> returns 54 tcRunIDs 63. Call 2: tsrunID='2739236' -> returns 54 tcRunIDs 64. ... (repeat for all 9) 65. Step 3: Total collected: 9 executions × 54 test cases = 486 total tcRunIDs 66. 67. PERFORMANCE CONSIDERATIONS FOR LARGE TEST RUNS: 68. When dealing with large numbers of test case runs (500+, 1000+), follow these guidelines: 69. 1. ALWAYS inform the user about the scale BEFORE starting operations: 70. Example: 'Found 9 executions with approximately 486 test case runs. This will require fetching data from all 9 executions and may take a moment.' 71. 2. For bulk status updates on 1000+ test case runs: 72. - NEVER attempt to update all 1000+ in a single operation 73. - Break into smaller batches of 10-20 test case runs per update 74. - Inform user: 'Found 1000 test case runs. Will process in batches of 20 to ensure reliability and performance.' 75. - Show progress: 'Processing batch 1/50 (20 test runs)...', 'Batch 2/50...' 76. 3. Recommended batch sizes: 77. - For status updates: 10-20 test case runs per batch 78. - For fetching data: Can handle larger batches (50-100) 79. - Adjust based on API response times and timeout limits 80. 4. Always provide progress updates for long-running operations: 81. - Before: 'Processing 1000 test runs in 50 batches of 20...' 82. - During: 'Completed 200/1000 test runs (10 batches)...' 83. - After: 'Successfully updated all 1000 test case runs.' 84. 5. Error handling for batch operations: 85. - If a batch fails, report which batch and continue with remaining 86. - Provide summary at the end: 'Completed 48/50 batches. 2 batches failed (batch 23, 45).' 87. - Allow user to retry failed batches specifically 88. EXAMPLE LARGE-SCALE WORKFLOW: 89. User: 'Update status to Failed for all test runs in VKMCP-TS-21' 90. Step 1: Discover all executions (9 found) 91. Step 2: Fetch all tcRunIDs (486 total) 92. Step 3: Inform user: 'Found 486 test case runs across 9 executions. Will update in 25 batches of 20 runs each.' 93. Step 4: Process in batches with progress updates 94. Step 5: Report completion: 'Successfully updated all 486 test case runs to Failed status.' 95. 96. CRITICAL: tsrunID and viewId parameters are REQUIRED 97. tsrunID is a STRING identifier for the test suite run execution 98. viewId is a NUMERIC identifier for the test execution view 99. !MOST IMPORTANT HOW TO GET tsrunID: 100. 1. Call API 'Execution/Fetch Executions' (FETCH_EXECUTIONS_BY_TESTSUITE) to get ALL available executions 101. 2. From the response, get value of following attribute -> data[].tsRunID for EVERY execution 102. 3. Example: Test Suite might have multiple executions with IDs '107021', '107022', '107023', etc. 103. 4. NEVER assume there are only 2-3 executions - always fetch to discover the actual count 104. !MOST IMPORTANT HOW TO GET viewId: 105. CRITICAL: Always resolve and use the correct test execution viewId for the current project when calling this tool. 106. The viewId parameter must be fetched from the active project's info (latestViews.TE.viewId). 107. Each QMetry project may have a different test execution viewId, so using a stale or incorrect viewId will result in incomplete or invalid test case run data. 108. Usage workflow: 109. 1. Fetch project info for the current project (Admin/Get info Service). 110. 2. Extract latestViews.TE.viewId from the response. 111. 3. Use this viewId in the Fetch Test Case Runs by Test Suite Run API call. 112. Example: 113. { 114. tsrunID: "2362144", 115. viewId: 104123, 116. start: 0, 117. page: 1, 118. limit: 25 119. } 120. This ensures the tool fetches the proper execution runs data for the selected project context. 121. SUPPORTED PARAMETERS: start, page, limit, tsrunID, viewId, filter, udfFilter, tcrUdfFilter, showTcWithDefects 122. PAGINATION: Use start, page, and limit for result pagination 123. PAYLOAD FORMAT: {"start": 0, "page": 1, "limit": 10, "tsrunID": "2362144", "viewId": 104123} 124. 125. === TEST RUN UDF (tcrUdfFilter) — ALL 7 FIELD TYPE FORMATS === 126. tcrUdfFilter filters test case RUNS by Test Run UDF values (not test case UDFs — use udfFilter for those). 127. Value is a JSON array string. Multiple conditions are combined with AND logic. 128. Base structure: {"type":"", "field":"", "value": [,"comparison":"..."] [,"isCascading":true]} 129. 130. --- TYPE 1: list (single-select lookup / dropdown) --- 131. Use for: single-select lookup list UDF fields (one value selected from a list). 132. value: array of numeric list item IDs — get IDs from FETCH_CUSTOM_LIST_ITEMS tool. 133. Format: {"type":"list", "field":"", "value":[,]} 134. Example: [{"type":"list","value":[5108701,5108697],"field":"8260LUP"}] 135. Matches runs where the UDF value is ANY of the provided list item IDs (OR within the array). 136. 137. --- TYPE 2: list (multi-select lookup list) --- 138. Use for: multi-select lookup list UDF fields (multiple values can be selected). 139. Syntax identical to single-select list — same format, just the UDF field itself is multi-select. 140. Format: {"type":"list", "field":"", "value":[,]} 141. Example: [{"type":"list","value":[5126503,5126502],"field":"PGTE_MULTILOOKUPLIST"}] 142. Matches runs where ANY of the UDF's selected values match any of the provided IDs. 143. 144. --- TYPE 3: list (cascading dropdown) --- 145. Use for: cascading dropdown UDF fields (parent-child linked dropdowns). MUST add isCascading:true. 146. Format: {"type":"list", "field":"", "value":[,], "isCascading":true} 147. Example: [{"type":"list","value":[5126498,5126499],"field":"cascade_vK","isCascading":true}] 148. CRITICAL: missing isCascading:true on a cascading field will cause incorrect results or API error. 149. 150. --- TYPE 4: string (short text) --- 151. Use for: single-line text UDF fields. 152. value: the string to search for (partial match / contains). 153. Format: {"type":"string", "field":"", "value":""} 154. Example: [{"type":"string","field":"TRString","value":"str"}] 155. 156. --- TYPE 5: string (large text / rich text) --- 157. Use for: multi-line or rich text UDF fields. Syntax is identical to short text string type. 158. Format: {"type":"string", "field":"", "value":""} 159. Example: [{"type":"string","field":"vk_large_text","value":"this is large text"}] 160. NOTE: Search is against the raw (HTML) content stored in the field; plain text search terms work fine. 161. 162. --- TYPE 6: date --- 163. Use for: date picker UDF fields. REQUIRES a 'comparison' property. 164. comparison: 'gt' = after the date (greater than), 'lt' = before the date (less than). 165. value: date string in 'MM-DD-YYYY' format, or empty string '' to leave the bound open. 166. Format: {"type":"date", "field":"", "comparison":"gt"|"lt", "value":"MM-DD-YYYY"} 167. Example — date range: [{"type":"date","field":"PGTE_DATEPICKER","comparison":"gt","value":"06-01-2026"},{"type":"date","field":"PGTE_DATEPICKER","comparison":"lt","value":"06-30-2026"}] 168. Example — open-ended (no upper bound): [{"type":"date","field":"PGTE_DATEPICKER","comparison":"gt","value":"06-01-2026"}] 169. To filter by a single date use two conditions (gt day-before AND lt day-after) or just one bound. 170. CRITICAL: 'comparison' field is mandatory for date type — omitting it causes API error. 171. 172. --- TYPE 7: numeric --- 173. Use for: number UDF fields. 174. value: a number (integer or decimal). 175. Format: {"type":"numeric", "field":"", "value":} 176. Example: [{"type":"numeric","value":2,"field":"NB_number_TR"}] 177. 178. --- COMBINING MULTIPLE FILTERS --- 179. All conditions in tcrUdfFilter array use AND logic — runs must satisfy ALL conditions. 180. Full example (all 7 types combined): 181. [ 182. {"type":"list","value":[5108701,5108697],"field":"8260LUP"}, 183. {"type":"list","value":[5126503,5126502],"field":"PGTE_MULTILOOKUPLIST"}, 184. {"type":"list","value":[5126498,5126499],"field":"cascade_vK","isCascading":true}, 185. {"type":"string","field":"TRString","value":"str"}, 186. {"type":"string","field":"vk_large_text","value":"large text"}, 187. {"type":"date","field":"PGTE_DATEPICKER","comparison":"gt","value":"06-01-2026"}, 188. {"type":"date","field":"PGTE_DATEPICKER","comparison":"lt","value":"06-30-2026"}, 189. {"type":"numeric","value":2,"field":"NB_number_TR"} 190. ] 191. --- FILTER PARAMETER SUMMARY --- 192. tcrUdfFilter: filter by Test Run UDF fields (this section) 193. udfFilter: filter by Test Case UDF fields (different from test run UDFs) 194. filter: filter by standard execution fields (runStatus, executedBy, etc.) 195. All three can be combined in a single request — they are independently applied with AND logic. 196. 197. hasTcRunUdf FLAG — IMPORTANT: 198. The response contains a 'hasTcRunUdf' boolean flag at the top level. 199. hasTcRunUdf: true → Project has Test Run UDFs configured; each record includes 'testRunUdfs' object. 200. hasTcRunUdf: false → Project has NO Test Run UDFs configured. 201. When hasTcRunUdf is false, the response includes a 'testRunUdfNote' with a professional explanation. 202. Inform the user: 'No Test Run UDFs are configured for this project. Contact a project administrator to set up Test Run UDF fields.' 203. NEVER attempt to read testRunUdfs from records when hasTcRunUdf is false — the field will not be present. 204. 205. TEST RUN UDF RESPONSE (testRunUdfs): 206. When the API returns Test Run UDF data, each row will include a 'testRunUdfs' object. 207. This is a key-value map of UDF field keys to their values, parsed from the API's 'udfjson' field. 208. HTML is stripped from rich text (large text) UDF fields for readable LLM output. 209. Example testRunUdfs in response: 210. testRunUdfs: { 211. "8260LUP": "l1", 212. "look_554": "99", 213. "cascade_vK": {"child": "aa", "parent": "abc"}, 214. "dateNJ": "06-02-2026", 215. "NB_Multilppup_TR": ["ahd"], 216. "Jal_Largetext": "asdef asdfads asdfasf asdf asdf asfd a sdfa" 217. } 218. Use pagination for large result sets (start, page, limit parameters) 219. This tool is essential for detailed test execution analysis and reporting 220. Critical for monitoring individual test case execution performance and UDF values 221. Use for compliance reporting and execution audit trails 222. Essential for test execution quality assurance and trend analysis

Update execution status for individual or multiple test case runs in bulk

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• entityIDs (string) required: Comma-separated IDs of Test Case Runs to update. CRITICAL: the parameter name is 'entityIDs' — do NOT use 'tcRunIDs', 'testCaseRunIds', 'runIds', or other variants. Accepts a number or string (e.g., 66095087 or '66095087' for single, '66095069,66095075' for bulk). To get the entityIDs - Call API 'Execution/Fetch Testcase Run ID'. From the response, get value -> data[].tcRunID

• entityType (enum): Type of Entity to Execute: 'TCR' (Test Case Run) or 'TCSR' (Test Case Step Run) (default: "TCR")

• qmTsRunId (string) required: Id of Test Suite Run to execute (required). CRITICAL: the parameter name is 'qmTsRunId' — do NOT use 'tsrunID', 'testSuiteRunId', 'tsRunID', or other variants. Accepts a number or string. To get the qmTsRunId - Call API 'Execution/Fetch Executions'. From the response, get value -> data[].tsRunID

• runStatusID (number) required: Id of the execution status to set (required). To get the runStatusID - Call API 'Admin/Project GET info Service' From the response, get value of following attribute -> allstatus[].id Common statuses: Pass, Fail, Not Run, Blocked, WIP, etc.

• dropID (union): Unique identifier of drop/build on which execution is to be performed (optional). To get the dropID - Call API 'Fetch Build/List' From the response, get value of following attribute -> data[].dropID

• isAutoExecuted (enum): Set '1' for automated and '0' for manual Execution Type

• isBulkOperation (boolean): Set true for bulk operations (multiple entityIDs), false for single execution update. Default: true if multiple comma-separated entityIDs, false otherwise

• comments (string): Optional comments for the execution status update

• username (string): If Part 11 Compliance is active then required for authentication

• password (string): If Part 11 Compliance is active then required for authentication

• qmRunObj (string): Internal QMetry run object (optional, usually empty string)

• type (enum): Type of Entity - same as entityType (for backwards compatibility)

Output Description: JSON object with success status, updated execution details, and confirmation message

Use Cases: 1. Update single test case run status to Pass, Fail, Blocked, or Not Run 2. Bulk update multiple test case run statuses in a single operation 3. Mark all selected test case runs as Not Run for re-execution 4. Update execution status after manual test execution 5. Set execution status based on automated test results 6. Update test execution status across different test environments 7. Track test execution progress and completion 8. Manage test execution status for compliance and reporting

Examples:

1. Update single test case run status to Failed (single execution)

{
  "entityIDs": "66095087",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123266,
  "isBulkOperation": false
}

Expected Output: Test case run 66095087 status updated to Failed successfully

2. Bulk update two test case runs to Pass status (bulk execution)

{
  "entityIDs": "66095069,66095075",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123268,
  "isBulkOperation": true,
  "comments": "All test cases passed successfully"
}

Expected Output: Test case runs 66095069 and 66095075 updated to Pass status successfully

3. Bulk update all selected test case runs to Not Run status

{
  "entityIDs": "66095069,66095075,66095081,66095087,66095093,66095099,66095105",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123269,
  "isBulkOperation": true
}

Expected Output: 7 test case runs updated to Not Run status successfully for re-execution

4. Update test case run with build/drop information

{
  "entityIDs": "66095087",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123266,
  "dropID": 947,
  "isBulkOperation": false
}

Expected Output: Test case run updated with execution status and build information

5. Update automated test execution status with automation flag

{
  "entityIDs": "66095069,66095075",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123268,
  "isAutoExecuted": "1",
  "isBulkOperation": true,
  "comments": "Automated test execution completed"
}

Expected Output: Automated test case runs updated to Pass status with automation flag

6. Update test case run status with Part 11 Compliance authentication

{
  "entityIDs": "66095087",
  "entityType": "TCR",
  "qmTsRunId": "2720260",
  "runStatusID": 123266,
  "username": "test.user",
  "password": "password",
  "isBulkOperation": false
}

Expected Output: Test case run status updated with Part 11 Compliance authentication

7. Update ALL executions of test suite VKMC-TS-20 to Failed (MULTI-CALL OPERATION)

{
  "entityIDs": "66341841,66342887,66342893,66342899",
  "entityType": "TCR",
  "qmTsRunId": "2733104",
  "runStatusID": 123269,
  "isBulkOperation": true
}

Expected Output: Execution 1/4 updated. The MCP Agent will automatically repeat this operation for executions 2733205, 2733306, and 2733407 using their corresponding entityIDs.

Hints: 1. CRITICAL: entityIDs, entityType, qmTsRunId, and runStatusID are REQUIRED parameters 2. 3. CRITICAL - ALWAYS FETCH STATUS IDs FROM PROJECT INFO: 4. NEVER use hardcoded or memorized status IDs. Status IDs are PROJECT-SPECIFIC and must be fetched dynamically. 5. MANDATORY WORKFLOW BEFORE USING runStatusID: 6. 1. Call mcp_smartbear_qmetry_fetch_qmetry_project_info with the current projectKey 7. 2. Extract the 'allstatus' array from the response 8. 3. Match the desired status NAME to find its corresponding ID 9. 4. Use the fetched ID in the runStatusID parameter 10. 11. EXAMPLE STATUS ID RESOLUTION: 12. User says: 'Update status to Failed' 13. Step 1: Call FETCH_PROJECT_INFO → Get allstatus array 14. Step 2: Find status where name='Failed' → Extract its id property 15. Step 3: Use that id as runStatusID (e.g., 123269 for 'Failed') 16. 17. COMMON STATUS NAMES (IDs vary by project - MUST VALIDATE): 18. - 'Passed' / 'Pass' - Test case executed successfully 19. - 'Failed' / 'Fail' - Test case failed with errors 20. - 'Blocked' - Test case cannot be executed due to blockers 21. - 'Not Run' - Test case not yet executed or needs re-execution 22. - 'WIP' / 'Work In Progress' - Test case execution in progress 23. - 'Not Applicable' - Test case not applicable for this execution 24. 25. WHY THIS IS CRITICAL: 26. - Status IDs are assigned per QMetry project and are NOT universal 27. - Using wrong status ID will update tests with incorrect status 28. - Example: ID 123268 might be 'Blocked' in one project but 'Passed' in another 29. - The allstatus array is the AUTHORITATIVE source for all status mappings 30. 31. HOW TO GET entityIDs (Test Case Run IDs): 32. 1. Call API 'Execution/Fetch Testcase Run ID' (FETCH_TESTCASE_RUNS_BY_TESTSUITE_RUN tool) 33. 2. From the response, get value of following attribute -> data[].tcRunID 34. 3. Example: Single ID '66095087' or Multiple IDs '66095069,66095075,66095081' 35. 4. For bulk operations, provide comma-separated IDs without spaces 36. HOW TO GET qmTsRunId (Test Suite Run ID): 37. 1. Call API 'Execution/Fetch Executions' (FETCH_EXECUTIONS_BY_TESTSUITE tool) 38. 2. From the response, get value of following attribute -> data[].tsRunID 39. 3. Example: Test Suite Run ID might be '2720260' 40. HOW TO GET runStatusID (Execution Status ID) - DETAILED PROCESS: 41. 1. Call API 'Admin/Get info Service' (FETCH_PROJECT_INFO tool) with projectKey 42. 2. From the response, locate the 'allstatus' array 43. 3. Search for the status object where name matches your desired status (case-insensitive) 44. 4. Extract the 'id' property from the matching status object 45. 5. NEVER use example IDs from documentation - they are project-specific 46. 47. EXAMPLE allstatus ARRAY STRUCTURE: 48. allstatus: [ 49. { name: 'Passed', defaultName: 'passed', id: 123266, color: '#14892C|#FFFFFF' }, 50. { name: 'Failed', defaultName: 'failed', id: 123269, color: '#FF6666|#FFFFFF' }, 51. { name: 'Blocked', defaultName: 'blocked', id: 123268, color: '#CCCCCC|#FFFFFF' }, 52. { name: 'Not Run', defaultName: 'notrun', id: 123270, color: '#205081|#FFFFFF', isdefault: true }, 53. { name: 'Not Applicable', defaultName: 'empty', id: 123267, color: '#59AFE1|#FFFFFF' } 54. ] 55. Note: Above IDs are EXAMPLES ONLY - fetch actual IDs from your project 56. HOW TO GET dropID (Build/Drop ID) - OPTIONAL: 57. 1. Call API 'Build/List' (FETCH_BUILDS tool) 58. 2. From the response, get value of following attribute -> data[].dropID 59. 3. Example: Build/Drop ID might be 947 60. ENTITY TYPES: 61. - 'TCR' = Test Case Run (most common use case) 62. - 'TCSR' = Test Case Step Run (for step-level execution updates) 63. BULK OPERATION FLAG: 64. - isBulkOperation=false: Single test case run update (one entityID) 65. - isBulkOperation=true: Multiple test case runs update (comma-separated entityIDs) 66. - Auto-detected: If entityIDs contains comma, defaults to true; otherwise false 67. AUTOMATION FLAG (isAutoExecuted) - OPTIONAL: 68. - '1' = Automated execution (test run by automation framework) 69. - '0' = Manual execution (test run by human tester) 70. - Used for execution tracking and reporting purposes 71. PART 11 COMPLIANCE (username & password) - CONDITIONAL: 72. - Required ONLY if Part 11 Compliance is active in your QMetry instance 73. - Used for regulatory compliance and audit trail purposes 74. - Not needed for standard QMetry installations 75. COMMENTS FIELD - OPTIONAL: 76. - Add execution notes, failure reasons, or status change context 77. - Useful for tracking why status was changed 78. - Appears in execution history and audit logs 79. COMMON EXECUTION STATUS NAMES: 80. - Pass: Test case executed successfully 81. - Fail: Test case failed with errors 82. - Blocked: Test case cannot be executed due to blockers 83. - Not Run: Test case not yet executed or needs re-execution 84. - WIP: Work In Progress - test case execution in progress 85. WORKFLOW FOR USER PROMPTS: 86. 1. If user says 'execute test case run by id to failed' or 'update status to fail': 87. - Fetch test case runs to get tcRunID (entityIDs) 88. - Fetch project info to get 'Fail' status ID (runStatusID) 89. - Set isBulkOperation=false for single ID 90. 2. If user says 'bulk update test case run status to pass' or 'update all to passed': 91. - Fetch test case runs to get multiple tcRunIDs 92. - Fetch project info to get 'Pass' status ID 93. - Set isBulkOperation=true 94. - Join multiple IDs with commas (no spaces) 95. 3. If user says 'execute status to not run of given test case run ids': 96. - Use provided IDs or fetch if needed 97. - Fetch project info to get 'Not Run' status ID 98. - Set isBulkOperation based on ID count 99. 4. If the user requests updating status for ALL executions of a test suite, the agent must: 100. 1. Call FETCH_EXECUTIONS_BY_TESTSUITE to get all qmTsRunIds. 101. 2. For each qmTsRunId: 102. - Call FETCH_TESTCASE_RUNS_BY_TESTSUITE_RUN to get tcRunID (entityIDs) 103. - Fetch project info to get 'Fail' status ID (runStatusID) 104. - Call BULK_UPDATE_EXECUTION_STATUS with the corresponding qmTsRunId + tcRunID + desired runStatusID 105. 3. Repeat until all executions are updated. 106. This tool is intended to be invoked multiple times in sequence for multi-execution updates. 107. FIELD MAPPING CRITICAL NOTES: 108. - entityIDs must be comma-separated STRING (e.g., '66095069,66095075') 109. - qmTsRunId must be STRING format (e.g., '2720260') 110. - runStatusID must be NUMERIC (e.g., 123268) 111. - dropID can be numeric or string (flexible) 112. API ENDPOINT: PUT /rest/execution/runstatus/bulkupdate 113. This tool is essential for test execution management and status tracking 114. Critical for maintaining accurate test execution records and reporting 115. Use for manual test execution updates and automated test result integration 116. Essential for test execution audit trails and compliance requirements

Fetch full detail data for a QMetry test suite including UDF field values

Toolset: Test Suites

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• id (number) required: Test Suite ID (numeric ID)

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

Output Description: JSON object with full test suite details including UDFTypeData map and all UDF field values

Use Cases: 1. Get UDF field values for a specific test suite 2. Retrieve full test suite metadata including custom fields 3. Inspect test suite details before updating UDF values

Examples:

1. Fetch details for test suite with ID 142013

{
  "id": 142013
}

Expected Output: Full test suite detail object with UDFTypeData, UDF field values, and metadata

Create a new defect/issue internally in QMetry.

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• 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.

Update an existing QMetry issue by DefectId and/or entityKey.

Toolset: Issues

Parameters:

• DefectId (number) required: ID of the defect/issue to be updated. CRITICAL: the parameter name is 'DefectId' (capital D) — do NOT use 'defectId', 'issueId', 'id', or other variants. Accepts a string or number.

• entityKey (string): Entity Key of the defect/issue to be updated

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

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

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

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

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

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

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

• 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.

• UDF (record<string, object>): UDF wrapper required for update. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value.

Output Description: JSON object with update status and details.

Use Cases: 1. Update issue summary (title) 2. Change issue priority, type, or owner 3. Update affected release or cycles 4. Update description or environment 5. Bulk update using DefectId and/or entityKey

Examples:

1. Update issue summary

{
  "DefectId": 118150,
  "summary": "Money withdrawal is success even if insufficient amount_updated"
}

Expected Output: Issue summary updated successfully.

2. Update issue priority

{
  "DefectId": 118150,
  "issuePriority": 189340
}

Expected Output: Issue priority updated successfully.

3. Update issue type

{
  "DefectId": 118150,
  "issueType": 189337
}

Expected Output: Issue type updated successfully.

4. Update affected release

{
  "DefectId": 118150,
  "affectedRelease": 3730
}

Expected Output: Affected release updated successfully.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. ALWAYS call 'Fetch UDF Layout' with entityType='IS', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout, i.e. qmDefaultValue.IS): { fieldName: defaultValueId } — sweep ALL entries. 4. defaultValues can contain BOTH system field defaults AND UDF field defaults — handle each differently: 5. → SYSTEM field defaults (fields in qmSDF.IS, e.g. component/Labels, issueType, issuePriority): route to TOP-LEVEL params, NOT to udfFields. 6. - MULTILOOKUPLIST system fields (e.g. component): default is a single ID — wrap in array: component: [5232632]. 7. - LOOKUPLIST system fields (e.g. issueType, issuePriority): default is a single ID — use directly. 8. → UDF field defaults (fields in qmUDF.IS, e.g. str1, lookup19, age19): route to udfFields param. 9. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload using default, routed correctly. 10. This applies to non-mandatory fields too (e.g. component/Labels). Omitting them = data loss. 11. IMPORTANT: QMetry's API sometimes returns 'defaultValues: {}' (empty) — if so, skip auto-apply and ask user for mandatory fields without defaults. 12. systemFields (from qmSDF.IS): isMandatory=true fields must retain a valid value after update. 13. IMPORTANT: QMetry's API sometimes returns 'systemFields: []' (empty). If so, treat summary, issueType, issuePriority as always mandatory. 14. fields/UDF (from qmUDF.IS): isMandatory=true UDF fields must be included if being changed. 15. === END DEFAULT VALUES === 16. 17. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 18. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 19. 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). 20. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 21. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 22. 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/...). 23. 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' 24. 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. 25. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 26. === END DATE FORMAT CHECK === 27. 28. To get the DefectId, call the Issue/Fetch issue tool and use data[].id from the response. 29. if you have pass issue key (VT-IS-5, MAC-IS-10 etc.) then first fetch issue by issue key to get issue id. 30. Along with DefectId, pass only those fields which are to be updated. 31. Refer to the Create Issue tool for valid field mappings and values. 32. You can update summary, priority, type, affectedRelease, affectedCycles, description, sync_with, issueOwner, component, environment, tcRunID, etc. 33. If you provide entityKey, it will be used for additional validation but DefectId is required. 34. 35. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 36. 1. Call 'Fetch UDF Layout' with entityType='IS', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 37. 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. 38. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 39. 3. For MULTILOOKUPLIST fields: pick array of IDs; also pass alias flat key (e.g., fieldNameAlias: 'Option Label'). 40. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 41. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 42. Example: udfFields: { is_field: 'value' }, UDF: { is_field: { fieldID: 3001, value: 'value' } } 43. 6. Mandatory UDF fields (isMandatory=true) MUST be included.

Fetch QMetry defects or issues - automatically handles viewId resolution based on project

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• viewId (number): ViewId for issues - SYSTEM AUTOMATICALLY RESOLVES THIS. Leave empty unless you have a specific viewId. System will fetch project info using the projectKey and extract latestViews.IS.viewId automatically. Manual viewId only needed if you want to override the automatic resolution.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

• isJiraIntegrated (boolean): Send true if current project is Integrated with Jira (default: false)

• sort (string): Sort Records - refer json schema, Possible property - entityKey, name, typeAlias, stateAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, priorityAlias, createdSystem, linkedTcrCount, linkedRqCount, dfOwner, attachmentCount, environmentText (default: "[{"property":"name","direction":"ASC"}]")

Output Description: JSON object with 'data' array containing issues. Each issue has 'id' (numeric defect ID — use this as defectId for Fetch Issue Details), 'entityKey', 'name'/'summary', and other fields. There is no 'DefectId' field in this response — 'id' is the defect identifier.

Use Cases: 1. List all issues in a project 2. Search for specific issues using filters 3. Get paginated issue results

Examples:

1. Get all issues from default project - system will auto-fetch viewId

{}

Expected Output: List of issues from default project with auto-resolved viewId

2. Get all issues from UT project - system will auto-fetch UT project's viewId

{
  "projectKey": "UT"
}

Expected Output: List of issues from UT project using UT's specific IS viewId

3. Get issues with manual viewId (skip auto-resolution)

{
  "projectKey": "MAC",
  "viewId": 166065
}

Expected Output: Issues using manually specified viewId 166065

4. List issues from specific project (ex: project key can be anything (VT, UT, PROJ1, TEST9)

{
  "projectKey": "use specific given project key",
  "viewId": "fetch specific project given projectKey defects or issues ViewId"
}

Expected Output: Issues using manually specified viewId 103097 or projectKey

5. Get issues by release/cycle filter

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"},{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: Issues associated with Release 8.12 (ID: 55178) and Cycle 8.12.1 (ID: 111577)

6. Get issues by release only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[55178],\"type\":\"list\",\"field\":\"release\"}]"
}

Expected Output: All defects or issues associated with Release 8.12 (ID: 55178)

7. Get issues by cycle only

{
  "projectKey": "MAC",
  "filter": "[{\"value\":[111577],\"type\":\"list\",\"field\":\"cycle\"}]"
}

Expected Output: All defects or issues associated with Cycle 8.12.1 (ID: 111577)

8. Search for specific issue by entity key

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-IS-636\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Issues matching the entity key criteria

9. Search for multiple defects or issues by comma-separated entity keys

{
  "projectKey": "MAC",
  "filter": "[{\"type\":\"string\",\"value\":\"MAC-IS-636,MAC-IS-637,MAC-IS-638\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Issues matching any of the specified entity keys

Hints: 1. CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and issues fetching 2. Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info 3. Step 2: Get project info using that projectKey, extract latestViews.IS.viewId 4. Step 3: Use the SAME projectKey and the extracted IS viewId for fetching issues 5. Step 4: If user doesn't specify projectKey, use 'default' for both project info and issues fetching 6. NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything 7. For search by issues key (like MAC-IS-1684), use filter: '[{"type":"string","value":"MAC-IS-1684","field":"entityKeyId"}]' 8. RELEASE/CYCLE FILTERING: Use release and cycle IDs, not names, for filtering 9. For release filter: '[{"value":[releaseId],"type":"list","field":"release"}]' 10. For cycle filter: '[{"value":[cycleId],"type":"list","field":"cycle"}]' 11. For combined release+cycle: '[{"value":[releaseId],"type":"list","field":"release"},{"value":[cycleId],"type":"list","field":"cycle"}]' 12. Get release/cycle IDs from FETCH_RELEASES_AND_CYCLES tool before filtering 13. FILTER FIELDS: name, stateAlias, typeAlias, entityKeyId, createdDate, createdByAlias, updatedDate, updatedByAlias, createdSystem, dfOwner, priorityAlias, linkedTcrCount, linkedRqCount, attachmentCount, componentAlias, environmentText 14. SORT FIELDS: entityKey, name, typeAlias, stateAlias, createdDate, createdByAlias, updatedDate, updatedByAlias, priorityAlias, createdSystem, linkedTcrCount, linkedRqCount, dfOwner, attachmentCount, environmentText 15. For multiple entity keys, use comma-separated values in filter 16. Use pagination for large result sets (start, page, limit parameters) 17. This tool is essential for defect management and issue tracking 18. Critical for quality assurance and defect lifecycle analysis 19. Use for compliance reporting and issue traceability 20. Helps maintain visibility into project defects and issues

Get issues that are linked (or not linked) to a specific test case run in QMetry

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• entityId (number) required: Id of Test case run (required for fetching linked issues). CRITICAL: the parameter name is 'entityId' — do NOT use 'tcRunId', 'testCaseRunId', 'runId', or other variants. Accepts a string or number. NOTE: To get the entityId - Call API 'Execution/Fetch Testcase Run ID' From the response, get value of following attribute -> data[].tcRunID

• getLinked (boolean): True to get only those issues that are linked with this Test case Run, False to get those issues which are not linked with this Test case Run. Default value true (get linked issues). (default: true)

• getColumns (boolean): Whether to get column information in response. (default: true)

• istcrFlag (boolean): Set True for test case run operations (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with issues array containing issue details, priorities, status, owner information, and linkage metadata

Use Cases: 1. Get all issues linked to a specific test case run for defect tracking 2. Find issues that are NOT linked to a test case run (gap analysis) 3. Generate defect reports and traceability matrix for test case runs 4. Monitor issue resolution progress for specific test case executions 5. Analyze test execution quality by examining linked defects 6. Filter issues by type, priority, status, or owner for test case runs 7. Audit issue-test case run relationships for compliance 8. Track defect lifecycle in relation to test execution results 9. Quality assurance - ensure proper issue tracking for failed test runs 10. Impact analysis - see which issues affect specific test executions

Examples:

1. Get all issues linked to test case run ID 1121218

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": true
}

Expected Output: List of issues linked to the test case run with issue details, status, and metadata

2. Get issues NOT linked to test case run (gap analysis)

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": false
}

Expected Output: List of issues that are NOT linked to test case run for gap analysis

3. Filter linked issues by issue type and status

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": true,
  "filter": "[{\"type\":\"list\",\"value\":[1],\"field\":\"typeAlias\"},{\"type\":\"list\",\"value\":[1,2],\"field\":\"stateAlias\"}]"
}

Expected Output: Bug type issues in Open or In Progress status

4. Search linked issues by name and priority

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": true,
  "filter": "[{\"type\":\"string\",\"value\":\"login\",\"field\":\"name\"},{\"type\":\"list\",\"value\":[1],\"field\":\"priorityAlias\"}]"
}

Expected Output: High priority issues containing 'login' in their name

5. Filter issues by date range and entity key

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": true,
  "filter": "[{\"value\":\"2024-01-01\",\"type\":\"date\",\"field\":\"createdDate\",\"comparison\":\"gt\"},{\"value\":\"2024-12-31\",\"type\":\"date\",\"field\":\"createdDate\",\"comparison\":\"lt\"},{\"type\":\"string\",\"value\":\"BUG-001,BUG-002\",\"field\":\"entityKeyId\"}]"
}

Expected Output: Specific issues created within date range

6. Filter issues by owner and created system

{
  "entityId": 1121218,
  "getColumns": true,
  "getLinked": true,
  "filter": "[{\"type\":\"list\",\"value\":[123],\"field\":\"dfOwner\"},{\"type\":\"list\",\"value\":[\"QMetry\"],\"field\":\"createdSystem\"}]"
}

Expected Output: Issues owned by specific user and created in QMetry

Hints: 1. WORKFLOW CRITICAL: NEVER use user-provided IDs directly as entityId! 2. ALWAYS fetch execution data first to get proper tcRunID values! 3. 4. WHEN USER ASKS: 'fetch linked issues of test suite [ID]' OR 'linked issues of test run [ID]': 5. STEP 1: Identify what type of ID the user provided 6. STEP 2A: If Test Suite ID → fetch executions by test suite → get tsRunID → fetch test runs → get tcRunID 7. STEP 2B: If Test Run ID → fetch test case runs by test suite run → get tcRunID 8. STEP 2C: If Test Case ID → fetch test case executions → get tcRunID 9. STEP 3: Use tcRunID as entityId for this tool 10. 11. ID HIERARCHY: Test Suite → Test Suite Runs → Test Case Runs (tcRunID = entityId) 12. ID HIERARCHY: Test Case → Test Case Executions (tcRunID = entityId) 13. 14. CRITICAL: entityId parameter is REQUIRED - this is the Test Case Run numeric ID (tcRunID) 15. HOW TO GET entityId: 16. 1. Call appropriate execution APIs to get test case runs 17. 2. From the response, extract data[].tcRunID 18. 3. Use tcRunID as entityId for this tool 19. 4. Example: tcRunID 1121218 becomes entityId: 1121218 20. 21. getLinked=true (default): Returns issues that ARE linked to the test case run 22. getLinked=false: Returns issues that are NOT linked to the test case run (useful for gap analysis) 23. istcrFlag=true (default): Set to true for test case run operations 24. getColumns=true (default): Include column metadata in response 25. 26. FILTER CAPABILITIES: Support extensive filtering by issue properties 27. FILTER FIELDS: name (string), typeAlias (list), stateAlias (list), entityKeyId (string), createdDate (date with comparison), createdByAlias (list), updatedDate (date with comparison), createdSystem (list), updatedByAlias (list), dfOwner (list), priorityAlias (list), linkedTcrCount (numeric), linkedRqCount (numeric), attachmentCount (numeric), componentAlias (list), environmentText (string), affectedRelease (list) 28. ISSUE TYPE IDs: Typically 1=Bug, 2=Enhancement, 3=Task (verify with your QMetry instance) 29. ISSUE STATE IDs: Typically 1=Open, 2=In Progress, 3=Resolved, 4=Closed (verify with your QMetry instance) 30. ISSUE PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 31. DATE FILTERING: Use 'gt' (greater than) and 'lt' (less than) comparisons for date fields 32. ENTITY KEY SEARCH: Use comma-separated values for multiple issue keys 33. CREATED SYSTEM: Use 'QMetry' or 'JIRA' to filter by creation system 34. OWNER IDs: Use numeric user IDs from QMetry user management 35. COMPONENT/LABEL IDs: Use numeric IDs for component/label filtering 36. ENVIRONMENT TEXT: Filter by environment description text 37. AFFECTED RELEASE: Use release IDs for filtering by affected releases 38. LINKED COUNT FILTERS: Use numeric values for linkedTcrCount, linkedRqCount, attachmentCount 39. Multiple filter conditions are combined with AND logic 40. Use pagination for large result sets (start, page, limit parameters) 41. This tool is essential for defect tracking and traceability audits 42. Critical for understanding test execution quality and issue relationships 43. Use for compliance reporting and issue lifecycle management 44. Helps establish relationships between test failures and reported issues 45. Essential for impact analysis when test case runs change or fail

Link one or more issues to a QMetry Testcase Run (execution).

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• issueIds (array) required: ID of issues to be linked to Testcase Run

• tcrId (number) required: ID of Testcase Run to link issues with. CRITICAL: parameter name is 'tcrId' — do NOT use 'tcRunId', 'testCaseRunId', or other variants. Accepts a string or number.

Output Description: JSON object with linkage status and details.

Use Cases: 1. Link a single issue to a testcase run 2. Link multiple issues to a testcase run 3. Automate defect association during test execution 4. Maintain traceability between defects and test runs

Examples:

1. Link one issue to a testcase run

{
  "issueIds": [
    "5054834"
  ],
  "tcrId": 567890
}

Expected Output: Issue 5054834 linked to testcase run 567890 successfully.

2. Link multiple issues to a testcase run

{
  "issueIds": [
    "5054834",
    "5054835"
  ],
  "tcrId": 567890
}

Expected Output: Issues 5054834, 5054835 linked to testcase run 567890 successfully.

Hints: 1. if you have pass issue key (VT-IS-5, MAC-IS-10 etc.) then first fetch issue by issue key to get issue id. 2. To get the issueIds, call the Fetch issues linked with testcases tool and use data[].defectID from the response. 3. To get the tcrId, call the Execution/Fetch Testcase Run ID tool and use data[].tcRunID from the response. 4. Both issueIds and tcrId are required. 5. You can link multiple issues at once by providing an array of IDs.

Get test case executions linked to a QMetry-native (non-Jira) defect/issue. ALWAYS present results as a unified table: Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label columns…>. NEVER show a separate type+value UDF breakdown — always combine identification fields and UDF values in one table per execution row.

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• linkedAssetId (number) required: Numeric defect ID of the QMetry issue. CRITICAL: parameter name is 'linkedAssetId' — do NOT use 'issueId', 'defectId', 'id', or other variants. Accepts a string or number. To get this ID, call the Fetch Defects or Issues tool and use data[].id from the response.

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• platformID (string): Platform ID to filter executions by environment/platform

• filter (string): JSON filter string. Supported fields: tcName (string), linkageLevel (string), executedVersion (string), runStatusName (list of status names), platformID (list of numeric IDs), executionCreatedByLoginAlias (list of usernames), isTestSuiteArchived (list: [1] active, [0] archived, [1,0] both). Example: '[{"type":"string","value":"login","field":"tcName"}]' (default: "[]")

Output Description: JSON object with 'data' array of execution records, 'hasTcRunUdf' boolean flag, and 'total' count. Each execution record ALWAYS contains these mandatory identification fields: 'tsEntityKey' (Test Suite Key, e.g. 'MAC-TS-42'), 'tsName' (Test Suite Name), 'releaseName' (Release), 'cycleName' (Cycle), 'platformName' (Platform/environment), 'executedVersion' (Executed Version of the test case), 'runStatusName' (Execution Status label), 'tcRunID' (numeric Test Run ID), 'tcName' (Test Case Name), 'tcEntityKey' (Test Case Key), and 'testRunUdfs' (array of objects each with name, label, fieldID, fieldType, value — use 'label' for display headers, null if not set). For LOOKUPLIST and MULTILOOKUPLIST fields, 'value' contains the resolved human-readable display name (from qmUDFList), not the raw internal uniqueLabel key. ALL project-defined UDF fields are always included, even those with no value. When hasTcRunUdf is false, a 'testRunUdfNote' field provides a professional explanation instead.

Use Cases: 1. Get all test executions linked to a specific defect 2. Audit which test cases were run against a given issue 3. Filter executions by run status (failed, passed, etc.) for an issue 4. Filter executions by platform/environment for an issue 5. Filter executions by tester/executor for an issue 6. Show archived and active test suite executions for an issue 7. View UDF (custom field) values on executions linked to an issue 8. Track test coverage and execution progress for a defect

Examples:

1. Get all executions linked to issue ID 9598240

{
  "linkedAssetId": 9598240
}

Expected Output: Present as ONE unified table — never as a separate type+value UDF breakdown. Example: | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | | MAC-TS-42 | Regression Suite | R1 | Sprint1 | Chrome | 1 | Failed | varis | chrome, edge, safari | Functional | | MAC-TS-43 | Login Suite | R1 | Sprint1 | Firefox | 2 | Blocked | john | firefox | Regression | Columns in order: Test Suite Key (tsEntityKey) | Test Suite Name (tsName) | Release (releaseName) | Cycle (cycleName) | Platform (platformName) | Executed Version (executedVersion) | Execution Status (runStatusName) | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

2. Get executions with pagination (page 1, 20 records)

{
  "linkedAssetId": 9598240,
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: First 20 executions linked to the issue

3. Filter executions by run status (failed or passed)

{
  "linkedAssetId": 9509016,
  "filter": "[{\"type\":\"list\",\"field\":\"runStatusName\",\"value\":[\"failed\",\"passed\"]}]",
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: Executions with failed or passed status for the issue

4. Filter executions by test case name

{
  "linkedAssetId": 9509016,
  "filter": "[{\"type\":\"string\",\"value\":\"login\",\"field\":\"tcName\"}]",
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: Executions where test case name contains 'login'

5. Filter by platform, status, and tester

{
  "linkedAssetId": 9509016,
  "filter": "[{\"type\":\"list\",\"field\":\"runStatusName\",\"value\":[\"failed\"]},{\"type\":\"list\",\"field\":\"platformID\",\"value\":[100145]},{\"type\":\"list\",\"field\":\"executionCreatedByLoginAlias\",\"value\":[\"Varis Khan\"]}]",
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: Failed executions on platform 100145 created by Varis Khan

6. Filter by status and include archived test suite executions

{
  "linkedAssetId": 9509016,
  "filter": "[{\"type\":\"list\",\"field\":\"runStatusName\",\"value\":[\"failed\",\"passed\"]},{\"value\":[1,0],\"type\":\"list\",\"field\":\"isTestSuiteArchived\"}]",
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: Executions with failed/passed status including archived test suites

7. Filter by execution version and linkage level

{
  "linkedAssetId": 9509016,
  "filter": "[{\"type\":\"string\",\"value\":\"1\",\"field\":\"executedVersion\"},{\"type\":\"string\",\"value\":\"Test Case\",\"field\":\"linkageLevel\"}]",
  "page": 1,
  "start": 0,
  "limit": 20
}

Expected Output: Executions at Test Case linkage level for version 1

Hints: 1. === MANDATORY RESPONSE FORMAT — READ THIS BEFORE RENDERING ANY OUTPUT === 2. 3. PIVOT RULE — CRITICAL: 4. The 'testRunUdfs' field on each execution is an array of { name, label, fieldID, fieldType, value }. 5. You MUST pivot this array into TABLE COLUMNS — do NOT render it as rows. 6. → Each testRunUdfs[i].label = a column header in the unified table 7. → Each testRunUdfs[i].value = the cell value for that execution's row 8. → testRunUdfs[i].fieldType = INTERNAL METADATA — NEVER show this as a column 9. → testRunUdfs[i].fieldID = INTERNAL METADATA — NEVER show this as a column 10. 11. FORBIDDEN PATTERNS — NEVER do any of these: 12. ❌ Do NOT render a separate sub-table (UDF Label | Type | Value) per execution 13. ❌ Do NOT show 'Type' or 'fieldType' as a visible column 14. ❌ Do NOT group output by tcRunID with individual breakdowns beneath each 15. ❌ Do NOT show raw UDF field keys (e.g. 'TRString', '8260LUP') as headers — use 'label' 16. 17. REQUIRED OUTPUT — ONE unified table, all executions as rows: 18. | Test Suite Key | Test Suite Name | Release | Cycle | Platform | Executed Version | Execution Status | <UDF Label 1> | <UDF Label 2> | ... | 19. |----------------|-----------------|---------|-------|----------|------------------|------------------|---------------|---------------|-----| 20. | MAC-TS-42 | Login Suite | R1 | S1 | Chrome | v1 | Failed | varis | chrome, edge | ... | 21. 22. MANDATORY COLUMNS (always first, in this order): 23. 1. Test Suite Key → tsEntityKey (e.g. 'MAC-TS-42') 24. 2. Test Suite Name → tsName (test suite display name) 25. 3. Release → releaseName 26. 4. Cycle → cycleName 27. 5. Platform → platformName 28. 6. Executed Version → executedVersion 29. 7. Execution Status → runStatusName 30. 8. Tested By → executionCreatedByLoginAlias/testedBy when present 31. 9+. One column per UDF field — use testRunUdfs[i].label as header, testRunUdfs[i].value as cell. 32. 33. Null UDF values → show as '-'. If hasTcRunUdf is false, show columns 1-8 only. 34. ISSUE EXECUTION UDF SOURCE — CRITICAL: 35. Do NOT call 'Fetch Test Run UDF Values' for issue execution UDFs. 36. Do NOT create or use another issue-specific UDF fetch tool. 37. Use this tool's response directly: it calls /rest/execution/getExecutionsForIssue for execution rows, parses each row's udfjson for saved UDF values, and uses Test Run UDF metadata to include all configured UDF labels with null/empty values. 38. === END MANDATORY RESPONSE FORMAT === 39. 40. CRITICAL: linkedAssetId is REQUIRED - this is the numeric defect ID from QMetry (not entity key like VKT-IS-5) 41. HOW TO GET linkedAssetId: Call Fetch Defects or Issues tool → use data[].id from the response 42. AUTO-RESOLVE: If user provides an issue entity key (e.g. VKT-IS-5, MAC-IS-10), first call Fetch Defects or Issues with that entity key as filter, extract data[].id, then use it as linkedAssetId 43. AUTO-RESOLVE FILTER EXAMPLE: to resolve VKT-IS-5 → use filter '[{"type":"string","value":"VKT-IS-5","field":"entityKeyId"}]' in Fetch Defects or Issues tool 44. This tool supports QMetry-native issues only — do NOT use for Jira-integrated projects 45. API SOURCE: Execution rows and saved UDF values come from /rest/execution/getExecutionsForIssue. The udfjson field contains saved Test Run UDF values, e.g. Tested_By, execution_type, Country_mcp_udf, environments_udf. 46. METADATA SOURCE: This tool also calls Test Run UDF metadata once to get all available labels, fieldIDs, field types, list options (qmUDFList), and empty fields. Merge metadata fields with udfjson values by UDF name. 47. RESPONSE FIELDS: hasTcRunUdf=true means executions have UDF data; each execution includes a 'testRunUdfs' array with ALL project-defined UDF fields 48. ALL UDF FIELDS: ALL project-defined Test Run UDF fields are returned for every execution — including fields not yet set (value: null) 49. Each element in testRunUdfs: { name, label, fieldID, fieldType, value } — use fieldID when calling 'Bulk Update Test Run UDFs' 50. VALUE RESOLUTION: For LOOKUPLIST and MULTILOOKUPLIST fields, values are resolved from their internal uniqueLabel key to the human-readable display name using qmUDFList lookup options. Always display the resolved name, not the raw uniqueLabel. 51. EXAMPLE testRunUdfs: [{ "name": "TRString", "label": "TR String", "fieldID": 229241, "fieldType": "STRING", "value": "test" }, { "name": "lookup_browser", "label": "Lookup Browser MCP", "fieldID": 229433, "fieldType": "LOOKUPLIST", "value": "Chrome" }, { "name": "dateField", "label": "Date", "fieldID": 229255, "fieldType": "DATETIMEPICKER", "value": null }] 52. FILTER FIELDS: 53. - tcName (string): filter by test case name substring 54. - linkageLevel (string): 'Test Case' or 'Test Step' 55. - executedVersion (string): version number as string e.g. '1' 56. - runStatusName (list): e.g. ["failed","passed","in progress"] 57. - platformID (list): numeric platform IDs e.g. [100145]. Get from FETCH_PLATFORMS tool 58. - executionCreatedByLoginAlias (list): usernames/login aliases e.g. ["john.doe"] 59. - isTestSuiteArchived (list): [1] active only, [0] archived only, [1,0] both 60. FILTER FORMAT: JSON string array — '[{"type":"list","field":"runStatusName","value":["failed"]}]' 61. Multiple filter conditions are combined with AND logic 62. Use pagination (page, start, limit) for large result sets 63. Get platform IDs using the FETCH_PLATFORMS tool before filtering by platformID 64. Execution status names are case-sensitive — use lowercase: 'failed', 'passed', 'in progress', 'blocked', 'not run' 65. hasTcRunUdf: false → No Test Run UDFs configured; testRunUdfs will not appear; a 'testRunUdfNote' field explains this.

Get issues that are linked (or not linked) to a specific test case in QMetry

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• getLinked (boolean): True to get only those issues that are linked with this Test case Run, False to get those issues which are not linked with this Test case Run. Default value true (get linked issues). (default: true)

• start (number): Start index for pagination - defaults to 0 (default: 0)

• page (number): Page number to return (starts from 1) (default: 1)

• limit (number): Number of records (default 10). (default: 10)

• filter (string): Filter criteria as JSON string (default '[]') (default: "[]")

Output Description: JSON object with issues array containing issue details, priorities, status, and linkage information

Use Cases: 1. Get all issues linked to a specific test case for defect tracking 2. Find issues that are NOT linked to a test case (gap analysis) 3. Generate traceability reports between test cases and issues 4. Filter issues by type, priority, status, or owner 5. Monitor issue resolution progress for specific test cases 6. Audit issue-test case relationships for compliance 7. Filter issues by summary content or execution version 8. Get issue details for test execution planning 9. Track linkage level (Test Case vs Test Step level) 10. Quality assurance - ensure proper issue tracking

Examples:

1. Get all issues linked to test case ID 4495658 (default behavior)

{
  "tcID": 4495658
}

Expected Output: List of issues linked to the test case with issue details, status, and metadata

2. Get all issues linked to test case ID 4495658 (explicit)

{
  "tcID": 4495658,
  "getLinked": true
}

Expected Output: List of issues linked to the test case with issue details, status, and metadata

3. Get issues NOT linked to test case (gap analysis)

{
  "tcID": 4495658,
  "getLinked": false
}

Expected Output: List of issues that are NOT linked to the test case

4. Get linked issues with pagination

{
  "tcID": 4495658,
  "getLinked": true,
  "limit": 25,
  "page": 1
}

Expected Output: Paginated list of issues linked to the test case

5. Filter linked issues by summary content (using default getLinked=true)

{
  "tcID": 4495658,
  "filter": "[{\"value\":\"login\",\"type\":\"string\",\"field\":\"summary\"}]"
}

Expected Output: Issues linked to test case that contain 'login' in their summary

6. Filter linked issues by status and priority

{
  "tcID": 4495658,
  "getLinked": true,
  "filter": "[{\"value\":[1,2],\"type\":\"list\",\"field\":\"issueState\"},{\"value\":[1],\"type\":\"list\",\"field\":\"issuePriority\"}]"
}

Expected Output: High priority issues in Open or In Progress status

7. Filter issues by execution version

{
  "tcID": 4495658,
  "getLinked": true,
  "filter": "[{\"value\":\"2\",\"type\":\"string\",\"field\":\"executedVersion\"}]"
}

Expected Output: Issues linked to version 2 of the test case execution

Hints: 1. CRITICAL: tcID parameter is REQUIRED - this is the Test Case numeric ID 2. getLinked parameter is OPTIONAL - defaults to true if not provided 3. HOW TO GET tcID: 4. 1. Call FETCH_TEST_CASES with filter on entityKeyId to resolve test case key to numeric ID 5. 2. From response, use data[index].tcID field 6. 3. Example: MAC-TC-1684 → tcID: 4495658 7. getLinked=true (default): Returns issues that ARE linked to the test case 8. getLinked=false: Returns issues that are NOT linked to the test case (useful for gap analysis) 9. If getLinked is not specified, it defaults to true (linked issues) 10. FILTER CAPABILITIES: Extensive filtering by issue properties 11. FILTER FIELDS: summary (string), executedVersion (string), linkageLevel (string), issueType (list), issuePriority (list), issueState (list), owner (list) 12. LINKAGE LEVEL: 'Test Case' for test case level links, 'Test Step' for step level links 13. ISSUE TYPE IDs: Typically 1=Bug, 2=Enhancement, 3=Task (verify with your QMetry instance) 14. ISSUE PRIORITY IDs: Typically 1=High, 2=Medium, 3=Low (verify with your QMetry instance) 15. ISSUE STATUS IDs: Typically 1=Open, 2=In Progress, 3=Resolved, 4=Closed (verify with your QMetry instance) 16. OWNER IDs: Use numeric user IDs from QMetry user management 17. Multiple filter conditions are combined with AND logic 18. Use pagination for large issue result sets (start, page, limit parameters) 19. This tool is essential for defect tracking and traceability audits 20. Helps establish relationships between test failures and reported issues 21. Critical for impact analysis when test cases change 22. Use for compliance reporting and quality metrics

Fetch full detail data for a QMetry issue including UDF field values

Toolset: Issues

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• defectId (number) required: Issue DefectId (numeric ID) — use data[].id from Fetch Issues/Defects response. The field in the list API response is named 'id', not 'DefectId'.

Output Description: JSON object with data property containing full issue details including UDFTypeData map and all UDF field values

Use Cases: 1. Get UDF field values for a specific issue 2. Retrieve full issue metadata including custom fields 3. Inspect issue details before updating UDF values

Examples:

1. Fetch details for issue with DefectId 1430676

{
  "defectId": 1430676
}

Expected Output: Full issue detail object with UDFTypeData map and all UDF field values including MUL1, TCR_STR, etc.

Hints: 1. CRITICAL: Use 'data[].id' from Fetch Issues/Defects response as 'defectId'. The list API response field is named 'id' — there is no 'DefectId' field in the list response. Do NOT guess or derive defectId from the entity key suffix. 2. AUTO-RESOLVE: If user provides an issue entity key (e.g. VKMCP2-IS-1, MAC-IS-10), first call Fetch Defects or Issues with filter '[{"type":"string","value":"VKMCP2-IS-1","field":"entityKeyId"}]', then use 'data[].id' as defectId. 3. UDF VALUES: Response includes a 'UDFTypeData' map with all UDF field values for the issue. 4. WORKFLOW: To fetch issue UDF values — (1) Fetch Issues with entityKey filter → get data[0].id, (2) in parallel Fetch UDF Layout entityType='IS' pageName='DETAIL' → get field labels/types, (3) call this tool with defectId=data[0].id → read UDFTypeData.

Import/Publish automation test results from TestNG, JUnit, Cucumber, Robot, HPUFT, or QAF frameworks into QMetry

Toolset: Automation

Parameters:

• file (string) required: Base64 encoded file content or file path. User must upload result file (.json, .xml, .zip up to 30 MB)

• fileName (string) required: Original filename with extension (.json, .xml, or .zip)

• entityType (enum) required: Format of result file: TESTNG, CUCUMBER, JUNIT, HPUFT, QAF, or ROBOT

• automationHierarchy (enum): TestNG/JUnit hierarchy: 1=Test Case-Test Step, 2=Test Case only, 3=Test Suite-Test Case. Default: 1

• testsuiteName (string): Custom test suite name. Ignored if automationHierarchy=3 for JUnit or =2 for ROBOT

• testsuiteId (string): Reuse existing Test Suite by ID or Entity Key. Ignored if automationHierarchy=3 for JUnit or =2 for ROBOT

• tsFolderPath (string): Test suite folder path. Creates folder if doesn't exist. Ignored if reusing test suite

• tcFolderPath (string): Test case folder path. Creates folder if doesn't exist. Ignored if reusing test case

• platformID (string): Platform ID or Platform Name. Default: 'No Platform'

• projectID (string): Project ID, Project Key, or Project name. Overrides project in header

• releaseID (string): Release ID or Release name. Requires projectID if provided

• cycleID (string): Cycle ID or Cycle name. Requires releaseID and projectID if provided

• buildID (string): Build ID or Build name

• testcase_fields (string): JSON string with test case system fields and UDFs. Ignored if reusing test case. Example: {"component":["com1"], "priority":"High"}

• testsuite_fields (string): JSON string with test suite system fields and UDFs. Ignored if reusing test suite. Example: {"testSuiteState":"Open", "testsuiteOwner":"user"}

• skipWarning (enum): 0=Fail if summary >255 chars, 1=Truncate summary to 255 chars. Default: 0

• is_matching_required (string): True=Create new TC if summary/steps don't match, False=Reuse linked TC. Default: True

Use Cases: 1. 1. Import TestNG XML results after CI/CD pipeline execution 2. 2. Publish JUnit test results to QMetry for tracking and reporting 3. 3. Upload Cucumber JSON results with custom test suite organization 4. 4. Import Robot Framework results with specific release/cycle mapping 5. 5. Link automation results to existing test suites for version tracking 6. 6. Create new test suites with custom names and folder structures 7. 7. Map test results to specific platforms (browsers, OS, devices) 8. 8. Associate imported results with releases, cycles, and builds 9. 9. Bulk import multiple test results from ZIP archive 10. 10. Configure test case/suite fields and user-defined fields during import

Examples:

1. Basic TestNG result import

{
  "file": "<base64_encoded_testng_xml_content>",
  "fileName": "testng-results.xml",
  "entityType": "TESTNG"
}

Expected Output: Auto-generated test suite created with UTC timestamp, test cases auto-linked, execution results updated, 'No Platform' linked

2. JUnit results with custom test suite name

{
  "file": "<base64_encoded_junit_xml_content>",
  "fileName": "junit-results.xml",
  "entityType": "JUNIT",
  "testsuiteName": "Regression Suite - Build 123",
  "automationHierarchy": "1"
}

Expected Output: Test suite 'Regression Suite - Build 123' created with Test Case-Test Step hierarchy

3. Cucumber results with platform and release mapping

{
  "file": "<base64_encoded_cucumber_json_content>",
  "fileName": "cucumber-results.json",
  "entityType": "CUCUMBER",
  "platformID": "Chrome 120",
  "releaseID": "Release 2.0",
  "cycleID": "Sprint 15",
  "testsuiteName": "API Automation Tests"
}

Expected Output: Test suite created, linked to Chrome platform, Release 2.0, and Sprint 15 cycle

4. Reuse existing test suite

{
  "file": "<base64_encoded_testng_xml_content>",
  "fileName": "testng-regression.xml",
  "entityType": "TESTNG",
  "testsuiteId": "PROJ-TS-42"
}

Expected Output: Test cases auto-linked to existing test suite PROJ-TS-42, execution results updated

5. Import with folder organization

{
  "file": "<base64_encoded_junit_xml_content>",
  "fileName": "junit-results.xml",
  "entityType": "JUNIT",
  "tsFolderPath": "/Automation/Regression",
  "tcFolderPath": "/Automation/API Tests",
  "testsuiteName": "API Regression Suite"
}

Expected Output: Test suite created in '/Automation/Regression' folder, test cases in '/Automation/API Tests' folder

6. Import with test case custom fields

{
  "file": "<base64_encoded_testng_xml_content>",
  "fileName": "testng-results.xml",
  "entityType": "TESTNG",
  "testcase_fields": "{\"priority\":\"High\",\"testCaseType\":\"Automated\",\"component\":[\"API\",\"Backend\"],\"testcaseOwner\":\"john.doe\",\"estimatedTime\":\"2h:30m:0s\"}"
}

Expected Output: Test cases created with High priority, Automated type, API and Backend components

7. Import ZIP file with multiple results

{
  "file": "<base64_encoded_zip_content>",
  "fileName": "test-results.zip",
  "entityType": "JUNIT",
  "testsuiteName": "Full Regression Suite",
  "skipWarning": "1"
}

Expected Output: Multiple test results imported from ZIP, summaries truncated if >255 chars

8. Import with custom hierarchy for JUnit

{
  "file": "<base64_encoded_junit_xml_content>",
  "fileName": "junit-results.xml",
  "entityType": "JUNIT",
  "automationHierarchy": "3",
  "projectID": "PROJ"
}

Expected Output: Multiple test suites created per tag, test cases per tag

9. Import with build and platform mapping

{
  "file": "<base64_encoded_testng_xml_content>",
  "fileName": "testng-results.xml",
  "entityType": "TESTNG",
  "buildID": "Build-1.2.3",
  "platformID": "Safari 17",
  "releaseID": "Release 1.2",
  "cycleID": "QA Cycle"
}

Expected Output: Results linked to Build 1.2.3, Safari 17 platform, Release 1.2, QA Cycle

10. Import with test suite and test case fields

{
  "file": "<base64_encoded_cucumber_json_content>",
  "fileName": "cucumber-results.json",
  "entityType": "CUCUMBER",
  "testsuite_fields": "{\"testSuiteState\":\"In Progress\",\"testsuiteOwner\":\"jane.smith\",\"description\":\"Sprint 15 automation results\"}",
  "testcase_fields": "{\"priority\":\"Medium\",\"component\":[\"UI\",\"Frontend\"],\"userDefinedFields\":{\"reviewedDate\":\"11-20-2024\",\"environment\":\"Staging\"}}"
}

Expected Output: Test suite and test cases created with custom fields and UDFs

Hints: 1. 1. CRITICAL: User MUST upload a valid result file before calling this tool 2. 2. USER FILE UPLOAD REQUIRED: Ask user to provide file in chat - system will convert to base64 3. 3. FILE REQUIREMENTS: 4. - Supported extensions: .json, .xml, .zip 5. - Maximum size: 30 MB 6. - ZIP files must contain files matching the specified entityType format 7. 4. REQUIRED PARAMETERS: 8. - file: Base64 encoded content or file path 9. - fileName: Original filename with extension 10. - entityType: TESTNG, CUCUMBER, JUNIT, HPUFT, QAF, or ROBOT 11. 5. ENTITY TYPES: 12. - TESTNG: TestNG XML format 13. - JUNIT: JUnit XML format 14. - CUCUMBER: Cucumber JSON format 15. - ROBOT: Robot Framework XML format 16. - HPUFT: HP UFT format 17. - QAF: QAF format 18. 6. AUTOMATION HIERARCHY (TestNG/JUnit only): 19. - TestNG: 20. * 1 (default): = Test Case, = Test Step 21. * 2: = Test Case only 22. * 3: under = Test Case, = Test Step 23. - JUnit: 24. * 1 (default): = Test Case, = Test Step 25. * 2: = Test Case only 26. * 3: = Test Suite, = Test Case (creates multiple test suites) 27. 7. TEST SUITE OPTIONS: 28. - testsuiteName: Custom name for new test suite 29. - testsuiteId: Reuse existing test suite by ID or Entity Key (e.g., 'PROJ-TS-42') 30. - tsFolderPath: Create test suite in specific folder (e.g., '/Automation/Regression') 31. - Note: testsuiteName/testsuiteId ignored if automationHierarchy=3 for JUnit or =2 for ROBOT 32. 8. TEST CASE OPTIONS: 33. - tcFolderPath: Create test cases in specific folder (e.g., '/Automation/API Tests') 34. - Folders created automatically if they don't exist 35. 9. LINKING OPTIONS: 36. - platformID: Platform ID or name (e.g., 'Chrome 120', 'Safari 17') 37. - projectID: Project ID, key, or name (overrides header project) 38. - releaseID: Release ID or name (requires projectID) 39. - cycleID: Cycle ID or name (requires releaseID and projectID) 40. - buildID: Build ID or name 41. 10. GET IDs FROM OTHER TOOLS: 42. - Platform IDs: Use 'Platform/List' API (FETCH_PLATFORMS tool) 43. - Project IDs: Use 'Project/List' API (FETCH_PROJECTS tool) 44. - Release IDs: Use 'Release/List' API (FETCH_RELEASES_CYCLES tool) 45. - Cycle IDs: Use 'Cycle/List' API (FETCH_RELEASES_CYCLES tool) 46. - Build IDs: Use 'Build/List' API (FETCH_BUILDS tool) 47. - Test Suite IDs: Use 'Testsuite/Fetch' API (FETCH_TEST_SUITES tool) 48. 11. CUSTOM FIELDS (testcase_fields): 49. - JSON string with system fields and UDFs 50. - System fields: component, priority, testCaseState, testCaseType, testcaseOwner, estimatedTime, description 51. - Example: {"component":["API"], "priority":"High", "testcaseOwner":"user"} 52. - Ignored if reusing existing test case 53. 12. CUSTOM FIELDS (testsuite_fields): 54. - JSON string with system fields and UDFs 55. - System fields: testSuiteState, testsuiteOwner, description 56. - Example: {"testSuiteState":"Open", "testsuiteOwner":"user"} 57. - Ignored if reusing existing test suite 58. 13. USER DEFINED FIELDS (UDFs): 59. - Include in testcase_fields or testsuite_fields under 'userDefinedFields' key 60. - Example: {"userDefinedFields": {"reviewedDate": "11-20-2024", "environment": "Staging"}} 61. - UDF types: STRING, LARGETEXT, LOOKUPLIST, MULTILOOKUPLIST, DATEPICKER, NUMBER 62. - See tool metadata for UDF validation rules and auto-create behavior 63. 14. SKIP WARNING OPTIONS: 64. - skipWarning='0' (default): Fail import if test case summary >255 characters 65. - skipWarning='1': Truncate summary to 255 characters and continue import 66. 15. MATCHING BEHAVIOR: 67. - is_matching_required='true' (default): Create new TC/version if summary/steps don't match 68. - is_matching_required='false': Reuse existing TC version if entity key or summary matches 69. 16. IMPORT BEHAVIOR EXAMPLES: 70. - Only file + entityType → Auto-generated test suite, 'No Platform', test cases auto-linked 71. - file + entityType + platformID → Auto-generated test suite with specified platform 72. - file + entityType + testsuiteId → Results updated in existing test suite 73. - file + entityType + platformID + testsuiteId → Results updated in existing test suite with platform 74. 17. FOLDER CREATION: 75. - If tsFolderPath or tcFolderPath specified and doesn't exist, it will be created automatically 76. - Use forward slashes for folder paths (e.g., '/Parent/Child') 77. 18. ESTIMATED TIME FORMAT: 78. - Format: '2h:30m:15s' or '4h' or '7m' or '0s' 79. - Range: 0 to 99999 minutes 80. 19. OWNER FIELDS: 81. - Use userAlias (username) not display name 82. - testcaseOwner: User must have Test Case module rights 83. - testsuiteOwner: User must have Test Suite module rights 84. - Owner not set if user not found or lacks permissions 85. 20. LOOKUPLIST/MULTILOOKUPLIST BEHAVIOR: 86. - If value doesn't exist and auto-create is ON: Value added to list 87. - If value doesn't exist and auto-create is OFF: Field blank or default value 88. - MULTILOOKUPLIST: New values added, old values persist 89. 21. MANDATORY FIELD VALIDATION: 90. - If mandatory system/UDF field missing: 91. * Auto-create OFF + value doesn't exist = Import FAIL 92. * Auto-create ON + value doesn't exist = Import SUCCESS (value created) 93. * Value exists = Import SUCCESS 94. 22. ERROR HANDLING: 95. - Check file size before upload (must be ≤30 MB) 96. - Validate file extension matches entityType 97. - Ensure required dependencies: cycleID requires releaseID and projectID 98. - If import fails, check QMetry UI for detailed error messages 99. 23. WORKFLOW: 100. Step 1: Ask user to upload result file in chat 101. Step 2: System converts file to base64 102. Step 3: Collect entityType and optional parameters 103. Step 4: Call this tool with file data and configuration 104. Step 5: QMetry processes file and creates/updates test artifacts 105. Step 6: Return import results with test suite and execution details 106. 24. USER INTERACTION REQUIRED: 107. - ALWAYS ask user to upload file before calling this tool 108. - Display supported formats: .json, .xml, .zip (up to 30 MB) 109. - Ask for entityType (framework used) 110. - Ask for optional parameters based on user's needs 111. 25. PERFORMANCE TIPS: 112. - For large imports, consider using ZIP files 113. - Reusing existing test suites is faster than creating new ones 114. - Use automationHierarchy wisely to control test case/suite structure

Fetches the status of an automation import job by request ID.

Toolset: Automation

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• requestID (number) required: Numeric request ID from import automation response. CRITICAL: parameter name is 'requestID' — do NOT use 'requestId', 'jobId', or other variants. Accepts a string or number.

Use Cases: 1. 1. Check if an automation import job is completed or still in progress. 2. 2. Retrieve status, progress, and details for a specific automation import request. 3. 3. Monitor automation result processing for CI/CD integrations.

Examples:

1. Fetch status for request ID 12345

{
  "requestID": 12345
}

Expected Output: Status, progress, and details of the automation import job for request ID 12345.

Fetch UDF (User Defined Field) definitions for Test Case, Test Suite, or Issue entities. Returns field names, types, fieldIDs, and lookup option IDs. Call this BEFORE creating or updating an entity with UDF values.

Toolset: UDF

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• entityType (enum) required: Entity type to fetch UDF field definitions for. 'TC' = Test Case (also returns step UDFs in stepFields), 'TS' = Test Suite, 'IS' = Issue.

• pageName (enum): 'ADD' returns fields for create operations (no fieldID needed). 'DETAIL' returns fields for update operations and includes fieldID (projectUserFieldID) required by the UDF update wrapper. Call with 'DETAIL' before updating an entity's UDF values. (default: "ADD")

Output Description: JSON with 'entityType', 'pageName'. All data is scoped by entityType key in the QMetry newlayout response: TC uses qmUDF.TC / qmSDF.TC / qmDefaultValue.TC; TS uses qmUDF.TS / qmSDF.TS / qmDefaultValue.TS; IS uses qmUDF.IS / qmSDF.IS / qmDefaultValue.IS. 'fields' array — UDF fields (name, label, fieldTypeName, fieldID, isMandatory, optional listName); isMandatory=true when allowBlank=false in QMetry. 'systemFields' array — system fields like Summary/Priority/Status (name, label, fieldTypeName, isMandatory); isMandatory=true when allowBlank=false. 'defaultValues' object — { fieldName: defaultValueId } pre-configured defaults (auto-fill when user omits the field; no need to ask user). TC-only: 'stepFields' — step UDF fields; 'stepSystemFields' — step system fields (mandatory via tcSteps[].mandatory=true); 'stepDefaultValues' — { fieldName: defaultValueId } from qmTCSDefaultValue.TCS. 'listOptions' map (listName → [{id, name, isArchived}]). '_note' with workflow instructions.

Use Cases: 1. Discover UDF fields before creating a Test Case with custom fields 2. Get fieldIDs before updating a Test Suite's UDF values 3. Find valid dropdown option IDs for a LOOKUPLIST UDF before setting a value 4. Identify mandatory UDF fields before creating an Issue 5. List all step-level UDF fields available for Test Case steps 6. Get CASCADINGLIST parent option IDs before fetching child values

Examples:

1. Get UDF field definitions for creating a Test Case

{
  "entityType": "TC",
  "pageName": "ADD"
}

Expected Output: { fields: [{ name: 'custom_text', label: 'Custom Text', fieldTypeName: 'STRING', fieldID: null, isMandatory: false }, ...], stepFields: [{ name: 'step_field', label: 'Step Field', fieldTypeName: 'STRING', ... }], listOptions: { myListKey: [{ id: 101, name: 'Option A' }] } }

2. Get UDF fieldIDs for updating a Test Suite

{
  "entityType": "TS",
  "pageName": "DETAIL"
}

Expected Output: { fields: [{ name: 'dropdown_field', label: 'Dropdown', fieldTypeName: 'LOOKUPLIST', fieldID: 2002, isMandatory: false, listName: 'myListKey' }, ...], listOptions: { myListKey: [{ id: 101, name: 'Option A' }, { id: 102, name: 'Option B' }] } }

3. Get UDF field definitions for creating an Issue

{
  "entityType": "IS",
  "pageName": "ADD"
}

Expected Output: { fields: [{ name: 'TCR_STR', label: 'String Field', fieldTypeName: 'STRING', fieldID: null }, ...], listOptions: {} }

Hints: 1. CALL THIS TOOL FIRST: Before creating or updating TC/TS/IS entities, always call this tool with pageName='ADD' to discover mandatory fields, defaults, field names, types, and valid option IDs. 2. pageName='ADD': Use before CREATE operations — returns field names + types + list options. fieldID is null (not needed on create). 3. pageName='DETAIL': Use before UPDATE operations — returns fieldID (projectUserFieldID) required in the UDF wrapper. 4. WORKFLOW FOR CREATE with UDFs: 5. 1. Call Fetch UDF Layout with entityType + pageName='ADD' 6. 2. For LOOKUPLIST/MULTILOOKUPLIST: pick IDs from listOptions[field.listName] 7. 3. For CASCADINGLIST: pick parent ID from listOptions[field.listName], then call Fetch Cascade Child Values to get child IDs 8. 4. Pass UDF values via 'udfFields' param on the create tool: { fieldName: value } 9. 5. Example: { udfFields: { custom_text: 'value', lookup_field: 101, multi_field: [101, 102], cascade_field: { parent: 201, child: 202 } } } 10. WORKFLOW FOR UPDATE with UDFs: 11. 1. Call Fetch UDF Layout with entityType + pageName='DETAIL' to get fieldIDs 12. 2. For LOOKUPLIST/MULTILOOKUPLIST: pick IDs from listOptions[field.listName] 13. 3. For CASCADINGLIST: pick parent ID, then call Fetch Cascade Child Values for child IDs 14. 4. Pass both 'udfFields' (flat root keys) AND 'UDF' wrapper (with fieldID) on the update tool: 15. udfFields: { custom_text: 'new value', lookup_field: 102 } 16. UDF: { custom_text: { fieldID: 1001, value: 'new value' }, lookup_field: { fieldID: 1002, value: 102 } } 17. 5. For LOOKUPLIST/MULTILOOKUPLIST in update: also set flat alias key — e.g. lookup_fieldAlias: 'Option B' 18. stepFields (TC only): Step-level UDF definitions are separate from entity-level UDF fields. They appear in stepFields (not fields). Use them when setting UDF values on test case steps. 19. listOptions: A map of listName → [{id, name, isArchived}]. Use 'id' as the UDF value for LOOKUPLIST/MULTILOOKUPLIST. Only include non-archived options unless user explicitly wants archived items. 20. EMPTY listOptions: If listOptions[field.listName] is missing or empty for a lookup field, the newlayout endpoint did not return those options. This tool automatically attempts a fallback to the UDF metadata endpoint to populate them. If listOptions is STILL empty after this tool returns, call 'Fetch Test Run UDF Metadata' with the same entityType — its 'lookupOptions' map uses the same listName keys and contains the full option list. 21. isMandatory: If true, this field MUST be included. Source: allowBlank=false in QMetry API (for UDF/system fields) or mandatory=true (for step system fields). 22. DATETIMEPICKER fields: date value MUST match the project's active date format. 23. Get format: project info → dateTimeFormatID → find in dateTimeFormatNew where id matches → read unique_value. 24. unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 25. Re-format user date to match before sending. NEVER guess the format — always check project info first. 26. defaultValues: Pre-configured defaults from QMetry. If a mandatory field has a defaultValues entry, use that value automatically without asking the user. Only ask user for mandatory fields with NO default. 27. stepDefaultValues: Same as defaultValues but for test case step fields. 28. PRE-CREATE MANDATORY CHECK WORKFLOW (CRITICAL — do this before every create): 29. 1. Call Fetch UDF Layout with pageName='ADD' for the entity type 30. 2. Check systemFields: for each field where isMandatory=true, check if defaultValues[field.name] exists 31. - Has default → use defaultValues[field.name] as the value, no need to ask user 32. - No default → MUST ask user to provide value before creating 33. 3. Check fields (UDF): same logic — isMandatory=true + no defaultValues entry → ask user 34. 4. For TC steps: check stepSystemFields and stepFields isMandatory, use stepDefaultValues for auto-fill 35. 5. Only after all mandatory fields are resolved (via default or user input) → proceed with create 36. This tool is scoped per project — list options, fieldIDs, and defaults are all project-specific.

Bulk update User Defined Field (UDF) values for one or more Test Case Runs in a test execution. Runs asynchronously in the background.

Toolset: UDF

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tcRunIDs (array) required: Array of Test Case Run IDs to update UDF values for. To get tcRunIDs — Call 'Fetch Test Case Runs by Test Suite Run' tool. From the response, get value of data[].tcRunID. Example: [41572006, 41572009, 41572013]

• UDF (record<string, object>) required: Object mapping UDF field names to their new values. Each key is the UDF field name (e.g. 'test_env', 'priority_field'). Each value is an object with fieldID and value (and optionally multiSelectAction for multi-select fields). All UDF fields are optional — include only the fields you want to update.

Output Description: JSON object with success status, code 'CO.BULK_TC_EXECUTION_UDF_UPDATE_STARTED', and message confirming the background job was queued.

Use Cases: 1. Bulk update a string UDF (e.g. build version, environment name) for multiple test runs 2. Set a date UDF field (e.g. execution date) across multiple test case runs 3. Update a numeric UDF field (e.g. story points, priority score) in bulk 4. Set a single-select lookup UDF to a new value for multiple runs 5. Append new values to a multi-select UDF field across multiple test runs 6. Replace all existing selections in a multi-select UDF with new values 7. Update a cascading list UDF (parent + child) for multiple test runs 8. Update multiple UDF fields of different types in a single bulk operation 9. Reset a UDF field value for all runs in a test suite execution 10. Sync automated test result metadata (environment, build, platform) into UDF fields after execution

Examples:

1. Bulk update a STRING UDF for multiple test runs

{
  "tcRunIDs": [
    41572006,
    41572009,
    41572013
  ],
  "UDF": {
    "8190_String": {
      "fieldID": 229241,
      "value": "regression-v2.1"
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background. Go to 'Scheduled Task' to track the process.

2. Bulk update a DATE UDF field for multiple test runs (MM-DD-YYYY format)

{
  "tcRunIDs": [
    41572006,
    41572009
  ],
  "UDF": {
    "KN_DATE": {
      "fieldID": 229255,
      "value": "06-20-2026"
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

3. Bulk update a NUMBER UDF field for multiple test runs

{
  "tcRunIDs": [
    41572006,
    41572009,
    41572013,
    41572015
  ],
  "UDF": {
    "defaultNum": {
      "fieldID": 229003,
      "value": 5
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

4. Bulk update a single-select LOOKUPLIST UDF for multiple test runs

{
  "tcRunIDs": [
    41572006,
    41572009
  ],
  "UDF": {
    "8260LUP": {
      "fieldID": 228563,
      "value": 5108697
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

5. Bulk update a MULTILOOKUPLIST UDF — APPEND new values to existing selections

{
  "tcRunIDs": [
    41572006,
    41572009,
    41572013
  ],
  "UDF": {
    "m_selections": {
      "fieldID": 229223,
      "value": [
        5158524,
        5158525
      ],
      "multiSelectAction": "append"
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

6. Bulk update a MULTILOOKUPLIST UDF — REPLACE existing selections with new values

{
  "tcRunIDs": [
    41572006,
    41572009
  ],
  "UDF": {
    "mullt_env": {
      "fieldID": 229425,
      "value": [
        5108697,
        5108698
      ],
      "multiSelectAction": "replace"
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

7. Bulk update a CASCADINGLIST UDF (parent + child) for multiple test runs

{
  "tcRunIDs": [
    41572006,
    41572009,
    41572013
  ],
  "UDF": {
    "cascade_mcp": {
      "fieldID": 229426,
      "value": {
        "parent": 5126498,
        "child": 5126499
      }
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background.

8. Bulk update multiple UDF fields of different types in a single operation

{
  "tcRunIDs": [
    41572006,
    41572009,
    41572013,
    41572015,
    41579875
  ],
  "UDF": {
    "8190_String": {
      "fieldID": 229241,
      "value": "smoke-test"
    },
    "KN_DATE": {
      "fieldID": 229255,
      "value": "06-20-2026"
    },
    "defaultNum": {
      "fieldID": 229003,
      "value": 3
    },
    "8260LUP": {
      "fieldID": 228563,
      "value": 5108697
    },
    "m_selections": {
      "fieldID": 229223,
      "value": [
        5158524,
        5158525
      ],
      "multiSelectAction": "append"
    },
    "mullt_env": {
      "fieldID": 229425,
      "value": [
        5108697,
        5108698
      ],
      "multiSelectAction": "replace"
    },
    "cascade_mcp": {
      "fieldID": 229426,
      "value": {
        "parent": 5126498,
        "child": 5126499
      }
    }
  }
}

Expected Output: Bulk updates to execution UDF values will run in the background. Go to 'Scheduled Task' to track the process.

Hints: 1. REQUIRED: 'tcRunIDs' must be a non-empty array of numeric Test Case Run IDs. Get IDs from 'Fetch Test Case Runs by Test Suite Run' tool → data[].tcRunID. 2. REQUIRED: 'UDF' must be an object with at least one field entry. Each key is the UDF field name; each value has 'fieldID' and 'value'. 3. VALUE FORMATS by field type: STRING: plain string, e.g. 'regression-build' NUMBER: number, e.g. 3 DATETIMEPICKER: date string in MM-DD-YYYY format, e.g. '06-20-2026' LOOKUPLIST (single select): numeric item ID, e.g. 5108697 MULTILOOKUPLIST (multi-select): array of item IDs, e.g. [5158524, 5158525] CASCADINGLIST: object with parent and child keys, e.g. {parent: 5126498, child: 5126499}. To get valid child IDs for a CASCADINGLIST field — first call 'Fetch Test Run UDF Metadata' to get the parent item IDs from lookupOptions, then call 'Fetch Cascade Child Values' with a parent item ID to get the available child IDs, then use {parent: , child: } as the value here. 4. MULTILOOKUPLIST — multiSelectAction rules: 'append' (default): new values are ADDED to existing selections. Use when user says 'add', 'include', 'append'. 'replace': existing selections are CLEARED and replaced with only the new values. Use when user says 'replace', 'set to', 'overwrite', 'change to'. If user does not specify, ALWAYS default to 'append'. Never assume 'replace'. 5. MULTILOOKUPLIST — apply multiSelectAction per field individually. Different multi-select fields in the same request can have different multiSelectAction values. 6. DATE FORMAT: Always use MM-DD-YYYY format for DATETIMEPICKER fields (e.g. '06-20-2026', not '2026-06-20'). Convert from any user-supplied date format before calling the tool. 7. ASYNC OPERATION: This API runs in the background. The success response means the job was queued, not that it completed. Tell the user to check 'Scheduled Task' in QMetry UI to track completion. 8. CRITICAL — FIELD IDs: The 'fieldID' for each UDF entry MUST be the exact numeric ID from QMetry's UDF definition — do NOT guess, infer, or fabricate fieldIDs. If the user has not provided a fieldID, ask the user to supply it or look it up in QMetry admin settings before calling this tool. Using a wrong fieldID will silently fail or update the wrong field. 9. CRITICAL — WORKFLOW: When user asks to bulk-update a UDF across all executions of a test suite run (e.g. tsRunID 731600), ALWAYS call 'Fetch Test Case Runs by Test Suite Run' first with that tsRunID to collect ALL tcRunIDs from the response (data[].tcRunID), THEN call this tool. Never skip the fetch step or hard-code tcRunIDs. 10. ALL UDF FIELDS ARE OPTIONAL: Only include the UDF fields the user wants to update. Do not include fields with no change. 11. tcRunIDs vs entityIDs: This tool uses 'tcRunIDs' (array of numbers). Do NOT confuse with 'Bulk Update Test Case Execution Status' which uses 'entityIDs' (comma-separated string).

Fetch the metadata (field definitions) for all Test Run UDF (User Defined Fields) configured in this QMetry project. Returns each field's name, display label, type, and numeric fieldID (projectUserFieldID) required for bulk updates.

Toolset: UDF

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

Output Description: JSON object with 'fields' array (each item has fieldID, name, label, fieldType, allowBlank, and optional listName/listMasterID) and 'lookupOptions' map for list-based fields. If lookupOptions is empty for a list field, options could not be fetched automatically.

Use Cases: 1. Get the fieldID for 'planned_execution_date' before bulk updating it 2. List all available Test Run UDF fields and their types in the project 3. Find the lookup list item IDs for a LOOKUPLIST or MULTILOOKUPLIST Test Run UDF 4. Discover UDF field names and IDs when user says 'what Test Run UDF fields are available'

Examples:

1. List all Test Run UDF fields in the project

{}

Expected Output: Array of fields with fieldID, name, label, fieldType, and lookupOptions for list-based fields.

Hints: 1. ALWAYS call this tool before 'Bulk Update Test Run UDFs' when the user has not explicitly provided a numeric fieldID. The 'fieldID' in the bulk update corresponds to 'projectUserFieldID' in this response. 2. This tool is the authoritative source of fieldIDs for all Test Run UDF fields — do NOT guess or hard-code fieldIDs. 3. For LOOKUPLIST and MULTILOOKUPLIST fields, the response 'lookupOptions' contains items with 'id', 'name' (display label), and 'uniqueLabel' (internal key stored in executions). When execution UDF values are returned by Fetch Issue Executions or Fetch Test Run UDF Values, LOOKUPLIST/MULTILOOKUPLIST values are already resolved from uniqueLabel → name. For bulk updates, use the item 'id' as the value. 4. DATE fields use MM-DD-YYYY format (e.g. '06-23-2026') when setting values via Bulk Update Test Run UDFs. 5. EMPTY lookupOptions: If 'lookupOptions' is empty or missing a list key for a LOOKUPLIST/MULTILOOKUPLIST field, the API did not return options for that field. In this case the user must provide the option name manually or check the QMetry UI for available option IDs. Do NOT proceed with a guess — ask the user for the option ID or name.

Fetch the Test Run UDF (User Defined Field) values for all test case runs in a given test suite run. Returns each run's UDF values enriched with field label and type information from metadata. Use this tool for test suite run UDF values (sourceContext='testSuiteRun'). Do NOT use this tool for test case executions — 'Fetch Test Case Executions' already calls metadata internally and returns 'testRunUdfs' in every execution row.

Toolset: UDF

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• tsrunID (string): Test Suite Run ID. CRITICAL: the parameter name is 'tsrunID' — do NOT use 'testSuiteRunId', 'tsRunID', or any other variant. Accepts a string or number (e.g. 731600 or '731600' — both are valid). Get this from 'Fetch Executions by Test Suite' → use data[].tsRunID from the response. Required when sourceRows is not provided.

• viewId (number): View ID for the test execution list (latestViews.TE.viewId from project info). Auto-resolved from project info when omitted. Required when sourceRows is not provided.

• sourceContext (enum): Which parent tool produced sourceRows. Use 'testSuiteRun' for Fetch Test Case Runs by Test Suite Run. Do NOT use this tool for Fetch Test Case Executions — that tool calls metadata internally and returns testRunUdfs on every execution row; use that data directly. Do NOT use this tool for Fetch Issue Executions; that tool already reads udfjson and enriches it with metadata. (default: "testSuiteRun")

• sourceRows (array): Optional rows already returned by Fetch Test Case Runs by Test Suite Run. The UDF tool will reuse these rows, enrich/pivot UDF values, and preserve identification fields instead of making the same execution-list API call again. Do NOT pass Fetch Test Case Executions rows here — those rows already have testRunUdfs enriched. Do not pass issue execution rows here; use Fetch Issue Executions output directly for issue UDFs.

• startIndex (number): Zero-based start index for pagination (default: 0). (default: 0)

• size (number): Number of test case runs to return per page (default: 50). (default: 50)

Output Description: JSON with hasTcRunUdf boolean, sourceContext, total count, defaultColumns, udfColumns, unifiedTableRows, runs array, and availableUdfFields array describing all UDF fields in the project. Render unifiedTableRows directly as the final table: default identification fields first, then one column per UDF label.

Use Cases: 1. Show me the UDF values for all runs in test suite run 731600 2. What is the planned execution date set on each run in this test cycle? 3. List the Test Run UDF values for test suite run 87039 4. Fetch test run UDFs of executions for tsRunID 731600

Examples:

1. Fetch UDF values for all runs in test suite run 731600

{
  "tsrunID": "731600",
  "sourceContext": "testSuiteRun"
}

Expected Output: Present as ONE unified table — never as a separate type+value breakdown. Example: | Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | Environments UDF | Execution Type | Country | | MAC-TC-5 | Login - valid credential | 1 | Passed | varis | chrome, edge, safari | Functional | India > i3 | | MAC-TC-6 | Login - invalid password | 2 | Failed | john | firefox | Regression | - | Columns: Test Case Key (entityKey) | Test Case Summary (summary) | Executed Version (latestVersion) | Execution Status (runStatus) | Tested By | then one column per UDF label. Use the UDF 'label' as column header. Show null UDF values as '-'.

Hints: 1. DEFAULT DISPLAY CONTRACT: Always render 'unifiedTableRows' as ONE table. Do not render UDFs as Label | Type | Value rows. 2. When sourceContext='testSuiteRun', mandatory columns are: Test Case Key | Test Case Summary | Executed Version | Execution Status | Tested By | then one column per UDF label. 3. PARENT-TO-UDF WORKFLOW: If Fetch Test Case Runs by Test Suite Run was already called, pass parentResponse.data as sourceRows with sourceContext='testSuiteRun'. This preserves identification fields and avoids repeating the same API call. 4. For prompts like 'Fetch test case runs of VKMCP-TS-1 and its Test Run UDFs': call Fetch Test Case Runs by Test Suite Run, then call this tool with sourceContext='testSuiteRun' and sourceRows=. 5. For prompts like 'Fetch Test Case Executions and show Test Run UDFs': call Fetch Test Case Executions ONLY — that tool already calls metadata internally and returns testRunUdfs on every execution row. Do NOT call this tool for test case executions. 6. For prompts like 'Fetch Issue Executions and Test Run UDFs': call Fetch Issue Executions only. Do not call this tool, because issue UDF values come from /rest/execution/getExecutionsForIssue udfjson and are already enriched by the issue tool with metadata. 7. If no parent rows are available, use 'tsrunID' from the 'Fetch Executions by Test Suite' tool (data[].tsRunID field). 8. 'viewId' is auto-resolved from latestViews.TE.viewId — leave blank unless explicitly overriding. It is only needed when sourceRows is not supplied. 9. If 'hasTcRunUdf' is false in the response, no Test Run UDFs are configured for this project. 10. The 'testRunUdfs' array on each run contains enriched UDF values with label and fieldID — use fieldID from here when calling 'Bulk Update Test Run UDFs'. 11. VALUE RESOLUTION: For LOOKUPLIST and MULTILOOKUPLIST fields, 'value' is resolved from the internal uniqueLabel key to the human-readable display name using qmUDFList lookup options. Always display the resolved name, never the raw uniqueLabel. 12. LOOKUP RESOLUTION WARNING: If the response contains '_lookupWarning', lookup options were missing for some fields. Individual UDF entries may have '_rawValue: true' and '_note' indicating the value is an unresolved internal ID. In that case, call 'Fetch Test Run UDF Metadata' separately and use its 'lookupOptions' to resolve the display name before showing the user. 13. This tool calls UDF metadata internally — no need to call 'Fetch Test Run UDF Metadata' separately when viewing values. 14. When sourceRows is omitted, this tool also calls the test-suite-run execution list API internally. When sourceRows is provided, it reuses those rows and does not refetch the parent execution list.

Fetch the child values of a CASCADINGLIST UDF field for a given parent item ID. Use this before bulk-updating a CASCADINGLIST Test Run UDF to discover valid child item IDs.

Toolset: UDF

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• id (number) required: Numeric ID of the parent cascade list item to fetch child values for. Get this from the 'lookupOptions' returned by 'Fetch Test Run UDF Metadata' for a CASCADINGLIST field — each option has an 'id' field.

• isArchReq (boolean): Whether to include archived child items in the response (default: false). (default: false)

Output Description: JSON object with 'parentId' (the input ID), 'parentName' (the parent item's display name), 'children' array (each item has id, name, uniqueLabel, isArchived), and a '_note' explaining how to use the IDs.

Use Cases: 1. Find valid child values for a CASCADINGLIST UDF before bulk-updating test runs 2. List all child options available under a specific parent cascade item 3. Resolve child item ID when user knows the parent but not the child 4. Discover cascade hierarchy for a UDF field before setting it on test executions

Examples:

1. Fetch child values for parent cascade item with ID 5173534

{
  "id": 5173534
}

Expected Output: { parentId: 5173534, parentName: "India", children: [{ id: 5173535, name: "i1", uniqueLabel: "i1", isArchived: false }, ...], _note: "Use 'id' from 'children' as the 'child' value in the CASCADINGLIST update." }

2. Fetch child values including archived items for parent ID 5126498

{
  "id": 5126498,
  "isArchReq": true
}

Expected Output: { parentId: 5126498, parentName: "abc", children: [...], _note: "..." }

Hints: 1. MANDATORY WORKFLOW for CASCADINGLIST bulk update:

1. Call 'Fetch Test Run UDF Metadata' → get the CASCADINGLIST field's 'fieldID' (projectUserFieldID) and parent item options from 'lookupOptions'.

2. Call this tool ('Fetch Cascade Child Values') with a parent item 'id' from step 1 → get child item IDs.

3. Call 'Bulk Update Test Run UDFs' with value: { parent: , child: } and the 'fieldID' from step 1. 2. The parent item IDs are in the 'lookupOptions' map returned by 'Fetch Test Run UDF Metadata'. Each entry under the field's listName contains items with 'id' — use that 'id' as the 'id' parameter here. IMPORTANT: If 'lookupOptions' from Fetch Test Run UDF Metadata is empty for the CASCADINGLIST field, the API did not return parent options. In this case, ask the user to provide the parent item ID from the QMetry UI — do NOT guess. 3. The response 'children' array contains objects with 'id', 'name', 'uniqueLabel', and 'isArchived'. Use 'id' as the 'child' value in the bulk update payload. 4. Set 'isArchReq: true' only if the user explicitly asks to include archived/inactive child options. 5. This endpoint requires 'scope' and 'orgcode' headers — these are injected automatically from the session context when 'Set Project Info' has been called. If you see an authorization error, call 'Set Project Info' first. 6. Do NOT call this tool for STRING, NUMBER, DATETIMEPICKER, LOOKUPLIST, or MULTILOOKUPLIST fields — only CASCADINGLIST (fieldType: 'CASCADINGLIST') fields have a parent-child hierarchy.

Fetch the quality gate configuration for a project and AI agent, including assessment scope and gate criteria.

Toolset: AI Agent

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• projectId (number) required: Numeric project ID for which to fetch the quality gate configuration. This is the internal numeric identifier, not the project key.

• agentIdentifier (string) required: Unique identifier of the AI agent whose gate configuration should be retrieved.

Use Cases: 1. Retrieve gate criteria and thresholds before generating a quality gate report 2. Check which quality gates are configured for a project and agent 3. Inspect assessment scope and gate parameters for release readiness evaluation

Examples:

1. Fetch gate configuration for project 45851 and agent 'RR'

{
  "projectId": 45851,
  "agentIdentifier": "RR"
}

Expected Output: Gate configuration object with assessment scope, gate criteria, and thresholds.

Hints: 1. REQUIRED: 'projectId' must be a valid numeric project ID (not the project key). 2. REQUIRED: 'agentIdentifier' must match a registered AI agent identifier. 3. Call this tool before 'Execute Quality Gate Report' to understand the gate criteria and available gates. 4. If AI Agent is not enabled for the project, the backend will return an appropriate error.

Execute a quality gate report by forwarding the request to the backend analytics engine and returning the results.

Toolset: AI Agent

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• reportName (string) required: Report name identifier (e.g. 'RR' for Release Readiness).

• gateIdentifier (string) required: Gate identifier to execute the report against (e.g. 'GATE1').

• projectId (number) required: Numeric project ID for the report scope.

• releaseId (number): Optional release ID to scope the report to a specific release.

• cycleIds (array): Optional array of cycle IDs to scope the report to specific cycles.

• page (number): Optional page number for paginated report results.

• limit (number): Maximum number of records to return per page. Defaults to 100 if not specified. (default: 100)

Use Cases: 1. Generate a release readiness report for a specific project, release, and cycle 2. Execute a quality gate assessment to evaluate project health against gate criteria 3. Run a gate report scoped to specific cycles within a release 4. Produce analytics data for quality gate evaluation and decision-making

Examples:

1. Execute a release readiness report for project 45851, release 90698, cycle 129140

{
  "reportName": "RR",
  "gateIdentifier": "GATE1",
  "projectId": 45851,
  "releaseId": 90698,
  "cycleIds": [
    129140
  ]
}

Expected Output: { "data": [...], "total": 0, "success": true, "page": {} }

2. Execute a gate report without release/cycle scoping

{
  "reportName": "RR",
  "gateIdentifier": "GATE1",
  "projectId": 45851
}

Expected Output: { "data": [...], "total": 0, "success": true, "page": {} }

Hints: 1. REQUIRED: 'reportName' identifies the report type (e.g. 'RR' for Release Readiness). 2. REQUIRED: 'gateIdentifier' identifies which gate to evaluate (e.g. 'GATE1'). 3. REQUIRED: 'projectId' must be a valid numeric project ID. 4. OPTIONAL: 'releaseId' scopes the report to a specific release. 5. OPTIONAL: 'cycleIds' scopes the report to specific test cycles within the release. 6. OPTIONAL: 'page' specifies the page number for paginated report results. 7. OPTIONAL: 'limit' sets the maximum number of records per page (defaults to 100). 8. Call 'Fetch Quality Gate Configuration' first to discover available gates and report parameters. 9. The response is returned exactly as received from the backend — no transformation is applied.

Export HTML content as a downloadable report file via the backend.

Toolset: AI Agent

Parameters:

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

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• htmlContent (string) required: HTML content to be exported as a report.

• fileName (string) required: Name for the exported report file (without extension).

Use Cases: 1. Export a generated release readiness report as an HTML file 2. Save AI-generated quality gate analysis as a downloadable report 3. Create a shareable HTML document from report content

Examples:

1. Export a release readiness report

{
  "htmlContent": "<h1>Release Readiness Report</h1><p>Generated by AI Agent.</p>",
  "fileName": "release-readiness-report"
}

Expected Output: Report file generated and returned by the backend.

Hints: 1. REQUIRED: 'htmlContent' is the full HTML string to export. 2. REQUIRED: 'fileName' is the report file name (without extension). 3. Typically called after generating report content from 'Execute Quality Gate Report' results.