Skip to content

Import CSV

Elric Wamugu edited this page May 21, 2020 · 27 revisions

Migration of databases to Uwazi using CSV files

Preparation for Import

It is useful to create a list (separate from the CSV file) of templates/formats that are to be migrated, mentioning type of field and name of field in Uwazi.

To import a CSV file, click on the "Private documents" icon and then "Import".

Guidelines and Conventions

  1. Save your file as a CSV (Comma Separated Values). CSV files are easier for Uwazi to parse.
  2. Migration works with matching names – therefore, one should create a structure in Uwazi with the same field names as the column headers in the CSV file. For field names one can use either lower case or capitals. It is always possible to rename fields in Uwazi after import.
  3. The order of the columns is not important, data will be imported in the correct column in Uwazi.
  4. The “title” is required and serves to identify a record. It does not have to be unique.
  5. The “date added” is filled automatically with information during the import into Uwazi.
  6. The names of columns should not contain empty spaces, use the actual property name/key value of the template field. You can find these values via the api: https://your_uwazi_url/api/templates.
  7. The pipe symbol | is to be used as the separator in a field with multiple values.
  8. To import geolocation data, the coordinates data should be included in one column with the latitude coordinates first and the longitude coordinates next with no spaces, separated by the pipe symbol. In the CSV file, this column should be named 'geolocation'.
  9. To import relationships, create a relationship property pointing to the correct templates, with the relationship types you want, etc. In the CSV, insert the entity title in the value for that metadata field, and it will create both the metadata value and the relationship itself. Currently, there is no way to create 'standalone' relationships.
  10. For links to external files/documents what you want to migrate to a Rich Text property in Uwazi, use the convention [Name](link), for example [HURIDOCS Micro-thesauri]( To import hyperlinks the Uwazi link property, follow the "label|url" protocol.
  11. It is possible to import different CSV files into the same template.
  12. If the various columns in the CSV file are to be migrated to different templates in Uwazi one should split the CSV file so that the data for each template are in separate CSV files.
  13. After an import has been done, editing of records should take place within Uwazi. A feature to update a set of imported records is under development.
  14. If the source data is in different languages, these languages should be configured beforehand in Uwazi.
  15. The data in different languages should be on their own columns with the column heading/title separated by a double underscore i.e title__en, title__fr, title__ar i.e
  16. To import the document itself, the main PDF file(s) should be compressed within a single ZIP file. This ZIP file should also include a CSV file which contains the title of the record to which the file is to be linked and a column with the name of the main file(s). Please note that our CSV import currently allows only the main document to be uploaded; the import of related attachments is not yet supported.
  17. Multiple dates within one field is not yet supported.

Related issues:

  • A feature is under development to export the structure as well as export all the data.
  • Another feature is importing only thesauri as documented on This will also allow to import terminology lists in different languages. HURIDOCS has developed 48 micro-thesauri for the documentation of human rights violations. They are available in several languages as CSV files, see
  • Different fields in Uwazi can be linked to the same thesaurus.
  • For exceptional situations occurring in particular instances we seek to make “work arounds” rather than new features which take more time.
Clone this wiki locally