Instructions for the Automated Import feature

Files

• You will need three files, all of which should be placed into your regular ftp directory:

  1. CSV: A standard .csv-formatted text file containing your data. The file can have any name. As usual, comma-delimit the fields, double-quote any fields containing commas or single-quotes, etc. You may include an optional header row, though any such row will be ignored for the purposes of the automated import.

  2. XML: A control file (again, with any filename) but with an .xml extension. This file describes the actions to be performed.

  3. GO: A "go" file, which can be empty, with the same name as the .xml file but with a .go extension. The import processor will not begin to process the .xml control file until this file is present. This allows you to upload your .csv and .xml in any order, and also to allow for timing delays while transmitting the .xml file. In any case, be sure to write this file last, when you are ready for your import to run. The contents of the .go file are irrelevant.

Control File Format

• The general format of the xml control file is as follows. It is not validated against an external DTD explicitly, but if the file is not well-formed or if it cannot be parsed correctly, you will receive the error message (in an email) and the file will be renamed with an "-error" extension.

• Please note that all the required text below is case sensitive. So, "Filename" must be "Filename" and not "filename", and "Delete ALL" must be "Delete ALL" and not "delete all", etc.

     <Import>
         <Filename hasHeader="true">yourfilename.csv</Filename>
         <Notifications>susan@xyz.com,george@xyz.com</Notifications>
         <ImportType>Update</ImportType>
         <UpdateType skipUnmatched="false">Update all</UpdateType>
         <TargetList>123</TargetList>
         <CSVFields>
             <Email/>
             <First/>
             <Last/>
         </CSVFields>
         <MatchFields>
            <Email/>
         </MatchFields>
    </Import>
  

• <Filename>: Name of a .csv file in the same directory as the .xml file. hasHeader will be "true" if the file contains a header row (which will then be skipped).

• <Notifications>: List of people to notify upon start and completion of the import, with commas between email addresses. Each recipient specified will receive both error and success notifications.

• <ImportType>: The type of import to run. Must be one of the following types:

  • Replace - Replace the entire target list with the contents of the csv file
  • Append - Add the entries in the csv file to the end of the existing list
  • Update - Update matching entries in the target list with the new data from the .csv file
  • Update Broadcasts - Update matching entries in all broadcast lists with the new data from the .csv file
  • Delete - Delete any entries from the target list matching any entry in the .csv file. (Special permission required.)
  • Delete ALL - Delete entries from all broadcast lists on the entire server matching any entry in the .csv file.(Special permission is required for this.)

• <UpdateType>: (Required only for an ImportType of "Update") Specifies what to do about duplicate matching entries when the update is run. The "skipUnmatched" attribute will be "true" if you want to completely skip all rows in the csv file that do not match the target list. If you set this value to "false", any non-matching rows in the .csv file will be added as new entries.
  The value for the UpdateType tag must be one of the following:

  • Update one - Update just one of the matching entries with the new data
  • Update all - Update all matching entries with the new data
  • Update one and remove remaining- Update a single entry and remove any matching duplicates.

• <TargetList>: The ID of the list against which to import. For an Update Broadcasts or a Delete ALL import, you can specify any valid list, otherwise use the appropriate target list ID, which is displayed on your Lists page. Updates will modify this list, appends will add to this list, deletes will delete from this list.

• <CSVFields>: List of all fields in your csv file, in the column order in which they appear. This might be a single field or many. They should be specified as <FieldName/> in the list. The field name choices (case sensitive) for imports are:

        City
        Company
        Country
        Email
        Fax
        Phone
        FirstName
        LastName
        OptIn
        Source
        State
        Street
        Title
        Zip
        Custom1
        Custom2
        Custom3
        Custom4
        Custom5
  

• <MatchFields>: (Required only for updates and deletes) For updates and deletes, you must include one or more fields to be matched against the target list. In order for the update or delete to be performed on an existing record, the record must exactly match all of the fields that you specify here. The choices for field names are the same as for the <CSVFields> tag.

Example

Suppose that you wished to delete all entries from all lists matching a list of email addresses in a file. You might create a deletethese.csv file looking like this:

    email1@somedomain.com
    email2@somedomain.com
    email3@somedomain.com

and so forth. Then, in the same directory, you'd put a control file, mydelete.xml:

 <Import>
     <Filename hasHeader="false">deletethese.csv</Filename>
     <Notifications>robert@xyz.com</Notifications>
     <ImportType>Delete ALL</ImportType>
     <TargetList>23</TargetList>
     <CSVFields><Email/></CSVFields>
     <MatchFields><Email/></MatchFields>
 </Import>

Once this file is written, you would write an empty file named mydelete.go to the same directory, and your import would be processed (the .xml and .go files deleted after processing, or renamed to error), and the import run at the next available opportunity.

Advanced Features

Automatic CSV filename selection

• The CSV file may be automatically determined by the file name of the XML file, if desired. To do this, use this form for the Filename entry in the XML control file: <Filename sameAsXML="true" newExtension=".csv"/> The "newExtension" attribute may be omitted, in which case it will default to .csv. When this form of the <Filename>is used, the filename for the CSV file will be the same as the XML file, minus the .xml ending, and adding the ending from the "newExtension" in its place.

• As always, the hasHeader attribute may be included if desired: <Filename hasHeader="true" sameAsXML="true" newExtension=".csv"/>

CSV file renaming

• An attribute, datestampCSV="true", may be added to the <Filename>tag to have the CSV file automatically renamed upon the processing of the XML control file. The CSV file will be renamed to have a suffix of the current date and time. For example:
  someimport.csv
  will become:
  someimport.csv_2018-8-20_17-34-18
  and that will be the file that will ultimately be imported. This attribute may be used in conjunction with automated CSV filename selection above, e.g.: <Filename sameAsXML="true" newExtension=".csv" datestampCSV="true"/>
  or with the more ordinary Filename usage: <Filename datestampCSV="true">someimport.csv</Filename>
  As always, the hasHeader attribute may be included if desired: <Filename hasHeader="true" datestampCSV="true">someimport.csv</Filename>

• Note that if the processing of the XML file fails for any reason, the CSV file will NOT be renamed.

Automatic target list selection

• The target list to be imported may alternatively be specified by a brand based upon the filename of the import (.csv) file.
• The first part of the filename, up to a specified delimiter, will be used as a brand.
• Then, all lists in the account will be searched for that brand (in a case-insensitive manner), and the first list found with that (case-insensitive, but otherwise exact) brand will be used as the target list of the import.
• The syntax for specifying this is: <TargetList findBrandDelimiter="_"> where, of course, the "_" delimiter specified may actually be any delimiter you wish to specify (even a string of several characters).
• In this example, if the filename to be imported is: thisbrand_tuesday_import-topexi.csv then "thisbrand" would be searched for in the brands of the lists in the account, and the first matching list (lowest List ID) will be used as the target list for the import. If no matching list is found, then the import will fail.
• This feature may be used with the automated CSV filename selection feature described above.

Note on Timing

• By default, the automated import processor checks for these files every 15 minutes, so it might take a few minutes for your new import request to be processed.
• Also, imports generally run one at a time to avoid overloading the system, so your requested import could be queued up
  behind earlier imports.

(END)