If your organisation is moving from Donorfy, the Donorfy migration brings your constituents, transactions, activities and related records across without exporting and mapping CSV files by hand. It reads directly from your Donorfy account, and you control each stage: connecting, matching Donorfy’s settings to yours, fetching each list, and importing it.

Before you start

  • The migration must be turned on for your beehive. Donorfy migration only appears under Data In and Out when it has been enabled for your beehive by a ThirdSectorBee platform administrator. Without it, the menu item is hidden and /import/donorfy takes you back to the home page. Ask your administrator if you’re planning a migration and can’t see it.
  • Permission. Every stage needs donorfy:config:change. Creating new subtypes or settings from the Lookups stage also needs permission to manage Relationships settings.
  • Donorfy credentials. Your Donorfy Tenant code (Donorfy labels it your “API key”, under Settings) and an Access key from an API permission you create in Donorfy.
  • Lists in Donorfy. The migration imports from Donorfy lists, so create the lists you need in Donorfy first.

Plan the migration with your team. Records are written to your live beehive, and re-importing is not a rollback.

The four stages

Open Data In and Out → Donorfy migration. The page is titled Donorfy migration and has four stages, Credentials, Lookups, Lists and Import. Move between them with the stage headings or Back and Next.

1. Credentials

  1. Enter the Tenant code and Access key, then click Save.
  2. Click Test connection. It tests the saved credentials, so always save first.

Connection successful. means you can carry on. Connection failed means one of the two values is wrong. If Donorfy couldn’t be reached, try again in a moment. Once an access key is saved, the field only needs filling in to replace it. Keep access keys out of emails and support messages.

2. Lookups

The Donorfy lookups stage loads Donorfy’s settings, such as funds, payment methods and touchpoint types, and keeps them until you click Refresh from Donorfy. Nothing is imported here; you’re telling ThirdSectorBee what each Donorfy value means.

  1. Classify each constituent type. For every Donorfy constituent type, choose Import as: Contact, Organisation, Resource, Tribute fund or Skip (don’t import), and add any Subtypes. A type left unclassified blocks the constituents import.
  2. Map each lookup value onto its ThirdSectorBee equivalent. The groups cover restricted funds, payment methods, bank accounts, collection systems, touchpoint types, communications consent, tags, fundraising activities and connection types.
    • Auto-match suggests matches by name. Review them before saving.
    • To create a missing value, choose Create “…” in ThirdSectorBee in its list, or use Create n unmapped values in ThirdSectorBee for a whole group.
    • Payment settings you create here use a default currency, which the page names; you can change it in Finance settings afterwards.
    • Connection types are not created here. Add any that are missing in Relationships → Configuration → Connection types, then return.
  3. Decide where each tag category goes. Open Tags under Constituents. Each Donorfy tag category is a section you can expand to see its tags. Under Mapping, choose:
    • Individual mapping to map each tag on its own. For each tag, choose Map to:
      • Tag maps it onto a ThirdSectorBee tag. Choose Add new tag to create it now. A tag you leave unmapped is created by name when the constituents are imported.
      • Custom field sets a contact custom field when the constituent has the tag. What it writes depends on the field’s type: a text field gets the tag’s name without its category, a number field gets 1, and a yes/no field gets yes. Date fields can’t be chosen. To make a new field, choose Create custom field…, then give it a name and a data type and, if you like, restrict it to some contact subtypes.
    • All tags to one custom field to put the whole category into one text custom field. Each tag is written as its name without the category, and a contact with several tags in the category gets them all, separated by commas.

    A field for a whole category must already exist: create it in Relationships settings first.

  4. Click Save mappings.

Lists under Information have no ThirdSectorBee equivalent and are shown for reference only.

3. Lists

For each list you want to bring across, choose the Donorfy list from its dropdown. Your list names are read from Donorfy once your connection test succeeds; if you’ve created a list in Donorfy since, click Get list names from Donorfy. Each choice saves straight away and shows the list’s type and its row count and date at its last run in Donorfy. To choose again, select the bin icon.

Then click Queue fetch. A fetch moves through Queued, Preparing snapshot and Fetching rows, and ends as Completed, Failed or Incomplete.

  • Preview shows a sample of the fetched rows. It’s a read-only check; nothing is imported.
  • Failed: queue the fetch again.
  • Incomplete: not every row was collected (the page shows how many of how many). Large lists can hit Donorfy’s four-hour snapshot limit; split the list by date in Donorfy and fetch the parts.
  • Re-fetch refreshes a list’s fetched rows.

4. Import

Lists import one at a time. Import Constituents first, because every other list refers to them; until it has finished, the other lists explain what they’re waiting for.

Donorfy list Becomes
Constituent List Contacts, organisations, resources or tribute funds, according to your classification, with their tags
All Transactions List Payments
Activity List Touchpoints
Pledge Pledged payments
RPI List Recurring payments
FR Pages Fundraising pages
Membership List Memberships, also reading the fetched Members List
Connection List Connections between constituents already imported

Click Import for a list. As it runs you’ll see rows written against rows sent; when it finishes, tallies show rows processed, what was imported and as what, rows skipped and why, rows imported with missing detail, Confirmed written and Failed to write. Rely on Confirmed written, not on the number sent, and open a few of the new records before moving on to lists that depend on them.

Lists that are not imported

The page lists these with the reason:

  • Campaign: created for you in the Lookups stage instead.
  • Constituent Tag: imported with the Constituent List.
  • Members List: imported as part of the Membership List.
  • Opportunity: no equivalent record; the pledges against them are imported.
  • RPI Beneficiary: no equivalent record.
  • Gift Aid Declaration: not supported yet, because Donorfy’s declarations carry no donor address, which HMRC claims require. Plan how you’ll re-collect or record declarations; see Collect a Gift Aid declaration.

Retrying and re-importing

A failed import offers the button again; a completed one offers Re-import. Before either, correct the classification, mappings or missing dependency that caused the problem, and check what was already written. Re-importing doesn’t undo earlier records.

For CSV files from other systems, see Run an import.