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

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 these permissions:

• System modules / access administration pages;
• Taxonomy module / administer taxonomy;
• Taxonomy_csv module / administer taxonomy by csv.

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
• ,Europe
• ,,France
• ,,,Paris

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

Partial lines are allowed, so a fifth 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, first to fourth lines above can be simplified to:

• World,Europe,France,Paris

Full lines, partial and one term lines can be mixed, but order is important two by two lines. In this example, if fourth and fifth lines are shift, < Paris > will become a child of < Switzerland >.

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"

2. Where are terms to import?

You can import your terms from a file or with a text area. Simply check your choice.

If import fails by one way (mainly due to character formats or server restrictions), you can try the second way as upload process is different.

Advanced setting allow you to set delimiter and format of the file (see below).

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

• 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 can have multiple characters only with text area import. 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 multiple characters only with text area import.
• 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 second fieldset.
• If you want to import big taxonomy and you can't increase maximum allowed time and memory on the server, you can activate Multistep autodivide import in the fifth fieldset. This option autodivides your taxonomy by the specified number of lines (100 by default). You only need to click a button to import each set of lines.
• Warning: with default Drupal "List terms" function, a memory error can occurs with big taxonomies. So use another manager as Taxonomy manager.
• 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.