TiddlyHoster - About:twab:Import

Tiddlers in Bag customers5
! Step 1: Backup Existing TiddlyWiki
It is ''highly'' recommended that you back up your current TiddlyWiki before you import contacts into your Address Book.  By default the import code will attempt to remove existing contacts before importing new ones.  It is possible but not likely that it could remove the wrong Tiddlers.  For additional safety you could reconfigure [[twab]] to keep existing contacts during an import as described in [[About:twab:Tweaks]].  Even still, you should backup your data before performing any imports.


! Step 2: Configure
By default [[twab]] will import any CSV data in the Tiddler [[TwabImport]].  You can easily change the Tiddler used for import by tweaking TwabPlugin as described in [[About:twab:Tweaks]].

Also, you should check on the value of the "config.macros.twab.preClean" variable as described in [[About:twab:Tweaks]].  If this value is "true" any existing contacts will be removed before new contacts are imported.

If you are fine with these 2 settings you don't need to do anything for this step.


! Step 3: Export
[[TwabPlugin]] was designed to import your existing Address Book as a comma-separated value (CSV) list of contacts.  Any strings that should be treated as one field with a comma in them should be surrounded by double quotes (e.g. a contact's job title is "Director, New Media").  All other commas will be interpreted as the separator between fields.  There should be no extraneous spaces between field values and commas (e.g. "Don, Mattingly , NYY").  

Most applications and online services will provide a means to export your contacts as a CSV file.  Once you've exported as CSV from your existing Address Book application you should place them into the [[TwabImport]] tiddler as plain text.


! Step 4: Inform twab of the Import Format
New to [[twab]] version 2.0, all imports and exports rely on mapping tiddlers.  There are a number of predefined choices as well as support for a customized mapping.  In addition to the [[default mapping|TwabDefaultFieldMap]], [[twab]] has built-in support for CSV data exported from the following locations:

* Yahoo! - [[TwabYahooFieldMap]]
* MSN - [[TwabMSNFieldMap]]
* Google - [[TwabGoogleFieldMap]] (see note after next paragraph)
* Outlook - [[TwabOutlookFieldMap]]

Once you place the CSV data into the [[TwabImport]] tiddler, simply add a tag to that tiddler to let [[twab]] know what format the data is in.  For example, if you've exported your data from Yahoo!, you would add a tag to [[TwabImport]] called "format:yahoo" and save the tiddler.  Twab will recognize the tag and know how to map the Yahoo! fields to its internal fields.  The full list of allowable tags for import is:

* Google - format:google
* Yahoo! - format:yahoo
* MSN - format:msn
* Outlook - format:outlook

''Note for Google users:'' Google's Gmail supports 3 export formats.  The first is one that it says is appropriate for importing into another Google account, the second is Microsoft Outlook's format, and the third is vCard format.  ''If you want to import your contacts from Gmail, you must export your contacts in Outlook format''.  Even still, in this case you ''must'' put the tag "format:google" on [[TwabImport]] because Google's Outlook format is not standard.  As for Google's internal format - it's very flexible but very difficult to work with.  I opted to pass on the challenge of parsing this format to keep the [[twab]] code as lean as possible.  One last thing - Google appears to have a habit of placing newlines (carriage returns) into the document it exports.  This is also non-standard.  In this case the only fix is to remove the newlines by hand as there's no easy way for me to detect them and remove them programatically.  Blame Google :)

If none of these mappings fit the bill, you can do one of two things.  You can use the default mapping ([[TwabDefaultFieldMap]]) or create your own map.  To use the default map, either put the tag "format:default" on the tiddler or leave off the "format:..." tag all together.  Twab will expect that the columns in the CSV data contain only names found in the [[TwabDefaultFieldMap]] tiddler.

The other option is to create your own mapping in a new Tiddler.  The mapping should follow the "name=value" format of the other mapping tiddlers.  To inform [[twab]] that you are using a custom mapper, place the tag "format:<Tiddler>" on the [[TwabImport]] tiddler, where "<Tiddler>" is the name of the tiddler that you created with the mappings.  For example, if you create a mapping tiddler called ~PalmTiddler, you would tag [[TwabImport]] as "format:PalmTiddler".

As a further example of mapping, let's say your current Address Book exports data that looks like this:

{{{
Sam,Adams,"Distributor, Beer",http://www.beer.com,555-1212
George,Washington,Bridge from NYC to NJ,,555-1313
}}}

[[twab]] needs to know how to map each of those fields.  You do this by providing a single header for all contacts as in this:

{{{
first.name,last.name,job.title,webpage,phone
Sam,Adams,"Distributor, Beer",http://www.beer.com,555-1212
George,Washington,Bridge from NYC to NJ,,555-1313
}}}

The above lines would be placed as shown into the TwabImport Tiddler.  Click this button to see how this should look: <<twab ImportTest>>
Note that you may need to scroll up to see the TwabImport Tiddler.

Some things to note:
* Every contact must have first name and last name fields or else [[twab]] will barf
* There shouldn't be any spaces between the commas and the field values (e.g. "first.name, last.name, ...")
* The order of the fields in the header is not important, but the order of fields in the header must match the order of the fields in each of the contacts below it.
* [[twab]] will not have any problem importing contacts where some of the fields are empty.  This is denoted by two commas in a row with no data between them as shown above.  The only required fields are the first name and last name fields.

! Step 5: Import
You can embed the twab import button in any Tiddler by adding the following code:
{{{
<<twab Import AddressBook>>
}}}
Which will result in: <<twab Import AddressBook>>

The first 2 parts of the macro should not be changed.  The last part, ''AddressBook'', declares the tags that should be assigned to each imported contact. Multiple tags are supported and should be separated by spaces as in this:

{{{
<<twab Import AddressBook importedContacts>>
}}}

These will be in addition to the tags specified in the configuration section of [[TwabPlugin]].    For that reason, the 3rd parameter is not required.  If it's not provided [[twab]] will use the default tag name.  See [[About:twab:Tweaks]] for more information.  This button is always accessible in the [[TwabPlugin]] Tiddler in case you don't want to create  a new Tiddler just for this reason.

Once the CSV data and the header are in the right place you can hit the above button to start the import.  You did backup your data right?  Large imports might take a long time, and it's not unusual for very large sets to cause a ~JavaScript popup asking permission to continue hogging resources.  An attentive and patient user will eventually get his or her contacts nestled safely inside the Tiddly.  Once the contacts are imported you can safely clear out the contents of TwabImport, although I do not recommend deleting it in case you want to import more contacts later.

! Step 6: Don't Panic
If something goes wrong on the import, keep in mind that all you have to do is to reload the Tiddly ''without'' saving your changes.  You can do this by pressing F5 in most browsers, or CTRL-R.  If prompted, say you want to discard changes and continue with the reload.  Any and all changes made since your last save will be lost (which is a good thing in this case).