A friend of mine who is a consultant was using iCal to record her time spent on her various clients and their projects. Then at the end of each month she would manually tally up her hours and copy them into an excel spreadsheet.

She complained it was tedious. "There are programs for that" I told her but she liked using iCal, she liked having everything in one place. And she didn't want to go about learning a new piece of software.

My first instinct was to see if iCal allowed users to define metadata for their entries - it doesn't (wouldn't it be nice if it did?) Entries do have a freeform notes field but relying on her to enter the necessary data in a consistent format would be asking a bit much.

I needed a way for her to create iCal entries outside of iCal so that she could input her metadata using a simple form. It turns out iCal is totally scriptable using AppleScript. Using Applescript Studio I could create a simple form based application for her to input her time and have it create new entries in iCal with her metadata populated in a consistent format in the notes field.

It's not the most elegant solution -- that would involve iCal supporting some sort of plugin architecture where you could define new entry types and the UI elements necessary to populate and display them.

Never having written any Applescript before I didn't really know where to start. Apple's Developer Connection has plenty of documentation here though. And if you've installed the Developer Tools that ship with OSX then you have everything you need in XCode.

In XCode create a new Applescript application by selecting "New Project..." from the File menu and "Applescript Application" form the dialog that pops up.

Start with your UI. Double click "MainMenu.nib" in the project window to open up Interface Builder. Layout your UI. Here is mine.

Next you need to connect various UI elements to applescript methods. For each control you wish to do this for, select it and open the Info inspector for it. Select Applescript from the dropdown and you will be presented with a list of events that you can hook up to methods in your applescript code. For my Calendar drop down I chose "awake from nib" under "Nib" and for the OK button I chose "clicked" under "Action". Underneath you also need to select which aplescript file will recieve the method signatures. You also want to enter a name for each of your controls on this screen so that it is easy to refer to them from your script.

For my applciation my applescript received these signatures:

Now I needed to write the code to connect to iCal. For my simple application I wanted to, one, get a list of calendars to populate the drop down and, two, create new entries in the selected calendar.

Rather than walking through my code, I'll point you to the resources I found helpful and just include the TimeEntry project at the end of the article.

Another tool that ships with the developer tools is the Script Editor. This is where you will find the Dictionaries that define each application's specific applescript hooks.

Apple also includes has some sample scripts here.

After a lot of trial and error I ended up with a simple application that creates entries in iCal with some simple XML inserted into the notes field to capture the structured bits.

At the beginning of the article I mentioned reporting on this data. For that I wrote another simple application where you specify a calendar, start date, and end date and it pulls out all the entries with the XML in their notes field.

Not much to add other than the dictionary for Microsft Excel's applescript is rather cryptic - a beter reference can be found here.

Tarballs of the sample apps: TimeLog, TimeReport.