Defining Task Inputs and Results

KosmicTask Help

Defining Task Inputs and Results

A task can accept a number of inputs of various types. When the task is run the inputs' values are passed to the task and can be accessed by the task script. The input types that are supported include Text, Numbers, List items, Dates, Files and File Paths.

To define a task input first click the Task button to display the task input view. Then click the + button labelled Task Inputs. A new task input pane will appear.

Edit window

To create an input we need to define at least two or three things:

  • A Name. I chose "Text file".
  • An input Type. In this case we want to select File.
  • A Description. Something like "Text file to be converted" will do.

That's it for the input. Now we need to adjust the task script so click the Edit button and change the script to the following:

# convert file to html
textutil -convert html "$1"
echo "HTML file saved to Documents folder"

Now enter the Run edit view again. Note that this time the left panel contains a file input panel. Click the Select button and choose our test RTF file again. Now when the task is run whatever RTF file we select gets converted to HTML.

We have modified our script to convert a file called $1. When a Bash script is run it can accept a list of N inputs which are numbered $1 to $N. KosmicTask takes our input file name and passes it into the script as $1. All of the scripting languages supported by KosmicTask can accept task inputs. Each of them accesses arguments in their own way but the principle is always the same.

Now we can convert RTF files of any type to HTML. This is apparently another improvement. However, there is a problem! If we delete the existing converted HTML file from our Documents folder and run the task we will find that even though the task succeeds the converted file does not appear. In order to understand why we need to think a bit more about how KosmicTask handles files as inputs and results.

Handling Files

As well as creating and running tasks KosmicTask allows us to share tasks. This means that we can allow other KosmicTask users to run tasks that we have created. This is a powerful idea. The task that you create to convert Pages documents to HTML can now be used by any other KosmicTask user on the local network to convert their Pages documents to HTML too.

So lets say that Barbara wants to convert a file using a task on Alice's computer. The contents of the file will obviously have to be sent to Alice's computer where they can be converted by Alice's task. There is no point just leaving the converted file on Alice's computer where Barbara cannot access it so Alice needs to return the converted file to Barbara. Barbara can then save the converted file on her own computer. The way that KosmicTask handles files has been designed to keep both Alice and Barbara happy.

When we created our task input recall that the input was called File. Even when we are just running a task that exists on our local computer this input sends the contents of the file, not its path, to the task. When the task receives the file contents it saves them temporarily and passes that temporary path into the script. We can demonstrate this by modifying our task script like so:

# convert file to html
textutil -convert html "$1"
echo "file path = $1"

If we run the task with this script we should see something like:

file path = /Users/Muggins/Library/Caches/com.mugginsoft.kosmictaskserver.files/xX4cVMVdKa-KosmicTempFile-.My Pages Document.rtf

This reveals where our temporary copy of our input file is stored. This happens regardless of whether the input file already exists on the local computer or has been sent from another machine on the local network. It also explains why we don't see our converted file appearing in our Documents folder. By default the textutil command creates the converted file in the same folder as the input file. This is not what we want. What we want is to return the converted file to the task user. KosmicTask makes this easy.

To return the converted file as a task result we modify the task script like so:

# convert file to html
textutil -convert html -output result.html "$1"

echo "---" echo "{KosmicFile: result.html}"

See the next section for an explanation of how this works. Note that we have an extra option to the textutil command to save our converted file as result.html.

Now when we run the task and select our RTF document the task result consists of an HTML file icon. Double clicking the icon will display a preview of the file content. The file can be saved by selecting menu File - Save "result.html" As...

KosmicTask Result Handling

Many tasks can return results simply by printing (or echoing in the case of our example). If the required result is simply a piece of text or a number then nothing further is required. In order to handle more complex results such as files and lists of objects KosmicTask uses a standard syntax to identify the structure of the result. The syntax used is called YAML and is easy for a task to generate and for you to read. You can read more about result handling later in this guide.

In order to return a structured result we simply need to print the the structure using our YAML syntax and make use of a number of keywords.

When returning a structured result in this way we first print the YAML document marker:

echo "---"

This identifies the result as a structured result and KosmicTask will attempt to interpret the result so. If there is an error anywhere in the printed result then KosmicTask will simply return the result string and will not attempt to decode it further.

Next we make use of the KosmicFile keyword. This informs KosmicTask that the value associated with the keyword is a file to be returned as part of the task result.

echo "{KosmicFile: result.html}"

The curly braces are YAML syntax for associating a value with a key. When KosmicTask scans such a result it notes the presence of the KosmicFile key and returns the contents of the indicated file as part of the task result.

Result File Handling

In our example we simply chose result.html as our file name and you might think, well, what happens if this file already exists? In this case KosmicTask has created a temporary, initially empty, working directory for us so we can confidently create new files without worrying about old files.

Another question might be, well if I share my task over the network and everyone starts using it won't I soon accumulate lots of copies of their converted files? The answer is no. When a task completes KosmicTask deletes all the files that were created in the tasks working directory. All other files created by a task in other directories remain untouched.

In fact the different scripting languages supported by KosmicTask handle the temporary files created by tasks in different ways depending on their requirements. The same principal applies that if the file is created in the recommended manner it will be automatically deleted when the task completes.

For any particular scripting language the best way to find out how to create task result files is to open the Resource Browser (menu Window - Resource Browser). Each language defines a File template that demonstrates how to correctly create result files. In addition you can refer to the usage document that is included in the browser for each scripting language (select the Documents item for your scripting language with the Resource Browser left hand pane). 

Improving Our Task - Part 2

Now our task is genuinely useful. We can convert a selected RTF file into HTML and we can even share our task over the network. However we still have to launch Pages, open our Pages document, export our document as RTF and then convert it using KosmicTask. It would certainly be better if our task could achieve all this too.

In order to improve our task further we will need to automate Pages. This aspect of improving our task is discussed in the Application Automation Guide