CSV Import & Export

Business Directory Plugin Import and Export features help you organize your listing data, create backups of the listings you have, make bulk changes to your current listings, and import hundreds of listings at one time. It’s a handy feature!

This document will walk you through the basic steps to import and export your listings and will give you tips on how to make the process quick and easy.

The Basics of importing and exporting

Business Directory Plugin has a tab for these features under Directory → Directory Content → Import & Export.

This article will cover both importing and exporting as well as some FAQs. You can use the menu on the right to skip to the section you need or read on to understand the entire process.

Importing Listings

Before importing your listings, please be sure that you have configured all of your form fields exactly as you want them. It is worthwhile to do this, create some listings, then tweak the fields to be exactly as you want them to appear.

The importance of this step cannot be overstated. Changing your form fields, deleting them, etc., may have a negative impact on your listings import. For example, if you import 100 listings and then change your fields, the 100 listings you imported won’t have the fields that you changed.

Let’s walk through the import settings on this tab and discuss each.

Files

The first two settings allow you to choose a file to attach for importing. The CSV file is the file that contains the data you want to import. We recommend keeping the overall import size under 5MB to avoid timeouts We’ll go over the options for creating the import file in a moment.

You can also select a ZIP file containing images that go with your listings if you have those. The names of these images should be referenced in the “images” column of your CSV file.

Separators

Beyond the file attachments, the first several settings ask about what symbol you'd like to use to separate your Columns, Images, and Categories.

The comma is selected by default for the Column Separator, and a semi-colon is selected for both the Image and the Category Separator. You can change these settings to match your CSV file separator. However, do not choose the same separator for each separator type, as it will make your file unreadable to the BD importer.

Listing Status

The Listing Status options include settings for the post status of NEW and EXISTING listings. Your choices here will set the status of the listings once they have been imported.

For new listings, the choices are

Published (default)
Pending Review

For existing listings, the choices are

Preserve existing status (default)
Pending review
Published

Missing Categories

The Missing Categories handling setting tells the system how to handle missing categories. Your options here are:

Auto-create categories (default setting)
Generate errors when a category is not found

IMPORTANT: Settings under Directory → Settings → Listings will override any choices you make here.

Miscellaneous Settings

The next few settings will tell the system how to handle existing images, whether to assign listings to a specific user, and allows you to choose a default user to be used if the username column is not present in the CSV file. If you turn Assign Listings to a specific user on and leave the assigned user column empty, it will be assigned to the admin by default.

If you choose to assign the imported listings to a specific user, the system will generate a dropdown menu for you to choose the default listing owner.

Batch size

The Number of listings imported on every cycle setting is related to the batch size of the import and should be left at the default of 40 unless you are having problems importing your listings due to memory problems. Using this setting, you can reduce the import batch size to 5 or 1 and then re-attempt the import.

This will result in a longer batch import time but will increase the chance of success on shared hosting platforms and other resource-constrained servers.

Email Notifications

The final setting on this page is used to tell the plugin how to handle email notifications during import. By default, this setting is turned off during the import. It is recommended to leave this as the setting when you run your import unless you want all listing owners to be notified that their listing has been created.

Test Import and Import Buttons

Finally, there are two buttons at the bottom of this page: Test Import and Import Listings.

Test Import will run a quick check of your CSV file and Import Listings will go directly to the process of importing your listings.

CSV File Formatting

The remaining information on this page will show you what your CSV file headings should be titled and whether or not data is required in a field for the import. The data included in the CSV File Formatting section includes a chart of the following items:

Header name/label
Field Type
Required?
Multivalued?

The headers here will show you exactly the headers for the columns of your CSV file and should be consulted before doing an import. Names and case matter! For example, if the header is listing-description, you can only use listing-description as the column header in your CSV file. Listing Description, Listing-Description, or Listing_Description will all cause your import to be rejected.

The Required? field will show you which fields must have data in them in your CSV file for importing. TIP: If you don’t have all of the required data for an import but want to require this information for new listings, you can turn off the requirement for data in the field under Directory → Directory Content → Form Fields for the import, then turn it back on after the import is complete.

Exporting Listings

To export ads via CSV, you must have data in your directory, either through direct entry OR via CSV Import. We always recommend adding your listings through the front-end submission form on your website so that any required fields are not empty.

IMPORTANT Please note that the export process is a resource-intensive task. If your export does not succeed try disabling other plugins first and/or increasing the values of the ‘memory_limit’ and ‘max_execution_time’ directives in your server’s php.ini configuration file.

To export your data, go to Directory → Directory Content → Import & Export and choose the Export tab

You’ll notice on this screen you have several options.

Which listings to export

Your choices here are

All
Active only
Active + Pending renewal

Export Images

Toggle on or off.

When you choose this option and toggle it on, the exporter will create a ZIP file with both a CSV file and listing images. By default, this is turned off.

Additional metadata to export

Depending on what you are doing with your exported file or the reason you need to export it, there are a variety of options to choose from that tell the system which data should get exported for each listing:

Include unique IDs for each listing (sequence_id column). IMPORTANT: If you plan to re-import the listings into your directory and don't want new ones created, select this option!
Author information (username) (checked yes by default)
Listing expiration date (checked yes by default)
Listing created date
Listing last updated date
Listing T&C acceptance date

CSV File Settings

What operating system will you use to edit the CSV file? * Windows and macOS versions of MS Excel handle CSV files differently. To make sure all your listing information is displayed properly when you view or edit the CSV file, we need to generate different versions of the file for each operating system. If you are using Google Sheets, choose Windows. Choose one of the following:

Windows (default)
macOS

Separators

