Home page for Opal-Convert: Opal-Convert VCF to CSV to VCF (vCard) (online link)



Opal-Convert CSV/Excel/vCard Documentation


  • Basics
  • Convert from vCard to CSV (VCF to CSV)
  • Convert from CSV to vCard (CSV to VCF)
  • Filter/transpose table
  • Other options
  • Upgrade Opal-Convert to handle more contacts




  • Basics

    Opal-Convert is very easy to use, yet powerful. Simply open a file (top left button) and Opal-Convert will automatically recognize whether you've loaded a vCard file (or files), or CSV. Then adjust any options (more details below), and then finally save the converted file/s (save button will turn green).



    As you change the options, the output will update immediately in realtime. This allows you to have instant feedback to see if the conversion results match your expectations (for example, to see whether a finished vCard picks up all the fields from your initial CSV input when you convert from CSV to vCard (VCF 2.1 or 3)). It's much more intuitive than saving a hundred times to check your results. Batch conversion is featured too so you can convert multiple vCards at once.

    You can also switch between 'Grid view' and 'Text view'. 'Grid view' is clearer to see, though the 'Text view' shows exactly what will be saved.

    Feel free to experiment with changing the options as you can reset them back to the defaults at any time (see top middle of main window).






    Converting from vCard (or vCards) to CSV

    First off, open a single vCard file or batch of vCard files from the "Open file/s" dropdown menu, then locate the files/s and click open.

    From this point, there are various options you may wish to consider when performing this conversion. Nevertheless, if you ignore them and go on to save the Excel/CSV file, you may find the results are still to your satisfaction, since Opal-Convert usually picks suitable output names by default. After opening the vCards, just make sure the Export format is correct, and maybe adjust the headers by clicking "Adjust Excel/CSV headers...". In any case, it's easy to experiment because the output changes instantly as you adjust the options.

    A note on batch conversion:
    You can convert a single vCard file to CSV, but Opal-Convert can also convert from multiple vCards. In this case, you might need to open a batch/folder of vCard files to create the final Excel/CSV file. This can be achieved either from opening a folder of vCard files (select "Open file/s -> From folder... (batch of vCards)") or opening the vCards directly from Outlook (select "From Outlook Directly (vCards)"). Alternatively, if you have only a single file, but one which contains multiple vCard contacts, don't open a batch, but instead select "Open file/s -> From file... (CSV or vCard file)". Opal Convert will automatically recognize that the file contains multiple vCards.

    If you want the final Excel/CSV table to have the headers down the first column instead of across the first row, then make sure you tick "Transpose / rotate the data" found in the bottom middle of the main window.

    Here are some of the main options that will be be shown. The section highlighted in blue is for advanced users and often not necessary for simple conversions.



    "Export format" dropdown menu
    Here you can decide which format you want Opal-Convert to export the CSV to. Choose between Nokia, GMail, Windows Contacts etc., or if you are exporting to a spreadsheet or your own custom CSV, select 'Custom' or 'Excel'. Note that selecting 'Excel' will export to an XLS file rather than CSV, as this offers greater compatibility with Excel such as unicode and in-cell new-line formatting.

    "Adjust Excel/CSV headers..." button
    Clicking this will open a new window (see right). This window allows you to map properties in the vCard to particular CSV headers such as 'Phone number' or 'Job title'. If you are converting to a fixed CSV format such as GMail or Nokia, you are restricted to the CSV headers that format supports, but if you are converting to a custom CSV or Excel file, you can name or rename the headers to your choice (this can be done afterwards in Excel by you of course, but Opal-Convert will try to pick appropriate headers automatically). Opal-Convert also allows you to 'ignore' particular headers to remove those columns entirely from the final CSV.

    "Reverse Parameters"
    This is only applicable to "Custom CSV" and Excel export formats. It's a cosmetic change and simply reverses the order of header components. For example, "Tel (work)" would become "Work: tel".


    Advanced options

    "Text encoding" dropdown menu
    Opal-Convert will automatically attempt to decipher the language/encoding format of the vCard/s. However, if you see strange or random symbols or characters in the left or right panel, then click "Advanced" and then click the "Text encoding" dropdown menu to see a range of encodings you can try out. The top ones in the list are most likely to work, so try those first. If this doesn't work, try picking one from the "Less common encodings", or from the rest.

    "Merge fields" tickboxes
    Ticking these will combine certain fields into a single column (rather than taking up 2 or more columns). For example, if "Name" is ticked, then a single column will be created for the first, last and middle names of a contact. If it is unticked, then three separate columns in the CSV will usually be created instead.

    "Delimiter if merging" (fields and cols)
    Fields: The character/symbol to use when merging the previously mentioned compound fields (see "Merge fields" above).
    Cols: The text/symbols to use when merging columns (only applicable when "Merge columns with same headers" is ticked).


    "Split item property groupings": For rare types of vCard collections, grouped properties may cause unwanted columns in the final CSV, so if you find this to be the case, untick this option. For example, the "TEL" property might be prefaced with "item1." to make "item1.TEL" for one vCard, "item2.TEL" for the next, "item3.TEL" for the third etc. etc. However, they all combine as "TEL" and should be treated as one column in the final CSV.

    "Filter out 'irrelevant' parameters": Even though such information is taken into account, certain tags (such as "encoding=quoted-printable" or "charset=utf-8") are usually redundant or superfluous in the final CSV. Nevertheless, try unticking this option to see what information may have been excluded in the CSV headers (only the headers will be affected).

    "Filter out HTML/XML/binary data": Certain vCards may have unwanted HTML or XML data. This will filter it. Also, any rows which contain binary data (denoted by "ENCODING=BASE64" in the parameter) will be filtered out if this option is selected.

    "Merge columns with same headers": If two or more CSV headers happen to share the same name (either by you or by chance), ticking this will merge those columns.

    "Include vCard name with adding to notes": Keeping this ticked is recommended as it means any vCard information assigned to a CSV header will include the vCard property name as well as the usual data. This is useful if you can't find an appropriate mapping for some properties in the "Adjust Excel/CSV headers..." window.

    Notes regarding the final converted CSV

    To the right is a selection of options for tweaking the final CSV output. Most times, you shouldn't need to change these as Opal-Convert will automatically adjust these according to the "Export format" in the "vCard options" panel.

    The "Enclose values with quotes" field and checkbox default settings are used for most programs, so keep them 'as is' unless you know what you're doing.

    You can adjust the "CSV delimiter" to use something other than a comma by clicking the change to... dropdown (a tab or pipe is sometimes used so that commas can be preserved in the original text without the need of surrounding quotes). If there is a clash, then you can decide what character (or characters) the delimiter should be converted to (the "Character/s to use if clash with delimiter" option).

    "Character/s to use if blank cell": If the CSV is intended for a platform other than Windows (e.g.: Mac, Linux or mobile phones), then you'll probably want to tick the "Use non-Windows End of Line" option. If you still have trouble, it may also be worth experimenting with the "Output Encoding" dropdown menu, and trying out the top-most options, though usually the default - Unicode (UTF-8) - will suffice. If you want carriage returns to be allowed in cells, untick "Replace newlines with custom char/s", but be aware that some spreadsheets or software may not allow cells with carriage returns inside.

    Finally, "Remove blank lines" may prove useful for badly written (and rare) programs which choke on blank lines in the CSV.

    Excel compatiblity

    This section can be ignored by the vast majority of users, since Opal-Convert supports saving to XLS directly (from v2.00 onwards).

  • For better compatiblity with Excel (or any spreadsheet), you may want to tick (or keep ticked) "Enclose values with double quotes" to the right of the window (allowing commas in the fields).

  • If you are importing a CSV with non English-based text, you may notice Excel won't properly display the text (it will come out as showing random/strange symbols). To solve this problem, follow "Option 2" below to open the file using Excel's text import wizard.

  • Excel also has issues when importing CSVs with fields containing numbers beginning with a zero or plus symbol (e.g.: phone numbers). If this applies to you, then you have two choices:
    • OPTION 1: Tick "Insert # next to numbers to cater for Excel bug", and then open the CSV in the usual way (making sure you view all files when you try to open the CSV into Excel (by default, only "All Excel Files" are shown))
      ....OR:
    • OPTION 2: In Excel, navigate to: Data » Import External Data » Import Data (Excel 2003)........... or Data » Get External Data » From Text (Excel 2008). Once the text import wizard appear, follow these steps:
      • Step 1: Make sure the "Delimited" radio button is selected. Then click next.
      • Step 2: Under the "Delimiters" subsection, tick the "comma" checkbox, and untick the "Tab" checkbox if it was ticked. Make sure the "Delimited" radio button is selected. Then click next.
      • Step 3: Under the "Data preview" subsection, highlight a column, and then click the "text" radio button under "Column data format". This needs to be done for all the columns (you can shift click to help select them all if you're handy with the keyboard). Click Finish. (If you need more help here, follow this thread (online link)).



  • Converting CSV to vCard (or vCards)

    First off, select the "From file... (CSV or vCard file)" from the "Open file/s" dropdown menu, then open your CSV file.

    Once the CSV is open, you should see it display on the left hand side of the main window, along with the resulting vCard/s on the right. You should also see the CSV import options panel as the picture to the left shows. The section highlighted in blue is for advanced users and often not necessary for simple conversions.

    Opal-Convert will automatically attempt to decipher the language/encoding format of the CSV. However, if you see unexpected or strange/random symbols or characters in the left or right panel, then first click "Advanced" and then click the "Text encoding" dropdown menu to see a range of encodings you can try out. The top ones in the list are most likely to work, so try those first. If this doesn't work, try picking one from the "Less common encodings", or from the rest.

    There are other CSV import options you may wish to consider at this stage, such as the "CSV delimiter" or "Account for quotes around values" option, but we'll discuss those later.

    If your CSV lacks a header row, make sure you tick "Add header row (field titles) if missing".

    Next step is to turn your eyes to the "vCard export options" panel:



    Make sure the "vCard format" is correct and then click the "Find matches to Excel/CSV headers..." button. A new window will open (see image to right) where you can map the CSV headers to the appropriate vCard properties.

    For example, for the "Tel (home)" property in the CSV, Opal-Convert will try to match this to the nearest property (which is "Phone (home)" in this case). Other CSV headers you use may not be recognized, so select the dropdown for each item and match them up if you can. You can also click an <ignore> button for any of the headers, so they're not included in the final vCard.

    If your CSV has an entire "address" or "name" occupying a single header/row/column, you'll want this to be picked up by the vCard "ADDR - Address Label" and "Full Name / File as" properties respectively. However, Outlook 2003 may have problems with the Address Label field, so it might be worth using the "ADDR - Street / Address line 1" property instead. You can also populate more specific vCard properties such as Last/First/Middle name and Street/Town/State.

    In the middle of the window is an option ("Look for vCard properties") to select between "Simple" and "Advanced". If you have simple needs (just need a name, mobile number and say, an address carried through), select "Simple". If you want complete control over the vCard and need more specialized fields (e.g. Nickname, IM address, or Assistant name, and many different types of phone), select "Advanced" instead.

    Once you're finished with this window, click Close.

    Most likely, you'll be able to save your vCards by clicking the green "Save" at the top right. However, under rarer circumstances (or for programs not yet specially supported), read on for further settings.


    Advanced options

    Now let's look at some of the vCard export options (see picture to the left), and then we're ready to save the file. As always, the best thing to do is experiment to see what works best. Opal-Convert makes this easy by adjusting the output on the fly as you tick or untick the various checkboxes.

    Output encoding: It may be worth experimenting with the "Output Encoding" dropdown menu if you have problems using the converted vCard/s in your vCard reader. If so, try out the top-most options, though usually the default - Unicode (UTF-8) - will suffice.

    Include unknown properties ("X-" prefix): If it turns out any CSV fields can't be translated (or are unknown to the vCard format generally), then if you tick "Include unrecognized properties", Opal-Convert will prefix such properties with "X-" and add them to the vCard, ensuring little or nothing gets lost.

    Use unix-style EOL: Certain computers, programs or devices expect a slightly different kind of text file to what Windows expects. Tick this option if you intend to use the vCard/s on the Mac, Unix, and most mobile phones.

    If empty, derive 'File as' from name/s: If the 'Full Name / File As' field hasn't already been assigned, Opal-Convert will create it from any existing names. It shouldn't hurt to keep this ticked (especially to help compatibility with Outlook 2003 if only the name fields (and not the formatted name) have been assigned to). But if for some reason, you'd like them to remain empty and unchanged (perhaps for you to complete later, then by all means, untick this option.

    vCard v3.0 (over 2.1): Some vCard readers may require the vCard in v3.0 format. If v2.1 fails when you try importing the vCard/s into your vCard reader, then try ticking this option.

    Don't merge duplicate vCard properties: Sometimes, vCard readers are intelligent enough to look for duplicates of a vCard property (such as email), but where each has a different value (in such a case, it may treat them individually, which can be good (e.g.: if the reader has multiple email fields)). Otherwise, it may be best to be on the safe side, and keep this unticked..

    Force VCF single line: If you use the vCard's 'Address Label' or 'Note' properties, untick this for better looking (though maybe less compatible) multi-line text.

    Include CSV header when using notes: When ticked, data added to the vCard's 'Notes' include the original CSV/Excel header. Handy for data you want to keep, but can't find a mapping.

    No newline start space: Some devices and programs don't follow the vCard specification to the letter, so this may need to be ticked.

    Merge all contacts into single VCF file In case your reader supports this option, ticking this allows every vCard to be stored into a single file rather than a collection of files (according to how many contacts you have).

    Comma after addr fields: Devices such as the Android phone may need additional commas to properly format the address.


    Outlook compatiblity

    If you intend to import the converted vCard/s into Outlook, instead of clicking "Save file/s" button, click the blue "Import vCards into Outlook" button. Opal-Convert will take you through the stages necessary to complete the process including allowing you to import a few sample vCards for testing purposes.


    An example CSV...

    You can convert a single CSV into a single vCard, or multiple-contact CSV into multiple vCards. A typical multi-contact CSV could look like this:
    Telephone, First name, Last name, Company, Email
    01234 567890, Dan, White, BCFS, dw@bcfs.com
    0089 56789, Simon, Wakefield, Piano TA Ltd., simonw@gmail.com
    -, Matthew, Smith, Gizmoz Corp, -
    99999, John, Jones, -, jj@opalgra.com
    

    Four vCards would be created from the above CSV data. In the above case, the CSV headers are along the first row. If the headers are down the first column, so make sure you tick "Transpose / rotate the data". When you're happy with the settings, click the "Save" button, and Windows will ask you to select a folder to save the vCards to (we recommend creating a new folder for this purpose).

    You can also convert a CSV to create just a single vCard. In this case, a typical simple CSV could look like:
    Full name, First name, Surname, Company, Address (work), E-mail, Tel (work), Tel (home), Mobile
    D P Jones, David, Jones, ABC ltd., AB12 3CD; UK, me@abc.com, 0123456, 987654, 0011 2233444
    In the above example, the CSV headers are across the top row. If the data is formatted with the headers down the first column instead (as shown below in effectively the same CSV), then make sure you tick "Transpose / rotate the data":
    Full name, David P Jones
    First name, David
    Surname, Jones
    Company, ABC ltd.
    Address (work), AB12 3CD; UK
    E-mail, contact@abc.com
    Phone (business), 01234 567890
    Phone (home), 01234 567890
    Mobile, 0011 2233444
    


    Notes regarding the CSV import

    Text encoding
    See above

    CSV delimiter
    When converting from CSV to vCard, you can choose what kind of CSV delimiter to use. Most of the time, it'll be a comma, but sometimes pipe or tab limited data is used.

    Add header row (field titles) if missing
    See above

    Account for quotes around values
    Opal-Convert will attempt to automatically detect for quotes around values. You shouldn't need to worry about this. However, in case it makes a mistake, tick (or untick) the "Account for quotes around values" option.

    Replaces newlines with custom char/s
    You might consider ticking this for a bit of extra safety if your vCard reader isn't 'clever' enough to recognize properties with carriage returns in them. If aesthetics is a priority though (e.g.: for the address), keep this unticked.

    Quote character
    If your CSV has quotes around each field, then this features allows you to set the character. Most CSVs use " but some use a single quote: '

    Remove whitespace around non-quoted fields
    This will delete any space around commas, so your vCard is formatted properly. This is optional and is only applicable for CSVs with quoted fields.

    Interpret \n and \" as newline and quote
    Some rare types of CSV use \n and \" to represent newlines and quotes respectively. Tick this option if you want to take this into account.


    Filter/tranpose table

    This selection of options apply no matter what you're converting from or to.

    Transpose / rotate the data
    You can change the layout of the table so that rows become columns and vice versa.

    Remove columns with no values in them
    Many CSVs have redundant column headers with no corresponding data. It's not recommend, but untick this ticked if you don't want these automatically removed.

    Keep/remove selected dropdown menu
    This is used in conjunction with the 'Cols' and 'Rows' entries below. You can choose whether to keep certain rows/columns or remove them.

    Cols/Rows fields:
    If you only want the first column or row kept from the input, then just type in "1" (without the quotes) in the "Cols" or "Rows" fields. If you want the 2nd and 3rd columns, then you can use a comma to separate each number "2,3". You can even change the order of the columns by typing say, "3,2".

    Remove rows containing:
    You can specifiy rows you want removed by searching for certain keywords (separate each word by a comma for multiple entries).

    Other options

    As previously mentioned you can change all options back to default with the "Reset default prefs" button. This is useful to allow experimentation, or if you feel as if things aren't working correctly (see top middle of main window).

    If you want Opal-Convert to be portable (so you can run it from a pen drive for example), then simply create an empty text file called "portable.dat" in the same location as the main executable.


    Upgrade Opal-Convert to handle more contacts

    If the demo version doesn't allow enough contacts, you can upgrade from the main web site.


    END OF DOCUMENTATION