Ruote::Exp::ListenExpression

Listens for activity (incoming or outgoing workitems) on a (set of) participant(s).

This expression is an advanced one. It allows for cross process instance communication or at least cross branch communication within the same process instance.

DO NOT confuse the listen expression with the 'listener' concept. They are not directly related. The listen expression listens to workitem activity inside of the engine, while a listener listens for workitems or launchitems from sources external to the ruote workflow engine.

It can be used in two ways : 'blocking' or 'triggering'. In both cases the listen expression 'reacts' upon activity (incoming or outgoing workitem) happening on a channel (a participant name).

blocking

A blocking example :

sequence do
  participant 'alice'
  listen :to => 'bob'
  participant 'charly'
end

Once the listen expression got applied, this process will block until a workitem (in any other process instance in the same engine) is dispatched to participant 'bob'. It then proceeds to charly.

triggering

This way of using 'listen' is useful for launching processes that "stalk" other processes :

Ruote.process_definition :name => 'stalker' do
  listen :to => 'bob' do
    participant :ref => 'charly'
  end
end

This small process will never exits and will send a workitem to charly each time the ruote engine sends a workitem to bob.

The workitems passed to charly will be copies of the workitem initially applied to the 'listen' expression, but with a copy of the fields of the workitem passed to bob, merged in.

Note : for now, the triggered segments of processes are 'forgotten'. The 'listen' expression doesn't keep track of them. This also means that in case of cancel, the triggered segments will not get cancelled.

:merge

By default, :merge is set to true, the listened for workitems see their values merged into a copy of the workitem held in the listen expression and this copy is delivered to the expressions that are client to the 'listen'.

:upon

There are two kinds of main events in ruote, apply and reply. Thus, a listen expression may listen to 'apply' and to 'reply' and this is defined by the :upon attribute.

By default, listens upon 'apply' (engine handing workitem to participant).

Can be set to 'reply', to react on workitems being handed back to the engine by the participant.

:to and :on

The :to attribute has already been seen, it can be replaced by the :on one.

Those two attributes are expected to hold regular expressions, so it's OK to write things like :

listen :to => "^user\_.+"

or

listen :to => /^user\_.+/

To listen for workitems for all the participant whose name start with "user_".

:wfid

By default, a listen expression listens for any workitem/participant event in the engine. Setting the :wfid attribute to 'true' or 'same' or 'current' will make the listen expression only care for events belonging to the same process instance (same wfid).