This module allows to import taxonomies, structures or simple lists of terms into a vocabulary from a CSV file, a url or a copy-and-paste text.

Csv format is a simple list of values separated by a delimiter, often comma (,) or semi-colon (;), and enclosures, often quotation marks ("). If you are unsure how to create a CSV file, you might want to use OpenOffice Calc or another spreadsheet application to export your data into a CSV file.

To import terms, user need one permission:

• Taxonomy_csv module / administer taxonomy by csv

• System modules / access administration pages
• Taxonomy module / administer taxonomy

Four items need to be set in order to import your terms.

1. What to import (content of the source)?

Source can be configured with the first field set. The first column always contains the term name. You can specify what you want to import and how additional columns should be imported.

Alone terms

Terms are imported as simple terms. Additional columns are ignored. Example:

• Diamond
• Gold
• Wood

Terms (flat vocabulary)

Use this option to import a lot of terms in order to create a flat vocabulary. All items in your file will be imported as terms. Example:

• Clothes, Trees, Houses
• Paris, Drupal

Hierarchical or one term by line structure

Use this option to create a structure of a vocabulary (tree). Your file can be written with two schemes.
In the first scheme, you need to set all ancestors to each term. The second column will be imported as the name of a child term of the term defined by the first column. The third column will be imported as a child of the second column, and so on. Lines can have any order. Example:

• Animal, Mammal, Whale
• Animal, Mammal, Monkey

Be careful: when a child is added or updated, line should contain all its ancestors. So a third line may be:

• Animal, Mammal, Human

but not:

• Mammal, Human

because in this second case, < Mammal > is imported as a first level term and not as a < Animal > term child as in previous line.

In the "one term by line structure" scheme, you can import terms without duplicate all its ancestor if previous term has ancestors. It is very useful with a spreadsheet application. It allows to easy build a structure and to upload a less heavy file. So your hierarchy can be:

World
	Asia
		Japan
			Tokyo
		Korea
			Seoul

So, first lines of your csv file can be:

• World
• ,Asia
• ,,Japan
• ,,,Tokyo
• ,,Korea
• ,,,Seoul
• ,Europe
• ,,France
• ,,,Paris

< Paris > will be automatically added as a child of < France > and so on.

Partial lines are allowed, so a next line can be:

• ,,Switzerland,Bern

< Switzerland > will be added as a child of < Europe > and of course < Bern > as a child of < Switzerland >.

In same way, above lines can be simplified to:

• World, Asia, Japan, Tokyo
• ,, Korea, Seoul
• World, Europe, France, Paris

Full lines, partial and one term lines can be mixed, but order is important two by two lines, except when there are only full lines. In this example, if fifth and sixth lines are shift, < Seoul > will become a child of < Japan >.

Related terms

Warning: in Drupal 7, related terms have been removed and replaced by fields. So this option is available only with Drupal 6.
Use this option to create links between terms, as "see also" in an encyclopedia. The second and next columns will be imported as related terms of the first column term. For example, a line may be:

• Baobab, Madagascar, Ghost

So < Baobab > will be related to < Madagascar > and < Ghost >. An option allow you to create subrelations, here between < Madagascar > and < Ghost > (see below).

Term description

The second column will be imported as the term description of the first column term. Example:

• "Baobab","An African tree"

Term weights

The second column will be imported as weight of the term defined by first column. Example:

• Baobab, 3

Synonyms terms

The second and next columns will be imported as synonyms terms of the first column term. Example:

• "United Kingdom","Great Britain","England"

Taxonomy manager export

This format is used by Taxonomy manager to export vocabularies. Columns are: vocabulary id, term id, term name, term description, first level parent 1, ..., first level parent n. Example:

• "1"; "25"; "Louis XVII"; "King of France"; "Louis XVI"; "Marie-Antoinette"

In this format, order of all lines is important: it's impossible to attach a parent to an item if this parent hasn't been imported in a previous line.
When a vocabulary is imported in an existing one, only option "ignore existing terms" can be used.

2. Where are terms to import?

You can import your terms from a file or with a text area. Simply check your choice. File can be a local file path or a url.

Advanced settings allow to set non standard delimiter and enclosure.

3. Where to import into (vocabulary destination)?

You can import your terms in a existing vocabulary or create a new one. You can import your terms too in a duplicate of an existing vocabulary.

When you want to import a new taxonomy into an existing one, it is recommended to process in three steps in order to allow a good import.

• First, check the import file with the < Autocreate a new vocabulary > option. Repeat this step while there are warnings and notices.
• Second, check new and existing terms merge with the < Duplicate an existing vocabulary > option. This choice creates a duplicate of your target existing vocabulary and import your new terms into. Original nodes attachments are not duplicated.
• Finally, you can import your file in the true vocabulary with the < Import in an existing vocabulary > option. This allows you to keep old links between existing terms and nodes.

If you only want to create a new vocabulary, the first choice is sufficient, unless when you have multiple files for one vocabulary.

4. How to import your terms?

Destination can be configured with the second field set. You can specify what will become existing terms. Four choices are possible, or less matching your source content:

Update terms and merge existing

Update current terms when name matches with imported ones and merge existing descriptions, parents, synonyms and related terms with new ones. Duplicates are removed. This choice is recommended if you want to keep a vocabulary and if you have descriptions, parents, synonyms and related terms you don't want to lose.

Update terms and replace existing

Update current terms if name matches, but remove existing descriptions, parents, synonyms and related terms. Choose this option if you are want to create a clean new vocabulary without losing existing terms.
Be careful: if there is no description, parent, synonym or related term, i.e. the line contains only a term in the first column, this removes the existing.

Ignore current terms and create new ones

Let current terms as they are and create a new term for the first column term.
Warning: This can create duplicate terms. It is recommended to use this option only if you are sure that imported taxonomy contains only new terms or if your vocabulary allows multiple parents.

Ignore all current terms and create new ones

Create a new term for each term on the line.

Advanced settings and hints

• To import big taxonomies when access to time and memory settings of server are forbidden, it is recommended first to disable some other modules as "pathauto" before import. Settings aren't lost when you disable a module - and not uninstall it -. After import process, modules can be reactivated.
  Second, you can use file import. Third, you can reduce log level. Fourth, you can use these tweaks.

  Disable internal cache

  This option disables internal cache, which allows to import complex vocabularies, with multiple parents and some duplicates. It's useless with simple lists of terms or tree structures, but it allows to display informations about import process. When disabled, no information about results can be displayed except eventual first error or warning.

  Manually set vocabulary hierarchy

  As to calculate vocabulary hierarchy is memory intensive, this option allows to set hierarchy manually without verify it.

  Disable line checks

  If you are sure that vocabulary to import is well formated (utf8, order of items...), you can disable checks. This option increases import speed by 5%.

• Warning: with default Drupal "List terms" function, a memory error can occurs with big taxonomies. So use another manager as Taxonomy manager.
• Delimiters (comma "," by default, semicolon ";" or tabulation) between terms can be chosen in Advanced settings in the second fieldset. You can choose a custom delimiter too. Delimiter is a one character string. Example with delimiter < ¤ >:
  
  • term 1¤This field has commas, a semicolon (;), a quotation mark (") and a tabulation, but it will be correctly imported.
• It is recommended to protect terms with enclosure characters as quotation marks ("), specialy if they contain non-ASCII letters or if imported items, in particular descriptions, contain the chosen delimiter. Example:
  
  • "term 1","This field has a comma, but it will be correctly imported."
  You can choose a custom enclosure character in Advanced settings in the second fieldset. Enclosure can have only one character or be null.
• It's recommended to use text area import or utf8 encoded file in order to avoid problems with non-ASCII terms. If your server doesn't support utf8 conversion, an option allows to disable it in the last fieldset.
• When you want to import child term names as well as descriptions, synonyms, related terms, term weights and a hierarchical structure, you should begin with the file containing the hierarchical structure. So first import child term names with the < Structure > option. Second, upload the other files with the adequate option and one of the Update terms... option.
• Be careful: if 1) source choice is not "Ignore" additional columns, 2) file or a line in the file has only one column and 3) you choose "Update and replace", the import process will be a remove process of matching items (first column terms are always kept or imported).

Another Drupal module allows CSV import too, despite its name: taxonomy XML. Its approach is different: it uses one file complient to thesauri standard ISO 2788, i.e. a three columns csv file: first term, type of link, second term, or, for specialists, subject, predicate, object. For Drupal 4.7 and Drupal 5, taxonomy batch operations is available too. So choose the module best matching your needs.