Migrating Your Historical Data

If you have existing data in Virtuous that you want to bring into WeGive, we recommend importing it manually using WeGive's Import Tool rather than relying on the integration's initial sync function. This article explains why and walks you through the process.

Why Manual Import Instead of Sync

The Virtuous integration includes a "Begin Sync from Virtuous" option that pulls your historical data over automatically. However, Virtuous's API has rate limits that cause frequent timeouts on larger datasets. When a sync times out, you have to restart it and hope it gets further before hitting the limit again. For organizations with thousands of contacts or transactions, this process can be unreliable and time-consuming.

Importing your data manually through WeGive's Import Tool gives you more control. You can work in manageable batches, verify each import step before moving on, and avoid the back-and-forth of dealing with API timeouts. It's also easier to catch and fix data issues when you're reviewing a CSV file than when you're watching a sync log.

If your Virtuous database is very small (a few hundred contacts and transactions), the sync function may work fine. For everyone else, manual import is the more reliable path.

Before You Start

Make sure you've completed everything in Prerequisites & Before You Begin, especially:

• The wg_id custom field has been created in Virtuous

• Duplicate emails have been cleaned up

• Unsupported recurring frequencies have been removed from your checkouts

Also, before importing any data, navigate to Engagement > Triggers in WeGive and pause all triggered messages. This prevents automated emails from firing as records are created during import.

Export Your Data from Virtuous

You'll need to export your data from Virtuous as CSV files. Use Virtuous's reporting and export tools to pull the following datasets:

• Contacts (both individuals and organizations)

• Projects (these map to Funds in WeGive)

• Segments (these map to Campaigns in WeGive)

• Gifts/Transactions

• Recurring Gifts

Export each data type into its own CSV file. Make sure your exports include Virtuous IDs for each record, as these will help WeGive match records correctly once the integration is running.

For specific instructions on exporting from Virtuous, refer to Virtuous's help documentation or contact their support team.

Prepare Your CSV Files

Before importing into WeGive, review your CSV files to make sure they meet WeGive's requirements.

File format: CSV (.csv) only. Maximum 50,000 records per file. If you have more, split into multiple files.

Date formatting: Dates must use YYYY-MM-DD format (e.g., 2024-09-12). DateTimes must use YYYY-MM-DDTHH:MM:SSZ format (e.g., 2024-09-12T15:30:00Z). Note the "T" between the date and time, not a space.

Required fields by data type:

Recurring plan frequencies must be exactly one of: Daily, Weekly, Every 2 Weeks, 1st & 15th, Monthly, Quarterly, Annually

Boolean fields use 1 for true and 0 for false.

Import Order

Import your data in this order. Each step depends on the one before it, so don't skip ahead.

Step 1: Contacts/Supporters. Import individual supporters first, then company supporters. These need to exist in WeGive before you can attach transactions or recurring plans to them.

Step 2: Funds/Designations. Import your Virtuous projects as funds in WeGive. Transactions reference funds, so these need to be in place first.

Step 3: Campaigns. Import your Virtuous segments as campaigns in WeGive.

Step 4: Transactions/Donations. Import your historical gifts. Each transaction must reference a donor that already exists in WeGive (by email or WeGive ID).

Step 5: Recurring Plans. Import active recurring donation plans last. Each plan must reference an existing donor.

How to Import

For each data type, follow these steps:

1. In WeGive, navigate to Data > Imports

2. Click the "+" icon to start a new import

3. Select Create as the import action

4. Select the data type you're importing (e.g., Individual Supporters)

5. Upload your CSV file

6. Map your CSV columns to the corresponding WeGive fields

7. Review the preview to make sure everything looks correct

8. Confirm and run the import

After each import completes, check the results on the Data > Imports page. Download the error report if any records failed and fix the issues before moving on to the next data type.

Tip: Import 1-2 test records first for each data type to make sure your field mapping and formatting are correct before running the full file.

Verify Your Data

After all imports are complete, take time to verify that everything came over correctly:

• Spot-check a handful of supporter records to make sure names, emails, addresses, and phone numbers imported accurately

• Verify that transactions are attached to the correct donors with the right amounts and dates

• Confirm that recurring plans show the correct frequency and amounts

• Check that funds and campaigns imported with the right names

Once you're satisfied the data looks good, you can enable the Virtuous integration (see Connecting WeGive to Virtuous) and it will keep everything in sync going forward. Don't forget to re-enable your triggered messages in Engagement > Triggers after the migration is complete.