QMetry: Fetch UDF Layout

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.