list_workflow_versions

Retrieve and manage workflow version history from ServiceNow to track changes, compare iterations, and maintain process documentation.

Instructions

List workflow versions from ServiceNow

Input Schema

TableJSON Schema

Name	Required	Description
`workflow_id`	Yes	Workflow ID or sys_id
`limit`	No	Maximum number of records to return
`offset`	No	Offset to start from

Implementation Reference

src/servicenow_mcp/tools/workflow_tools.py:300-357 (handler)

The main handler function that executes the tool logic: unwraps parameters using ListWorkflowVersionsParams schema, authenticates, queries the ServiceNow wf_workflow_version table API with workflow_id filter, and returns versions list with metadata.

def list_workflow_versions(
    auth_manager: AuthManager,
    server_config: ServerConfig,
    params: Dict[str, Any],
) -> Dict[str, Any]:
    """
    List versions of a specific workflow.
    
    Args:
        auth_manager: Authentication manager
        server_config: Server configuration
        params: Parameters for listing workflow versions
        
    Returns:
        Dict[str, Any]: List of workflow versions
    """
    # Unwrap parameters if needed
    params = _unwrap_params(params, ListWorkflowVersionsParams)
    
    # Get the correct auth_manager and server_config
    try:
        auth_manager, server_config = _get_auth_and_config(auth_manager, server_config)
    except ValueError as e:
        logger.error(f"Error getting auth and config: {e}")
        return {"error": str(e)}
    
    workflow_id = params.get("workflow_id")
    if not workflow_id:
        return {"error": "Workflow ID is required"}
    
    # Convert parameters to ServiceNow query format
    query_params = {
        "sysparm_query": f"workflow={workflow_id}",
        "sysparm_limit": params.get("limit", 10),
        "sysparm_offset": params.get("offset", 0),
    }
    
    # Make the API request
    try:
        headers = auth_manager.get_headers()
        url = f"{server_config.instance_url}/api/now/table/wf_workflow_version"
        
        response = requests.get(url, headers=headers, params=query_params)
        response.raise_for_status()
        
        result = response.json()
        return {
            "versions": result.get("result", []),
            "count": len(result.get("result", [])),
            "total": int(response.headers.get("X-Total-Count", 0)),
            "workflow_id": workflow_id,
        }
    except requests.RequestException as e:
        logger.error(f"Error listing workflow versions: {e}")
        return {"error": str(e)}
    except Exception as e:
        logger.error(f"Unexpected error listing workflow versions: {e}")
        return {"error": str(e)}

src/servicenow_mcp/tools/workflow_tools.py:40-46 (schema)

Pydantic model defining the input parameters for the tool: required workflow_id, optional limit and offset for pagination.

class ListWorkflowVersionsParams(BaseModel):
    """Parameters for listing workflow versions."""
    
    workflow_id: str = Field(..., description="Workflow ID or sys_id")
    limit: Optional[int] = Field(10, description="Maximum number of records to return")
    offset: Optional[int] = Field(0, description="Offset to start from")

src/servicenow_mcp/utils/tool_utils.py:550-556 (registration)
Tool registration in get_tool_definitions(): maps name to (aliased handler, input schema, return type hint, description, serialization method) used by MCP server.
```
"list_workflow_versions": (
    list_workflow_versions_tool,
    ListWorkflowVersionsParams,
    str,  # Expects JSON string
    "List workflow versions from ServiceNow",
    "json",  # Tool returns list/dict
),
```

src/servicenow_mcp/tools/__init__.py:78-91 (registration)

Imports list_workflow_versions from workflow_tools.py into tools namespace for exposure.

from servicenow_mcp.tools.workflow_tools import (
    activate_workflow,
    add_workflow_activity,
    create_workflow,
    deactivate_workflow,
    delete_workflow_activity,
    get_workflow_activities,
    get_workflow_details,
    list_workflow_versions,
    list_workflows,
    reorder_workflow_activities,
    update_workflow,
    update_workflow_activity,
)

ServiceNow MCP Server