# -*- Mode: perl; indent-tabs-mode: nil -*-
#
# The contents of this file are subject to the Mozilla Public
# License Version 1.1 (the "License"); you may not use this file
# except in compliance with the License. You may obtain a copy of
# the License at http://www.mozilla.org/MPL/
#
# Software distributed under the License is distributed on an "AS
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
# implied. See the License for the specific language governing
# rights and limitations under the License.
#
# The Original Code is the Bugzilla Bug Tracking System.
#
# Contributor(s): Marc Schumann <wurblzap@gmail.com>
#                 Max Kanat-Alexander <mkanat@bugzilla.org>
#                 Clement Ka Chan <cchan@mvista.com>

package Bugzilla::WebService::Bug;

use strict;
use base qw(Bugzilla::WebService);
import SOAP::Data qw(type);

use Bugzilla::Constants;
use Bugzilla::Error;
use Bugzilla::Field;
use Bugzilla::WebService::Constants;
use Bugzilla::Util qw(detaint_natural);
use Bugzilla::Bug;
use Bugzilla::BugMail;
use Bugzilla::Constants;
use Bugzilla::CGI;
use Bugzilla::Search;

#############
# Constants #
#############

# This maps the names of internal Bugzilla bug fields to things that would
# make sense to somebody who's not intimately familiar with the inner workings
# of Bugzilla. (These are the field names that the WebService uses.)
use constant FIELD_MAP => {
    status      => 'bug_status',
    severity    => 'bug_severity',
    description => 'comment',
    summary     => 'short_desc',
    platform    => 'rep_platform',
};

use constant GLOBAL_SELECT_FIELDS => qw(
    bug_severity
    bug_status
    op_sys
    priority
    rep_platform
    resolution
);

use constant PRODUCT_SPECIFIC_FIELDS => qw(version target_milestone component);

use constant CRITERIA_MAP => {
    'bug_num'			 => 'bug_id',
    'BNUM'			 => 'bug_id', 			# short form
    'summary'			 => 'short_desc',
    'SUMM'			 => 'short_desc', 		# short form
    'product'			 => 'product',
    'PROD'			 => 'product', 			# short form
    'version'			 => 'version',
    'VERS'			 => 'version', 			# short form
    'Platform'			 => 'rep_platform',
    'PLAT'			 => 'rep_platform', 		# short form
    'url'			 => 'bug_file_loc',
    'URL'			 => 'bug_file_loc', 		# short form
    'os_version'		 => 'op_sys',
    'OS_V'		  	 => 'op_sys', 			# short form
    'status'			 => 'bug_status',
    'STAT'			 => 'bug_status', 		# short form
    'status_whiteboard'		 => 'status_whiteboard',
    'WBRD'			 => 'status_whiteboard', 	# short form
    'keywords'			 => 'keywords',
    'KEYW'			 => 'keywords', 		# short form
    'resolution'		 => 'resolution',
    'RESO'		 	 => 'resolution', 		# short form
    'severity'			 => 'bug_severity',
    'SEVE'			 => 'bug_severity', 		# short form
    'priority'			 => 'priority',
    'PRIO'			 => 'priority', 		# short form
    'component'			 => 'component',
    'COMP'			 => 'component', 		# short form
    'assigned_to'		 => 'assigned_to',
    'ASGN'			 => 'assigned_to', 		# short form
    'reported_by'		 => 'reporter',
    'REPR'		    	 => 'reporter', 		# short form
    'votes'			 => 'votes',
    'VOTE'			 => 'votes', 			# short form
    'qa_contact'		 => 'qa_contact',
    'QA'		         => 'qa_contact', 		# short form
    'cc'			 => 'cc',
    'CC'			 => 'cc', 			# short form
    'depends_on'		 => 'dependson',
    'DEPS'		  	 => 'dependson', 		# short form
    'blocks'			 => 'blocked',
    'BLKS'			 => 'blocked', 			# short form
    'target_milestone'		 => 'target_milestone',
    'TRGT'		 	 => 'target_milestone', 	# short form
    'last_changed'		 => 'delta_ts',
    'LCHG'			 => 'delta_ts', 		# short form
    'days_changed'		 => 'days_elapsed',
    'DAYS'		         => 'days_elapsed', 		# short form
    'comment'			 => 'longdesca',
    'CMMN'			 => 'longdesca', 		# short form
    'alias'			 => 'alias',
    'ALIA'			 => 'alias', 			# short form
    'ever_confirmed'		 => 'everconfirmed',
    'CNFM'		 	 => 'everconfirmed', 		# short form
    'reporter_accessible' 	 => 'reporter_accessible',
    'RACC' 	 		 => 'reporter_accessible', 	# short form
    'cc_accessible'		 => 'cclist_accessible',
    'CACC'		 	 => 'cclist_accessible', 	# short form
    'group'			 => 'bug_groupa',
    'GRP'			 => 'bug_groupa', 		# short form
    'estimated_hours'		 => 'estimated_time',
    'EST'			 => 'estimated_time', 		# short form
    'remaining_hours'		 => 'remaining_time',
    'RMNG'			 => 'remaining_time', 		# short form
    'hours_worked'		 => 'work_time',
    'HRS'			 => 'work_time', 		# short form
    'percentage_complete'	 => 'percentage_complete',
    'PERC'			 => 'percentage_complete', 	# short form
    'content'			 => 'content',
    'CNTN'			 => 'content', 			# short form
    'classification'		 => 'classification',
    'CLSS'			 => 'classification', 		# short form
    'creation_date'		 => 'creation_ts',
    'CREA'			 => 'creation_ts', 		# short form
    'deadline'			 => 'deadline',
    'DDLN'			 => 'deadline', 		# short form
    'commenter'			 => 'commenter',
    'CMTR'			 => 'commenter', 		# short form
};

