Tutorial: Submitting New Items to Musi-Cal

(Note: Anywhere you see something like send a "foo" command to the Musi-Cal command processor it means to send an email message to concerts@musi-cal.com with a message body of "foo".)

There are several ways to submit concert dates to Musi-Cal. You can

Send one or more add commands to the Musi-Cal command processor
Send itineraries to the Slicer-Dicer for conversion into add commands.
Submit dates using the Web.
Send your itineraries to itinerary@musi-cal.com on a regular basis

This document focuses on the first two methods. You may also want to read the tutorials on the itinerary@musi-cal.com alias (by email: send a "help itinerary" command to the Musi-Cal command processor) and on creating patterns for the Musi-Cal Slicer-Dicer (by email: send a "help pattern" command to the Musi-Cal command processor).

Add Command

Adding new data to Musi-Cal by email is easy. The add command accepts a number of fields that define the various fields that will be saved in the database. To get you started here's a short example.

    add
        type folk
        performer Bogle,Eric
        date 03 May 1995
        city Regina
        state SK
        venue Holy Rosary Hall
        info (306)949-6594
    end

The keywords "add" and "end" must appear on a line by themselves. Similarly, each field described must be defined on a single line. To create long fields that might extend past the right margin, you can terminate the line with a backslash ('\'):

    info Tickets $17.50 - by mail: The Bottom Line, 15 West Fourth Street, New York, NY 10012. Include $.50 handling fee per order.

As long as none of the continuation lines begin with keywords that are special to the add command and it is okay to have a space where the line breaks, you can dispense with the backslash:

    info Tickets $17.50 - by mail: The Bottom Line,
	15 West Fourth Street, New York, NY 10012.
	Include $.50 handling fee per order.

Several fields are required in each entry: the date, location (city and state, province or country), and either a performer or event name. All other fields are optional.

Note that all add commands (in fact, all Musi-Cal commands) must be sent to concerts@musi-cal.com. You can include any mix of commands in a single message.

Saving Some Typing

If you are submitting multiple entries for the same artist or venue, much of the data will be identical for each entry. To save some typing, the add command will reuse data from the previous add command that is not specified. For instance, in the Eric Bogle item above, if he was to appear at Holy Rosary Hall on three successive weeks in May, it would be sufficient to give the three commands:

    add
        type folk
        performer Bogle,Eric
        date 03 May 1995
        city Regina
        state SK
        venue Holy Rosary Hall
        info (306)949-6594
    end
    add
	date 10 May 1995
    end
    add
	date 17 May 1995
    end

You have to be careful! What's wrong with the following commands?

    add
	type folk
	performer Evan & Jaron
	date August 21, 1995
	venue New Music Cafe
	city New York
	state NY
    end
    add
	date August 27, 1995
	event US Open Tennis Tournament
	city Flushing
	state NY
    end
    add
	date August 28, 1995
	venue The Jewish Mother
	city Virginia Beach
	state VA
    end

Note that in the second entry there is an event field but no venue field. In the third entry there is a venue but no event. In neither entry was the missing field overridden. They should be given as

    add
	date August 27, 1995
	venue
	event US Open Tennis Tournament
	city Flushing
	state NY
    end
    add
	date August 28, 1995
	event
	venue The Jewish Mother
	city Virginia Beach
	state VA
    end

If you would prefer not to have to worry about what came before, simply give a clear command before each add command:

    clear
    add
	type folk
	performer Evan & Jaron
	date August 21, 1995
	venue New Music Cafe
	city New York
	state NY
    end

You will then have to enter all fields for the add command. Nothing will be retained across successive commands.

Converting Lots of Data

Even with the savings in typing you get using the add command you are still in for a lot of typing if you have lots of data to submit. Early on, we noticed that there was a lot of data on the net available in one-gig-per-line formats such as:

     5/26    OH  Borders Books/Westlake/                      216/892-7667
     5/31    OH  Arabica Coffeehouse/Cleveland/               216/791-0300
     6/7     OH  Arabica Coffeehouse/Cleveland/               216/791-0300
     6/9     OH  Booksellers Bookstore/Beachwood/             216/831-5035
     6/11,17,18,24,25 OH  King's Co. Ren. Festival/Streetboro/ 216/628-2803

Manually converting lots of data in that format would be a bi... (Whoa, there, Skip! This is a family-oriented site...) Well, let's just say it would be mighty discouraging, pardner. We were so discouraged we wrote some software to help convert data that looked like what you see above into the set of add commands necessary to actually submit them to Musi-Cal. The details are a bit much for a short tutorial, but here's how the data above was converted using the Musi-Cal Concert Itinerary Slicer-Dicer:

    default
	keywords folk
	performer Abelson,Matthew
	pattern %{smonth}/%{days} %{st} %{venue}/%{city}%{?/%{info}}
    end

    convert
	 5/26    OH  Borders Books/Westlake/                      216/892-7667
	 5/31    OH  Arabica Coffeehouse/Cleveland/               216/791-0300
	 6/7     OH  Arabica Coffeehouse/Cleveland/               216/791-0300
	 6/9     OH  Booksellers Bookstore/Beachwood/             216/831-5035
	 6/11,17,18,24,25 OH  King's Co. Ren. Festival/Streetboro/ 216/628-2803
    end

Note that in the default command we've described the missing constant data (the performer and keywords in this case) and how to decipher the raw data. To get full details about the default and convert commands, send the following commands to the Musi-Cal command processor:

    help patterns
    help templates
    help manual

The reply will contain the full users guide for the Musi-Cal email interface (the only place the default and convert commands are currently described), a short tutorial on how to create patterns (lifted mostly from the users guide) and some heavily commented templates for adding items to Musi-Cal.

There are two other ways of submitting concert information to Musi-Cal that offload the harder Slicer-Dicer stuff onto Musi-Cal people. If you have concert itineraries in a form that would be usable by the Slicer-Dicer, you can email them to itinerary@musi-cal.com or make them available via WWW or FTP and just send the URL to concertmaster@musi-cal.com. In either case, any time new information is detected, the contents of the latest itinerary will replace the old itinerary. For more information about using the itinerary@musi-cal.com alias, send a "help itinerary" command to the Musi-Cal command processor.

Batch Updates

Suppose you really get the hang of things and you're busy keeping one or more artists' tour itineraries up-to-date. You submit a bunch of dates for an artist. A month or so later, you might have some new dates, cancellations, or minor changes. You've got all the new data in a one-line-per-gig format, but you'll find it's a pain to try and determine what things changed, are new or were deleted. Forget all that rigamarole! It's much easier to just zap all the old entries still in the database and completely replace them with new up-to-date items. The secret is to define a special keyword that you use for that artist (or venue, if you are submitting for a particular venue). If you define a keyword that looks something like

    .matthewabelson.40917

it will be added to all the add commands generated by the Slicer-Dicer. What's more, right before the add commands are generated a special delkey command is generated that will cause all entries containing that keyword to be deleted. The output from the Slicer-Dicer will look like

	delkey
	    key .matthewabelson.40917
	end

	add
	    performer Abelson,Matthew
	    type folk
	    keywords .matthewabelson.40917
	    date 26 May 1995
	    city Westlake
	    state OH
	    venue Borders Books
	    info 212/892-7667
	end
	...

These special keywords are hidden. You won't see them in query or edit command output. They can't be deleted, even if you attempt to delete all the keywords in an entry. The keyword must be of a special form. It must start with a dot. The dot must be followed by one or more alphabetic, hyphen or underscore characters that do not make up an existing keyword in the system and another dot. The second dot must be followed by one or more decimal digits.

To be useful, this special keyword must be reused, so don't forget it. I suggest you save a template for each artist that contains the default command and an empty convert command that you reuse over and over:

    default
	type folk
	keywords .matthewabelson.40917
	performer Abelson,Matthew
	pattern %{smonth}/%{days} %{st} %{venue}/%{city}%{?/%{info}}
    end

    convert
    end

Submission Responses

Every mail message you send to the concerts mail alias should elicit a reply. If your message contains one or more add commands the reply should contain lines similar to

    Successfully added entry for Joe Schmoe on 13 January 1996 (id 54969).

The id in parentheses can be saved for future reference if you need to make changes. (This saves an edit step.) If the database is locked for any reason the response will instead be something like

    Successfully added entry for Joe Schmoe on 13 January 1996 (held - database is locked).

The id won't be known until the database is unlocked and all queued items are handled, thus it can't tell you what the actual id will be.

A different sort of message will be returned for each message handled by the Slicer-Dicer. You will receive one mail message directly from the Slicer-Dicer that contains your original input with each line prefaced by a #. Interspersed with your input will be either a line like

    # Above line converted cleanly and submitted

or an add command with a warning or error message like

    add
	performer Mollys,The
	type folk
	keywords .themollys.450
	city Purgatory
	state CO
	### Warning: Can't find lat/long for Purgatory, CO.  Double-check the spelling.
	info 970/247-9861
	venue Sky Resort
	date 18 January 1996- 21 January 1996
	# Info: This event may already be in the database.
    end

If the warning is correctable, make the necessary changes (possibly also to your raw input to avoid that message in the future!) and submit the resulting add command. If not (for a missing city, for instance), you may well have to just discard the add command.

If an input line is not followed immediately by either an add command or a message indicating the item was submitted, the Slicer-Dicer did not recognize that line as a valid event. This may or may not require corrections.

Gotchas

There are a number of formatting conventions to follow when adding new items to the database.

Performer names must be given in sorting order. For individual performers this normally means last name first, separated by a comma.
Multiple performer names must be separated by a slash ('/'). For instance, if Tom Paxton and John Gorka where playing on the same stage, you'd specify the performer names as
```
	    performer Paxton,Tom/Gorka,John
      
```
Make sure the words in your submission are properly capitalized. SOME PEOPLE SEEM TO HAVE THE CAPS LOCK KEY ON WHILE TYPING.
Multiple keywords should be separated by commas. e.g.:
```
	    keywords folk,rock
      
```
A list of all valid keywords can be retrieved by sending a "help genres" command to the Musi-Cal command processor.
People (at least most Americans :-) tend not to be great at geography. This is unfortunate, because in addition to not doing very well at "Jeopardy!", "Where in the World is Carmen San Diego?" and the hopelessly elementary geography questions in "Family Double Dare" it means that entries with misspelled cities, states or countries show up in unusual places in Musi-Cal or don't get displayed at all. Please double-check the spelling of place names. If you use the Slicer-Dicer it will attempt to look up the latitude and longitude of cities and warn you if it can't find anything. Also, don't forget there are lots of cities with the same name, particularly in many US states (good-sized cities named Bloomington are in Minnesota, Indiana and Illinois, for instance).
When submitting entries for the US and Canada, give just the city and state or province. Don't add 'USA' or 'Canada'. When submitting entries for other countries, give just the city and country. There is currently no means to handle provinces, states, counties or republics in other countries.