Introduction
A CSV (Comma Separated Values) file is a simple text file format used to store tabular data, such as a spreadsheet or database. Each line in the file represents a separate record, and the values within each record are separated by commas. CSV files are widely supported by spreadsheet programs like Microsoft Excel and can be easily created, edited, or exported from such applications.
Within Keeping Culture, the CSV file must only include records pertaining to a single Knowledge class, List, or Archive Item/View relationship. Mixing records from unrelated classes within one spreadsheet is not permitted.
To import, update, or merge records using a CSV file, first upload the CSV and any related media files to the Archive Files directory. After uploading, you can choose your import file from the relevant wizard.
Creating a CSV of Knowledge class or List records
To prepare a CSV file, create a spreadsheet with column headings that correspond to the attributes or fields of the Knowledge class or List intended for import. Populate each row with the relevant metadata for every record.
Creating a CSV to import media into an Archive Item class
To prepare a CSV file, you will want to create a spreadsheet where the column headings relate to the attributes (fields) of both the Archive Item class and corresponding Archive View class.
In addition, you will need an additional column to specify the relative file path to the corresponding media file to import. The relative path should point to the media file’s location, relative to the CSV file itself.
Import file and folder structure example
Take a moment to look at this simple file and folder structure.
The ‘ImportPhotos.csv’ file contains the metadata for your import. In the same directory as this file, you’ll find a folder named ‘media’. Within the ‘media’ folder, there’s a subfolder called ‘photos’, which contains three JPEG images.
Here are the relative paths from the location of ‘ImportPhotos.csv’ to each image:
- media/photos/FieldTrip20170322.jpg
- media/photos/IMG9347.jpg
- media/photos/TIF03dFES.jpg
Remember to use forward slashes ( / ) to separate directories in file paths—do not use backslashes.
When importing Archive Item records that have multiple Views (like pages, tracks, clips, or different perspectives), you need a column with a shared value to show which rows belong together. Sometimes you can use an existing column such as Document Title for this purpose; other times, it may be necessary to create a new column just for grouping, though this column doesn’t need to be imported into the archive.
Each subsequent View should then be listed in rows immediately following the first one, maintaining their proper order. Doing so allows the system to identify all related Views as part of the same Archive Item.
During file processing, the shared column value of the current row is compared to that of the previous row. If these values are the same, the media and metadata from the current row are incorporated as a View record under the previous Archive Item. This assessment continues until a differing shared value is encountered, at which point a new Archive Item record is generated.
Exporting records from the archive to create a CSV file
A straightforward method for creating a CSV file suitable for import is to export a few records from the archive using the ‘CSV & TAB Exporter’ format. This process will generate a file containing the appropriate attribute headers along with sample metadata rows.
When you are ready to input your own metadata, retain only the header row and remove all other rows before entering your data.
For Archive Item records, the column header for the media record is not necessary; however, a column for the relative file path should remain. Any columns that are not required can be safely deleted from the file.
Limitations of CSV format
The CSV format has limitations when it comes to bringing metadata into the archive. The system offers several formatting techniques to improve the accuracy of the information being entered. However, there are some significant drawbacks to using CSV files:
- Features: CSV file imports do not support features. A feature is a complex data structure with properties that make it impractical to support in an unstructured format like CSV.
- Annotations: The system can process basic text-based annotations from a CSV file, but it cannot process audio and movie annotations. Annotations are complex data structures with dates, contributors, annotation text, and source text, and the system has limited capacity to interpret this complexity.
- References to Archive Items and Views: Column values derived from references to Archive Items and Views, through archive numbers and archive view numbers, may not be processed by the system. This is because the system cannot create an Archive Item and View record, as this relies on other metadata and a media file. Consequently, references to Archive Items and Views will be ignored.
- Sound record images: the image or sequences of images associated with Sound records cannot be exported or imported.
Date Formats for Import
When entering dates in your CSV file, use one of the following recognised formats to ensure compatibility with the archive:
- DD/MM/YYYY (e.g., 23/09/2025)
- MM/YYYY (e.g., 09/2025)
- YYYY (e.g., 2025)
- Decade (e.g., 1980s)
- Range of years (e.g., 1980 – 1988)
- Range of months (e.g., 03/2017 – 06/2017)
- Range of days (e.g., 13/07/2002 – 20/07/2002)
- Circa date (e.g., 1985c)
Using these formats helps maintain consistency and ensures your data is correctly interpreted by the system.
Note: If you’re using Excel, check your CSV in a text editor to confirm the dates remain compatible.
Formatting techniques
Providing a list of values for attributes that accepts multiple values
When you need to separate multiple values within a single line of text—such as a list of names, or tags—a delimiter is used. A delimiter is a specific character or sequence of characters that marks the boundary between individual items in the list. The most common delimiter is a comma (,), but others like semicolons (;) or pipes (|) can also be used.
For example, if you have a list of place names to include in a column of your CSV file, you might write: “Adelaide, Alice Springs, Darwin”. Here, the comma acts as the delimiter, clearly separating the text into three place names.
When importing, it’s crucial to ensure that the chosen delimiter does not appear within the actual values. Using the wrong delimiter may cause the data to be separated incorrectly.
Providing child attribute values in compound attribute fields
A compound attribute combines several attributes into one field. For instance, the Creator and Role attribute in Photos is a compound attribute, where the Creator (a Person record) acts as the parent, and the Role (a Creator Role record) serves as the child.
When you enter values for a compound attribute, you can place the child attribute’s value inside curly brackets—for example: “Kerry Johnson {Photographer}”. In this case, Kerry Johnson is identified as the Creator, while Photographer specifies the Role.
If there are multiple child attributes, use a pipe (|) as a separator within the curly brackets. For instance: “Jack Fields {Manager|Port Augusta}” assigns ‘Manager’ to the first child attribute and ‘Port Augusta’ to the second.
Adding a reference profile Id to multi-referenced attributes
Multi-referenced attributes, such as Tags, are capable of referencing values from multiple classes. However, when specifying one or more values within a CSV file, the system cannot inherently determine which class each value is associated with.
For instance, a CSV column value such as “Alyawarr {@:88}, Art and Craft {@:18}, ABC Indigenous Archive {@:20}” identifies three tags that reference classes with IDs 88, 18, and 20, respectively.