[rt-users] What do "first", "last" and "all" mean in --transaction on rt-crontool?

[Craig Ringer]

I've taken a look at the RT Book, the rt-crontool docs
http://bestpractical.com/docs/rt/latest/rt-crontool.html and the Wikia
article http://requesttracker.wikia.com/wiki/UseRtCrontool and haven't
been able to find an explanation of what exactly the transaction options
mean and control.

They're not related to database-level transactions since RT doesn't make
use of them.

I did some reading of the code and I'd like to confirm that my
understanding of what I see is accurate.

It looks like --transaction picks an *existing* transaction to set as
the context of the cronjob. 'first' for the tx that created the ticket,
'last' for the most recent ticket, or 'all' to select all transactions
on the ticket.

process(...) is called on each transaction found. It tests the condition
against the transaction and bails out if the condition doesn't match.
Otherwise, prepare the action with the specified argument and if prepare
succeeds, commit it.

So basically, rt-crontool --transaction all will apply the action to
*every* tx on the scrip if the condition matches the tx; 'last' on the
most recent tx and 'first' on the first tx on the ticket. It's not the
first/last tx that matches the condition; the transaction is picked and
THEN the condition is applied to decide whether an action should be taken.

It looks like all this is designed to have rt-crontool "piggy-back" on
existing transactions, which makes sense in that you don't want to
create a new transaction for each run, especially when you might not do
anything. It's a bit confusing when you're doing things that don't
really care about a particular transaction though.

--transaction-type looks like it refers to the Transaction.Type field,
with values like:

 DelWatcher
 SystemError
 Create
 AddLink
 DeleteLink
 Enabled
 Comment
 ResolveReminder
 Forward Transaction
 Set
 Status
 AddWatcher
 CustomField
 Disabled
 CommentEmailRecord
 Correspond
 EmailRecord
 AddReminder


so you could write:

--transaction last --transaction-type Comment

to find the most recent Comment on each ticket and, if one exists, apply
the Action to that transaction.

I'm a little puzzled by the way crontool doesn't seem to have the
ability to create a *new* transaction for matching tickets. I guess the
action code is supposed to do that if a new transaction is required, eg
when adding a Comment to a ticket.

Some actions and conditions don't require a transaction context, and for
those no --transaction should be specified; there's an implicit
"--transaction none" where "undef" is passed as the transaction to act
on in process(...) .

This can result in unexpected effects, like sending mail in the name of
the person who last did something on the ticket, so it's best to avoid
specifying a transaction unless you know you need one and one makes
sense in that context.

For example, if you invoke RT::Action::SendEmail, it'll use the
transaction in GetFriendlyName to get the creator of the current
transaction and from it, the friendlyname. Same with SetReturnAddress.

It might be worth elaborating on this a little more in the documentation
and/or book. Feel free to use any of the above.

-- 
 Craig Ringer                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services