Automating Koku Transactions on iOS

What I’m about to describe is a way to automate transaction creation for the finance app Koku. I’m aware there’s an iPhone app, but it lacks a URL scheme and a way to automate making new transactions. This is my (successful) attempt to make automation with Koku possible.

On OS X

You need three pieces of software on OS X to use this system: Koku (of course!), Dropbox and Hazel. You could do this with folder actions, but Hazel is better and easier to use.

Hazel koku

Hazel

Hazel needs to monitor a folder where you’re going to upload .plist files containing the information about the new transactions you’re creating. It just needs to be somewhere in your Dropbox folder. Set your Hazel rule to match files where all are true:

  • Name starts with Koku transaction
  • Extension is “.plist”

That’s it.

The action you’ll run is “Execute AppleScript” and here is the AppleScript you’ll paste it:

--Get the file name as text so that you can use it with "property list file".
set theFile to theFile as text

--Get values from the property list file you'll create with Drafts on iOS.
tell application "System Events"
    tell property list file theFile
        tell contents
            set _desc to value of property list item "name"
            set _cost to value of property list item "cost"
        end tell
    end tell
end tell

--Create the transaction.
tell application "Koku"
    activate
    tell document 1
        --Change the account name to the account you want to add to in Koku.
        set theTransaction to mktrans in account "Cash"
        set date of theTransaction to (current date)
        set description of theTransaction to _desc as string
        set withdrawal of theTransaction to _cost as number
        set seen of theTransaction to true
        --This is where you can add custom tags for transactions.
        --Add as many as needed.
        if _desc is "Food" then
            addtag named "food" to theTransaction
        end if
    end tell
end tell

What this will do is pull a transaction name and cost from a .plist file and create a new transaction in your “Cash” account and then insert the supplied data. Because of the limited amount of information that Drafts can parse, you’re limited to two data points. Setting up:

if _desc is "Food" then
    addtag named "food" to theTransaction
end if

…will allow you to add tags, but only if you tell the script what titles to look for.

On iOS

On iOS you need Drafts and Launch Center Pro to make this all work well.

Drafts

In Drafts, create a Dropbox action called “Koku”. This will be a template that will upload a .plist file with [[title]] placing the first line of the draft into the .plist as the transaction title and [[body]] inserting the amount. With just this template, you can create a number of Launch Center Pro actions that will insert the necessary text where it needs to be. Here is the .plist template:

Open this link on your iOS device to import .plist template into Drafts

2013 02 27 12 43 21

Launch Center Pro

Launch Center Pro will be responsible for supplying Drafts with the data that Drafts needs to create the .plist files. You’re essentially supply Drafts with:

[name]
[cost]

What you’ll need to do is send:

[name]%0A[cost]

The name being the transaction title, “%0A” is a url encoded line break and cost is the amount of the withdrawal.

Here’s an example for a “Food” transaction action URL:

drafts://x-callback-url/create?text=Food%0A[prompt-num]&action=Koku

You can change any titles or insert a specific cost in to make it even more automatic, like this one for my train pass that costs ¥1000.

drafts://x-callback-url/create?text=Train%0A1000&action=Koku

The last example I’ll show you is one to add variable titles and costs. Launch Center Pro will not let you use a keyboard prompt and a number prompt in the same action so you need two actions. One will give you a prompt, send the text to Drafts, Drafts will run its “Set draft to clipboard” action and then drop you back in Launch Center Pro. Then, run the second “Set Cost” action and that will send the clipboard as title and inputted cost as cost to your regular “Koku” action and then upload a plist as normal.

--Copy to Clipboard
drafts://x-callback-url/create?text=[prompt]&action=Copy%20to%20Clipboard&x-success=launchpro://

--Set Cost
drafts://x-callback-url/create?text=[clipboard]%0A[prompt-num]&action=Koku&x-success=launchpro://

There you have it. A working system to automate Koku transaction creation from iOS. Is it worth it? There is a Koku iPhone app after all. But if you enter the same transactions over and over, you’ll get tired of using the Koku iPhone app all the time. With a little bit of set up, this system works pretty well.