|< Day Day Up >|
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.
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:
|< Day Day Up >|