epsilon-submission-toolbox

Epsilon CSV Submission Template

Instructions

Create a folder for your collection at the root level of the toolkit.
Create a CSV file containing your correspondence data in the folder you created.
Ensure that the first row contains the required, as well as any desired, column names.
Enter each letter onto a separate row.
Place a copy of csv/key.csv in the folder you created. This will be the “key file” for your collection.
Supply information about your collection in your key file.
If your letters csv has different field names that the recommended Epsilon ones, enter them into the local_name column in your key file.

That’s it.

Create a CSV file containing your correspondence data

All records require the following information:

correspondence details of both the sender and recipient
date of the letter
information about where the item currently is (ie. institution and shelfmark or, if it only exists in a printed source (e.g. a journal), it’s bibliographical details)

While these details represent the bare minimum required for a useable letter record, many other fields are available (see below).

Ensure that the first row of the CSV contains column names

If you use Epsilon’s recommended names for the columns, all that remains for you to do is Supply information about your collection in your key.csv file.

If any of your column names differ from Epsilon’s recommendation, you will need to provide the information to map your column names onto ours with your key.csv.

For example, if the field name you use for the recipient’s address (recipient_address) is ‘address’, scroll to the line for recipient_address in key.csv and add the text address into the local_name cell (Cell D) for that row.

N.B: It’s only necessary to provide mapping information for fields whose names differ. If all but two of your fields match Epsilon’s, you only need to provide mapping information for those two.

You can find a full list of the Epsilon fields and their purpose in Epsilon Fields.

Supply essential information in key.csv

In addition to providing you with the ability to map custom field names onto their Epsilon counterparts, the key.csv file also lets you supply default values for each individual field that we support. This value will be used whenever the field is empty (or does not exist) within your CSV.

For example, if you wish to record your name as the contributor of the records, you would scroll to publicationstmt_contributor in key.csv and place your name into the default_val cell (Cell C).

While you can supply default values for any field, default values make more sense for some fields than others. In fact, there are five fields where it is essential for you to provide a default value, esp if their data is not recorded in your csv.

epsilon_collection_name provides the full name for your collection (e.g. The John Doe Collection)
epsilon_collection_facet provide the shortened form of your collection name (e.g. John Doe Collection) that’s used in Epsilon’s search forms and browsing facets
publicationstmt_contributor provides the name of the person (or organisation) submitting the record into Epsilon
letter_date_min and letter_date_max provide the earliest and latest in which any letters could have been sent. Even if the date of the letter is unknown, you can provide logical values for these fields - e.g. your correspondent cannot write a letter before s/he was born or after their death). These values will be used to ensure that any undated letters or letters with an open ended range (‘before DATE’ or ‘after DATE’) sort properly within the entire Epsilon collection.
The value must be provided in yyyy-mm-dd format, e.g. 2024-04-15
If you do not supply unique identifiers for the letters within your collection (DOE-PROJECT1, DOE-PROJECT2, etc) in your correspondence csv, you will need to supply a default_val in doc_id_prefix (e.g. DOE-PROJECT). Epsilon will then create id values for them combining this prefix with the record’s row number in your correspondence csv (not counting the header).

You can find a full list of the Epsilon Fields and their purpose in Epsilon Fields (below).

Epsilon Fields