###########
# Methods #
###########
sub _xl {
    my ($name) = @_;
    $name =~ s/^\s*//g;  # remove leading and trailing spaces
    $name =~ s/\s*$//g;
    return FIELD_MAP->{$name} if (FIELD_MAP->{$name} ne '');
    return CRITERIA_MAP->{$name} if (CRITERIA_MAP->{$name} ne '');
    # custom field not defined in static map will pass through w/o translation
    return $name;
}

sub _get_boolean_chart {
    my ($root_aref) = @_;
    my $buffer = {};
    my $chart_idx = 0;
    foreach my $chart_aref (@$root_aref) {
        my $row_idx = 0;
        foreach my $row_aref (@$chart_aref) {
            my $col_idx = 0;
            foreach my $col_aref (@$row_aref) {
                $buffer->{"field$chart_idx-$row_idx-$col_idx"} =  _xl($col_aref->[0]);
                $buffer->{"type$chart_idx-$row_idx-$col_idx"}  =  $col_aref->[1];
                $buffer->{"value$chart_idx-$row_idx-$col_idx"} =  $col_aref->[2];
                $col_idx++;
            }
            $row_idx++;
        }
        $chart_idx++;
    }
    return $buffer;
}

sub search {
    my ($self, $params) = @_;
    my @orderstrings = ($params->{order} ne '') ? ($params->{order}) : ();

    ThrowCodeError('param_required', {param => 'criteria'}) 
      unless (defined($params->{'criteria'}) && $params->{'criteria'} ne ''); 

    my $href = _get_boolean_chart($params->{'criteria'});
    my $srch_params = new Bugzilla::CGI;
    while (my ($k,$v) = each %$href) {
        $srch_params->param($k,$v);
    }
    $srch_params->param('query_format', 'advanced');

    my $search;
    eval { $search = new Bugzilla::Search(
			  'fields' => ['bugs.bug_id'],
			  'params' => $srch_params,
			  'order' => \@orderstrings); }; 
    if($@) { ThrowCodeError('param_required', {function => 'Bugs.search', param => "$@"});}

    my $dbh   = Bugzilla->dbh;
    my $query = $search->getSQL();
    $query .= " " . $dbh->sql_limit($params->{'limit'}) if ($params->{'limit'} ne '');

    my $buglist_sth;
    eval {
	$buglist_sth = $dbh->prepare($query);
	$buglist_sth->execute(); };
    if($@) { ThrowCodeError('param_required', {function => 'Bugs.search', param => "$@"}); }

    my $ids_aref = $buglist_sth->fetchall_arrayref();
    my @ids = map { $_->[0] } @$ids_aref;
    my $href = {ids =>\@ids};
    $href->{get_duplicates} = $params->{get_duplicates} if ($params->{get_duplicates} ne '');
    return $self->get_bugs($href);
}

