6.2. Gritty Details

Now that you have seen a number of simple examples of custom scrip code, let's get into details of how these work and what objects are available for your custom code.

6.2.1. Tickets and Transactions

The two most important objects for custom scrip code and custom templates are the ticket and transaction objects. The ticket object is the ticket being modified. Any changes applied as part of the current transaction are reflected in the state of the related ticket object.

The transaction object represents the changes being made to the ticket. So for example, if the owner of a ticket is changed, then the transaction contains both the old and new owner IDs.

In a custom action or condition, these two objects are available via $self->TicketObj and $self->TransactionObj. You can access additional objects through those objects. For example, if you want the RT::User object representing a ticket's owner, you should use $self->TicketObj->OwnerObj. To get the ticket's queue object, use $self->TicketObj->QueueObj.

For more details, read the documentation for the RT::Ticket, RT::Ticket_Overlay, RT::Transaction, and RT::Transaction_Overlay modules.

6.2.2. Other Objects and Globals

Besides the ticket and transaction, several other pieces of the RT API often are useful when creating custom scrips.

$object->CurrentUser( )

Most objects in the RT class hierarchy inherit from RT::Base, which provides a CurrentUser( ) method. This represents the user currently operating on the object. In the web interface, this is the logged-in user who is triggering the scrip.

RT::Nobody( )

The RT::Nobody( ) function returns an RT::User object for the Nobody user. You can compare this user's ID to another user ID to check if that user is a real user. For example, you might have a condition that is true whenever the owner changes, as long as the previous owner wasn't Nobody. Or you might have an action that is triggered only when a ticket is assigned from a real user to Nobody.

RT::SystemUser()

RT::SystemUser() returns an RT::User object for RT's internal superuser, RT_SystemUser. RT uses this user internally to do things that need to happen without access control, such as performing internal consistency checks. Generally, you shouldn't ever do anything as the system user, but it's ok to use to look at things if you want to avoid ACL checks.

$RT::Logger

This is a Log::Dispatch object with outputs based on your RT config. You can call methods on this object like debug( ), warn( ), or error( ) to log output from your code. This is useful both for debugging as well as for logging serious errors.

Everything else

Of course, RT is a large system with a complex API. There are many other objects that you may want to make use of, such as queues, users, or custom fields. See Chapter 9 and the documentation for the relevant modules for more details on the API.

6.2.3. Scrip Stage

When you create or modify a scrip via the web interface, you are given a choice of Stage. The three options are TransactionCreate, TransactionBatch, and Disabled. Disabled simply means that the scrip will never run, and it is a simple way to turn off a scrip that you may want to re-enable later.

The TransactionCreate stage is the default for all scrips, and it is what all the scrips created use when RT is installed.

By default, RT does not enable the TransactionBatch stage. To turn it on you must add this line to your RT_SiteConfig.pm file:

     Set($UseTransactionBatch , 1); 

The difference between the create and batch stages is only relevant when an action creates multiple transactions, which can happen quite easily with normal web interface usage. For example, if you use the Jumbo form to change the subject of a ticket and assign it to someone else, you will end up creating at least two transactions, one for the subject change and one for the owner change.

When scrips run in the create stage, they run once for each transaction. Generally, this isn't a problem, as the scrip's condition will be true only for one of these transactions. But for some types of scrips, this may be problematic.

When a scrip's stage is set to TranactionBatch, it will run only once, no matter how many transactions are generated. But it will have access to all of the transactions at once. We will show a specific example of why this is useful later.

6.2.4. Custom Conditions

Writing a custom condition is pretty simple. All your code has to do is return true or false. If it returns true, the scrip continues and executes its action. If it returns false, the scrip is done.

When you're creating your own condition modules, you should always subclass RT::Condition::Generic and then override the IsApplicable( ) method. This is how the default actions that ship with RT all work.

6.2.5. Custom Actions

Actions are actually divided into two phases, prepare and cleanup. The latter is often referred to as the commit phase in the internals.

If the action's prepare phase code returns a false value, then the scrip is discarded and the action's commit phase never runs. This allows an action to decide not to run. If your action always will be executed, you can just define code for the commit phase.

Note that stopping an action by returning false from the prepare phase is orthogonal to the scrip's condition. You can mix and match conditions and actions, so you will still want your action to return false if it cannot execute. For example, you may have an action that creates a new ticket for the ticket's owner. If the ticket's owner is "Nobody," you probably don't want to run the action.

The commit phase should be where the action does things like send email, create a new ticket, etc.

6.2.6. Custom Templates

When you create a custom action, you may want create a custom template to go with it. Or you might just want to change RT's templates for the standard actions.

As we mentioned earlier, templates use Text::Template for generating output. Of course, the authoritative source of information on the module is the module's documentation, but there are a few points worth noting:

• Anything enclosed in { curly braces } is Perl code. The code may contain multiple statements. The value of the last statement is used as output. If you do not want to generate output simply end the block with an empty string: '';. Each separate block is in a separate scope, so you cannot use lexical variables created in another block.

• Anything you append to the $OUT variable appears in the template's output:

       One and two:     { for ( 1..2 ) {           $OUT .= " * $_\n";       }       '';     } 

  
  

  This generates this text:

       One and two:     * 1     * 2 

  
  

• If you want to add a curly brace to the output, you can escape it: \{.