list_change_requests
Retrieve and filter change requests from ServiceNow by assignment group, category, state, timeframe, or type to streamline change management processes.
Instructions
List change requests from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Implementation Reference
- Main handler function implementing the logic to list change requests from ServiceNow API, including parameter validation, query building, and HTTP request.
def list_change_requests( auth_manager: AuthManager, server_config: ServerConfig, params: Dict[str, Any], ) -> Dict[str, Any]: """ List change requests from ServiceNow. Args: auth_manager: The authentication manager. server_config: The server configuration. params: The parameters for listing change requests. Returns: A list of change requests. """ # Unwrap and validate parameters result = _unwrap_and_validate_params( params, ListChangeRequestsParams ) if not result["success"]: return result validated_params = result["params"] # Build the query query_parts = [] if validated_params.state: query_parts.append(f"state={validated_params.state}") if validated_params.type: query_parts.append(f"type={validated_params.type}") if validated_params.category: query_parts.append(f"category={validated_params.category}") if validated_params.assignment_group: query_parts.append(f"assignment_group={validated_params.assignment_group}") # Handle timeframe filtering if validated_params.timeframe: now = datetime.now().strftime("%Y-%m-%d %H:%M:%S") if validated_params.timeframe == "upcoming": query_parts.append(f"start_date>{now}") elif validated_params.timeframe == "in-progress": query_parts.append(f"start_date<{now}^end_date>{now}") elif validated_params.timeframe == "completed": query_parts.append(f"end_date<{now}") # Add any additional query string if validated_params.query: query_parts.append(validated_params.query) # Combine query parts query = "^".join(query_parts) if query_parts else "" # Get the instance URL instance_url = _get_instance_url(auth_manager, server_config) if not instance_url: return { "success": False, "message": "Cannot find instance_url in either server_config or auth_manager", } # Get the headers headers = _get_headers(auth_manager, server_config) if not headers: return { "success": False, "message": "Cannot find get_headers method in either auth_manager or server_config", } # Make the API request url = f"{instance_url}/api/now/table/change_request" params = { "sysparm_limit": validated_params.limit, "sysparm_offset": validated_params.offset, "sysparm_query": query, "sysparm_display_value": "true", } try: response = requests.get(url, headers=headers, params=params) response.raise_for_status() result = response.json() # Handle the case where result["result"] is a list change_requests = result.get("result", []) count = len(change_requests) return { "success": True, "change_requests": change_requests, "count": count, "total": count, # Use count as total if total is not provided } except requests.exceptions.RequestException as e: logger.error(f"Error listing change requests: {e}") return { "success": False, "message": f"Error listing change requests: {str(e)}", } - Pydantic model defining the input parameters and their validation for the list_change_requests tool.
class ListChangeRequestsParams(BaseModel): """Parameters for listing change requests.""" limit: Optional[int] = Field(10, description="Maximum number of records to return") offset: Optional[int] = Field(0, description="Offset to start from") state: Optional[str] = Field(None, description="Filter by state") type: Optional[str] = Field(None, description="Filter by type (normal, standard, emergency)") category: Optional[str] = Field(None, description="Filter by category") assignment_group: Optional[str] = Field(None, description="Filter by assignment group") timeframe: Optional[str] = Field(None, description="Filter by timeframe (upcoming, in-progress, completed)") query: Optional[str] = Field(None, description="Additional query string") - src/servicenow_mcp/utils/tool_utils.py:504-510 (registration)Tool registration entry in get_tool_definitions dictionary, mapping the tool name to its handler function, input schema, description, and serialization details.
"list_change_requests": ( list_change_requests_tool, ListChangeRequestsParams, str, # Expects JSON string "List change requests from ServiceNow", "json", # Tool returns list/dict ), - src/servicenow_mcp/tools/__init__.py:23-32 (registration)Import of the list_change_requests function for re-export in the tools package.
from servicenow_mcp.tools.change_tools import ( add_change_task, approve_change, create_change_request, get_change_request_details, list_change_requests, reject_change, submit_change_for_approval, update_change_request, ) - Helper function used by the handler to unwrap, validate, and parse input parameters against the Pydantic schema.
def _unwrap_and_validate_params(params: Any, model_class: Type[T], required_fields: List[str] = None) -> Dict[str, Any]: """ Helper function to unwrap and validate parameters. Args: params: The parameters to unwrap and validate. model_class: The Pydantic model class to validate against. required_fields: List of required field names. Returns: A tuple of (success, result) where result is either the validated parameters or an error message. """ # Handle case where params might be wrapped in another dictionary if isinstance(params, dict) and len(params) == 1 and "params" in params and isinstance(params["params"], dict): logger.warning("Detected params wrapped in a 'params' key. Unwrapping...") params = params["params"] # Handle case where params might be a Pydantic model object if not isinstance(params, dict): try: # Try to convert to dict if it's a Pydantic model logger.warning("Params is not a dictionary. Attempting to convert...") params = params.dict() if hasattr(params, "dict") else dict(params) except Exception as e: logger.error(f"Failed to convert params to dictionary: {e}") return { "success": False, "message": f"Invalid parameters format. Expected a dictionary, got {type(params).__name__}", } # Validate required parameters are present if required_fields: for field in required_fields: if field not in params: return { "success": False, "message": f"Missing required parameter '{field}'", } try: # Validate parameters against the model validated_params = model_class(**params) return { "success": True, "params": validated_params, } except Exception as e: logger.error(f"Error validating parameters: {e}") return { "success": False, "message": f"Error validating parameters: {str(e)}", }