sub _get_duplicates {
    my ($return_aref) = @_;
    my @ids = grep { $_->{'internals'}->{'bug_status'} =~ /RESOLVED/  
                     && $_->{'internals'}->{'resolution'} =~/DUPLICATE/ } @$return_aref;
    return unless (@ids > 0);

    my $id_list = join(',', map { $_->{'internals'}->{'bug_id'} } @ids );
    my ($dbh, $sth);

    $dbh = Bugzilla->dbh;
    $sth = $dbh->prepare("SELECT dupe, dupe_of FROM duplicates WHERE dupe IN ($id_list)");
    $sth->execute;
    my $dupe_of_href = $sth->fetchall_arrayref;

    my %dupe_of = map {$_->[0] => $_->[1]} @$dupe_of_href;

    foreach my $item (@$return_aref) {
	if ($dupe_of{$item->{'internals'}->{'bug_id'}} ne '') {
	    $item->{'duplicate_of'} = type('int')->value(0 + $dupe_of{$item->{'internals'}->{'bug_id'}});
	}
    }
}

sub get_bugs {
    my ($self, $params) = @_;
    my $ids = $params->{ids};
    defined $ids || ThrowCodeError('param_required', { param => 'ids' });

    my @return;
    foreach my $bug_id (@$ids) {
        ValidateBugID($bug_id);
        my $bug = new Bugzilla::Bug($bug_id);

        # Timetracking fields are deleted if the user doesn't belong to
        # the corresponding group.
        unless (Bugzilla->user->in_group(Bugzilla->params->{'timetrackinggroup'})) {
            delete $bug->{'estimated_time'};
            delete $bug->{'remaining_time'};
            delete $bug->{'deadline'};
        }
        # This is done in this fashion in order to produce a stable API.
        # The internals of Bugzilla::Bug are not stable enough to just
        # return them directly.
        my $creation_ts = $self->datetime_format($bug->creation_ts);
        my $delta_ts    = $self->datetime_format($bug->delta_ts);
        my %item;
        $item{'creation_time'}    = type('dateTime')->value($creation_ts);
        $item{'last_change_time'} = type('dateTime')->value($delta_ts);
        $item{'internals'}        = $bug;
        $item{'id'}               = type('int')->value($bug->bug_id);
        $item{'summary'}          = type('string')->value($bug->short_desc);
        $item{'resolution'}       = type('string')->value($bug->resolution);
        $item{'status'}           = type('string')->value($bug->bug_status);

        if (Bugzilla->params->{'usebugaliases'}) {
            $item{'alias'} = type('string')->value($bug->alias);
        }
        else {
            # For API reasons, we always want the value to appear, we just
            # don't want it to have a value if aliases are turned off.
            $item{'alias'} = undef;
        }

        push(@return, \%item);
    }
    _get_duplicates(\@return) if (exists $params->{get_duplicates} && ($params->{get_duplicates} > 0));
    return { bugs => \@return };
}

sub create {
    my ($self, $params) = @_;

    Bugzilla->login(LOGIN_REQUIRED);

    my %field_values;
    foreach my $field (keys %$params) {
        my $field_name = FIELD_MAP->{$field} || $field;
        $field_values{$field_name} = $params->{$field}; 
    }

    # Make sure all the required fields are in the hash.
    foreach my $field (Bugzilla::Bug::REQUIRED_CREATE_FIELDS) {
        $field_values{$field} = undef unless exists $field_values{$field};
    }

    # WebService users can't set the creation date of a bug.
    delete $field_values{'creation_ts'};

    my $bug = Bugzilla::Bug->create(\%field_values);

    Bugzilla::BugMail::Send($bug->bug_id, { changer => $bug->reporter->login });

    return { id => type('int')->value($bug->bug_id) };
}

sub legal_values {
    my ($self, $params) = @_;
    my $field = FIELD_MAP->{$params->{field}} || $params->{field};

    my @custom_select =
        Bugzilla->get_fields({ type => FIELD_TYPE_SINGLE_SELECT });
    # We only want field names.
    @custom_select = map {$_->name} @custom_select;

    my $values;
    if (grep($_ eq $field, GLOBAL_SELECT_FIELDS, @custom_select)) {
        $values = get_legal_field_values($field);
    }
    elsif (grep($_ eq $field, PRODUCT_SPECIFIC_FIELDS)) {
        my $id = $params->{product_id};
        defined $id || ThrowCodeError('param_required',
            { function => 'Bug.legal_values', param => 'product_id' });
        grep($_->id eq $id, @{Bugzilla->user->get_accessible_products})
            || ThrowUserError('product_access_denied', { product => $id });

        my $product = new Bugzilla::Product($id);
        my @objects;
        if ($field eq 'version') {
            @objects = @{$product->versions};
        }
        elsif ($field eq 'target_milestone') {
            @objects = @{$product->milestones};
        }
        elsif ($field eq 'component') {
            @objects = @{$product->components};
        }

        $values = [map { $_->name } @objects];
    }
    else {
        ThrowCodeError('invalid_field_name', { field => $params->{field} });
    }

    my @result;
    foreach my $val (@$values) {
        push(@result, type('string')->value($val));
    }

    return { values => \@result };
}

