- NAME
- DESCRIPTION
- REQUIRES
  - RT::Record::Role
  - LifecycleColumn
  - Status
- PROVIDES
  - Status
  - LifecycleObj
  - Lifecycle
  - ValidateStatus
  - ValidateStatusChange
  - SetStatus
  - _SetStatus
  - _SetLifecycleColumn

# NAME

RT::Record::Role::Status - Common methods for records which have a Status column

# DESCRIPTION

Lifecycles are generally set on container records, and Statuses on records which belong to one of those containers. RT::Record::Role::Lifecycle handles the containers with the Lifecycle column. This role is for the records with a Status column within those containers. It includes convenience methods for grabbing an RT::Lifecycle object as well setters for validating Status and the column which points to the container object.

# REQUIRES

## RT::Record::Role

## LifecycleColumn

Used as a role parameter. Must return a string of the column name which points to the container object that consumes RT::Record::Role::Lifecycle (or conforms to it). The resulting string is used to construct two method names: as-is to fetch the column value and suffixed with "Obj" to fetch the object.

## Status

A Status method which returns a lifecycle name is required. Currently unenforced at compile-time due to poor interactions with "AUTOLOAD" in DBIx::SearchBuilder::Record. You'll hit run-time errors if this method isn't available in consuming classes, however.

# PROVIDES

## Status

Returns the Status for this record, in the canonical casing.

## LifecycleObj

Returns an RT::Lifecycle object for this record's `Lifecycle`. If called as a class method, returns an RT::Lifecycle object which is an aggregation of all lifecycles of the appropriate type.

## Lifecycle

Returns the "Name" in RT::Lifecycle of this record's "LifecycleObj".

## ValidateStatus

Takes a status. Returns true if that status is a valid status for this record, otherwise returns false.

## ValidateStatusChange

Validates the new status with the current lifecycle. Returns a tuple of (OK, message).

Expected to be called from this role's "SetStatus" or the consuming class' equivalent.

## SetStatus

Validates the status transition before updating the Status column. This method may want to be overridden by a more specific method in the consuming class.

## _SetStatus

Sets the Status column without validating the change. Intended to be used as-is by methods provided by the role, or overridden in the consuming class to take additional action. For example, "_SetStatus" in RT::Ticket sets the Started and Resolved dates on the ticket as necessary.

Takes a paramhash where the only required key is Status. Other keys may include Lifecycle and NewLifecycle when called from "_SetLifecycleColumn", which may assist consuming classes. NewLifecycle defaults to Lifecycle if not provided; this indicates the lifecycle isn't changing.

## _SetLifecycleColumn

Validates and updates the column named by "LifecycleColumn". The Status column is also updated if necessary (via lifecycle transition maps).

On success, returns a tuple of (1, message, new status) where new status is the status that was transitioned to, if any. On failure, returns (0, error message).

Takes a paramhash with keys Value and (optionally) RequireRight. RequireRight is a right name which the current user must have on the new "LifecycleColumn" object in order for the method to succeed.

This method is expected to be used from within another method such as "SetQueue" in RT::Ticket.

← Back to index