Understand Imports

Maxio's import tool allows you to make large-scale changes to the data in your system. This can save you a significant amount of time by avoiding manual data entry. The available imports allow you to create, update, or delete multiple items at the same time, as well as a number of other helpful tasks.

WARNING: An import can make extensive permanent changes to your financial data. It requires a working knowledge of the application and the records it holds, so be certain of a mapping before you run it. Contact support@maxio.com if you have any questions.

Importing basics

The items below cover several essential aspects of the import that you should familiarize yourself with before proceeding.

• The import function must be activated in your account by Maxio staff. Contact support if you do not see the Import options in the Admin window.
• Once enabled, the import function is available for all admin users. We recommended you audit your user list to ensure your users have the appropriate level of permissions. Roles are further explained in Understand User Roles and Access Controls.
• An import can partially succeed. Rows that pass validation are imported, and rows that fail are reported with their line numbers. Download the error file, correct those rows, and re-import only that file. Re-importing the whole file can fail or duplicate work, because the records that already imported still exist.
• There is no way to undo an import, so you should always perform a backup before running an import. Also, you cannot stop an import once it starts.
• Import files must use the CSV UTF-8 encoding. The XLS/XLSX format does not work, and neither does CSV with UTF-16 encoding. A byte order mark on a UTF-8 file is fine, since the importer strips it when it reads the file.
• Most CSV files require some level of clean-up, which is explained further in Format a CSV File for Import.
• You should use a sandbox environment to familiarize yourself with the importer before executing imports in production.

Import types

Maxio provides the following types of standard imports:

• Create: Add new records.
• Update: Make changes to existing records.
• Delete: Remove existing records. Contact support if you'd like to perform a Delete import, as it must first be activated in your account.
• Create and/or Update: Add new records and make changes to existing ones in the same file. Like Delete, this action must first be activated in your account, so contact support if you do not see it.

The system also contains the following additional imports:

• Renumber
• Rename
• Item Groups
• Transaction Renewal Linkages
• Import Payment Profiles
• Generate Entries - System
• Import Entries - Custom
• Generate Invoice Schedules

You can access these imports by clicking the Additional Imports option.

Background process

Maxio decides whether to run an import in the background based on the size of the file you upload, not the number of rows it contains. Anything above roughly 5 KB is queued as a background job, which is a small enough threshold that most real import files qualify. Running in the background allows you to continue to use the system while the import completes. If multiple imports are requested on the server, they only consume a dedicated amount of resources to prevent any impact on other users. You can view the status of background imports on the Results page.

Data model

It is important to understand the relevant components of Maxio's data model since the import function is designed to populate tables in the database. Customers, Contracts, and Transactions form the backbone of that model, with Items, Invoices, Invoice Line Items, and Revenue Records hanging off them. The flowchart below explains how these objects work together within the system's hierarchy.

The solid black arrows in the model above represent a standard one-to-many database relationship (parent-child, foreign key required), which means many child records can exist for the same parent record. For example, a customer can have an unlimited number of child contracts but a single contract can only belong to one customer. The dashed black lines represent required one-to-one relationships, and the dashed blue arrow represents an optional one-to-many relationship.

Note that Items sit outside the Customer and Contract chain. An Item is a catalog-level record that Transactions and Invoice Line Items point at, so it does not belong to any single contract or customer.

Next steps

Now that you have a general understanding of importing, you can construct the CSV file and then execute the import.

Related information

To send metered usage records to Advanced Billing from a CSV rather than writing directly to Maxio Core records, see Import Metered Usage.

To create new subscriptions in Advanced Billing from a CSV, which uses a separate tool from the Maxio Core importer described here, see Import Subscriptions from a CSV.