Application Automation Guide

KosmicTask Help

Application Automation Guide

In the Task Scripting Guide we developed a simple Bash script that converted an RTF file exported from Pages into HTML. In this section we will automate Pages to perform the required RTF export.

Many applications on OS X are scriptable. This means that our task can send a scriptable application specific commands and queries. Using this approach we can construct a task that talks to Pages and converts our file as required.

Not all applications are scriptable however. A simple way to determine if an application can be automated in this way is to search the Internet for examples. A more exact way is to open the AppleScript Editor application and choose menu File - Open Dictionary... to display a browsable list of scriptable applications. Each scriptable application maintains a dictionary of the commands that it responds to. If your target application appears in the displayed list then you can automate it. Pages does provide a command dictionary (or terminology as it is commonly known) and selecting it in the browser displays a list of all the commands that it accepts.

There are number of ways that we can follow to automate Pages. Unfortunately none of them involve using a Bash script! This means that we will have to adopt another scripting language in order to further enhance our script. This is a common occurrence when writing tasks. However, KosmicTask supports a wide range of scripting languages and this makes it easy to rework a task. In this case we will rework our task as an AppleScript powered task.

AppleScript is an OS X scripting language that is ideally suited for automating applications. The commands sent to our application are composed of discrete packets of information known as AppleEvents and AppleScript is one of the most popular ways of generating and sending these events. Note that there are other ways of automating applications and we will explore these later.

Rather than modifying our original Bash task let's work on a copy. So close the edit window and save our task when prompted. In the main application window make sure our conversion task is selected and click the Duplicate button in the toolbar.

Moving from Bash to AppleScript

The first thing we need to do is to rework our Bash script into AppleScript. The easiest way to accomplish this is to use one of the existing AppleScript templates. Select the script edit view and click the Template button in the toolbar. In the left hand resource browser select AppleScript - Application - Templates to display all the available AppleScript templates. Select the File template. Our Bash script will be replaced and our script type changed to AppleScript.

One notable difference between our Bash script and AppleScript is that our AppleScript task will have to be built before we run it. Click the Build button in the toolbar. If there are any errors in the script you will have to fix them before the task can be run. For some supported scripting languages there is no build stage, for others it is optional and for some required.

The default AppleScript File template we have selected looks something like this:

on KosmicTask()
  try
    -- get a result file object from KosmicTask.
    -- the file will be automatically deleted when the task ends.
    tell application "KosmicTask"
      set resultFile to result file with name "capture.png"
    end tell

    -- the shell script below will expect a POSIX path
    set picPosixPath to POSIX path of file resultFile

    -- do screen capture via shell
    do shell script "screencapture -t png " & quoted form of picPosixPath

    -- return file contents and message
    return {kosmicFile:resultFile, kosmicInfo:"file returned"}
  on error errorMessage number errorNumber
    return {kosmicError:errorMessage}
  end try
end KosmicTask

This script doesn't convert a file (it takes a screenshot instead) but it does execute an external command and it does return a file so it should serve as a good starting point for our conversion task. There are some things to note though before we proceed:

Firstly the way we create a temporary result file is completely different.

  -- get a result file object from KosmicTask.
  -- the file will be automatically deleted when the task ends.
  tell application "KosmicTask"
    set resultFile to result file with name "capture.png"
  end tell

In this case we ask the KosmicTask application itself to create a file object us for us. KosmicTask will delete this file as we require when our task exists.

Secondly the script makes use of some additional result keywords to send additional information back to the user. So if an error occurs we use the KosmicError keyword to return an error message:

  on error errorMessage number errorNumber
    return {kosmicError:errorMessage}
  end try

A First AppleScript Task

Now that we have our template in place we can modify it to re-implement our RTF to HTML file conversion task.

on KosmicTask(filePath)
  try
    -- get a result file object from KosmicTask.
    -- the file will be automatically deleted when the task ends.
    tell application "KosmicTask"
      set resultFile to result file with name "result.html"
    end tell

    -- the shell script below will expect a POSIX path
    set posixPath to POSIX path of file resultFile

    -- build our command
    set command to "textutil -convert html -output " & quoted form of posixPath
    set command to command & " " & quoted form of filePath

    -- do command via shell
    do shell script command

    -- return file contents and message
    return {kosmicFile:resultFile, kosmicInfo:"file returned"}

  on error errorMessage number errorNumber
    return {kosmicError:errorMessage}
  end try
end KosmicTask

This task behaves just like its Bash based predecessor.

The main point to note is that our task is implemented as a function called KosmicTask and that this function takes a single argument which is the path to our input file. Many of the supported scripting languages support the use of functions in this way while others (usually those derived from command line interfaces) do not.

As ever, the Usage document that can be accessed in the Resource Browser is a good place to find out how various features are implemented in each of the supported languages.

Now that we have our task implemented in AppleScript we can move on to automating Pages itself.