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.



169
170
171
172
173
174
# File 'lib/ruote/receiver/base.rb', line 169

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.



195
196
197
198
# File 'lib/ruote/receiver/base.rb', line 195

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
144
145
146
147
148
149
150
151
152
153
154
155
# File 'lib/ruote/receiver/base.rb', line 130

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

#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

#signObject

A receiver signs a workitem when it comes back.

Not used much as of now.



161
162
163
164
# File 'lib/ruote/receiver/base.rb', line 161

def sign

  self.class.to_s
end