Importing Initial Data¶

Once you’ve got Tabbycat installed, the next step is to import data for the tournament: that is, import details of teams, speakers, adjudicators and rounds. There are a few ways to do this, each with their advantages and disadvantages.

To help you decide which to choose, here’s a summary:

Method	Best for	Drawcard	Drawback
Demonstration data	Trying out Tabbycat	Loads sample data in one click	Not for use with real tournaments
Simple importer	Small and medium-sized tournaments	Easy to use	Only deals with basic data
Edit database	Adding data not handled by the simple importer or editing existing data	Can handle all types of information	Adding large amounts of data is time consuming
`importtournament` command	Large tournaments	Easier to repeat, can handle most formats of information	Requires basic knowledge of how to use a command line interface
Developing your own importer	Large tournaments with custom needs	Easier to repeat, will take information in whatever format it is already in	Requires background in Python and and learning about the importer classes
API	Tournaments with external registration systems	Less manual intervention	Requires programming knowledge or use of an existing external application

Demonstration data¶

If you’re just learning or experimenting with Tabbycat, there are two demonstration datasets available, each with a sample set of teams, adjudicators, etc., so that you can immediately start running rounds. Just be aware that these probably won’t relate to anyone at your real-life tournament.

To load a demonstration dataset, click New Tournament link on the home page (once logged in as admin). You’ll see a page titled “Create New Tournament”. Scroll to the bottom of this page and click on one of the links at the bottom.

Simple importer¶

The simple importer is the easiest way to get a tournament going, and we recommend it for small- and medium-sized tournaments. It allows you to add institutions, teams, adjudicators, venues, venue categories and venue constraints. (If you need to add anything else, use the Edit Database area instead.)

To get started, create a new tournament using the New Tournament link on the home page (once logged in as admin). It’ll ask you for a few basic pieces of information.

Then, once you’re in your tournament, click Setup in the left-hand menu, then Import Data, to open the simple importer.

You first need to add institutions. Once institutions are added, you can then add teams and adjudicators in the relevant sections. Each of these is a two-step process:

For institutions and venues, it will first ask you to copy-paste a list of names and properties in a comma-separated table format. The second step is to confirm individual fiels.
For teams and adjudicators, it will first ask you how many teams/adjudicators to add for each institution (or who lack an institutional affiliation). The second step is to fill in their details, for example, names.

Finally, if you would like to use venue categories and/or venue constraints, you can do so using the two last sections of the simple importer.

Note

If copying and pasting from a spreadsheet, an easy way to make a comma-separated table is to save a spreadsheet with the relevant information as a *.csv file, then open this file in a plain text editor (such as Notepad or TextEdit), and copying it from there.

Editing the database¶

Sometimes, the simple importer just isn’t enough—whether because you need more customization than the simple importer handles (e.g. adjudicator feedback questions), or because some participants changed their details after you imported the inital data. In this case, the easiest thing to do is to edit the database via the Django administrative interface (under Setup > Edit Database).

The general pattern goes like this: Go to Setup > Edit Database, find the type of object you wish to add/change, and click “Add” or “Change”. Then, fill in what you need to and save the object.

Caution

The Edit Database area is very powerful, and naturally if you mess things up, you can insert potentially catastrophic inconsistencies into the database. For participant information this is hard to do, but it’s worth keeping in mind.

The `importtournament` command on local installations¶

We’ve written a management command called importtournament to help automate the tournament set-up. The script, however, is neither foolproof nor comprehensive, so you might find you need to modify things slightly if your tournament structure is different from ours. Be prepared to try this a few times to get it to work. Nonetheless, this is probably the fastest way to set up a tournament.

Copy and rename the data/demo folder
See the CSV files in the new folder, and add/replace the data as per your tournament. Note that the institutions (i.e. first column) in the speakers.csv and adjudicators.csv files must match the institutions in the second column of the institutions.csv file. And that all CSV files must end with a blank line.
Use this command, replacing YOUR_DATA_DIR with your new folder’s name. (Square brackets indicate optional arguments; if you use them, omit the square brackets. All of them relate to the name of your tournament.)

$ ./manage.py importtournament YOUR_DATA_DIR [--slug SLUG] [--short-name SHORT_NAME] [--name FULL_NAME]

This script has a number of options. They’re worth taking a look at before you run the script. For details, see:

$ ./manage.py importtournament --help

Assuming the command completes successfully without errors, you should double check the data in the Django interface, as described above in Editing the database. In particular you should check that the Rounds have the correct draw types and that silent rounds have been marked correctly.

`importtournament` on Heroku installs¶

If you want to use the importtournament command locally but then upload that data to Heroku, you can do so with these instructions.

Danger

This step wipes the Heroku database clean, and replaces it with the contents of your local database. If you have any data on the Heroku site that isn’t also in your local database, that data will be lost and will not be recoverable.

Tip

If you have multiple Heroku sites, you may find that the heroku commands refuse to run, prompting you to specify an app. If so, add --app yourappname to each heroku command.

Enable maintenance mode on Heroku. This takes the site offline, to ensure that no-one can possibly create or change any data on the site while you’re pushing a new database up:
```
heroku maintenance:on
```
Reset the database. (Caution: This permanently deletes all information on your Heroku database!)

heroku pg:reset

Push your local database to Heroku:

heroku pg:push yourlocaldatabasename DATABASE

You might need to specify your local PostgreSQL credentials by adding PGUSER=yourusername PGPASSWORD=******** PGHOST=localhost to the beginning of that command. (This sets environment variables to those values for the duration of that one command.)

Disable maintenance mode:
```
heroku maintenance:off
```

Developing your own importer¶

If our suggested file formats cause you headaches, it might be easier to write your own importer. We have a generic importer framework that should make this easier, so for some tournaments it might (very conceivably) be faster to write your own importer to conform to your data, than it is to make your data conform to our importer. You need a background in Python in order to do this. For more details, see Tournament Data Importers.

Application Programming Interface (API)¶

Participants can be imported in Tabbycat through the API, using authenticated endpoints making POST requests to the relevant endpoints. There may be tournament registration software which interfaces with Tabbycat, or you may have to program one yourself, in any language.