create_catalog_item_variable
Add custom fields to ServiceNow catalog items to collect specific information from users during service requests.
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
- The core handler function that implements the tool logic by constructing a POST request to the ServiceNow item_option_new API endpoint 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 model defining the input schema (parameters) 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")
- Pydantic model defining the output schema for the create_catalog_item_variable tool.class CatalogItemVariableResponse(BaseModel): """Response from catalog item variable operations.""" success: bool = Field(..., description="Whether the operation was successful") message: str = Field(..., description="Message describing the result") variable_id: Optional[str] = Field(None, description="The sys_id of the created/updated variable") details: Optional[Dict[str, Any]] = Field(None, description="Additional details about the variable")
- src/servicenow_mcp/utils/tool_utils.py:457-463 (registration)Registration of the tool in the get_tool_definitions() dictionary, specifying the aliased handler, input schema, return type hint, description, and serialization method for MCP integration."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 ),