These are the symbols you choose to separate multiple data points in your CSV file. Some people may want to change this, however, the default values are ; and those default values work for most people.

Export Listings Button

Once you have selected the settings you need, you are ready to export your listings.

Click the Export Listings button.

The processor will work for a moment (depending on how many listings you have in your directory) and then a button will appear that lets you know you can now download your exported listings.

FAQs and Troubleshooting

How do I get a template CSV file that matches my current fields exactly?

Follow these steps:

Configure your form fields under Directory → Directory Content → Form Fields
Create a listing from the front end (this means go to your site and create the listing)
Only fill out the fields that are required (these fields will have an asterisk)
Click on the See Example tab and generate your file
Download the CSV file
Use this file as a template for your import - the headers will match exactly and are case-specific and you’ll know which fields are required and MUST have data in them)
Verify that your file is saved in CSV UTF-8 format before importing

Is there an example file available for me to use?

Yes! You can get a sample CSV file based on your exact setup by clicking on the See Example button in the top right corner of the Import page and then choosing the Download Example button.
TIP: You can create an entry using the front-end submission form by completing only the required fields so that you have all of the required fields filled out and then do an export. Doing this will format everything perfectly for you and you’ll easily see which fields require data and which do not.

I have a CSV file already and it has extra data that I don’t need - how do I get my data into the right format?

Follow the steps to export your listings or download a sample CSV file using the See Example button
Copy the exact headers over to your CSV file using the headers created by Business Directory Plugin.
Delete extraneous data columns to keep the file neat and readable.

My directory listings have ZIP codes that start with a zero. Are there special rules that apply in this situation?

Yes!

If your directory has any entries in Connecticut (CT), Massachusetts (MA), Maine (ME), New Hampshire (NH), New Jersey (NJ), Puerto Rico (PR), Rhode Island (RI), Vermont (VT), Virgin Islands (VI), APO Europe (AE), FPO Europe (AE), or any other locale with a Zip Code that starts with a zero, you will need to follow specific instructions.

If you are using the text-only format of a CSV file to import listings, there is no issue. But if you are using Excel or Numbers to edit the file, or are doing an EXPORT-CHANGE-IMPORT using one of those programs, the ZIP Code field must be changed to a TEXT field in order to avoid losing the leading zeroes that are what begin the ZIP codes for these locations. If you need access to a program that can do this for you, please visit this site.

Can I import images for my listings when I import data?

If you want to import images within your ads as well, you must provide a separate ZIP file with all the images contained in it. The names of these images should be referenced in the “images” column of your CSV file. In the image field, the filenames should be listed. For example, exampleimage.jpg
NOTE The image file is often the reason for a failed import. Try to use the smallest size of image you think you will need, at most. Putting 100 2MB images into a ZIP file will only choke the uploader and cause timeouts during upload!

My listings have multiple images. How do I import them?

Follow the instructions for attaching a ZIP file of images.
If you have multiple images for a single listing, you must separate their names with the “Image Separator” character, which is a semi-colon by default. For example imagetitle1.png;imagetitle2.gif;imagetitle3.jpg.
Set the path to these files using the names of the images in the ZIP file and their file extension.

Is there a maximum number of listings I can import at one time?

There is no upper limit on the number of records that can be imported using the CSV file process, though your hosting plan may have some effect on the process. This is typically something that your hosting company can help you with, including reading any error logs that have been produced.
A CSV file of 25000 records isn't a problem for Business Directory Plugin itself, but it may overflow the memory of most hosting services during import. We would recommend that you break up your import into files that are smaller — starting with about 1000 listings and see how that goes. You may need to adjust up or down, depending on your hosting plan.

How can I import a listing with multiple categories?

Here is an example of correct category formatting for importing multiple categories (NOTE: your headers may be different from the example shown):

There are a lot of possible settings for these fields so the very best way to determine what is needed for your import file is to create a listing using the social fields, do an export, then import it to make sure it works.

For example, if I choose only to have the URL and icon show for each social field, my import file should look like this:

URL,,SocialSiteName,

Getting the exact formatting you need is best determined by doing an export of a completed listing.

What happens if I have to do a second import? Or a third?

Each time you do an import without using a Sequence ID to match the imported listings to existing listings, new listings will be created.
To avoid adding duplicate listings you can export your listings with a Sequence ID and then use those in your import file. This is the only way to get the Sequence IDs.
You can also delete all of your current listings before doing an import.

NOTE: Be sure to use the See Example button at the top to get started with a template CSV file–it's WAY easier than typing it from scratch and helps avoid common errors.

Common errors to avoid during import

Your CSV file should be based on the sample CSV file that is created under Directory → Directory Content → Import & Export, by clicking the See Example button. Generate that if you haven’t already. The example will include all of your current listing data, including the correct headers to use when you import the file. Once the example file is visible, you can download the file and edit it.
Your CSV file must have every column from the sample file, named exactly the same as shown in your grid on this configuration page. Don’t delete any of them, especially the OPTIONAL ones.
Your CSV file should have data in every column that is required. Optional columns/fields can be left empty below the header, but you cannot remove the column!
Text fields can’t have single quotes in them without putting double quotes around the whole field (e.g. “Bob’s Market”)
Dates must be in the expected format of the CSV import settings (MM/DD/YYYY)
Imports work best after you’ve completed all field configuration, so make sure you do that first (especially naming the fields)

PRO TIP: If you want to upload a URL that is replaced by text for your URL field, use the following format in your CSV file: “https://mysite.com,My Website” That will populate the link and the text into their proper places. Instead of looking like this in the listing: https://businessdirectoryplugin.com/ The link will look like this instead: My Website

CSV Import & Export

The Basics of importing and exporting