Class: Ruote::Workitem

Inherits:
Object
  • Object
show all
Includes:
WithH
Defined in:
lib/ruote/workitem.rb

Overview

A workitem can be thought of an “execution token”, but with a payload (fields).

The payload/fields MUST be JSONifiable.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from WithH

#h, #h=, included, #to_h

Constructor Details

#initialize(h) ⇒ Workitem


42
43
44
45
# File 'lib/ruote/workitem.rb', line 42

def initialize(h)

  self.h = h
end

Class Method Details

.from_json(json) ⇒ Object

Given a JSON String, decodes and returns a Ruote::Workitem instance.3 If the decode thing is not an object/hash, will raise an ArgumentError.


393
394
395
396
397
398
399
400
401
402
# File 'lib/ruote/workitem.rb', line 393

def self.from_json(json)

  h = Rufus::Json.decode(json)

  raise ArgumentError(
    "Arg not a JSON hash/object, but a #{h.class}. Cannot create workitem"
  ) unless h.is_a?(Hash)

  self.new(h)
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Warning : equality is based on fei and not on payload !


167
168
169
170
171
# File 'lib/ruote/workitem.rb', line 167

def ==(other)

  return false if other.class != self.class
  self.h.fei == other.h.fei
end

#[](key) ⇒ Object

Shortcut for #lookup(key)

workitem.fields['customer']['city']
  # or
workitem.lookup('customer.city')
  # or
workitem['customer.city']

229
230
231
232
# File 'lib/ruote/workitem.rb', line 229

def [](key)

  lookup(key.to_s)
end

#[]=(key, value) ⇒ Object

Shortcut for #set_field(key, value)

workitem.fields['customer']['city'] = 'Toronto'
  # or
workitem.set_field('customer.city', 'Toronto')
  # or
workitem['customer.city'] = 'Toronto'

242
243
244
245
# File 'lib/ruote/workitem.rb', line 242

def []=(key, value)

  set_field(key.to_s, value)
end

#as_json(pretty = false) ⇒ Object

Encodes this workitem as JSON. If pretty is set to true, will output prettified JSON.


385
386
387
388
# File 'lib/ruote/workitem.rb', line 385

def as_json(pretty=false)

  pretty ? Rufus::Json.pretty_encode(@h) : Rufus::Json.encode(@h)
end

#commandObject

(advanced)

Shortcut for wi.fields

__command__ is read by the 'cursor' and the 'iterator' expressions when a workitem reaches it (apply and reply).


344
345
346
347
# File 'lib/ruote/workitem.rb', line 344

def command

  h.fields['__command__']
end

#command=(com) ⇒ Object

(advanced)

Shortcut for wi.fields = x

__command__ is read by the 'cursor' and the 'iterator' expressions when a workitem reaches it (apply and reply).


356
357
358
359
360
361
362
363
# File 'lib/ruote/workitem.rb', line 356

def command=(com)

  com = com.is_a?(Array) ? com : com.split(' ')
  com = [ com.first, com.last ]
  com[1] = com[1].to_i if com[1] and com[0] != 'jump'

  h.fields['__command__'] = com
end

#dispatched_atObject

When was this workitem dispatched ?


160
161
162
163
# File 'lib/ruote/workitem.rb', line 160

def dispatched_at

  fields['dispatched_at']
end

#dupObject

Returns a complete copy of this workitem.


76
77
78
79
# File 'lib/ruote/workitem.rb', line 76

def dup

  Workitem.new(Rufus::Json.dup(@h))
end

#errorObject

Shortcut for wi.fields


256
257
258
259
# File 'lib/ruote/workitem.rb', line 256

def error

  h.fields['__error__']
end

#feiObject

Returns a Ruote::FlowExpressionId instance.


69
70
71
72
# File 'lib/ruote/workitem.rb', line 69

def fei

  FlowExpressionId.new(h.fei)
end

#field_or_param(key) ⇒ Object Also known as: fop

Like #param_or_field, but priority is given to the field.


318
319
320
321
322
323
# File 'lib/ruote/workitem.rb', line 318

def field_or_param(key)

  key = key.to_s

  h.fields[key] || (h.fields['params'] || {})[key]
end

#fieldsObject

Returns the payload, ie the fields hash.


128
# File 'lib/ruote/workitem.rb', line 128

def fields; h.fields; end

#fields=(fields) ⇒ Object

Sets all the fields in one sweep.

Remember : the fields must be a JSONifiable hash.


134
135
136
137
# File 'lib/ruote/workitem.rb', line 134

def fields=(fields)

  h.fields = fields
end

#hashObject

Warning : hash is fei's hash.


177
178
179
180
# File 'lib/ruote/workitem.rb', line 177

def hash

  self.h.fei.hash
end

#lookup(key, container_lookup = false) ⇒ Object Also known as: lf

For a simple key

workitem.lookup('toto')

is equivalent to

workitem.fields['toto']

but for a complex key

workitem.lookup('toto.address')

is equivalent to

workitem.fields['toto']['address']

198
199
200
201
# File 'lib/ruote/workitem.rb', line 198

def lookup(key, container_lookup=false)

  Ruote.lookup(h.fields, key, container_lookup)
end

#ownerObject

Used by some participants, returns the “owner” of the workitem. Mostly used when reserving workitems.


124
# File 'lib/ruote/workitem.rb', line 124

def owner; h.owner; end

