Tutorial: Gig Gopher

(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".)

Many publicity people in the music business already have established electronic mailing lists to which they send tour itineraries. The Musi-Cal Gig Gopher makes submitting itineraries to Musi-Cal as easy as possible by leveraging that existing publicity mechanism. If you have tour itineraries in a one-line-per-event format, where the various elements of the event are well-delimited from each other, you can very likely submit those itineraries to Musi-Cal by simply adding the email address itinerary@musi-cal.com to your existing electronic mailing list.

Gig Gopher requirements for your itineraries are pretty flexible, but there are a few things to pay attention to:

The data must be in a format that is amenable to conversion by the Musi-Cal Concert Itinerary Slicer-Dicer. Furthermore, that data format must not change. If you change your data format, you must let us know, preferably ahead of time.
Events should be in a "well-delimited" format amenable to input as raw data to the Musi-Cal Slicer-Dicer.
The format of the data must stay the same across multiple submissions.
If there is something about your data format that makes it difficult or impossible to convert using the Slicer-Dicer, you should be willing to make some changes to accommodate the process. If your data is in free-form text, that reads well, but we can't really use it.
You should be willing to take the short amount of time necessary to review the conversion results, make any necessary corrections, and forward the results to concertmaster@musi-cal.com.
We need your email address so we can forward the conversion results to you and can contact you if we have trouble with your data.
We need some constant information about your tour itineraries, type of music, or venue phone number and address, that sort of thing.
The subject and email address in the From: field must always be the same for different versions of the same artist's itinerary, typically the name of the performer(s) and the sender's address, respectively.
Finally, and most importantly, you must have the authority to give us the data. That implies that the data is either yours or you have the approval from the owner to distribute it to us.

If we've never heard of the performer you are submitting for (that is a very good possibility - we don't claim to be omniscient musical aficionados) you should give us a few keywords in the first message you send to the itinerary alias that describe the type of music the artist plays, or submit a Notes Index entry about that artist using the Web form or email interface.

Well-delimited Data

The definition of "well-delimited" is purposely a bit vague. In general, we need to be able to build a pattern that identifies the various fields (date, city, state, venue and so forth) in the entry. Although most people can read

    102995BerkeleyCAFreight&Salvage

it isn't properly delimited. There is no separator between the month, day, year, city, state or venue name.

We're getting pretty good at automatically massaging itineraries into a form suitable for the other Musi-Cal software that ultimately will process the tour data. One rule you must adhere to is that fields that can contain white space must not be separated from the next field in the line by white space. For instance, the following is good:

    San Francisco, CA

but the following is bad:

    San Francisco CA

The pattern matcher will gobble up the " CA" as part of the city name because city names can contain white space and it won't know that the city only has two words. If you want to learn more about the nitty-gritty of pattern matching and creation in the Slicer-Dicer, check out the tutorial on creating patterns.

What sort of data works? Here are a few examples of dates that are formatted pretty well for our needs.

Check out the tour information on Warner Brothers Records' site. All the HTML markup needed to generate tabular output serves as excellent delimiters.

Here's some Robert Cray tour data we converted some time ago.

    09/15/95  Toronto(ON)          Massey Hall    
    09/16/95  Montreal(PQ)         Le Spectrum De Montreal        
    09/17/95  Burlington(VT)        Flynn Theatre  
    09/19/95  New Haven(CT)         Toad's Place   
    09/20/95  Binghamton(NY)       Broome Co. Forum Th.   
    09/22/95  Columbus(OH)          Brewery District Fest  
    09/23/95  Cincinnati(OH)        Bogart's       
    10/03-4/95  Saratoga(CA)          Mountain Winery

Here's some data that came from a database.

    "Burns Sisters",,"10/06/95","Wilkes-Barre","PA","Chickory House","Folk"
    "Burns Sisters",,"10/07/95","Bethlehem","PA","Godfrey Daniels","Folk"
    "Burns Sisters",,"09/29/95","New York","NY","The Bottom Line","Folk"

All the dates shown or described above are well-delimited. Each date is on a single line and in a consistent format we can describe to the Concert Itinerary Slicer-Dicer.

Here is a slightly more detailed description of an example that works. This is from a Joan Osborne date that occurred in October 1995:

    10/12/95  Norfolk, VA (8pm)         Naro Theater

Slashes separate the month from the day and the day from the year. There is no need for a separator other than white space after the year, since it can only contain digits. The comma serves as an excellent delimiter between the city and state. White space is sufficient after a state, province, or country abbreviation because they can't contain white space (although the same is not true of spelled out names such as "North Carolina" or "United Kingdom"). The event time is well-separated from the rest of the line by the parens, and the venue name needs no trailing delimiter because it's the last item in the listing.

If you are used to posting itineraries in tabular format (nicely lined up in columns) with only white space between the fields we may be able to massage it into a form we can use, but we may also ask you for some changes in the input.

How does itinerary@musi-cal.com work? It's magic... :-) Well, not really. The first time you send an itinerary to the itinerary alias its subject/email combination won't be recognized and the message will be forwarded to a human who will then build the necessary framework for input to the other Musi-Cal software. That and subsequent mailings with the same subject from the same person will then get processed by the automated system. We will contact you if we have trouble with your input.

If you choose to use this method of submitting events to Musi-Cal you will be set up as the reviewer of the output. You will get two to four mail messages in reply to a single itinerary. The first will identify all the items that were automatically extracted from your itinerary and submitted to the calendar. Normally, you can just scan that and delete it. There may be situations where it is obvious that a particular gig has been missed by the pattern matcher, however. If that happens and you can't figure out why, just let us know. (Send email to concertmaster@musi-cal.com with a copy of the output that you can't decipher.) The second message will be a confirmation of the automatic additions. Again, for the most part you can scan and delete that message. The third message, if necessary, will identify tour dates that weren't automatically submitted because warnings or errors were generated. You should fix the generated add commands (and if necessary, your raw itinerary data) and submit them yourself or contact us if you have problems. After you submit the corrections you will receive a confirmation of those additions.

The itinerary@musi-cal.com mail alias interacts with several other pieces of software in the Musi-Cal system. Very briefly, the itinerary you send is saved in a file on our system where it is picked up and processed by our Gig Gopher software. The Gig Gopher takes raw itineraries and generates input for Musi-Cal's Slicer-Dicer. The Slicer-Dicer generates a set of add commands that are submitted to the calendar database itself. You can learn more about the details of submitting concert information to Musi-Cal by sending the "help submit" command to the Musi-Cal command processor or reading the Web version.

Licensing | Help | FAQ | Home