Epsilon field name	Description
doc_id	If your letters already have unique identifiers within your project, please supply it in this field. Unique identifiers must start with a letter. `default_val` will be ignored for this field.
doc_id_prefix	If you do not supply unique identifiers within your correspondence csv, you MUST provide a `default_val` for this field. Epsilon will create unique identifiers using it and the letter’s row number.
modification_date	OPTIONAL The date your record was last modified. The value must be provided in `yyyy-mm-dd` format, e.g. `2024-04-15`)
title	The title of the letter `default_val` will be ignored for this field.
sender_name_full	The full name of the sender (e.g. John Quentin Doe)
sender_name_canonical	A shorter form of the name used in the facets (e.g. Doe, J. Q.)
sender_surname	The sender’s surname (e.g. Doe)
sender_forename	The senders forename(s)	(e.g. John Quentin.)
recipient_name_full	The recipient’s full name (e.g. Arthur N. Other)
recipient_name_canonical	The recipient’s name for the facets (e.g. Other, A. N.)
recipient_surname	The recipient’s surname (e.g. Other)
recipient_forename	The recipient’s forename(s) (e.g. A. N.)
letter_date_sorting	REQUIRED The date of the letter in `yyyy-mm-dd` format, e.g. 1880-11-19. This value will be used when sorting chronologically. This should reflect where you want the letter to appear in a sequence. For example, if you know a letter was written during a particular week, you can assign it a particular day during that week where you would like the letter to appear in a date-sorted set.
letter_date_text	OPTIONAL A textual form of the date (e.g. 19 Nov 1880; 19? Nov 1880; after 18 January 1888; 18-25 Dec 1869) If this field is empty a textual version of the `letter_date_sorting` value will be created. For example, if `letter_date_sorting` were 1880-11-19, Epsilon would supply a value of 19 Nov 1880. Strictly speaking, it is only necessary to provide a textual version of the date when it differs from what Epsilon would create, e.g. ‘19? Nov 1880’, ‘after 18 January 1888’, and ‘18-25 Dec 1869’
letter_date_min	The earliest date for the letter in `yyyy-mm-dd` format, e.g. `2024-04-15`. If `letter_date_text` was ’18-25 Dec 1869’, this field would have a value of ‘1869-12-18’. If it were ‘after 18 January 1888’, `letter_date_min` would be `1888-01-19`. You MUST provide a default value for this field in your key.csv.
letter_date_max	The latest date for the letter in `yyyy-mm-dd` format. If `letter_date_text` was ’18-25 Dec 1869’, this field would have a value of ‘1869-12-25’. If it were ‘before 18 January 1888’, `letter_date_min` would be `1888-01-17`. You MUST provide a default value for this field in your key.csv.
sender_address	OPTIONAL The sender’s address. This can be at any level of detail you choose to record.
recipient_address	OPTIONAL The recipient’s address. This can be at any level of detail you choose to record.
language	OPTIONAL The language(s) in the letter
epsilon_collection_name	REQUIRED The full name that you would like your collection to have in Epsilon. While you can supply this value for each letter in your correspondence csv, it makes more sense to supply it in default value for this field in the key.csv
epsilon_collection_facet	REQUIRED The shortened name that you would like your collection to have in Epsilon’s search form and browse facet. While you can supply this value for each letter in your correspondence csv, it makes more sense to supply it in default value for this field in the key.csv
sourcedesc_provenance	Records the location of the letter if it’s recorded in a single string in your collection (e.g. Cambridge University Library, GBR/0180/RGO 6/1:42).
sourcedesc_idno	Records the identifier/classmark for the item (e.g. GBR/0180/RGO 6/1:42)
sourcedesc_collection	Records the collection the item is in within the holding institution.
sourcedesc_repository	Records the body that holds the item (e.g. Cambridge University Library).
sourcedesc_repository_key	OPTIONAL Epsilon holds a Repository Authority list of repositories, or the institutions and people that hold the items. If this repository already exists within Epsilon’s Repository authority list, you can supply its value here.
publicationstmt_contributor	REQUIRED The name of the individual or organisation submitting the record to Epsilon.
publicationstmt_item_url	OPTIONAL A hyperlink to the record’s entry on the holding institutions publicly accessible catalogue or index.
publicationstmt_year	OPTIONAL	If the item has been published elsewhere, you can put the publication year here.
seriesstmt_text	OPTIONAL If you created a modern printed edition of this work and you have permission from the publisher to contribute the text to Epsilon, you can record the publication information for the edition here.
seriesstmt_url	OPTIONAL A URL to your printed edition of the work.
seriesstmt_collection	OPTIONAL
seriesstmt_also_published_in	OPTIONAL If the text of the letter has been published elsewhere, you can record the publication information here.
summary	OPTIONAL A summary or abstract of content of the letter.