Module: Ruote::ReceiverMixin

Included in:
Dashboard, LocalParticipant, Receiver
Defined in:
lib/ruote/receiver/base.rb

Overview

The core methods for the Receiver class (sometimes a Mixin is easier to integrate).

(The dashboard itself includes this mixin, the LocalParticipant module includes it as well).

Instance Method Summary collapse

Instance Method Details

#fetch_flow_expression(workitem_or_fei) ⇒ Object Also known as: fexp, flow_expression

Convenience method, given a workitem or a fei, returns the corresponding flow expession.



157
158
159
160
161
162
 
# File 'lib/ruote/receiver/base.rb', line 157

def fetch_flow_expression(workitem_or_fei)

  Ruote::Exp::FlowExpression.fetch(
    @context,
    Ruote::FlowExpressionId.extract_h(workitem_or_fei))
end

#fetch_workitem(fexp_or_fei) ⇒ Object Also known as: workitem, applied_workitem

A convenience methods for advanced users (like Oleg).

Given a fei (flow expression id), fetches the workitem as stored in the expression with that fei. This is the “applied workitem”, if the workitem is currently handed to a participant, this method will return the workitem as applied, not the workitem as saved by the participant/user in whatever worklist it uses. If you need that workitem, do the vanilla thing and ask it to the [storage] participant or its worklist.

The fei might be a string fei (result of fei.to_storage_id), a FlowExpressionId instance or a hash.

on_terminate processes are not triggered for on_error processes. on_error processes are triggered for on_terminate processes as well.



183
184
185
186
 
# File 'lib/ruote/receiver/base.rb', line 183

def fetch_workitem(fexp_or_fei)

  Ruote::Workitem.new(flow_expression(fexp_or_fei).h.applied_workitem)
end

#flunk(workitem, error_class_or_instance_or_message, *err_arguments) ⇒ Object

Can be used to raise an error in the workflow instance.

Can be called either with an error class and arguments, either with an error instance (and no arguments).

The workitem can be either an instance of Ruote::Workitem or a workitem in its Hash representation.

receiver.flunk(workitem, ArgumentError, "not enough info")

rescue => e
  receiver.flunk(workitem, e)
end



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/ruote/receiver/base.rb', line 76

def flunk(workitem, error_class_or_instance_or_message, *err_arguments)

  err = error_class_or_instance_or_message

  if err.is_a?(String)
    err = RuntimeError.new(err)
    err.set_backtrace(caller)

  elsif err.is_a?(Class)
    err = err.new(*err_arguments)
    err.set_backtrace(caller)
  end

  workitem = workitem.h if workitem.respond_to?(:h)

  @context.storage.put_msg(
    'raise',
    'fei' => workitem['fei'],
    'wfid' => workitem['wfid'],
    'msg' => {
      'action' => 'dispatch',
      'fei' => workitem['fei'],
      'participant_name' => workitem['participant_name'],
      'participant' => nil,
      'workitem' => workitem
    },
    'error' => {
      'class' => err.class.name,
      'message' => err.message,
      'trace' => err.backtrace
    })
end

#launch(process_definition, fields = {}, variables = {}, root_stash = nil) ⇒ Object

Given a process definitions and optional initial fields and variables, launches a new process instance.

This method is mostly used from the Ruote::Dashboard class (which includes this mixin).

process_definition must be a result of Ruote.process_definition call or XML or JSON serialized process definition, as accepted by Ruote::Reader#read.

fields are workflow parameters that will be placed in workitem.fields.

Calls to this method returns the newly launched “workflow instance id” (“wfid” for short), the [hopefully] unique identifier for the process instance.

custom :wfid

When calling this method, it’s OK to pass a field named :wfid (Symbol, not String) that will be used as the identifier for the process instance.



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/ruote/receiver/base.rb', line 130

def launch(process_definition, fields={}, variables={}, root_stash=nil)

  wfid = fields[:wfid] || @context.wfidgen.generate

  @context.storage.put_msg(
    'launch',
    'wfid' => wfid,
    'tree' => @context.reader.read(process_definition),
    'workitem' => { 'fields' => fields },
    'variables' => variables,
    'stash' => root_stash)

  wfid
end

#receive(workitem) ⇒ Object

This method pipes back a workitem into the engine, letting it resume in its flow, hopefully.



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/ruote/receiver/base.rb', line 40

def receive(workitem)

  workitem = workitem.to_h if workitem.respond_to?(:to_h)

  @context.storage.put_msg(
    'receive',
    'fei' => workitem['fei'],
    'workitem' => workitem,
    'participant_name' => workitem['participant_name'],
    'receiver' => sign)
end

#reply(workitem) ⇒ Object

Wraps a call to receive(workitem)

Not aliasing so that if someone changes the receive implementation, reply is affected as well.



57
58
59
60
 
# File 'lib/ruote/receiver/base.rb', line 57

def reply(workitem)

  receive(workitem)
end

#sign ⇒ Object

A receiver signs a workitem when it comes back.

Not used much as of now.



149
150
151
152
 
# File 'lib/ruote/receiver/base.rb', line 149

def sign

  self.class.to_s
end