Skip to main content

Getting Started

This guide walks you through setting up The One Migrate and running your first migration job from end to end.

  1. Log in to your Hub account at my.theonestack.com.
  2. In the Hub Bar at the top, click Migrate (the FolderSync icon). This opens app.theonemigrate.app and signs you in automatically via Hub SSO.

Initial Setup Checklist​

  • Hub organization with Migrate access
  • At least one desktop agent registered (see Agents)
  • Azure Storage account connected (for file/mailbox jobs)
  • The One Mission organization with integration key ready (for RockRMS jobs)
  • At least one Client created
  • At least one Project created under that client

Key Concepts​

Client​

A Client represents one of your managed customers. Everything in Migrate is scoped to a client: projects, jobs, and usage stats roll up per client.

Project​

A Project is the container for a migration engagement. It defines:

  • The project type (file migration, mailbox migration, archive, full migration, or RockRMS import)
  • The Azure Storage connection (OAuth-linked account, container, storage tier)
  • Optional bandwidth schedule (e.g., full speed 6 PM–6 AM, throttled during business hours)
  • Linked PSA ticket and project IDs for billing and tracking

One project can contain many jobs. For example, a "Full Migration — Acme Corp" project might have separate jobs for files, mailboxes, and data imports.

Agent​

The desktop agent runs on a machine at your client's site (or your MSP's office) and executes the actual data transfer. The cloud dashboard dispatches jobs to agents and receives live progress back.

Job​

A Job is one unit of migration work assigned to a specific agent. It includes the source (where data comes from), destination (where it goes), filters (age, file patterns), and transfer config (concurrency, chunk size, bandwidth limit).

Job Lifecycle​

created → scanning → ready → running → completed
                                  └→ paused
                                  └→ failed
                                  └→ cancelled

The agent scans the source first to determine total file/byte counts (scanning), becomes ready, then begins uploading (running). You can pause or cancel from the dashboard at any time.

First Migration Job — End to End​

Step 1: Create a Client​

  1. From the sidebar, click Clients → New Client.
  2. Enter:
    • Name — your customer's company name
    • Contact Name and Contact Email — optional, for your reference
    • PSA Company ID — optional, links to a PSA company record
  3. Click Save. The client is created with status active.

Step 2: Register an Agent​

See Agents for full installation instructions. The short version:

  1. Go to Settings → Headless Agent Registration → click Generate Code.
  2. Copy the 8-character code (valid for 24 hours).
  3. On the client's machine, run: 
    migrate-agent --register <CODE>
  4. The agent appears in the Agents list with status Online.

Step 3: Create a Project​

  1. Click Projects → New Project.
  2. Select the Client you just created.
  3. Choose a Project Type:
    • File Migration — local or cloud files to Azure Blob / OneDrive / SharePoint
    • Mailbox Migration — Exchange or M365 mailboxes between tenants
    • Archive — move files to Azure Blob Cool or Archive tier
    • Full Migration — combination of file and mailbox jobs
    • RockRMS Import — import from a RockRMS database to The One Mission
  4. Enter a Project Name.
  5. For file/mailbox/archive projects, click Connect Azure Storage:
    • Sign in with a Microsoft account that has Storage Blob Data Contributor on the target storage account.
    • Select the storage account, container, and storage tier (Hot / Cool / Cold / Archive).
    • Set an optional blob prefix (e.g., acme-corp/files).
  6. Optionally set a Bandwidth Schedule — set the window when full-speed transfers are allowed and the throttled speed in Mbps outside that window.
  7. Click Create Project.

Step 4: Create a Job​

  1. From the project page, click New Job.
  2. Select the Agent to run this job.
  3. Enter a Job Name (e.g., "Acme Corp — C:\Users\Files — Jan 2026").
  4. Choose the Job Type (must match the project type).
  5. Configure the Source:
    • For local files: enter the local path (e.g., C:\Users or /home)
    • For OneDrive/SharePoint: enter the source Microsoft tenant ID
    • For Google Drive / Dropbox: enter account credentials
    • For RockRMS: enter the SQL Server connection string and select campuses
  6. Configure the Destination (defaults to the project's Azure connection).
  7. Set optional Filters: only include files older than a certain date, include/exclude file patterns.
  8. Adjust Transfer Config:
    • Concurrency — parallel upload streams (default: 4, max: 32)
    • Chunk size — upload chunk size in MB (default: 8, max: 256)
    • Bandwidth limit — Mbps cap (overrides project schedule for this job)
    • Verify integrity — SHA-256 checksum after upload (default: on)
    • Delete after upload — remove source files after successful transfer (default: off, use with caution)
  9. Click Create Job.

The job is created with status created. The dashboard automatically dispatches a start_job command to the assigned agent. Within seconds, the agent begins scanning the source.

Step 5: Monitor Progress​

  1. The job appears on the Jobs page and in the Dashboard → Active Jobs panel.
  2. Click the job to see:
    • Files: completed / total / failed / skipped
    • Bytes: completed / total
    • Current transfer speed
    • Estimated time remaining
  3. To pause a running job: click Pause on the job detail page. The command delivers to the agent within ~10 seconds.
  4. To resume: click Resume.
  5. To cancel: click Cancel. Cancellation is immediate; any files already uploaded remain at the destination.

Step 6: Review the Report​

When the job reaches completed (or failed), a report is automatically available:

  • Duration, GB transferred, file count, success rate
  • CSV export for client documentation

Navigate to Reports → select the job → Export CSV.