Opal-Convert CSV/VCF/Excel/vCard Documentation

Opal-Convert is very easy to use, yet powerful. Simply open a file (top left button), or copy/paste into the left white panel. Then select a format to convert from (e.g.: CSV is chosen below), select an output format ("Convert to..." dropdown menu), adjust any options (more details below), and then finally save the file (save button will turn green).

As you change the options (for example, the CSV delimiter here), 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 files at once.

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).

Batch conversion

If you would like to convert many files at once, you may find it is best to experiment with just one of them first of all. This is because you can try changing the options and see if the resulting output in the right panel is to your liking. The great thing is, as you're changing the options, the output updates in realtime to give you instant feedback on what works best for you. Once you're happy with a single input file, then you can perform a batch conversion by selecting the Open File/s dropdown menu, and clicking "From folder (batch)". From there, select your folder, click the save button (make sure the "Convert to" is CSV first), and choose your output folder.

If you are converting from Excel/CSV to multiple vCards, you won't need to use batch, since multiple contacts can be stored in the CSV. However, if you are converting from vCard to CSV, you may wish to open a batch/folder of vCards to create a single CSV file.

If you want to disable batch mode, close and reopen the program.

Filter/tranpose table

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

Keep/remove selected
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".

Tranpose table option
You can change the layout of the table so that rows become columns and vice versa.

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. This is useful for experimentation, or if you feel as if things aren't working correctly (see top middle of main window).

There's also a unicode option (top left of main window) which allows you to insert a larger range of text characters than usual. However, pasting in the input window can be slower as a result for very large documents.

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.

Converting from CSV

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

You also have the option to remove trailing commas (or whatever the delimiter is) with the "Remove trailing commas/whitespace" button. For example, "1,2,3,,, , ," will become "1,2,3".

Converting from HTML table

You don't need to necessarily extract the table from the HTML as Opal-Convert will automatically hunt for table data inside the HTML. The "Keep HTML inside cells" option will keep tags such as bold or font.

You have three options to load the HTML: copy/paste directly, load a file (or files), or load a URL.

Converting from Programmer 2D Array

Example input might be:

{"1", "2", "3", "4" },
{"5", "6", "7", "8" },
{"9", "10", "11", "120" }

Converting from vCard (or vCards)

When converting from vCard (VCF), the most common usage here will be to convert from vCard (or multiple vCards) to CSV/Excel. There are many 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. In any case, it's easy to experiment because the output changes instantly as you adjust the options. See here for converting from Excel/CSV *to* vCard instead of from vCard to Excel/CSV.

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. Alternatively, if you have only a single file, but one which contains multiple vCards. In this case, don't open a batch, but instead select "Open file/s -> From 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:

"Property (Parameter/s), Value" dropdown menu
This menu presents a selection of two options which determine the layout of the output CSV.
For example, compare these two different layouts:
Tel (home), 01234 567890
Home: Tel, 01234 567890

Filter out properties with binary data
Any rows which contain binary data (denoted by "ENCODING=BASE64" in the parameter) will be filtered out if this option is selected.

Delimiter to use if merging fields
Compound fields such as name and address items will be together in one row (if the appropriate tick is selected from the window shown by clicking the "More..." button. The delimiter just means what each field is separated by in this case.

Filter out HTML and XML: Certain vCards may have unwanted HTML or XML data. This will filter it.

Replace \n and =0D=0A with delimiter: Certain vCards may have these 'carriage returns' in the labels. Ticking this will replace it with the delimiter.

Filter rows with empty values: Any empty rows can be filtered out if desired.

Adjut CSV field names... This button opens a whole new window to further adjust the options for the vCard. Here's a description of the options:

Fields 1-7 indicate the names that should be used in the final CSV (or other) output.

The first column of ticks indicate whether that vCard property is included in the final CSV.

The 3rd column "Include params?" indicates whether parameters are featured in the final output. Paramaters could include the "types" of the property, such as "home", "fax", or "cell" for the "TEL" property,............ or say, "home", "work", or "parcel" for the "ADR" (address) property.

The "Merge fields?" column determines whether fields should be merged into one row in the final output or not. For example, the address could be on one line, or it could be separated into Street, Town, State etc. property-value records.

"Name if using merging". Read the previous line. If "Merge fields?" was ticked, then this will determine the property name for the row in the output.

"Include empty fields?". If a field from say... an adress (e.g.: Town) is empty, this will determine whether or not to include that property anyway. (If the line is merged, then the delimiter will be used instead).

For better compatiblity with Excel (or any spreadsheet), you may want to tick (or keep ticked) "Enclose values with double quotes" (allowing commas in the fields). Finally make sure you view all files when you try to open the CSV into Excel (by default, only "All Excel Files" are shown).

See the next section for setting some of the options regarding the CSV format that you're converting to.
See later for converting TO vCard instead of from.

Converting to CSV

When you convert from another format to CSV, you can adjust the delimiter to a comma or something else. A tab or pipe is sometimes used so that commas can be preserve in the original text. If there is a clash, then you can decide what character (or characters) the delimiter should be converted to.

Converting to HTML table

It's easy to convert to HTML. The characters < and > are special HTML codes, so these will be replaced by { and } respectively (you can change these to something else).

Optionally, all horizontal cells can be put into one line for a shorter document. If this isn't desired, then the more usual way would be to untick "one <tr> per line".

Finally, you can make the first column or row bold, and pad empty fields with the usual <td></td> syntax to represent empty cells. This produces more standard HTML.

Converting to Programmer 2D array

This will produce a typical 2D C or C++ style array so that you can incorporate your data into programs. You can adjust a 2D string array to a 2D float/double array by ticking the "No quotes" option. Example conversion from CSV could be:

1,2,3,4
5,6,7,8
9,10,11,12

to...

string[,] s = new string[,]
{
{"1", "2", "3", "4" },
{"5", "6", "7", "8" },
{"9", "10", "11", "12" }
}

Converting to vCard (or vCards)

When converting to vCard, you'll probably be interested in converting from Excel (or CSV format).

First off, select CSV/Excel from the "Convert from..." dropdown, and "vCard" from the "Convert to..." dropdown, then open the Excel/CSV file to the left panel using the "Open file/s" button (you can paste the data into the panel if you prefer).

To facilitate conversion, Opal-Convert allows you to adjust the header keywords to the appropriate vCard properties (click the "Find matches to CSV fields..." button, and you'll see the image to the right). 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 "<ignore>" any of the CSV 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. You can also populate more specific vCard properties such as Last/First/Middle name and Street/Town/State. At the top of the window shown to the right is an option to select the type of vCard Opal-Convert will create. Start off with "Outlook (Simple)" or "vCard 2.1" mode and try the other modes out if you need more specific and rarely used properties (e.g. Nickname, IM address, or Assistant name).

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.

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.

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 (you can choose to either save them out as separate files, or include all four vCards in on multiple-contact VCF file (select "Merge multiple contacts into single VCF file" in this case). 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, Phone (business), Phone (home), Mobile
David P Jones, David, Jones, ABC ltd., AB12 3CD; UK, contact@abc.com, 01234 567890, 01234 567890, 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

See Converting from CSV to set the options in the initial CSV.
See earlier for converting FROM vCard instead of to.