Skip to content

GUI

Jump to bottom
Jeffrie Budde edited this page Apr 10, 2026 · 1 revision

Graphical interface

The GUI provides a multi-step wizard built with PySide6 that guides users through the migration process with visual feedback, environment analysis, and real-time progress monitoring. It uses the same migration logic as the CLI, ensuring consistent behavior.

Installation

The GUI requires PySide6. Install with:

# Install GUI package
pip install -e packages/gui

# Or use the launcher from GUI package
onelogin-migration-gui

Launching the GUI

onelogin-migration-gui --config config/migration.yaml

Or via the main CLI:

python -m onelogin_migration_gui.main

Options:

  • --config PATH - Path to YAML config (defaults to config/migration.yaml)
  • --export PATH - Optional pre-generated source export (skips the export phase)
  • -v, --verbose - Enable debug logging in terminal

Auto-configuration: If the config file doesn't exist, the GUI automatically copies migration.template.yaml as a starting point.

Wizard steps

The GUI uses an 8-step wizard workflow:

1. Welcome

  • Introduction to the OneLogin Migration Wizard
  • Overview of the migration process
  • Quick start instructions

2. Source

  • Configure source provider credentials
    • Provider selection (Okta, and others as configured)
    • Domain
    • API token
    • Rate limits
  • Test Connection button validates credentials
  • Shows connected status with checkmark
  • Credentials auto-save to system keyring on successful test

3. Target (OneLogin)

  • Configure OneLogin API credentials
    • Client ID
    • Client secret
    • Region (US/EU)
    • Subdomain
  • Test Connection button validates OAuth flow
  • Displays authentication status

4. Options

Configure migration behavior:

  • Dry-run mode - Simulate without writing
  • Verbose logging - Enable debug output
  • Concurrency - Enable multi-threading
  • Worker threads - Control parallelism
  • Export directory - Where to save artifacts

5. Objects

Select what to migrate:

  • ☑ Users
  • ☑ Groups (as OneLogin roles)
  • ☑ Applications
  • ☐ Policies (not yet supported)

Toggle categories on/off before migration.

6. Analysis

Comprehensive environment analysis with detailed reports:

Features:

  • Analyze Source Environment - Fetches and analyzes your source provider data
  • User Analysis:
    • Total user count and status breakdown
    • Custom attribute discovery
    • Profile field statistics
    • Export to CSV/XLSX
  • Group Analysis:
    • Group count and membership statistics
    • Nested group detection
    • Member distribution
    • Export to CSV/XLSX
  • Application Analysis:
    • Application count by protocol (SAML, OIDC, etc.)
    • OneLogin connector matching recommendations
    • Configuration details
    • Export to CSV/XLSX
  • Custom Attribute Recommendations:
    • Fields requiring custom attributes
    • Normalized attribute names
    • Data type analysis
    • Export list

Export Options:

  • CSV format (lightweight, universally compatible)
  • XLSX format (Excel-compatible with formatting)

Detail Dialogs:

  • Click "View Details" for in-depth analysis
  • Sortable, searchable data tables
  • Real-time filtering
  • Connector ID lookup for applications

7. Summary

Review all settings before migration:

  • Source configuration (provider, domain, rate limits)
  • Target configuration (OneLogin)
  • Migration options
  • Selected categories

Start Migration button begins the process.

8. Progress

Real-time migration monitoring:

  • Per-category progress bars
    • Users: X/Y completed
    • Groups: X/Y completed
    • Applications: X/Y completed
  • Overall progress percentage
  • Live log stream with color-coded messages
  • Status indicator (Running, Complete, Error)
  • Stop button to cancel migration

Features

Connection testing

Both Okta and OneLogin steps include connection testing:

  • Validates credentials before migration
  • Tests API connectivity
  • Verifies permissions
  • Shows clear success/error messages

Environment analysis

Comprehensive pre-migration analysis:

  • User, group, and application inventory
  • Custom attribute discovery
  • OneLogin connector recommendations
  • Export analysis to CSV/XLSX
  • Detailed data views with sorting and filtering

Real-time progress

Progress tracking provides:

  • Per-category completion counts
  • Visual progress bars
  • Overall migration percentage
  • Live log streaming
  • Color-coded status messages

State persistence

  • Migration state saved automatically
  • Resume capability after cancellation
  • Skip already-migrated items on restart
  • ID mappings preserved between runs

Theme support

Light and dark themes:

  • Automatic OS theme detection
  • Manual theme toggle
  • Consistent styling across all dialogs

Error handling

Graceful error management:

  • Network errors displayed in dialogs
  • Invalid credentials caught during testing
  • API failures shown with details
  • Migration continues for other items
  • State saved before exit

Navigation

Navigation buttons:

  • Next - Advance to next step (enabled when current step valid)
  • Back - Return to previous step
  • Cancel - Exit wizard (confirmation required if migration running)

Keyboard shortcuts:

  • Enter - Advance to next step (when valid)
  • Esc - Cancel wizard
  • Ctrl+S - Save configuration

Workflow example

Safe exploration:

  1. Launch GUI: python -m onelogin_migration_gui.main
  2. Step through wizard entering credentials
  3. Test connections on Source and Target steps
  4. Enable dry-run mode in Options
  5. Select categories in Objects
  6. Review Summary and click Start Migration
  7. Watch Progress as migration runs
  8. Review logs and exported artifacts

Production migration:

  1. Run dry-run first to validate
  2. Return to Options step and disable dry-run
  3. Navigate to Summary
  4. Click Start Migration
  5. Monitor progress bars and logs
  6. Wait for completion
  7. Verify results in OneLogin Admin Console

Comparison with CLI

Feature GUI CLI
Connection testing ✓ Built-in Manual via API calls
Configuration editing ✓ Visual editor Text editor required
Real-time progress ✓ Visual bars Text progress indicators
Resume capability ✓ Automatic ✓ Automatic
Suitable for Interactive use Automation/scripting
Dependencies PySide6 required No GUI dependencies

Troubleshooting

GUI won't launch:

# Ensure PySide6 is installed
pip install .[gui]

# Check for errors with verbose mode
onelogin-migration-tool gui -v

Connection test fails:

  • Verify credentials in configuration
  • Check API token/client secret hasn't expired
  • Confirm region is correct (us/eu)
  • Test network connectivity to APIs
  • Review terminal logs with -v flag

Migration gets stuck:

  • Check terminal for error messages (use -v)
  • Click Stop and review logs
  • Verify rate limits aren't being exceeded
  • Check for network interruptions
  • Try resuming - state is saved automatically

State not persisting:

  • Ensure export_directory is writable
  • Check disk space for migration_state.json
  • Review file permissions
  • Look for migration_state.json in export directory

Advanced usage

Using pre-generated export:

# 1. Generate export via CLI
onelogin-migration plan --config config/migration.yaml \
  --output source_export.json

# 2. Launch GUI with export
python -m onelogin_migration_gui.main --config config/migration.yaml \
  --export source_export.json

Bulk CSV workflow:

  1. Enable bulk_user_upload in Options step
  2. Complete migration to generate CSV
  3. Find bulk_user_upload_{timestamp}.csv in export directory
  4. Upload CSV manually in OneLogin Admin Console
  5. Users → Import Users → Upload CSV

Debug mode:

# Run GUI with maximum verbosity
python -m onelogin_migration_gui.main --config config/migration.yaml -v

Watch terminal for detailed logs while GUI runs.

Clone this wiki locally