1;

__END__

=head1 NAME

Bugzilla::Webservice::Bug - The API for creating, changing, and getting the
details of bugs.

=head1 DESCRIPTION

This part of the Bugzilla API allows you to file a new bug in Bugzilla,
or get information about bugs that have already been filed.

=head1 METHODS

See L<Bugzilla::WebService> for a description of B<STABLE>, B<UNSTABLE>,
and B<EXPERIMENTAL>.

=head2 Utility Functions

=over

=item C<legal_values> B<EXPERIMENTAL>

=over

=item B<Description>

Tells you what values are allowed for a particular field.

=item B<Params>

=over

=item C<field> - The name of the field you want information about.
This should be the same as the name you would use in L</create>, below.

=item C<product_id> - If you're picking a product-specific field, you have
to specify the id of the product you want the values for.

=back

=item B<Returns> 

C<values> - An array of strings: the legal values for this field.
The values will be sorted as they normally would be in Bugzilla.

=item B<Errors>

=over

=item 106 (Invalid Product)

You were required to specify a product, and either you didn't, or you
specified an invalid product (or a product that you can't access).

=item 108 (Invalid Field Name)

You specified a field that doesn't exist or isn't a drop-down field.

=back

=back


=back

=head2 Bug Creation and Modification

=over

=item C<get_bugs> B<EXPERIMENTAL>

=over

=item B<Description>

Gets information about particular bugs in the database.

=item B<Params>

=over

=item C<ids>

An array of numbers and strings.

If an element in the array is entirely numeric, it represents a bug_id
from the Bugzilla database to fetch. If it contains any non-numeric 
characters, it is considered to be a bug alias instead, and the bug with 
that alias will be loaded. 

Note that it's possible for aliases to be disabled in Bugzilla, in which
case you will be told that you have specified an invalid bug_id if you
try to specify an alias. (It will be error 100.)

=back

=item B<Returns>

A hash containing a single element, C<bugs>. This is an array of hashes. 
Each hash contains the following items:

=over

=item id

C<int> The numeric bug_id of this bug.

=item alias

C<string> The alias of this bug. If there is no alias or aliases are 
disabled in this Bugzilla, this will be an empty string.

=item summary

C<string> The summary of this bug.

=item creation_time

C<dateTime> When the bug was created.

=item last_change_time

C<dateTime> When the bug was last changed.

=item status

C<string> bug status

=item resolution

C<string> resolution

=item duplicate_of

C<string> bug id for which the current bug is a duplicate of.

=item internals B<UNSTABLE>

A hash. The internals of a L<Bugzilla::Bug> object. This is extremely
unstable, and you should only rely on this if you absolutely have to. The
structure of the hash may even change between point releases of Bugzilla.

=back

=item B<Errors>

=over

=item 100 (Invalid Bug Alias)

If you specified an alias and either: (a) the Bugzilla you're querying
doesn't support aliases or (b) there is no bug with that alias.

=item 101 (Invalid Bug ID)

The bug_id you specified doesn't exist in the database.

=item 102 (Access Denied)

You do not have access to the bug_id you specified.

=back

=back



=item C<create> B<EXPERIMENTAL>

=over

=item B<Description>

This allows you to create a new bug in Bugzilla. If you specify any
invalid fields, they will be ignored. If you specify any fields you
are not allowed to set, they will just be set to their defaults or ignored.

You cannot currently set all the items here that you can set on enter_bug.cgi.

The WebService interface may allow you to set things other than those listed
here, but realize that anything undocumented is B<UNSTABLE> and will very
likely change in the future.

=item B<Params>

Some params must be set, or an error will be thrown. These params are
marked B<Required>. 

Some parameters can have defaults set in Bugzilla, by the administrator.
If these parameters have defaults set, you can omit them. These parameters
are marked B<Defaulted>.

Clients that want to be able to interact uniformly with multiple
Bugzillas should always set both the params marked B<Required> and those 
marked B<Defaulted>, because some Bugzillas may not have defaults set
for B<Defaulted> parameters, and then this method will throw an error
if you don't specify them.

The descriptions of the parameters below are what they mean when Bugzilla is
being used to track software bugs. They may have other meanings in some
installations.

=over

=item C<product> (string) B<Required> - The name of the product the bug
is being filed against.

=item C<component> (string) B<Required> - The name of a component in the
product above.

=item C<summary> (string) B<Required> - A brief description of the bug being
filed.

=item C<version> (string) B<Required> - A version of the product above;
the version the bug was found in.

=item C<description> (string) B<Defaulted> - The initial description for 
this bug. Some Bugzilla installations require this to not be blank.

=item C<op_sys> (string) B<Defaulted> - The operating system the bug was
discovered on.

=item C<platform> (string) B<Defaulted> - What type of hardware the bug was
experienced on.

=item C<priority> (string) B<Defaulted> - What order the bug will be fixed
in by the developer, compared to the developer's other bugs.

=item C<severity> (string) B<Defaulted> - How severe the bug is.

=item C<alias> (string) - A brief alias for the bug that can be used 
instead of a bug number when accessing this bug. Must be unique in
all of this Bugzilla.

=item C<assigned_to> (username) - A user to assign this bug to, if you
don't want it to be assigned to the component owner.

=item C<cc> (array) - An array of usernames to CC on this bug.

=item C<qa_contact> (username) - If this installation has QA Contacts
enabled, you can set the QA Contact here if you don't want to use
the component's default QA Contact.

=item C<status> (string) - The status that this bug should start out as.
Note that only certain statuses can be set on bug creation.

=item C<target_milestone> (string) - A valid target milestone for this
product.

=back

In addition to the above parameters, if your installation has any custom
fields, you can set them just by passing in the name of the field and
its value as a string.

=item B<Returns>

A hash with one element, C<id>. This is the id of the newly-filed bug.

=item B<Errors>

=over

=item 103 (Invalid Alias)

The alias you specified is invalid for some reason. See the error message
for more details.

=item 104 (Invalid Field)

One of the drop-down fields has an invalid value. The error message will
have more detail.

=item 105 (Invalid Component)

Either you didn't specify a component, or the component you specified was
invalid.

=item 106 (Invalid Product)

Either you didn't specify a product, this product doesn't exist, or
you don't have permission to enter bugs in this product.

=item 107 (Invalid Summary)

You didn't specify a summary for the bug.

=item 504 (Invalid User)

Either the QA Contact, Assignee, or CC lists have some invalid user
in them. The error message will have more details.

=back

=back

=item C<search> B<EXPERIMENTAL>

=over

=item B<Description>

This function allows you to construct a query similar to the Boolean 
Charts on the Advance Search tab and the obtain the search result 
in the return hash value. The Boolean Charts internally are arranged 
in tables, rows and then columns. Each column contains a single 
boolean expression with three fields, the data field, the boolean 
operator and the operand. (See the Boolean Chart section in 
the Advance Search tab for all the supported operator type features). 
Each field value will be accepted as plain text. A mandatory criteria 
parameter is required, and parameters like limit and order are optional. 
If the get_duplicates key is set, the corresponding duplicate of bug id
will be retrieved in the duplicate_of field of the returned bug object.
Composite OR expression can be contructed by arranging multiple columns
in the same rows. And Composite AND expression can be contructed by
stacking them as rows with in a chart, and so on with multiple charts.
The limit and the order options allow you to contruct page size, 
navigator etc.

=item B<Params>

Some params must be set, or an error will be thrown. These params are
marked B<Required>. 

The descriptions of the parameters below are what they mean when Bugzilla is
being used to track software bugs. They may have other meanings in some
installations.

=over

=item C<criteria> (string) B<Required> - The critera in the form of an
array reference, it is comprised of at least one boolean chart, with 
one row and one column. Each column is an array reference pointer to
three fields, the query field, the boolean operator type and the value 
to be used in the boolean expression. The following illustrate how the
criteria is being passed to the search WebService API

 $soapresult = $proxy->call('Bugs.search', 
  {criteria => [
     [
       [
         [col 1], [col2]
       ], #row 1 
       [
         [col 1]
       ], #row 2 
     ],  #chart 1
     [
       [
         [col 1], [col2]
       ], #row 1 
       [
         [col 1]
       ], #row 2 
     ],  #chart 2
   ], 
  limit => ...,
  order => ...,
  get_duplicates => ...,
 })
  
=item C<limit> (integer) B<Optional> - The number of row to be retrieved
per call, this should curtail the straining of the server resource if 
the result set is huge.

=item C<order> (string) B<Optional> - The sort columns followed by sort order
token ASC - as ascending, and DESC as descending. You may put column name
if you know exactly the column name of the internal data schema of the 
repository of bugs, otherwise see the mapping symbol below.

=item C<get_duplicates> (string) B<Optional> - A flag when specified will
as the WebService API to pull up it's duplicate if it's status became RESOLVED,
and it's resolution became DUPLICATE. The {duplicate_of} field of the returned
bug will contain the duplicate bug's id.

=item C<criteria map> (string) B<Defaulted> - In order to support the future
grow of Bugzilla database schema and properly shield the WebService API 
Application from the impact of future changes. A translation CRITERIA_MAP
is created. Using the values from the CRITERIA_MAP will ask the API to perform
translation automatically before performing the querying. 

The following is the static criteria field values (long form, short form):

    'bug_num'             'BNUM'
    'summary'	          'SUMM'
    'product'             'PROD'
    'version'             'VERS'
    'Platform'	          'PLAT'
    'url'                 'URL'
    'os_version'          'OS_V'
    'status'              'STAT'
    'status_whiteboard'   'WBRD'
    'keywords'            'KEYW'	
    'resolution'          'RESO'	
    'severity'            'SEVE'
    'priority'            'PRIO'
    'component'           'COMP'
    'assigned_to'         'ASGN'
    'reported_by'         'REPR'
    'votes'               'VOTE'
    'qa_contact'          'QA'
    'cc'                  'CC'
    'depends_on'          'DEPS'
    'blocks'              'BLKS'
    'target_milestone'    'TRGT'
    'last_changed'        'LCHG'
    'days_changed'        'DAYS'
    'comment'             'CMMN'
    'alias'               'ALIA'
    'ever_confirmed'      'CNFM'
    'reporter_accessible' 'RACC'
    'cc_accessible'       'CACC'
    'group'               'GRP'
    'estimated_hours'     'EST'
    'remaining_hours'     'RMNG'
    'hours_worked'        'HRS'
    'percentage_complete' 'PERC'
    'content'             'CNTN'
    'classification'	  'CLSS'
    'creation_date'       'CREA'
    'deadline'            'DDLN'
    'commenter'           'CMTR'

Anything that doesn't fit into this list will bypass the mapping checks as pass
through value. If the spelling mistake is made, the Search module or 
the MySQL will throw an exception. This will allow custom fields to be included
in the search criteria.

The following is a list of supported boolean operators and it's English
representation (you may also extract them from the page source of 
the Advanced Search tab).

    'equals'         => 'is equal to'
    'notequals'      => 'is not equal to'
    'anyexact'       => 'is equal to any of the strings'
    'substring'      => 'contains the string'
    'casesubstring'  => 'contains the string (exact case)'

    'notsubstring'   => 'does not contain the string'
    'anywordssubstr' => 'contains any of the strings'
    'allwordssubstr' => 'contains all of the strings'
    'nowordssubstr'  => 'contains none of the strings'
    'regexp'         => 'contains regexp'
    'notregexp'      => 'does not contain regexp'

    'lessthan'       => 'is less than'
    'greaterthan'    => 'is greater than'
    'anywords'       => 'contains any of the words'
    'allwords'       => 'contains all of the words'
    'nowords'        => 'contains none of the words'
    'changedbefore'  => 'changed before'

    'changedafter'   => 'changed after'
    'changedfrom'    => 'changed from'
    'changedto'      => 'changed to'
    'changedby'      => 'changed by'
    'matches'        => 'matches'

Please see Bugzilla Search Guide for all the values of
the boolean expression.

=item B<Boolean Expression inside as the column in the criteria chart>

Sample of a a query 

C<Query Text> Get all the customer related and show stopper bugs that has been 
modified in the last 12 hours.

criteria =>
[
  [ 
    ["last_changed", "greaterthan", "-12h"], #row 1
    ["cf_customer_issue", "equals", "1"], ["PRIO", "equals", "P1"] #row 2
  ], #chart 1
   #... more chart if needed
], # critera chart

The resulting filter to be applied should be 
 (last_changed > -12h) AND 
   (cf_customer_issue = 1 OR priorty = P1)

Since the columns are used as OR, and rows are used as AND. Negation
and re-forumulation using set algebra may be needed to create the 
desirable composite boolean expression.

=back

=item B<Returns>

Please see C<get_bugs> for the return values, errors and exceptions.


=back
