Table of Contents

Getting Your Data into Sonar

Mitchell Paul-Soumis Updated by Mitchell Paul-Soumis

Read Time: 6 mins

Currently, Data Imports are limited to DIDs, Voice Providers, and CDRs. Additional features will be added in the future.

The Data Import tool allows you to bring external data into your Sonar instance seamlessly. This tool is designed to take your data, and your organization methods, and convert it into the format(s) Sonar uses. This is largely accomplished by the manual association of headers that Sonar expects to see with the data you provide.

Prerequisites for Data Import

To use the Data Import tool, you need to ensure the correct permissions have been added to your user. There are 3 Data Import category permissions, and one tertiary permission that is also required. Your user role must have the following permissions enabled:

  • Call Detail Record Import
  • DID Import
  • Voice Provider Rate Import
  • And at least View permissions for Voice Providers

Accessing Data Imports

Data imports are accessible through your instance settings:

  1. Click on Settings
  2. Select Data Imports
Imports are also available from the entity's page, such as Settings → Voice → DID

This page contains both the button to start a new data import, and a table that provides a list of all your imports, both successful and unsuccessful.

Table breakdown

The Data Imports table is one of the few tables in Sonar that do not allow for result filtering. Instead, each column is sortable, and contains basic information about the import. For details on each column, take a look at the following section.

  1. The ID column shows you the ID number of the import.
  2. The Type column shows what kind of data was imported, based on the selection made. See Importing Data.
  3. The Progress column shows how far along the data import is. If an import fails once it's started, the progress will be made blank, displayed as a “-” on the table.
    The percentage value will update the initial 50% quite quickly, as this first half is pre-processing. The remainder will update depending on the total number of records being imported.
  4. The Status column provides the up-to-date import status. The displayed statuses are:
    1. Pending
    2. Invalid
    3. Queued
    4. In progress
    5. Successful
    6. Failed
    7. Duplicate
  5. The User column shows the display name of the user who initiated the data import.
  6. The Created column shows the date and time the import was started.
  7. The final column allows you to view additional details of the import.

Import details breakdown

Clicking on the “View Details” button for any import

  1. This is the ID of the Data Import
  2. This section contains important information about the import, including its type, current status, and successful or failed import amounts.
  3. The Failed Imports section of the details page will list the details of the first 25 rows that failed.
    When an import fails with select rows, you can correct those values and run a new import. When an import fails, no data is imported, and so all data must be corrected and resubmitted.

Importing Data

To start the Data Import process, all you need to do is click on the Create Data Import button in the top-right corner of the page. This will open the modal, where you need to select the type of data you'll be importing.

Regardless of which data type you're importing, selecting the type will open an additional details page, where you provide some additional field information.

Some data sources will have additional fields to fill out, such as “Voice Provider Rate”, where the Charge Percent is set for all VPRs before importing them:


After filling out the required fields, click the “Select File” button to upload your file to your Sonar instance. This will open your operating system's native file manager, and allow you to select any .csv file on your system. While most CSV files will upload quickly, a progress bar is visible during file upload.

Until the file has finished uploading and all headers are selected, you will not be able to proceed with the import, and the "Create" button will remain inaccessible.
Image of the File upload in progress

Selecting your fields

Once the file is finished uploading, you need to select which columns correspond to which headers on your dataset. Additionally, you need to select the starting row for the data import. In most cases, the starting row will be your first row with data, if your headers are included in the CSV file.

In this example Data Import, the headers are selected and the first column that contains data has also been selected. Once the upload starts, these determine how the data will be matched in Sonar. Whether your data already contained headers, or contained incorrect headers, you will still have to set them during file upload.

Choosing your headers
The Sonar Data Import solution largely ignores the headers included with your data. When you upload a file, you will need to manually assign the headers based on the data type being uploaded. In this example, all the header data for the CDR import is wrong, but the headers provided by the importer ignore those, and provide the correct ones regardless.



The order of your columns is equally irrelevant, as the header locations are completely variable, and will conform to your data.

Once everything is matched, click on “Create” and the Import will start.

Until the file has finished uploading and all headers are selected, you will not be able to proceed with the import, and the "Create" button will remain inaccessible.

Import Queues

Once an import has started, it will be queued. Every minute, the Sonar system will check for any queued imports and start the oldest one. Only one import can be running at a time, and the next import will not start until:

  1. The first import has completed, and
  2. 1 minute has passed since the last check.

What Causes Import Failures

Failures during Data Imports can occur at many stages of the process, but they all share the same root cause: your data file. Generally speaking, Sonar will be able to provide information on the cause of the import failure, but the most common failures are:

  1. Unmatched information – Generally, this only occurs for CDR imports, as unless the DIDs are mapped to an account, their CDR cannot be added to the instance.
  2. Duplicate information – This can occur across all import types, and is caused by attempting to import a record which already exists
    Voice Provider Rates will never experience this error, as rate decks imported to the same Voice Provider will always overwrite the older data.
  3. Invalid – If the data is, for some reason, completely invalid, the process will fail.

Although quite uncommon, if more than 10000 records fail in a single import, a unique failure will occur, with the following message:

The number of validation errors found in the import exceeds the limit for one attempt, and import validation is incomplete. The import may contain additional validation errors. Please make corrections and try again.

How did we do?

Frequently Used Terms

How To Use GraphiQL to Understand the Sonar API

Contact