submit_change_for_approval

Submit a ServiceNow change request for approval by providing the change ID and optional comments to initiate the approval workflow.

Instructions

Submit a change request for approval

Input Schema

TableJSON Schema

Name	Required	Description	Default
`change_id`	Yes	Change request ID or sys_id
`approval_comments`	No	Comments for the approval request

Implementation Reference

src/servicenow_mcp/tools/change_tools.py:669-755 (handler)

The core handler function implementing the submit_change_for_approval tool logic: validates params, updates change request state to 'assess', creates approval record in sysapproval_approver table.

def submit_change_for_approval(
    auth_manager: AuthManager,
    server_config: ServerConfig,
    params: Dict[str, Any],
) -> Dict[str, Any]:
    """
    Submit a change request for approval in ServiceNow.

    Args:
        auth_manager: The authentication manager.
        server_config: The server configuration.
        params: The parameters for submitting a change request for approval.

    Returns:
        The result of the submission.
    """
    # Unwrap and validate parameters
    result = _unwrap_and_validate_params(
        params, 
        SubmitChangeForApprovalParams,
        required_fields=["change_id"]
    )
    
    if not result["success"]:
        return result
    
    validated_params = result["params"]
    
    # Prepare the request data
    data = {
        "state": "assess",  # Set state to "assess" to submit for approval
    }
    
    # Add approval comments if provided
    if validated_params.approval_comments:
        data["work_notes"] = validated_params.approval_comments
    
    # 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",
        }
    
    # Add Content-Type header
    headers["Content-Type"] = "application/json"
    
    # Make the API request
    url = f"{instance_url}/api/now/table/change_request/{validated_params.change_id}"
    
    try:
        response = requests.patch(url, json=data, headers=headers)
        response.raise_for_status()
        
        # Now, create an approval request
        approval_url = f"{instance_url}/api/now/table/sysapproval_approver"
        approval_data = {
            "document_id": validated_params.change_id,
            "source_table": "change_request",
            "state": "requested",
        }
        
        approval_response = requests.post(approval_url, json=approval_data, headers=headers)
        approval_response.raise_for_status()
        
        approval_result = approval_response.json()
        
        return {
            "success": True,
            "message": "Change request submitted for approval successfully",
            "approval": approval_result["result"],
        }
    except requests.exceptions.RequestException as e:
        logger.error(f"Error submitting change for approval: {e}")
        return {
            "success": False,
            "message": f"Error submitting change for approval: {str(e)}",
        }

src/servicenow_mcp/tools/change_tools.py:84-89 (schema)

Pydantic BaseModel defining input schema for the tool: requires change_id, optional approval_comments.

class SubmitChangeForApprovalParams(BaseModel):
    """Parameters for submitting a change request for approval."""

    change_id: str = Field(..., description="Change request ID or sys_id")
    approval_comments: Optional[str] = Field(None, description="Comments for the approval request")

src/servicenow_mcp/utils/tool_utils.py:468-474 (registration)

MCP tool registration in get_tool_definitions(): maps name to (handler alias, schema, return type, description, serialization).

"submit_change_for_approval": (
    submit_change_for_approval_tool,
    SubmitChangeForApprovalParams,
    str,
    "Submit a change request for approval",
    "str",  # Tool returns simple message
),

src/servicenow_mcp/tools/__init__.py:23-32 (registration)

Export/import of the handler function in tools package __init__.py for module-level access.

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,
)

src/servicenow_mcp/utils/tool_utils.py:84-85 (helper)
Import alias of the handler as submit_change_for_approval_tool used in MCP registration.
```
    submit_change_for_approval as submit_change_for_approval_tool,
)
```

ServiceNow MCP Server