ss-tools/specs/008-migration-ui-improvements/quickstart.md

Quickstart: Migration UI Improvements

Date: 2025-12-27 | Status: Draft

Overview

This guide provides step-by-step instructions for using the new Migration UI Improvements feature.

Prerequisites

• Running instance of the migration tool
• Valid user session
• At least one migration task (completed or in progress)

Installation

No additional installation required. The feature is integrated into the existing migration UI.

Using the Feature

1. Viewing Task History

Steps:

1. Navigate to the Migration Dashboard
2. Locate the "Recent Tasks" section
3. View the list of your recent migration tasks

What you'll see:

• Task ID
• Status (Pending, Running, Success, Failed, Awaiting Input)
• Start time
• "View Logs" action button

Screenshot: [Placeholder for task history screenshot]

2. Viewing Task Logs

Steps:

1. From the task history list, click "View Logs" on any task
2. A modal will open showing detailed logs

What you'll see:

• Timestamped log entries
• Log levels (INFO, WARNING, ERROR)
• Detailed error messages
• Context information for errors

Screenshot: [Placeholder for log viewer screenshot]

3. Handling Database Password Prompts

Scenario: A migration fails due to missing database password

Steps:

1. Start a migration that requires database passwords
2. When the system detects a missing password error:
   • Task status changes to "Awaiting Input"
   • A notification appears
   • The task shows "Requires Input" indicator
3. Click "View Logs" to see the specific error
4. The system will show a password prompt with:
   • Database name requiring password
   • Original error message
   • Password input field
5. Enter the required password(s)
6. Click "Submit" to resume the migration

What happens next:

• The migration resumes with the provided credentials
• Task status changes back to "Running"
• If password is incorrect, you'll be prompted again

Screenshot: [Placeholder for password prompt screenshot]

API Usage Examples

List Recent Tasks

curl -X GET \
  'http://localhost:8000/api/tasks?limit=5&offset=0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api.v1+json'

Get Task Logs

curl -X GET \
  'http://localhost:8000/api/tasks/TASK_ID/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api.v1+json'

Resume Task with Password

curl -X POST \
  'http://localhost:8000/api/tasks/TASK_ID/resume' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api.v1+json' \
  -d '{
    "passwords": {
      "PostgreSQL": "your_secure_password"
    }
  }'

Troubleshooting

Common Issues

Issue: No tasks appearing in history

• Solution: Check that you have started at least one migration task
• Solution: Verify your session is valid
• Solution: Try refreshing the page

Issue: Task stuck in "Awaiting Input" state

• Solution: Check the task logs for specific error details
• Solution: Provide the required input through the UI
• Solution: If input was provided but task didn't resume, try again

Issue: Password prompt keeps appearing

• Solution: Verify the password is correct
• Solution: Check for multiple databases requiring passwords
• Solution: Contact administrator if issue persists

Error Messages

• "Task not found": The specified task ID doesn't exist or you don't have permission
• "Task not awaiting input": The task is not in a state that requires user input
• "Invalid password": The provided password was rejected by the target system
• "Unauthorized": Your session has expired or is invalid

Configuration

Task Retention

Configure how long completed tasks are retained:

# In backend configuration
TASK_RETENTION_DAYS=30
TASK_RETENTION_LIMIT=100

Pagination Limits

Adjust default pagination limits:

# In backend configuration
DEFAULT_TASK_LIMIT=10
MAX_TASK_LIMIT=50

Best Practices

1. Monitor Tasks: Regularly check task history for failed migrations
2. Prompt Response: Respond to "Awaiting Input" tasks promptly to avoid delays
3. Log Review: Always review logs for failed tasks to understand root causes
4. Password Management: Use secure password storage for frequently used credentials
5. Session Management: Ensure your session is active before starting long migrations

Integration Guide

Frontend Integration

// Example: Fetching task list
import { getTasks } from '/src/services/taskService'

const fetchTasks = async () => {
  try {
    const response = await getTasks({ limit: 10, offset: 0 })
    setTasks(response.tasks)
    setTotal(response.total)
  } catch (error) {
    console.error('Failed to fetch tasks:', error)
  }
}

Backend Integration

# Example: Extending TaskManager
from backend.src.core.task_manager import TaskManager

class EnhancedTaskManager(TaskManager):
    def get_tasks_for_user(self, user_id, limit=10, offset=0):
        # Implement user-specific task filtering
        pass

Support

For issues not covered in this guide:

• Check the main documentation
• Review API contract specifications
• Contact support team with error details

Changelog

2025-12-27: Initial release

• Added task history viewing
• Added task log inspection
• Added interactive password prompts
• Added API endpoints for task management

Feedback

Provide feedback on this feature:

• What works well
• What could be improved
• Additional use cases to support

[Feedback Form Link Placeholder]

Next Steps

1. Try the feature with a test migration
2. Familiarize yourself with the error patterns
3. Integrate with your existing workflows
4. Provide feedback for improvements