RT 6.0.0 Documentation

RT::Transaction

  RT::Transaction - RT's transaction object

SYNOPSIS

  use RT::Transaction;

DESCRIPTION

Each RT::Transaction describes an atomic change to a ticket object or an update to an RT::Ticket object. It can have arbitrary MIME attachments.

METHODS

Create

Create a new transaction.

This method should almost never be called directly. Wrappers are available for some cases. See "_NewTransaction" in RT::Record.

Accepts the following parameters:

    TimeTaken -- Time spent on this transaction in minutes
    TimeWorker -- User id of the user who worked the time,
                  can be different from Creator
    TimeWorkedDate -- Date the recorded time was worked, can be different
                      from Created
    Type -- Type of this transaction
    Data -- For recorded email, the message id of this transaction
    Field -- The field tracked by this transaction
    OldValue -- Previous value for this field
    NewValue -- Current (new) value for this field
    MIMEObj -- MIME object associated with this transaction
    ActivateScrips -- Should scrips run for this transaction?
    DryRun -- Pass DryRun to scrips, skipping the commit phase
    ObjectType -- Object this transaction applies to, like 'RT::Ticket'
    ObjectId -- The Id this transaction applies to
    ReferenceType -- Type of reference, if Old/New Value are a reference
    OldReference -- Id reference for the old value tracked by this transaction
    NewReference -- Id reference for the new value tracked by this transaction
    SquelchMailTo -- One or more email addresses to not send to on this transaction

Scrips

Returns the Scrips object for this transaction. This routine is only useful on a freshly created transaction object. Scrips do not get persisted to the database with transactions.

Rules

Returns the array of Rule objects for this transaction. This routine is only useful on a freshly created transaction object. Rules do not get persisted to the database with transactions.

Delete

Delete this transaction. Currently DOES NOT CHECK ACLS

Message

Returns the RT::Attachments object which contains the "top-level" object attachment for this transaction.

HasContent

Returns whether this transaction has attached mime objects.

Returns the content of this transaction as a string. Optionally quoted. When transaction has no content, returns the message "This transaction appears to have no content". Read ContentObj to understand how the content is determined.

Arguments:

Type - type of the content to return, either text/plain or text/html
Quote - quote the content and prepends it with the "QuoteHeader"
Wrap - size at which to wrap the content in case of text/plain.

Examples:

    # returns html content of the transaction
    my $content = $txn->Content( Type => 'text/html' );

    # returns plain text content of the transaction
    my $content = $txn->Content( Type => 'text/plain' );

    # returns html content of the transaction, quoted
    my $content = $txn->Content( Type => 'text/html', Quote => 1 );

    # returns text content of the transaction, quoted and wrapped at 60 characters
    my $content = $txn->Content( Type => 'text/plain', Quote => 1, Wrap => 60 );

QuoteContent

Class method utility. Takes content, its type, options and returns the content, quoted, wrapped and with header if asked.

Takes a paramhash.

Type - type of the content, either 'text/html' or 'text/plain' (default)
Content - the content to work on
QuoteHeader - string, header to prepend to the content if Quote is true
Wrap - integer, wrap the content at this many characters, defaults to QuoteWrapWidth option from RT config or 70 if it's not set. Applies only if expected content type is text/plain.

Example:

    # quote some html content as text/html
    my $res = RT::Transaction->QuoteContent(
        Type        => 'text/html',
        Content     => '<p>Hello, world!</p>',
        QuoteHeader => 'John Doe wrote:',
    );

QuoteHeader

Returns text prepended to content when transaction is quoted (see Quote argument in "Content"). By default returns localized "On <date> <user name> wrote:\n".

ApplyQuoteWrap PARAMHASH

Wrapper to calculate wrap criteria and apply quote wrapping if needed.

QuoteWrap PARAMHASH

Wrap the contents of transactions based on Wrap settings, maintaining the quote character from the original.

Addresses

Returns a hashref of addresses related to this transaction. See "Addresses" in RT::Attachment for details.

ContentObj

Returns the RT::Attachment object which contains the content for this Transaction.

Takes Type argument, which can be either text/plain or text/html, and defines preferred content type. If Type is set to text/html, this will return an HTML part of the message, if available. Otherwise it looks for a text/plain part. If the argument is missing, it defaults to the value of $RT::Transaction::PreferredContentType.

If there is no attachment of the preferred content type, returns the first textual part (as defined in RT::I18N::IsTextualContentType).

All the attachments with filenames or marked as attached files are excluded here, because it doesn't make much sense to use them as transaction content.

Returns undef if there is no attachment matching these rules.

_IsDisplayableTextualContentType

We may need to pull this out to another module later, but for now, this is better than RT::I18N::IsTextualContentType because that believes that a message/rfc822 email is displayable, despite it having no content

Subject

If this transaction has attached mime objects, returns the first one's subject Otherwise, returns null

Attachments

Returns all the RT::Attachment objects which are attached to this transaction. Takes an optional parameter, which is a ContentType that Attachments should be restricted to.

_Attach

A private method used to attach a mime object to this transaction.

Description

Returns a text string which describes this transaction

BriefDescription

Returns a text string which briefly describes this transaction

BriefDescriptionAsHTML

Returns an HTML string which briefly describes this transaction.

IsInbound

Returns true if the creator of the transaction is a requestor of the ticket. Returns false otherwise

_Value

Takes the name of a table column. Returns its value as a string, if the user passes an ACL check

CurrentUserCanSee

Returns true if current user has rights to see this particular transaction.

This fact depends on type of the transaction, type of an object the transaction is attached to and may be other conditions, so this method is preferred over custom implementations.

It always returns true if current user is system user.

Object

Returns the object current transaction belongs to.

CAVEAT: the returned object is cached, reload it to get the latest data.

NewReferenceObject

OldReferenceObject

Returns an object of the class specified by the column ReferenceType and loaded with the id specified by the column NewReference or OldReference. ReferenceType is assumed to be an RT::Record subclass.

The object may be unloaded (check $object->id) if the reference is corrupt (such as if the referenced record was improperly deleted).

Returns undef if either ReferenceType or NewReference/OldReference is false.

UpdateCustomFields

Takes a hash of:

    CustomField-C<Id> => Value

or:

    Object-RT::Transaction-CustomField-C<Id> => Value

parameters to update this transaction's custom fields.

LoadCustomFieldByIdentifier

Finds and returns the custom field of the given name for the transaction, overriding "LoadCustomFieldByIdentifier" in RT::Record to look for queue-specific CFs before global ones.

CustomFieldLookupType

Returns the RT::Transaction lookup type, which can be passed to RT::CustomField->Create() via the 'LookupType' hash key.

SquelchMailTo

Similar to Ticket class SquelchMailTo method - returns a list of transaction's squelched addresses. As transactions are immutable, the list of squelched recipients cannot be modified after creation.

Recipients

Returns the list of email addresses (as Email::Address objects) that this transaction would send mail to. There may be duplicates.

DeferredRecipients($freq, $include_sent )

Takes the following arguments:

a string to indicate the frequency of digest delivery. Valid values are "daily", "weekly", or "susp".
an optional argument which, if true, will return addresses even if this notification has been marked as 'sent' for this transaction.

Returns an array of users who should now receive the notification that was recorded in this transaction. Returns an empty array if there were no deferred users, or if $include_sent was not specified and the deferred notifications have been sent.

ACLEquivalenceObjects

This method returns a list of objects for which a user's rights also apply to this Transaction.

This currently only applies to Transaction Custom Fields on Tickets, so we return the Ticket's Queue and the Ticket.

This method is called from "HasRight" in RT::Principal.