Currently supported data source: KeyPay
A typical migration takes 5-10 minutes to complete, varying based on employee count and timesheet volume.
Prerequisites
Before starting a migration, ensure you have:
Definitiv Database Provisioned - A new Definitiv database must be provisioned with a user account created with appropriate database rights. This is typically handled by your implementation consultant.
Schema/Client Name - Your unique database schema identifier, provided by your implementation team.
Manage Data Migrations Permission - Your user account must have the “Manage Data Migrations” permission assigned. This permission is found under the Configuration category in User Permissions and requires two-factor authentication to be enabled on your account.
Accessing Data Migration
Navigate to the Organisation dropdown menu in the top navigation.
2.Select Data Migration.
3.The Data Migration interface will load.
Starting a Migration
Step 1: Configure the Migration
Select Data Source - Choose “KeyPay” from the Data Source dropdown.
Enter Database Schema Name - Input the schema/client name provided to you.
Step 2: Review Migration Steps
Once you select a data source, the migration playbook loads displaying all migration steps. The playbook shows:
Playbook Name and Version - Identifies the migration configuration being used
Migration Steps List - All data categories that will be migrated
You can optionally: - Search steps - Filter the list to find specific migration steps - Enable/Disable steps - Use checkboxes to include or exclude specific steps (advanced users only)
Step 3: Start the Migration
Click Start Migration to begin the process. The button will change to “Migrating…” while the process runs.
What Gets Migrated
The migration imports data in the following categories:
Organisation Setup - Organisation details, default departments, projects, roles, and award template configurations.
Organisational Structure - Locations, pay items (additions, deductions, leave, accruals, reimbursements).
Configuration - Pay calendars, employment types, accrual types, organisation bank accounts.
Employee Data - Employee records, contact information, emergency contacts, employment records, tax declarations, superannuation details, bank accounts, additions/deductions, pay calendar assignments, work schedules, location assignments, leave policy assignments, and custom pay policies.
Time Attendance - Timesheets and leave applications. This data is included to support payroll reconciliations with the external system during the transition period.
Monitoring Progress
During migration, the interface displays:
Progress Bar - Visual indicator showing completion percentage.
Current Step - The migration step currently being processed.
Records Processed - Running count of records migrated.
Migration Logs - Real-time log entries showing detailed progress.
Log Filtering
Use the Errors & Warnings Only checkbox to filter the log display and focus on issues that may need attention.
Migration Statuses
Status | Description |
Queued | Migration is queued and waiting to start |
Processing | Migration is actively running |
Completed | Migration finished successfully |
Completed With Errors | Migration finished but some records had errors |
Failed | Migration encountered a fatal error |
Cancelled | Migration was cancelled by user |
Reset | Migration data has been purged |
Viewing Migration History
Click View History to open the Process History drawer, which displays:
Process ID - Unique identifier for each migration.
Data Source - The source system (e.g., KeyPay).
Status - Current status of the migration.
Records - Number of records processed.
From the history, you can:
View - Restore a previous migration’s logs and progress details.
Purge - Remove all data from a completed migration (most recent only).
Purging a Migration
If you need to reset your database to its original state (before the migration), you can purge the migration data.
When to Purge
Test migration completed and you want to start fresh.
Migration completed with errors and you want to retry.
Data needs to be re-migrated from source.
How to Purge
Click View History.
Locate the most recent migration.
Click the Purge button (only available on the most recent completed migration).
Review the warning message carefully.
Click Yes, Purge Migration to confirm.
What Gets Deleted
Purging permanently removes all data migrated as part of that process:
All employee records and their associated data.
Time attendance data including timesheets and leave applications
Organisational structure (departments, locations, roles)
Policies and configurations
Warning: This action cannot be undone.
Post-Migration Steps
Once migration completes successfully:
Review the logs - Check for any warnings or errors that may need attention.
Verify data - Spot-check employee records, organisational structure, and time attendance data.
Configure remaining settings - Some settings may require manual configuration after migration.
Test payroll - Run a test pay cycle to ensure all data migrated correctly.
Troubleshooting
Migration Won’t Start
Problem: Clicking “Start Migration” does nothing or shows an error
Solutions: - Ensure both Data Source and Database Schema Name are filled in - Check that no other migration is currently running (only one migration can run at a time) - Verify you have the ManageDataMigrations permission
Migration Shows “Completed With Errors”
Problem: Migration finished but reported errors
Solutions: - Review the migration logs for specific error messages - Filter logs to “Errors & Warnings Only” to identify issues - Common causes include missing required data in the source system or data format mismatches - You may need to fix source data and re-run the migration (purge first if needed) - Alternatively, depending on the size of the issue, it is possible to exit migration and correct the data directly in Definitiv screens or via Workbooks
Migration Failed
Problem: Migration stopped with “Failed” status
Solutions: - Check the logs for the fatal error message - Common causes include database connectivity issues or invalid schema name - Verify your schema name is correct - Contact support if the error persists
Cannot Purge Migration
Problem: Purge button is disabled or unavailable
Solutions: - Only the most recent migration can be purged - Cannot purge a migration that is currently processing - Cannot purge a migration that has already been reset - Cannot purge a migration that failed (no data to purge)
Migration Taking Too Long
Problem: Migration seems stuck or is taking longer than expected
Solutions: - Large datasets may take longer - check the Records Processed counter to confirm progress - Monitor the Current Step to see if processing is advancing - A typical migration takes 5-10 minutes, varying based on employee and timesheet counts - If truly stuck, contact support by raising a case online.
Schema Name Not Working
Problem: Migration fails immediately with schema-related error
Solutions: - Verify the exact schema name provided by your implementation team - Schema names are case-sensitive - Ensure there are no extra spaces before or after the schema name.
Getting Help
If you encounter issues not covered in this guide, contact your Definitiv implementation team or support representative with:
The Process ID from your migration.
Screenshots of any error messages.
The migration logs (can be viewed by clicking View History and selecting the migration)