Taxonomy CSV import help

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 semicolon (;), 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.

What to import (content of the source)?
Where are terms to import?
Where to import into (vocabulary destination)?
How to import your terms?
Advanced settings and hints

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

Source can be configured with the first field set. Except with some formats, the first column contains the term name. You can specify what you want to import and how additional columns should be imported.
Vocabulary structure should be imported first when multiple files are used. So choose options Full term links, flat, structure, polyhierarchy, first level of parents or children before relations, descriptions, etc.

1. Alone terms

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

Diamond
Gold
Wood

2. Full term definitions and links

This option allows to import full term definitions and direct links to other terms.

Format is: term name, term id, vocabulary name or id, term description, weight, number of synonyms, number of first level parents, number of first level children, number of related terms, list of synonyms, list of first level parents, list of first level children, list of related terms, list of vocabulary ids or names of related terms.

Only term name should be defined. Other values can be empty. Term id need to be set only for duplicate terms. Example with one synonym, two first level parents, no children, one relation with a term of another vocabulary:

Drupal, , Knowledge management, "Created by Dries Buytaert in 1998", 10, 1, 2, 0, 1, Drop, CMS, CMF, Open source, Software
Term 1, , Vocabulary 1, "Description of term 1", 10, 1, 2, 0, 1, Synonym 1, Direct parent 1, Direct parent 2, Related term 1, Vocabulary of related term 1

A simpler option, Full term definitions, allows to import only definitions.

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

4. Hierarchical tree structure or one term by line structure

Use this option to create a tree structure of a vocabulary (geography, classification...). To import a hierarchy with multiple parents as a genealogical one, it's advised to use "Polyhierarchy", "First level children" or "First level parents" imports.

Your file can be written with two schemes and a mixed one.

First scheme: Full ancestors of a term

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.

Second scheme: One term by 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

,,Italia,Abruzzo,Chieti,Chieti
,,,,,Civitaluparella

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

Mixed scheme

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

5. Polyhierarchical structure

Use this option to create a a polyhierarchical structure, as a genealogy.
Format is the same than tree structure: each term is the child of previous item: parent, child, sub-child... and so on.
There are four differences. First, the first item doesn't need to be a root. Second, duplicate terms are always merged, except when one is the direct parent of the other one, because it's forbidden in Drupal. So, if the vocabulary is monohierarchical and without non-direct duplicate terms, as in the previous geographical example, result is the same than with previous option. Third, lines can be partial too, but in some case of duplicates, result may differ. Last, polyhierarchy can be recursive.
For example, lines may be:

Grand-Mother, Mother, Daughter
Grand-Father, Mother, Son
Grand-Mother 2, Father, Daughter
Grand-Father 2, Father, Son
              ,       , Son 2
              , Uncle
Grand-Mother 2, Uncle
Father, Son 3

6. First level parents of a list of terms

This choice allows to create a vocabulary in which terms can have more than one parent, as in a genealogy (polyhierarchy).
The first item is imported as a term, the second and next as first level parents of first term. For example, lines may be:

Daughter, Mother, Father
Son, Mother, Father
Son 2, Father
Son 3, Father
Mother, Grand-Mother, Grand-Father
Father, Grand-Mother 2, Grand-Father 2
Uncle, Grand-Mother 2, Grand-Father 2

7. First level children of a list of terms

Mother, Daughter, Son
Father, Daughter, Son, Son 2, Son 3
Grand-Mother, Mother
Grand-Father, Mother
Grand-Mother 2, Father, Uncle
Grand-Father 2, Father, Uncle

The three previous examples import the same vocabulary when existing items option is "update and merge", which is the recommended one.

8. Related terms

Warning: in Drupal 7, related terms have been removed and replaced by fields. So this option is available only with Drupal 6. To get same functionnality, you need to create a "relations" field.
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).

9. Full term definitions

This option allows to import full term definitions. Format is: name, weight, description, list of synonyms if any. Example:

Street, 1, "A urban way", Avenue, Road

A more complete option, Full term definitions and links, allows to import not only definitions, but links to other terms too.

10. Term descriptions

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

"Baobab","An African tree"

11. Term weights

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

Baobab, 3

12. Synonyms terms

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

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

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

When source content is Full term definitions and links, destination is determined by source. If third column is an id, a new vocabulary will be created. If it's a name, a vocabulary will be created if it doesn't exist. If it's empty or zero, a vocabulary will be autocreated, duplicated or used depending on the destination option. This process is used for related terms too.

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.

5. Advanced settings and hints

Big taxonomies import

To import big taxonomies (from 1000 or 10000 lines depending on the server) when access to time and memory settings of server are forbidden, it is recommended first to disable some other taxonomy related 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
To disable internal cache allows to import vocabularies of any size. Internal cache is used to speed up process, to reduce access to sql base and to be informed about 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 and enclosures

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. Quotation marks (") are automatically managed.

Permissions

To import terms, user need one permission:

Taxonomy_csv module / administer taxonomy by csv

This permission is often associated with these ones:

System modules / access administration pages
Taxonomy module / administer taxonomy

Other hints

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 Full term definitions and links, Flat, Structure, Polyhierarchy,Parents or Children 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 compliant to thesauri standard ISO 2788, i.e. a three columns csv file: term, type of link (relation, description, synonym...), item, or, for specialists, subject, predicate, object. Additional fields are managed as the third one. For Drupal 4.7 and Drupal 5, taxonomy batch operations is available too. So choose the module best matching your needs.