ruote-kit (RESTful ruote & middleware)

kit.rubyforge.org/ruote (soon)
kit.rubyforge.org/ruote/rdoc (soon)

A RESTful wrapper around the ruote workflow engine, built as a modular sinatra application.

Follow development:

#ruote on Freenode
groups.google.com/group/openwferu-users
opensourcery.co.za
@kennethkalmer on Twitter

Alpha Status

ruote-kit is under heavy development and will likely change violently over the coming weeks (albeit for the better).

Dependencies you currently need are:

bundler 0.9.5 or later (gem install bundler)
sinatra
sinatra-respond_to
haml
rufus-json and a compatible backend
rspec (only to run the specs)

ruote-kit uses bundler to setup and maintain its environment. Before running ruote-kit for the first time you need to install bundler and then run:

$ bundle install

Bundler will download all the required gems and install them for you. To bundle the gems you can simply run ‘bundle lock’ and all the gems will be unpacked in .bundle

Getting started quickly

Using the RubyGem

Install the gem and its dependencies
```
$ gem install ruote-kit
```

You’ll need an empty directory

$ mkdir my-ruote-kit && cd my-ruote-kit

There are two files needed in that directory: Gemfile and config.ru

Gemfile
```
source :gemcutter
gem 'ruote-kit'
```

config.ru

begin
  # Try to require the preresolved locked set of gems.
  require ::File.expand_path('.bundle/environment', __FILE__)
rescue LoadError
  # Fall back on doing an unlocked resolve at runtime.
  require "rubygems"
  require "bundler"
  Bundler.setup(:default)
end

# load json backend
require 'yajl-ruby'    # best choice as fastest, but uses a c module
# require 'json_pure'  # should work everywhere

require 'ruote-kit'

RuoteKit.configure do |config|
  config.register { catchall }
end

use Rack::CommonLogger
use Rack::Lint

run RuoteKit::Application

Just to make sure every dependency is resolved
```
$ bundle check
```
If there are missing dependencies (there shouldn’t be any if the gem installation succeeded)
```
$ bundle install
```
Get going
```
$ rackup
```

Using the source

Get the source files using git

$ git clone http://github.com/kennethkalmer/ruote-kit.git && cd ruote-kit

Make sure every dependency is resolved
```
$ bundle install
```
Get going
```
$ rackup
```

Accessing the web interface

If ruote-kit starts up without any issues (ie missing dependencies), you can point your browser to ‘localhost:9292/_ruote/’ to get going. By default ruote-kit binds to all IP addresses, so this works out the box remotely too.

Plugging ruote-kit into your rack-stack

ruote-kit is fully self-sufficient piece of rack, but can be slotted into any rack middleware stack without issues.

Example:

RuoteKit.configure do |config|
  # make changes if needed
  # Register participants if needed
  config.register do
    participant :toto do |wi|
      # ...
    end
    # register the catchall participant if needed
    require 'ruote/part/storage_participant'
    catchall Ruote::StorageParticipant
  end
end

# Slot into the stack
use RuoteKit::Application

Notes for Rails

See github.com/tosch/ruote-on-rails for an example Rails app.

Configuring ruote-kit & ruote

ruote-kit can be configured using RuoteKit#configure, after which it will start the engine. From that point the engine is accessible through RuoteKit.engine.

Without any configuration ruote-kit will use file system persistence, and save the work in a sub-folder of the current working directory named work_<env>, where env is the RACK_ENV or RAILS_ENV.

Registration of participants

ruote participants may be registered within the block given to RuoteKit#configure by the RuoteKit::Configuration#register method. It expects a block containing of participant and one or less catchall calls (see example above).

Note that all participant calls after a catchall one are pretty useless: The catchall will eat all their cookies.

The `workitems` resource

The workitems resource relies on the Ruote::StorageParticipant. You’ll have to register at least one Storage Participant if you ever want to see a workitem in the resource. Example:

require 'ruote/part/storage_participant'
RuoteKit.engine.register_participant :storage, Ruote::StorageParticipant

You may also use the catchall participant provided by RuoteKit. It’s named ‘.+’, so it will catch all workitems for any participant mentioned in your workflow definitions which are not already caught by another (previously) registered participant. So make sure to register the catchall after your own participants. The catchall participant may be registered by calling catchall within the block given to RuoteKit::Configuration#register (this will use Ruote::StorageParticipant as participant implementation, you may use any options of Ruote::Engine#register_participant to overwrite that default – see the example above).

Running workers

If you’re using ruote-kit as part of your rack stack you’ll need to start at least one worker separately or the workflows won’t be executed. You won’t need more than one worker unless you are running hundreds of processes at the same time.

To run a worker you need to setup a worker script similar to the rake example below:

require 'rake'
require 'ruote-kit'

desc "Run a ruote-kit worker"
task :ruote_kit_worker do

  RuoteKit.configure do |config|
    # Setup your configuration
  end

  RuoteKit.run_worker!
end

This will only work correctly if using the default file system persistence. Support for ruote-couch is coming soon.

Feedback & bug reports

Please bear in mind that the project is still in its alpha days. Keep bug reports and suggestions limited to the google group and #ruote channel, at least for the time being.

Please do not hesitate to come back with any feedback.

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.