Importing data into Administrate

Overview

The Import feature enables organizations to import and manage their data at scale. Users can create or update records in bulk for Accounts, Contacts, Events, Course Templates, Resources, and all other entities in the system. This tool automates the data upsert process, eliminating manual, repetitive tasks and reducing errors.

Why We Built This

Teams entered data manually or waited for support to help with large imports. Both options wasted time. We built this tool to fix that problem.

Who this helps:

• Implementation teams load data faster during setup.
• Customers update large amounts of data in bulk without waiting for support.
• The tool removes the bottleneck. You move data in bulk. You do it yourself.

What Is It?

The import tool uses our GraphQL API to handle large data uploads. When we add new entities, fields, or operations to the API, they show up in the import tool automatically. No waiting for updates.

You pick what you want to import, such as Events. You pick what you want to do, such as Create or Update. You download the template CSV. You fill it with your data. You upload it.

That's the process.

The system processes imports asynchronously, providing detailed success and failure reports for visibility into import results.

Key Features

• Universal Entity Support
• Custom Fields Support
• Directly leverages the GraphQL API schema to stay consistent with platform capabilities.
• Auto Scalable
• Detailed Error Reporting
• Advanced lookup options: customize lookups to find records by name, ID, or other supported fields.

How It Works

Pick Entity and Operation, such as Accounts and Create → Download CSV → Fill Data in CSV → Upload CSV → Queue → Background Processes import → Result shown with error reporting.

Each row in the CSV becomes an individual GraphQL mutation call, processed with the same validation and business logic as manual operations through the UI or API.

Message and Positioning

Every enterprise platform has import tools. Ours works differently. We built it on our GraphQL API. The same API we use internally. You get the same power we have.

Keep it simple if you want. Upload a file. Update some records. Done.

Or go deeper. Use the full API surface. If an operation exists in our API, you can bulk-process it through the import tool.

Use cases

• Implementation/onboarding: New customer with thousands of accounts, learners, or courses from their legacy system.
• Seasonal Training Scheduling: Training coordinators can bulk import scheduled events and publish them immediately, eliminating hours of manual session creation.
• Data Clean-up Updates: Admins can process bulk updates, such as event cancellations, in a single operation instead of updating each record individually through the UI.

Pricing

This feature is available as part of our Essentials Package.

How To Guide

Navigate to Settings → Import Tool in your Administrate instance.

Click the Import Data button to begin a new import.

Follow the instructions on screen.

Configuring and Running Your Import

Choose the entity you want to import, such as Events, Course Templates, or Accounts.

Choose whether you want to create new records or update existing records.

1. The table shows historical imports, if they exist.
   1. Entity: The entity you’re importing to.
   2. Mutation: The operation requested, such as Create or Update.
   3. Status: The status of the import. You can click View legend for information.
      1. Partial: Some records were not processed. You can download the failure file to see why.
      2. Pending: File has not been processed. Expect this to be processed in the next few minutes.
      3. Completed: Import was successful. All records have been processed.
      4. Failed: Import failed. You can download the failure file to see why.

2. Click Import Data to load the modal.
3. For example, let’s say you want to import a list of new Accounts.
   1. Select the Account entity.
   2. Select the Create operation.
   3. Hit Next.
4. The next step lets you configure the import CSV template that you need to download. After you specify your settings, download the template.

5. Fill the template with your data, then upload it.
   1. You can open the template in Excel, Google Sheets, or your preferred spreadsheet application.
   2. The template includes column headers corresponding to the fields available in the GraphQL API for your selected entity and mutation.
   3. Columns marked as Optional can be deleted if you don’t need them.
   4. You can reorder columns as needed for easier data entry.
6. Click Finish.
7. The data import is now in the queue and will be processed shortly. You can track the status from the import table.

Running and reviewing an import

Once your CSV file is prepared and your import settings are confirmed, Administrate queues the import for processing. The system applies records according to the selected entity, operation, matching behavior, validation results, and permissions.

After the import runs, review the results carefully. Confirm which records were created, updated, skipped, or returned errors before relying on the imported data operationally.

For larger imports, run a small pilot first and verify the results before processing the full file.

Verifying imported data

After an import completes, verify the imported records before relying on the data operationally.

Recommended verification steps include:

• Confirm expected record counts were imported.
• Review validation warnings, skipped rows, partial results, or failed rows.
• Verify that relationships and lookup fields resolved to the correct records.
• Confirm required fields populated as expected.
• Spot-check imported records in the application UI.

Verification is especially important when importing updates to existing records, working with relationship-heavy data, or processing large datasets.

Common Workflows

Importing Accounts

