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. Data Imports are powered by Flatfile, which provides the ability to import a considerable selection of file formats.

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 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
    8. Unauthorized
  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 all rows that failed to import, along with the value of that row.
    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 “Upload File” button to open the Flatfile window. Uploading your file is easy – you can either drag the file from your file manager into the browser window, or click “Select file” and find the desired data file.

As the file uploads, you'll be provided with a progress bar, useful for those much larger uploads that can take quite some time to import:

Once the upload is complete, the data will be displayed, and you'll be prompted to select Header information. This part of the import process is perhaps the most flexible, as even if no header information (or the wrong header information) was included in your data file, it can be corrected at this stage.

The automatic header identification will attempt to search the entire document to find what could be headers. This stage lets you make sure the right row is selected.

After confirming the header row selection, you'll be required to confirm the match between headers and template fields

Choosing your headers
When you have a file without headers, or the headers were not automatically identified, you have a few options to continue the import:

1. Manually select the correct row by scrolling through the list. If no rows exist with headers, you can either add them to your file, or proceed to one of the other options:


2. Select a row that you will use as the template for the headers. This row will then be associated with the template headers. Do note that the selected row will not be uploaded with the rest of your data when used this way.


3. If you don't have a header row in your data, you can skip the entire process and use the alphabet instead. This lets you use the A, B, and C at the top of the Flatfile table and assign them to the template headers.

Once you've selected your headers, click on Continue button to process the data. This will bring you to the finalization page:

This page gives you a final chance to review your data along with the headers being associated with each column. Once you're done, click on

Flatfile will then begin processing your data, and you'll be returned to the main “Create Data Import” page, where the “Create” button can be clicked to begin the import.

Once an Import complete, or fails, notifications will be sent based on your user preferences.

Pausing and Resuming Data Imports

During the process of uploading your data to Sonar, you can close the Flatfile modal using the “X” in the top-right corner. Closing the window will preserve the data you've already uploaded, and the stage you're at in the import process. Resuming your upload will give you the option to continue the process, or start over:

Import Queues

Once an import has started, it will be queued. Every 5 minutes, 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. 5 minutes 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.
  4. Unauthorized – Sonar and Flatfile could not reliably determine that the submitted data was created by a logged-in user.

How did we do?

Frequently Used Terms

How To Use GraphiQL to Understand the Sonar API

Contact