Browse files

Documentation for writing ruote participants

  • Loading branch information...
1 parent 4cec49a commit eb7cae70fc7df3e362501998c9e88b52de49c44c @kennethkalmer committed with Kenneth Kalmer Jul 11, 2009
Showing with 115 additions and 1 deletion.
  1. +2 −1 Manifest.txt
  2. +113 −0 RuoteParticipants.txt
@@ -6,6 +6,7 @@ Manifest.txt
@@ -68,7 +69,6 @@ daemon_generators/rspec/templates/tasks/rspec.rake
@@ -91,6 +91,7 @@ lib/daemon_kit/em.rb
@@ -0,0 +1,113 @@
+= Writing remote ruote participants with daemon-kit
+daemon-kit is an ideal housing for remote ruote participants, providing a lot
+of convenience in terms of receiving and sending workitems, delegating work to
+pseudo-participant classes, handling configuration of the communication channel
+between ruote and the remote participant, and much more.
+== What is ruote?
+Ruote is a Ruby workflow engine. It is a powerful tool for defining, running and
+orchestrating business processes.
+== What are remote participants?
+Remote participants are participants that perform their work in a different
+Ruby processes from the one running the engine. This is useful in two cases,
+possibily many more, that involves autonomous participants.
+* Autonomous participants located on remote servers, driven by identity
+* Clustering autonomous participants to process workitems from a queue
+To learn more about the differences between local and remote participants
+please see
+Currently on the AMQP components are in place in daemon-kit, with XMPP coming
+== Creating a remote participant with daemon-kit
+Generate your daemon using the 'ruote' generator:
+ $ daemon_kit partd -i ruote
+Make sure you have the JSON gem install, and the AMQP gem as well.
+== Configuring the daemon
+You need to review +config/ruote.yml+ to specify the AMQP queues that the daemon
+will subscribe to for receiving workitems. You'll also need to configure the
+AMQP gem be updating +config/amqp.yml+
+The generated daemon in +libexec/+ already defaults to using AMQP as a transport
+for workitems.
+== Writing pseudo-participants
+Pseudo-participants in daemon-kit are pure Ruby classes. Implement your classes
+in +lib/+ and require them from +lib/<daemon_name>.rb+.
+Register your classes as pseudo-participants by registering them in the daemon
+file in +libexec+, just as the Sample class is registered in the generated
+code. Your class will be instantiated upon registration, and will be re-used
+for every incoming workitem passed to it.
+All your public methods in the pseudo-participant classes should be accept
+a single parameter, which is a ruote workitem in pure Hash form.
+== Wiring up the remote participant in ruote
+See the complete code here:
+A sample process definition might look something like this:
+ class QuoteProcess < OpenWFE::ProcessDefinition
+ sequence do
+ kit :command => '/sample/quote', :queue => 'work1'
+ console
+ end
+ end
++kit+ in the above process definition is registered with the ruote engine as an
+AMQPParticipant. The AMQPParticipant delivers workitems to the specified AMQP
+Based on the values in +config/ruote.yml+, your daemon will be subscribed to
+those queues.
+The second part is delegating the workitem inside the daemon to the correct
+pseudo-participant. This is handled by the +:command+ parameter in the process
+definition. DaemonKit::Workitem looks at the command parameter of the incoming
+workitem, and then finds a registered pseudo-participant instance and calls the
+requested method on that class.
+The +:command+ parameter follows the following convention (stolen shamelessly
+from Nanite):
+ :command => '/class_name/method_name'
+When classes are registered, the name of the class is downcased and camel-case
+words are separated by underscores. Method names are not changed, but methods
+are required to be public.
+== Processing workitems and replying to the engine
+The methods called in the pseudo-participants receive a single parameter, a
+ruote workitem as a hash. The participant is then free to analyze the hash
+and perform the appropriate actions required. The return value of the method
+is discarded, and the workitem is returned back to the engine. If the method
+modified the workitem, these changes will be sent along as well.
+== Random other notes
+Apart from configuring the AMPQ client (or XMPP in future) and the ruote.yml
+file, daemon developers don't need to worry about anything related to receiving
+workitems or sending replies.
+Our aim is to allow you to swap between participants on both sides of the
+transport without changing any of your code.

0 comments on commit eb7cae7

Please sign in to comment.