Start the import:

1. Go to Import Tool.
2. Click Import Data.
3. Select your entity: Account.
4. Select your action: Create.
5. Click Next Step.

Set up your template:

1. Choose how many phone numbers and addresses you need for each account.
2. Download the template.
3. Look at the first four rows. Do not delete them:
   • Row 1: Field names you can read.
   • Row 2: System codes that tell the importer which field to use.
   • Row 3: Description of each field.
   • Row 4: Field type.

Upload your data:

1. Fill in your data starting at row 5.
2. Click Next Step in Administrate.
3. Upload your file.
4. Click Finish.

Your file processes in a few minutes. Your accounts get created.

Importing Contacts

1. Go to Import Tool.
2. Click Import Data.
3. Select your entity: Contact.
4. Select your action: Create.
5. Click Next Step.

Proceed with the next steps.

Importing Courses

1. Go to Import Tool.
2. Click Import Data.
3. Select your entity: Course Template.
4. Select your action: Create.
5. Click Next Step.

Proceed with the next steps.

Importing Events

1. Go to Import Tool.
2. Click Import Data.
3. Select your entity: Event.
4. Select your action: CreateClassroom / CreateBlended / CreateLMS.
5. Click Next Step.

Proceed with the next steps.

Publish Events in Bulk

1. Go to Import Tool.
2. Click Import Data.
3. Select your entity: Event.
4. Select your action: update.
5. Click Next Step.
6. Download the template.
7. Modify the sheet to have just the IDs and the lifecycle.
8. Under the Event Id column, paste your event IDs.
9. Under the Lifecycle State column, put in published.
10. Upload the file.

Permissions

You need the Import Data - edit permission to use this feature.

You can find this feature in Settings → Import Tool.

You can import data for any entity you have access to. You can only import to companies you have access to.

What Happens After You Upload

Upload your file, check the results, fix any errors, and re-upload if needed. Success files show what got created. Failure files tell you what went wrong.

When Things Go Right

Your import worked. Download the success file to see what you created.

The first column shows the ID for each resource. You can use this ID to find or update the resource later.

When Things Go Wrong

Some rows failed. Download the failure file to see why.

The first column explains the error for each failed row. Read the message to understand what needs fixing.

Fix and Re-Upload

You can edit the failure file and upload it again. The error column stays in the file, but you can remove it if you want. Administrate ignores that column.

Steps to fix:

1. Download the failure file.
2. Read the error messages.
3. Fix the problems in your data.
4. Upload the file again.
5. The process repeats until everything imports successfully.

When You Need Help

If you see "Unknown Error" in your failure file, something unexpected happened. Contact the support team and send them your failure file so they can investigate.

Helpful Tips

• You can reorder columns.
• You can delete columns marked as Optional.
• You can edit the lookup to look up on supported fields, for example: Lookup(account, emailAddress) will find the account by the email address.

For further information, see the GraphQL API documentation for the entity you’re importing.

Common import error patterns

Most import failures fall into a small number of repeatable patterns. Understanding these patterns makes troubleshooting significantly faster.

Identifier and matching errors

• Records fail to update because identifiers do not match existing records.
• Duplicate records are created because matching fields are missing or incorrect.
• Lookup fields reference records that do not exist or are inaccessible.

Validation and formatting errors

• Required fields are missing.
• Date, numeric, or boolean values use invalid formats.
• CSV structure issues prevent proper parsing.

Relationship and dependency errors

• Dependent records are imported before prerequisite records exist.
• Referenced entities are unavailable in the current company or visibility context.

For detailed troubleshooting workflows and failure interpretation, see:

• Troubleshooting: Import Errors (CSV) 
• Import Processing Model (How Imports Behave) 

Troubleshooting

Handling Failures

If you see "Unknown Error" in your failure file, contact our support team. Provide the date and time of your import.

For support and engineering: Check Sentry to identify the issue.

Known Issues

We’re getting these resolved as soon as possible.

• Rows processed don’t include success vs failure.
• Some formatting issues occur when you download failed files.
• If there are no successful or failed files, the option should be disabled.

Documentation by workflow

Use the articles below for deeper reference or entity-specific import guidance:

• Import Data (CSV): Overview & Workflows
• Import Processing Model (How Imports Behave)
• Prepare your CSV file for import
• Troubleshooting: Import Errors (CSV)
• Import Contacts (CSV): Create
• Import Events (CSV): createClassroom

Need help?

• If your import is Partial or Failed, download the failure file first and correct errors before re-uploading.
• If results look unexpected, such as duplicates or incorrect updates, stop and review your identifiers and matching logic before running another batch.