Taxonomy CSV import/export

This module allows to import/export taxonomies, structures or simple lists of terms into/from a vocabulary from/to 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 LibreOffice Calc or another spreadsheet application to export your data into a CSV file.

Specific import or export formats can be added simply by a plug-in mecanism (or ask author!).

After enabling the module, permissions "import taxonomy by csv" and "export taxonomy by csv" need to be set. Main "administer taxonomy" permission is not needed to use module, but this is recommended.

Internationalization is supported, except for attached Fields [Taxonomy CSV pour Drupal 7 only]. So you can import a list or a structure of terms, then translate them.

This module supports drush and allows to import or to export taxonomies by csv with command line interface.

Taxonomy CSV for Drupal 7 has got a simpler UI compared to the version for Drupal 6, because taxonomy has been reworked with fields in Drupal 7. Help for Drupal 6 version is available in English or in French.

1. Formats

Multiple formats can be used to import or export vocabulary. Except with some formats, the first column contains the term name. You can specify what you want to export and how additional columns should be imported.

To import a complex taxonomy, it's recommended to import terms in this order:

• Structure (flat, tree or polyhierarchical)
• Fields (name, weight, description, parent and what you want)
• Translation (if i18n is installed)

That's what you can choose in the first tab.

1. Structure

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

2. 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:
Be careful: when a child is added or updated, line should contain all its ancestors. So a third line may be:
but not: 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: < 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 > 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:

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

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

2. Fields

Terms are imported with a csv scheme provided by the user.

1. Fields CSV format

The csv scheme should contain each column header of the csv input. The column header is the name (not the label) of the field where to import items into. It can be a default header (name, description, weight, vid, vocabulary_machine_name, guid) or a custom field. The first item is always the name or the tid of a term.

For example, you want to import a list of car makers, and you would like each car maker to have custom fields indicating nationality and date of origine(origine of example, fictional):

So, with 'Fields' format, you can set your format:

or more generically:

Items can be repeated for multivalued fields.

The module supports all field types as long as they have a 'value' in their definition. These fields has been checked:

• text
• text_long
• text_with_summary
• number_decimal
• number_integer
• number_float
• list_boolean
• taxonomy_term_reference [Note: if value is a number, the field will be linked to the term with that tid; if value is a string, the field will be linked to an existing or a new term with that name.]
• file

2. Autocreation of Fields

Custom fields are automatically created if they don't exist and then attached to the vocabulary. By default, a 'text' field is created when the field doesn't exist. If you want to create another type of field, you have to set it with "|" symbol in the vocabulary section of the form. The field is not created or modified if it exists.

For exemple, you want to import these items (origine of example):

Your custom format will be:

Your custom fields will be:

3. Term translation

Translation is available only if i18n is installed and the submodule i18n Taxonomy is enabled. Furthermore, the i18n mode of the vocabulary should be "Translate" or "Localize".

Warning: If you have a tree structure, you should import it before fields or translations, and for each translation if you use a full Translate mode.

Format: The term is in the first column followed by its translations. If the i18n mode is Localize, then description and translated descriptions can be added.

For vocabulary with Translate mode:

For vocabulary with Localize mode:

Examples:

Notes

• With a vocabulary in Translate mode, a term with an undefined language cannot be translated, so do not forget to choose a language when you import original terms.
• With a vocabulary in Localize mode, only terms with a undefined language can be translated, so do not set a language when you import original terms.
• All languages should have been enabled in Regional and language settings before import.
• Important: If your taxonomy is structured, you should import the structure before. Furthermore, if the i18n mode is Translate, you should import the structure for each translation before. The translate process only creates translation sets for terms, but does not recreate any structure.
• With Translate mode, terms with an undefined language ("und") cannot be translated.
• With Localize mode, only terms with an undefined language can be translated, so the first language should be "und" and the default language of the site cannot be used.

2. Import

Taxonomy CSV allows to import structure and properties of terms.

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

Source can be configured with the first field set. See formats.

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.

3. How is formatted your source?

Import need to be utf-8 formatted, without byte order mark in preference.

This group of settings allows to set non standard delimiter and enclosure and specific locales, such as "fr_FR.utf8".

• 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.
• Warning: when you export a vocabulary, delimiter and enclosure should not be used in term definitions, specially in descriptions. Export process will stop in case of problem.

4. Which vocabulary do you want to import into?

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

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

• First, check the import file with the < Autocreate a new vocabulary > option. Repeat this step while there are warnings and notices.
• Second, 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.

5. When a term exists, what to do with it?

Destination can be configured with the next field set. You can specify what will become existing terms when you import a term with the same name.

• Update terms and merge existing (avoid duplicate terms)

  Update current terms when name matches with imported ones and merge existing descriptions, parents, etc. Duplicates are removed. This choice is recommended. Note: Duplicate terms in trees are fully supported.

• Ignore current terms and create new ones (may create duplicate terms)

  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.

6. Informations on process and big taxonomies import

This group of options allows to choose informations displayed at end of process.

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.
Next, you can use these tweaks (in groups of options).

• Reduce log level

  Stats, terms and notices or warnings displayed at the end of process are memory consomming. So, you can reduce or disable them.

• 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 formatted (utf8, order of items...), you can disable checks. This option increases import speed by 5%.

3. Export

Taxonomy CSV allows to export structures and properties of terms of one or all vocabularies.

Simply choose what you want to export (see formats) and how to export. Some formats may be unavailable.

4. Drush and Taxonomy csv import API

This module supports drush: you can import/export taxonomies from the command line interface with drush taxocsv-import and drush taxocsv-export. See command line help for more information.

More generally, this module can be used as an API. You can use the full module as a dependance or directly in your module. Import is run as this:

Or as this (line level import):

Possible formats are explained in comments or above. Some may be unavailable.

Taxonomy Builder API can be more convenient in some cases. Choice depends on your needs. Taxonomy CSV is designed as a run-once module with checks and multiple formats, while Taxonomy Builder is a permanent, light and quick module. A full explanation of the differences in design can be found here.

5. Advanced settings and hints

1. Permissions

To import/export terms, user needs 'Import taxonomy by CSV' and 'Export taxonomy by CSV' rights.
Furthermore, user needs general taxonomy permissions (Drupal 6) or taxonomy permissions (Drupal 7). These permissions are often associated with access rights for administration pages.

2. Other hints

• It's recommended to use utf8 encoded file in order to avoid problems with non-ASCII terms.
• Some memory or compatibility issues have been reported with some modules as Pathauto, taxonomy_vtn and taxonomynode (see #495548, #447852 and #540916). It's advised to increase server and php memory temporary (no problem reported with 256 MB) or to disable these modules manually (settings aren't lost when you disable a module - and not uninstall it -). After import process, you can decrease memory and reactivate modules.

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.

Taxonomy manager can be used too.

For export, you can use Taxonomy XML too or one of backup modules. Taxonomy CSV is a more specialised tool which allows more precise tuning.