If you are using FilmFreeway, you can ignore import mappings. SparqFest pre-defines an import mapping for the standard FilmFreeway export. Create a custom import mapping if you:
- Run your submissions from your own spreadsheet
- Have an intermediate step between export from FilmFreeway and import to SparqFest and you add additional columns in that process
An import mapping is a set of rules that map a column from your spreadsheet to fields in SparqFest. It allows you to map any single column to one or more SparqFest fields, or you can just ignore the column.
Understanding CSV Files
If you are experienced with importing/exporting from FilmFreeway or spreadsheets in general, then you have likely worked with CSV files. CSV stands for “comma-separated values”. Without diving too deep into the technical details, a CSV file is a text file that is independent of any vendor-specific spreadsheet format and can be understood by all kinds of applications.
When you export from FilmFreeway, you receive a CSV file that SparqFest can interpret and use to create submissions in SparqFest. If you are reading this article, you likely are using a process other than a straight FilmFreeway export and thus need to make sure you can get your data into a CSV format.
Third-party Platforms
If you are using a third-party platform other than FilmFreeway, it should have an export mechanism similar to FilmFreeway and the result will be either a CSV file or a JSON file. If you have an option, select CSV. If the only option is JSON, contact our support team and we will add JSON support.
Google Spreadsheets
To export your Google Spreadsheet, Go to “File” > “Download” > “Comma Separated Values (.csv)”. This will download your spreadsheet to your hard drive as a CSV file that SparqFest can read.
If you try opening this CSV file on your laptop, your local spreadsheet application like Excel or Numbers will attempt to open it. If you open this file, make changes, and save it, it will save the changes into a new file in the application's native format (e.g. .xls). You will therefore need to do a CSV export from that tool to be able to import the changes you made.
Microsoft Excel
Microsoft makes exporting a CSV file more complex than it needs to be. Excel has a number of CSV options when exporting, and most of them are very Microsoft-specific. The video below shows the export from a French machine running macOS. The process should be similar on other platforms and languages, though Windows may provide extra options.
To do the export, go to “File” > “Save As” and select the appropriate CSV format. You want a straight CSV export—no Windows, no DOS, no Macintosh. If your version of Excel exports into UTF-8 and non-UTF-8 variants, you want the UTF-8 variant.
When “Comma-Separated” Does Not Mean Comma-Separated
In many different locales, a “,” is a decimal-separator and thus a CSV file created in those locales won't be comma-separated. If you look at an actual export file from a French computer, for example, it will be using the “;” as a separator. You don't need to worry about this distinction—SparqFest understands it all.
Apple Numbers
The process in Apple Numbers is very straightforward. Go to “File” > “Export As” and select “CSV…”. This will bring up a dialog that asks you what kind of CSV file you want. You want one with the text encoding set to UTF-8.
Creating an Import Mapping
To create an import mapping, go to “Submitting” > “Import Mappings” and click “+ create”.
The “New Import Mapping” Dialog
There are three ways to create a new import mapping:
- From scratch, where you manually define every mapping
- Copy existing, where you copy a known mapping (like FilmFreeway) and customize it
- Upload sample, where you upload a spreadsheet and SparqFest interprets it and you tweak it
For festivals who export from FilmFreeway and then add a few columns during their decision process, the second approach is generally the best. For most everyone else, the last approach is the best.
When you copy an existing mapping, the dialog will ask you for the mapping to copy. If, on the other hand, you are uploading a sample, you will need to click the “Nothing Selected” link to upload a CSV file. Nothing additional is needed if you are creating a mapping from scratch.
Mapping Fields
When you click on a mapping to make changes, you will see a form with three tabs:
The Import Mapping Editor
The Basic Info tab supports only the name field. The name exists simply to help you know what mapping you are working with.
The Field Mappings Tab
Most of your import work happens in the field mappings tab. On the left hand side are a list of fields for SparqFest submitters and submissions. On the right hand side are any columns that have not yet been mapped. To map columns, simply drag a column from the right over to the SparqFest field on the left.
Most of the work on this FilmFreeway variant is already done
If you selected “Copy Existing” during the creation process, this tab will have everything from the existing mapping that you copied. You may event have no unmapped columns.
If, on the other hand, you uploaded a sample, all of the columns from your sample will be present and unmapped.
A mapping from scratch will have no fields mapped and no unmapped columns—you do everything from scratch.
Mapping a New Column
To add a new field click the “+ Add” field in the “Unmapped Columns” area.
Once you have unmapped columns, you can start mapping them as shown in the video above by dragging them from the unmapped columns area to the appropriate SparqFest field.
Nothing Saves Until You Save
As you can see in the video above, your changes are underlined in orange. If you add a new column, the unmapped column will be underlined. If you change a mapping, the mapping will be underlined. To make these changes permanent, go to the bottom of the form and click “Save”.
Copying an Existing Mapping
In the sample video, our custom spreadsheet has just one column for the submission title, but SparqFest has multiple title fields. In practice, you don't have to map all of the title fields since they are language variants—SparqFest will automatically attempt a machine translation where appropriate. If you don't want SparqFest to perform a translation or if you are dealing with a random column that simply maps to multiple SparqFest fields, you can duplicate a field so that it maps to multiple fields.
Removing a Mapping
To remove an existing mapping, drag it from its current location back over to the unmapped columns area. If the column is mapped to multiple fields, it will simply disappear from the field. If you are removing its only mapping, however, it will now show up as an unmapped field.
The Value Configuration Tab
For most fields, you need only define the mappings from the spreadsheet to SparqFest. A select few fields, however, have special values you need to help SparqFest interpret. The value configuration tab enables you to define these value mappings.
The options for configuring the format for individual fields
Currently, the value configuration tab asks you for the following information:
- What terms you use for different decision states that SparqFest tracks
- How durations are formatted in your spreadsheet
- How individual items are separated within list columns like categories
Decision States
SparqFest supports the following decision states:
- Undecided - no decision has been made on the submission
- Selected - the submission should be an Official Selection
- Deferred - the submission is not being considered for the current edition
- Rejected - the submission will not be an Official Selection
How SparqFest maps FilmFreeway decision states
The figure above shows how SparqFest is configured to map decisions values exported from FilmFreeway. In this example, there are three FilmFreeway values that map to a “Selected” state in SparqFest ("award winner", “nominee”, and “selected”). The text should appear EXACTLY as it will appear in your spreadsheets.
You don't have to map every single value. The “Default Decision” determines how the import mapping treats a decision status you have not defined.
Duration Format
We rely on the durations from your submission form for estimating runtimes until we receive the exhibition copy from the filmmaker. In order to accurately pull in the duration values, we need to know the format from the CSV file. You have the following options for duration values:
- Seconds - the duration is a numeric value that is in seconds
- Minutes - the duration is a numeric value that is in minutes
- Hours - the duration is a numeric value that is in hours
- Formatted Duration - the duration is a text value like 00:23:52 or “23 min 52 seconds”
The formatted duration option is very flexible, but it will interpret standalone numeric values as seconds. If you have frames in the duration, it should be separated by a “;” (e.g. “00:25:52;12”.
List Separators
The final value configuration to check is what kind of separator separates multiple values in a list.
The “Genres” column from FilmFreeway is an example of a list column. Submitters can specify more than one genre for their work. This value:
Fantasy, Drama
means that the selection is both fantasy and genre. The separator is a “,”. This, for the Genre Separator definition, you would indicate that genres are comma-separated.
The other options are:
- Tab separated - a tab separates each individual member of the list
- Newline separated - a newline separates each individual member of the list
- Other - you specify whatever character is separating list members