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

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

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



225
226
227
228
229
230
# File 'lib/ruote/receiver/base.rb', line 225

def fetch_flow_expression(workitem_or_fei)

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

- (Object) fetch_workitem(fexp_or_fei) 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.



251
252
253
254
# File 'lib/ruote/receiver/base.rb', line 251

def fetch_workitem(fexp_or_fei)

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

- (Object) flunk(workitem, error_class_or_instance_or_message, *err_arguments)

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), or a string message 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")
receiver.flunk(workitem, "ArgumentError", "not enough info")
receiver.flunk(workitem, ArgumentError, "not enough info", backtrace)
receiver.flunk(workitem, "ArgumentError", "not enough info", backtrace)
receiver.flunk(workitem, "not enough info")

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


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
# File 'lib/ruote/receiver/base.rb', line 116

def flunk(workitem, error_class_or_instance_or_message, *err_arguments)

  err = error_class_or_instance_or_message
  trace = Ruote.pop_trace(err_arguments)

  err =
    case err
      when Exception
        err
      when Class
        err.new(*err_arguments)
      when String
        begin
          Ruote.constantize(err).new(*err_arguments)
        rescue #NameError # rescue instanciation errors too
          RuntimeError.new(err)
        end
      else
        ArgumentError.new(
          "flunk() failed, cannot bring back err from #{err.inspect}")
    end

  err.set_backtrace(trace || err.backtrace || caller)

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

  at = Ruote.now_to_utc_s

  @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,
      'put_at' => at
    },
    'error' => {
      'class' => err.class.name,
      'message' => err.message,
      'trace' => err.backtrace,
      'at' => at,
      'details' => err.respond_to?(:ruote_details) ? err.ruote_details : nil
    })
end

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

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.



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
# File 'lib/ruote/receiver/base.rb', line 186

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

  #puts caller.select { |l|
  #  ! (l.match(/test\/unit[\.\/]/) or l.match(/\/rspec-core-/))
  #} if @context.logger.noisy
    #
    # this is useful when noisy and running through a set of tests

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

  fields = Rufus::Json.dup(fields)
  variables = Rufus::Json.dup(variables)
  root_stash = Rufus::Json.dup(root_stash)
    #
    # making sure symbols are turned to strings

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

  wfid
end

- (Object) receive(workitem)

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



75
76
77
78
79
80
81
82
83
84
85
# File 'lib/ruote/receiver/base.rb', line 75

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

- (Object) reply(workitem)

Wraps a call to receive(workitem)

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



92
93
94
95
# File 'lib/ruote/receiver/base.rb', line 92

def reply(workitem)

  receive(workitem)
end

- (Object) sign

A receiver signs a workitem when it comes back.

Not used much as of now.



217
218
219
220
# File 'lib/ruote/receiver/base.rb', line 217

def sign

  self.class.to_s
end