#param_or_field(key) ⇒ Object Also known as: pof

Sometimes a value is passed as a[n expression] parameter or as a workitem field, with priority to the parameter.

sequence do
  set 'f:country' => 'uruguay'
  participant 'toto'
    # in toto, workitem.param_or_field(:country) will yield 'uruguay'
  participant 'toto', :country => 'argentina'
    # workitem.param_or_field(:country) will yield 'argentina'
end

309
310
311
312
313
314
# File 'lib/ruote/workitem.rb', line 309

def param_or_field(key)

  key = key.to_s

  (h.fields['params'] || {})[key] || h.fields[key]
end

#param_textObject

When a participant is invoked like in

accounting 'do_invoice', :customer => 'acme corp'

then

p workitem.params
  # => { 'ref' => 'accounting', 'do_invoice' => nil, 'customer' => 'acme corp' }

and

p workitem.param_text
  # => 'do_invoice'

It returns nil when there is no text passed directly.


293
294
295
296
# File 'lib/ruote/workitem.rb', line 293

def param_text

  (params.find { |k, v| v.nil? } || []).first
end

#paramsObject

Shortcut for wi.fields

When a participant is invoked like in

participant :ref => 'toto', :task => 'x"

then

p workitem.params
  # => { 'ref' => 'toto', 'task' => 'x' }

272
273
274
275
# File 'lib/ruote/workitem.rb', line 272

def params

  h.fields['params'] || {}
end

#participant_nameObject

The participant for which this item is destined. Will be nil when the workitem is transiting inside of its process instance (as opposed to when it's being delivered outside of the engine).


85
86
87
88
# File 'lib/ruote/workitem.rb', line 85

def participant_name

  h.participant_name
end

#re_dispatch_countObject

How many times was this workitem re_dispatched ?

It's used by LocalParticipant re_dispatch mostly, or by participant which poll a resource and re_dispatch after a while.


377
378
379
380
# File 'lib/ruote/workitem.rb', line 377

def re_dispatch_count

  h.re_dispatch_count || 0
end

#resultObject

A shortcut to the value in the field named __result__

This field is used by the if expression for instance to determine if it should branch to its 'then' or its 'else'.


144
145
146
147
# File 'lib/ruote/workitem.rb', line 144

def result

  fields['__result__']
end

#result=(r) ⇒ Object

Sets the value of the 'special' field __result__

See #result


153
154
155
156
# File 'lib/ruote/workitem.rb', line 153

def result=(r)

  fields['__result__'] = r
end

#set_field(key, value) ⇒ Object

Like #lookup allows for nested lookups, #set_field can be used to set sub fields directly.

workitem.set_field('customer.address.city', 'Pleasantville')

Warning : if the customer and address field and subfield are not present or are not hashes, set_field will simply create a “customer.address.city” field and set its value to “Pleasantville”.


216
217
218
219
# File 'lib/ruote/workitem.rb', line 216

def set_field(key, value)

  Ruote.set(h.fields, key, value)
end

#sidObject

Returns the String id for this workitem (something like “0_0!!20100507-wagamama”).

It's in fact a shortcut for

Ruote::FlowExpressionId.to_storage_id(h.fei)

54
55
56
57
# File 'lib/ruote/workitem.rb', line 54

def sid

  Ruote::FlowExpressionId.to_storage_id(h.fei)
end

#sub_wf_launched_atObject

Returns the UTC time string indicating when the sub-workflow was launched.


119
# File 'lib/ruote/workitem.rb', line 119

def sub_wf_launched_at; h.sub_wf_launched_at; end

#sub_wf_nameObject

Returns the name of the sub-workflow the workitem is currently in. (If it's in the main flow, it will return the name of the main flow, if that flow has a name…)


111
# File 'lib/ruote/workitem.rb', line 111

def sub_wf_name; h.sub_wf_name; end

#sub_wf_revisionObject

The equivalent of #sub_wf_name for revisions.


115
# File 'lib/ruote/workitem.rb', line 115

def sub_wf_revision; h.sub_wf_revision; end

#tObject


332
333
334
335
# File 'lib/ruote/workitem.rb', line 332

def t

  h.fields['t'] ||= {}
end

#tagsObject

Shortcut for wi.fields


367
368
369
370
# File 'lib/ruote/workitem.rb', line 367

def tags

  h.fields['__tags__'] || []
end

#timed_outObject

Shortcut for wi.fields


249
250
251
252
# File 'lib/ruote/workitem.rb', line 249

def timed_out

  h.fields['__timed_out__']
end

#wf_launched_atObject Also known as: launched_at

Returns the UTC time string indicating when the workflow was launched.


101
# File 'lib/ruote/workitem.rb', line 101

def wf_launched_at; h.wf_launched_at; end

#wf_nameObject Also known as: definition_name

Returns the name of the workflow to which this workitem belongs, or nil.


92
# File 'lib/ruote/workitem.rb', line 92

def wf_name; h.wf_name; end

#wf_revisionObject Also known as: definition_revision

Returns the revision of the workflow to which this workitem belongs, or nil.


97
# File 'lib/ruote/workitem.rb', line 97

def wf_revision; h.wf_revision; end

#wfidObject

Returns the “workflow instance id” (unique process instance id) of the process instance which issued this workitem.


62
63
64
65
# File 'lib/ruote/workitem.rb', line 62

def wfid

  h.fei['wfid']
end