create_catalog_item_variable
Add custom fields to ServiceNow catalog items to collect user input during request processes. Define variable types, labels, requirements, and validation rules for structured data collection.
Instructions
Create a new catalog item variable
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| catalog_item_id | Yes | The sys_id of the catalog item | |
| name | Yes | The name of the variable (internal name) | |
| type | Yes | The type of variable (e.g., string, integer, boolean, reference) | |
| label | Yes | The display label for the variable | |
| mandatory | No | Whether the variable is required | |
| help_text | No | Help text to display with the variable | |
| default_value | No | Default value for the variable | |
| description | No | Description of the variable | |
| order | No | Display order of the variable | |
| reference_table | No | For reference fields, the table to reference | |
| reference_qualifier | No | For reference fields, the query to filter reference options | |
| max_length | No | Maximum length for string fields | |
| min | No | Minimum value for numeric fields | |
| max | No | Maximum value for numeric fields |
Implementation Reference
- Core handler function that executes the tool by constructing a POST request to the ServiceNow item_option_new table API and handling the response.def create_catalog_item_variable( config: ServerConfig, auth_manager: AuthManager, params: CreateCatalogItemVariableParams, ) -> CatalogItemVariableResponse: """ Create a new variable (form field) for a catalog item. Args: config: Server configuration. auth_manager: Authentication manager. params: Parameters for creating a catalog item variable. Returns: Response with information about the created variable. """ api_url = f"{config.instance_url}/api/now/table/item_option_new" # Build request data data = { "cat_item": params.catalog_item_id, "name": params.name, "type": params.type, "question_text": params.label, "mandatory": str(params.mandatory).lower(), # ServiceNow expects "true"/"false" strings } if params.help_text: data["help_text"] = params.help_text if params.default_value: data["default_value"] = params.default_value if params.description: data["description"] = params.description if params.order is not None: data["order"] = params.order if params.reference_table: data["reference"] = params.reference_table if params.reference_qualifier: data["reference_qual"] = params.reference_qualifier if params.max_length: data["max_length"] = params.max_length if params.min is not None: data["min"] = params.min if params.max is not None: data["max"] = params.max # Make request try: response = requests.post( api_url, json=data, headers=auth_manager.get_headers(), timeout=config.timeout, ) response.raise_for_status() result = response.json().get("result", {}) return CatalogItemVariableResponse( success=True, message="Catalog item variable created successfully", variable_id=result.get("sys_id"), details=result, ) except requests.RequestException as e: logger.error(f"Failed to create catalog item variable: {e}") return CatalogItemVariableResponse( success=False, message=f"Failed to create catalog item variable: {str(e)}", )
- Pydantic BaseModel defining the input parameters and validation schema for the create_catalog_item_variable tool.class CreateCatalogItemVariableParams(BaseModel): """Parameters for creating a catalog item variable.""" catalog_item_id: str = Field(..., description="The sys_id of the catalog item") name: str = Field(..., description="The name of the variable (internal name)") type: str = Field(..., description="The type of variable (e.g., string, integer, boolean, reference)") label: str = Field(..., description="The display label for the variable") mandatory: bool = Field(False, description="Whether the variable is required") help_text: Optional[str] = Field(None, description="Help text to display with the variable") default_value: Optional[str] = Field(None, description="Default value for the variable") description: Optional[str] = Field(None, description="Description of the variable") order: Optional[int] = Field(None, description="Display order of the variable") reference_table: Optional[str] = Field(None, description="For reference fields, the table to reference") reference_qualifier: Optional[str] = Field(None, description="For reference fields, the query to filter reference options") max_length: Optional[int] = Field(None, description="Maximum length for string fields") min: Optional[int] = Field(None, description="Minimum value for numeric fields") max: Optional[int] = Field(None, description="Maximum value for numeric fields")
- src/servicenow_mcp/utils/tool_utils.py:411-417 (registration)Central registration of the tool in get_tool_definitions() dictionary. Maps tool name to handler alias, input schema, return type hint, description, and output serialization method used by the MCP server."create_catalog_item_variable": ( create_catalog_item_variable_tool, CreateCatalogItemVariableParams, Dict[str, Any], # Expects dict "Create a new catalog item variable", "dict", # Tool returns Pydantic model ),