#summary Describes the various actions that Taskr can execute
#labels API

= Introduction =

Each Taskr task executes one or more actions. An action can be anything -- a simple shell command or piece of Ruby code to execute all the way to a complex network call to an external REST service.

Each kind of action is an implementation of a Taskr `Action` class written in Ruby. You can think of an action as a function that takes some set of named parameters -- the particular parameters depend on the action type. Taskr comes packaged with several `Action` classes. This page describes each of these built-in actions and their parameters. If you are interested in implementing your own actions, please see ImplementingCustomActions.

A quick way to see all of the actions available in your Taskr server is to log in via the web-based interface (http://localhost:7007/tasks by default) and click on the [http://localhost:7007/tasks/new Schedule New Task] link. The available Action types are listed under the `action_class_name` pulldown. Selecting any of these actions displays the selected action's parameters.

Below is a screenshot of the "New Task" page:

http://ruby-taskr.googlecode.com/files/taskr.screenshot3.png

= Built-in Actions and their Parameters =

== Shell Action ==

The `Shell` action allows Taskr to execute tasks much like the Unix cron system. The `Shell` task simply executes some piece of shell script on the local system (i.e. the machine that the Taskr service is running on).

|| *Parameter* || *Description ||
|| `command` || The shell command to execute. The command syntax depends on what shell your system is running. On a Linux system, this is probably `bash`, on Windows it's almost certainly `DOS`. For example, if you are running a `bash` shell, then the `command` parameter could be `touch /tmp/test; echo "done"`. This would update the modification timestamp of the file `/tmp/test` and print out the string "done" to `stdout` ||
|| `as_user` _(optional)_ || Execute the `command` as the given user. If ommitted, the command will be executed as the user that the Taskr server is running as. Note that the `as_user` parameter will probably only work if Taskr is running as root. ||


== Ruby Action ==

Executes the given block of Ruby code.

|| *Parameter* || *Description ||
|| `code` || The Ruby code to execute. For example: `puts "Hello World!"` will print out the string "Hello World!" to `stdout`. ||


== Rest Action ==

Places an HTTP [http://en.wikipedia.org/Representational_State_Transfer REST] call to the given URL. This is useful for triggering actions in other RESTful services. Since Taskr is a RESTful service, using the Rest action it is possible to talk back to the Taskr service, to for example create or delete another task.

|| *Parameter* || *Description ||
|| `url` || The URL where the REST call should be sent. For example: `http://localhost:7007/tasks.xml` ||
|| `method` || The HTTP method to use when placing the call. The common methods are `GET`, `POST`, `PUT`, and `DELETE`, although other methods are possible. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html ||
|| `params` || A hash (a.k.a. associative array) of key-value pairs to send with the request. Generally abstraction libraries like Ruby's [ActiveResourceClientExample ActiveResource] and PHP's [PHPZendRestClientExample Zend_Rest_Client] will automatically convert hashes/associative arrays for you, so you can specify this parameter's value in your native programming language's format. ||
|| `username` _(optional)_ || If the REST resource requires authentication, use this to specify the username. Currently on HTTP Basic authentication is supported. ||
|| `password` _(optional)_ || Same as above, but specifies the password credential. ||


== Howlr Action ==

Send a message through a [http://howlr.googlecode.com Howlr] service. Howlr provides a RESTful interface for sending out emails and other kinds of messages, so the Howlr action  can be used to send messages at a given time or interval. Since Howlr is a RESTful service, this is essentially just a customized version of the Rest Action described above.

|| *Parameter* || *Description ||
|| `url` || The URL where the message should be posted to. For example: `http://howlr.example.foo:7008/messages.xml` ||
|| `subject` || The subject of the message. ||
|| `body` || The body of the message. ||
|| `recipients` || Comma or semi-colon separated list of recipients. For example: `joe@example.foo; <Sally Smith> ssmith@example.foo` ||
|| `from` || The message will show up as being sent from this address. For example: `Scheduler Service <taskr@example.foo>` ||
|| `username` _(optional)_ || If your Howlr service requires authentication, use this to specify the username. ||
|| `password` _(optional)_ || Same as above, but specifies the password credential. ||


== Taskr4rails Action ==

Executes code on a remote Rails server. See [Taskr4rails] for more info.

=== Custom Actions ===

As mentioned above, it is fairly easy to implement and install your own actions types. Please see ImplementingCustomActions for details.