Upgrade to 4.0.13
[usit-rt.git] / lib / RT / Group.pm
1
2 # BEGIN BPS TAGGED BLOCK {{{
3 #
4 # COPYRIGHT:
5 #
6 # This software is Copyright (c) 1996-2013 Best Practical Solutions, LLC
7 #                                          <sales@bestpractical.com>
8 #
9 # (Except where explicitly superseded by other copyright notices)
10 #
11 #
12 # LICENSE:
13 #
14 # This work is made available to you under the terms of Version 2 of
15 # the GNU General Public License. A copy of that license should have
16 # been provided with this software, but in any event can be snarfed
17 # from www.gnu.org.
18 #
19 # This work is distributed in the hope that it will be useful, but
20 # WITHOUT ANY WARRANTY; without even the implied warranty of
21 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
22 # General Public License for more details.
23 #
24 # You should have received a copy of the GNU General Public License
25 # along with this program; if not, write to the Free Software
26 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
27 # 02110-1301 or visit their web page on the internet at
28 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
29 #
30 #
31 # CONTRIBUTION SUBMISSION POLICY:
32 #
33 # (The following paragraph is not intended to limit the rights granted
34 # to you to modify and distribute this software under the terms of
35 # the GNU General Public License and is only of importance to you if
36 # you choose to contribute your changes and enhancements to the
37 # community by submitting them to Best Practical Solutions, LLC.)
38 #
39 # By intentionally submitting any modifications, corrections or
40 # derivatives to this work, or any other work intended for use with
41 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
42 # you are the copyright holder for those contributions and you grant
43 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
44 # royalty-free, perpetual, license to use, copy, create derivative
45 # works based on those contributions, and sublicense and distribute
46 # those contributions and any derivatives thereof.
47 #
48 # END BPS TAGGED BLOCK }}}
49
50 # Released under the terms of version 2 of the GNU Public License
51
52 =head1 NAME
53
54   RT::Group - RT's group object
55
56 =head1 SYNOPSIS
57
58 use RT::Group;
59 my $group = RT::Group->new($CurrentUser);
60
61 =head1 DESCRIPTION
62
63 An RT group object.
64
65 =head1 METHODS
66
67
68
69
70
71 =cut
72
73
74 package RT::Group;
75
76
77 use strict;
78 use warnings;
79
80 use base 'RT::Record';
81
82 sub Table {'Groups'}
83
84
85
86 use RT::Users;
87 use RT::GroupMembers;
88 use RT::Principals;
89 use RT::ACL;
90
91 use vars qw/$RIGHTS $RIGHT_CATEGORIES/;
92
93 $RIGHTS = {
94     AdminGroup              => 'Modify group metadata or delete group',     # loc_pair
95     AdminGroupMembership    => 'Modify group membership roster',            # loc_pair
96     ModifyOwnMembership     => 'Join or leave group',                       # loc_pair
97     EditSavedSearches       => 'Create, modify and delete saved searches',  # loc_pair
98     ShowSavedSearches       => 'View saved searches',                       # loc_pair
99     SeeGroup                => 'View group',                                # loc_pair
100     SeeGroupDashboard       => 'View group dashboards',                     # loc_pair
101     CreateGroupDashboard    => 'Create group dashboards',                   # loc_pair
102     ModifyGroupDashboard    => 'Modify group dashboards',                   # loc_pair
103     DeleteGroupDashboard    => 'Delete group dashboards',                   # loc_pair
104 };
105
106 $RIGHT_CATEGORIES = {
107     AdminGroup              => 'Admin',
108     AdminGroupMembership    => 'Admin',
109     ModifyOwnMembership     => 'Staff',
110     EditSavedSearches       => 'Admin',
111     ShowSavedSearches       => 'Staff',
112     SeeGroup                => 'Staff',
113     SeeGroupDashboard       => 'Staff',
114     CreateGroupDashboard    => 'Admin',
115     ModifyGroupDashboard    => 'Admin',
116     DeleteGroupDashboard    => 'Admin',
117 };
118
119 # Tell RT::ACE that this sort of object can get acls granted
120 $RT::ACE::OBJECT_TYPES{'RT::Group'} = 1;
121
122
123 #
124
125 # TODO: This should be refactored out into an RT::ACLedObject or something
126 # stuff the rights into a hash of rights that can exist.
127
128 __PACKAGE__->AddRights(%$RIGHTS);
129 __PACKAGE__->AddRightCategories(%$RIGHT_CATEGORIES);
130
131 =head2 AddRights C<RIGHT>, C<DESCRIPTION> [, ...]
132
133 Adds the given rights to the list of possible rights.  This method
134 should be called during server startup, not at runtime.
135
136 =cut
137
138 sub AddRights {
139     my $self = shift;
140     my %new = @_;
141     $RIGHTS = { %$RIGHTS, %new };
142     %RT::ACE::LOWERCASERIGHTNAMES = ( %RT::ACE::LOWERCASERIGHTNAMES,
143                                       map { lc($_) => $_ } keys %new);
144 }
145
146 =head2 AvailableRights
147
148 Returns a hash of available rights for this object. The keys are the right names and the values are a description of what the rights do
149
150 =cut
151
152 sub AvailableRights {
153     my $self = shift;
154     return($RIGHTS);
155 }
156
157 =head2 RightCategories
158
159 Returns a hashref where the keys are rights for this type of object and the
160 values are the category (General, Staff, Admin) the right falls into.
161
162 =cut
163
164 sub RightCategories {
165     return $RIGHT_CATEGORIES;
166 }
167
168 =head2 AddRightCategories C<RIGHT>, C<CATEGORY> [, ...]
169
170 Adds the given right and category pairs to the list of right categories.  This
171 method should be called during server startup, not at runtime.
172
173 =cut
174
175 sub AddRightCategories {
176     my $self = shift if ref $_[0] or $_[0] eq __PACKAGE__;
177     my %new = @_;
178     $RIGHT_CATEGORIES = { %$RIGHT_CATEGORIES, %new };
179 }
180
181
182
183 =head2 SelfDescription
184
185 Returns a user-readable description of what this group is for and what it's named.
186
187 =cut
188
189 sub SelfDescription {
190         my $self = shift;
191         if ($self->Domain eq 'ACLEquivalence') {
192                 my $user = RT::Principal->new($self->CurrentUser);
193                 $user->Load($self->Instance);
194                 return $self->loc("user [_1]",$user->Object->Name);
195         }
196         elsif ($self->Domain eq 'UserDefined') {
197                 return $self->loc("group '[_1]'",$self->Name);
198         }
199         elsif ($self->Domain eq 'RT::System-Role') {
200                 return $self->loc("system [_1]",$self->Type);
201         }
202         elsif ($self->Domain eq 'RT::Queue-Role') {
203                 my $queue = RT::Queue->new($self->CurrentUser);
204                 $queue->Load($self->Instance);
205                 return $self->loc("queue [_1] [_2]",$queue->Name, $self->Type);
206         }
207         elsif ($self->Domain eq 'RT::Ticket-Role') {
208                 return $self->loc("ticket #[_1] [_2]",$self->Instance, $self->Type);
209         }
210         elsif ($self->Domain eq 'SystemInternal') {
211                 return $self->loc("system group '[_1]'",$self->Type);
212         }
213         else {
214                 return $self->loc("undescribed group [_1]",$self->Id);
215         }
216 }
217
218
219
220 =head2 Load ID
221
222 Load a group object from the database. Takes a single argument.
223 If the argument is numerical, load by the column 'id'. Otherwise, 
224 complain and return.
225
226 =cut
227
228 sub Load {
229     my $self       = shift;
230     my $identifier = shift || return undef;
231
232     if ( $identifier !~ /\D/ ) {
233         $self->SUPER::LoadById($identifier);
234     }
235     else {
236         $RT::Logger->crit("Group -> Load called with a bogus argument");
237         return undef;
238     }
239 }
240
241
242
243 =head2 LoadUserDefinedGroup NAME
244
245 Loads a system group from the database. The only argument is
246 the group's name.
247
248
249 =cut
250
251 sub LoadUserDefinedGroup {
252     my $self       = shift;
253     my $identifier = shift;
254
255     if ( $identifier =~ /^\d+$/ ) {
256         return $self->LoadByCols(
257             Domain => 'UserDefined',
258             id     => $identifier,
259         );
260     } else {
261         return $self->LoadByCols(
262             Domain => 'UserDefined',
263             Name   => $identifier,
264         );
265     }
266 }
267
268
269
270 =head2 LoadACLEquivalenceGroup PRINCIPAL
271
272 Loads a user's acl equivalence group. Takes a principal object or its ID.
273 ACL equivalnce groups are used to simplify the acl system. Each user
274 has one group that only he is a member of. Rights granted to the user
275 are actually granted to that group. This greatly simplifies ACL checks.
276 While this results in a somewhat more complex setup when creating users
277 and granting ACLs, it _greatly_ simplifies acl checks.
278
279 =cut
280
281 sub LoadACLEquivalenceGroup {
282     my $self = shift;
283     my $principal = shift;
284     $principal = $principal->id if ref $principal;
285
286     return $self->LoadByCols(
287         Domain   => 'ACLEquivalence',
288         Type     => 'UserEquiv',
289         Instance => $principal,
290     );
291 }
292
293
294
295
296 =head2 LoadSystemInternalGroup NAME
297
298 Loads a Pseudo group from the database. The only argument is
299 the group's name.
300
301
302 =cut
303
304 sub LoadSystemInternalGroup {
305     my $self       = shift;
306     my $identifier = shift;
307
308     return $self->LoadByCols(
309         Domain => 'SystemInternal',
310         Type   => $identifier,
311     );
312 }
313
314
315
316 =head2 LoadTicketRoleGroup  { Ticket => TICKET_ID, Type => TYPE }
317
318 Loads a ticket group from the database. 
319
320 Takes a param hash with 2 parameters:
321
322     Ticket is the TicketId we're curious about
323     Type is the type of Group we're trying to load: 
324         Requestor, Cc, AdminCc, Owner
325
326 =cut
327
328 sub LoadTicketRoleGroup {
329     my $self       = shift;
330     my %args = (Ticket => '0',
331                 Type => undef,
332                 @_);
333         $self->LoadByCols( Domain => 'RT::Ticket-Role',
334                            Instance =>$args{'Ticket'}, 
335                            Type => $args{'Type'}
336                            );
337 }
338
339
340
341 =head2 LoadQueueRoleGroup  { Queue => Queue_ID, Type => TYPE }
342
343 Loads a Queue group from the database. 
344
345 Takes a param hash with 2 parameters:
346
347     Queue is the QueueId we're curious about
348     Type is the type of Group we're trying to load: 
349         Requestor, Cc, AdminCc, Owner
350
351 =cut
352
353 sub LoadQueueRoleGroup {
354     my $self       = shift;
355     my %args = (Queue => undef,
356                 Type => undef,
357                 @_);
358         $self->LoadByCols( Domain => 'RT::Queue-Role',
359                            Instance =>$args{'Queue'}, 
360                            Type => $args{'Type'}
361                            );
362 }
363
364
365
366 =head2 LoadSystemRoleGroup  Type
367
368 Loads a System group from the database. 
369
370 Takes a single param: Type
371
372     Type is the type of Group we're trying to load: 
373         Requestor, Cc, AdminCc, Owner
374
375 =cut
376
377 sub LoadSystemRoleGroup {
378     my $self       = shift;
379     my $type = shift;
380         $self->LoadByCols( Domain => 'RT::System-Role',
381                            Type => $type
382                            );
383 }
384
385
386
387 =head2 Create
388
389 You need to specify what sort of group you're creating by calling one of the other
390 Create_____ routines.
391
392 =cut
393
394 sub Create {
395     my $self = shift;
396     $RT::Logger->crit("Someone called RT::Group->Create. this method does not exist. someone's being evil");
397     return(0,$self->loc('Permission Denied'));
398 }
399
400
401
402 =head2 _Create
403
404 Takes a paramhash with named arguments: Name, Description.
405
406 Returns a tuple of (Id, Message).  If id is 0, the create failed
407
408 =cut
409
410 sub _Create {
411     my $self = shift;
412     my %args = (
413         Name        => undef,
414         Description => undef,
415         Domain      => undef,
416         Type        => undef,
417         Instance    => '0',
418         InsideTransaction => undef,
419         _RecordTransaction => 1,
420         @_
421     );
422
423     # Enforce uniqueness on user defined group names
424     if ($args{'Domain'} and $args{'Domain'} eq 'UserDefined') {
425         my ($ok, $msg) = $self->_ValidateUserDefinedName($args{'Name'});
426         return ($ok, $msg) if not $ok;
427     }
428
429     $RT::Handle->BeginTransaction() unless ($args{'InsideTransaction'});
430     # Groups deal with principal ids, rather than user ids.
431     # When creating this group, set up a principal Id for it.
432     my $principal    = RT::Principal->new( $self->CurrentUser );
433     my $principal_id = $principal->Create(
434         PrincipalType => 'Group',
435         ObjectId      => '0'
436     );
437     $principal->__Set(Field => 'ObjectId', Value => $principal_id);
438
439     $self->SUPER::Create(
440         id          => $principal_id,
441         Name        => $args{'Name'},
442         Description => $args{'Description'},
443         Type        => $args{'Type'},
444         Domain      => $args{'Domain'},
445         Instance    => ($args{'Instance'} || '0')
446     );
447     my $id = $self->Id;
448     unless ($id) {
449         $RT::Handle->Rollback() unless ($args{'InsideTransaction'});
450         return ( 0, $self->loc('Could not create group') );
451     }
452
453     # If we couldn't create a principal Id, get the fuck out.
454     unless ($principal_id) {
455         $RT::Handle->Rollback() unless ($args{'InsideTransaction'});
456         $RT::Logger->crit( "Couldn't create a Principal on new user create. Strange things are afoot at the circle K" );
457         return ( 0, $self->loc('Could not create group') );
458     }
459
460     # Now we make the group a member of itself as a cached group member
461     # this needs to exist so that group ACL checks don't fall over.
462     # you're checking CachedGroupMembers to see if the principal in question
463     # is a member of the principal the rights have been granted too
464
465     # in the ordinary case, this would fail badly because it would recurse and add all the members of this group as 
466     # cached members. thankfully, we're creating the group now...so it has no members.
467     my $cgm = RT::CachedGroupMember->new($self->CurrentUser);
468     $cgm->Create(Group =>$self->PrincipalObj, Member => $self->PrincipalObj, ImmediateParent => $self->PrincipalObj);
469
470
471     if ( $args{'_RecordTransaction'} ) {
472         $self->_NewTransaction( Type => "Create" );
473     }
474
475     $RT::Handle->Commit() unless ($args{'InsideTransaction'});
476
477     return ( $id, $self->loc("Group created") );
478 }
479
480
481
482 =head2 CreateUserDefinedGroup { Name => "name", Description => "Description"}
483
484 A helper subroutine which creates a system group 
485
486 Returns a tuple of (Id, Message).  If id is 0, the create failed
487
488 =cut
489
490 sub CreateUserDefinedGroup {
491     my $self = shift;
492
493     unless ( $self->CurrentUserHasRight('AdminGroup') ) {
494         $RT::Logger->warning( $self->CurrentUser->Name
495               . " Tried to create a group without permission." );
496         return ( 0, $self->loc('Permission Denied') );
497     }
498
499     return($self->_Create( Domain => 'UserDefined', Type => '', Instance => '', @_));
500 }
501
502 =head2 ValidateName VALUE
503
504 Enforces unique user defined group names when updating
505
506 =cut
507
508 sub ValidateName {
509     my ($self, $value) = @_;
510
511     if ($self->Domain and $self->Domain eq 'UserDefined') {
512         my ($ok, $msg) = $self->_ValidateUserDefinedName($value);
513         # It's really too bad we can't pass along the actual error
514         return 0 if not $ok;
515     }
516     return $self->SUPER::ValidateName($value);
517 }
518
519 =head2 _ValidateUserDefinedName VALUE
520
521 Returns true if the user defined group name isn't in use, false otherwise.
522
523 =cut
524
525 sub _ValidateUserDefinedName {
526     my ($self, $value) = @_;
527
528     return (0, 'Name is required') unless length $value;
529
530     my $dupcheck = RT::Group->new(RT->SystemUser);
531     $dupcheck->LoadUserDefinedGroup($value);
532     if ( $dupcheck->id && ( !$self->id || $self->id != $dupcheck->id ) ) {
533         return ( 0, $self->loc( "Group name '[_1]' is already in use", $value ) );
534     }
535     return 1;
536 }
537
538 =head2 _CreateACLEquivalenceGroup { Principal }
539
540 A helper subroutine which creates a group containing only 
541 an individual user. This gets used by the ACL system to check rights.
542 Yes, it denormalizes the data, but that's ok, as we totally win on performance.
543
544 Returns a tuple of (Id, Message).  If id is 0, the create failed
545
546 =cut
547
548 sub _CreateACLEquivalenceGroup { 
549     my $self = shift;
550     my $princ = shift;
551  
552       my $id = $self->_Create( Domain => 'ACLEquivalence', 
553                            Type => 'UserEquiv',
554                            Name => 'User '. $princ->Object->Id,
555                            Description => 'ACL equiv. for user '.$princ->Object->Id,
556                            Instance => $princ->Id,
557                            InsideTransaction => 1,
558                            _RecordTransaction => 0 );
559       unless ($id) {
560         $RT::Logger->crit("Couldn't create ACL equivalence group");
561         return undef;
562       }
563     
564        # We use stashuser so we don't get transactions inside transactions
565        # and so we bypass all sorts of cruft we don't need
566        my $aclstash = RT::GroupMember->new($self->CurrentUser);
567        my ($stash_id, $add_msg) = $aclstash->_StashUser(Group => $self->PrincipalObj,
568                                              Member => $princ);
569
570       unless ($stash_id) {
571         $RT::Logger->crit("Couldn't add the user to his own acl equivalence group:".$add_msg);
572         # We call super delete so we don't get acl checked.
573         $self->SUPER::Delete();
574         return(undef);
575       }
576     return ($id);
577 }
578
579
580
581
582 =head2 CreateRoleGroup { Domain => DOMAIN, Type =>  TYPE, Instance => ID }
583
584 A helper subroutine which creates a  ticket group. (What RT 2.0 called Ticket watchers)
585 Type is one of ( "Requestor" || "Cc" || "AdminCc" || "Owner") 
586 Domain is one of (RT::Ticket-Role || RT::Queue-Role || RT::System-Role)
587 Instance is the id of the ticket or queue in question
588
589 This routine expects to be called from {Ticket||Queue}->CreateTicketGroups _inside of a transaction_
590
591 Returns a tuple of (Id, Message).  If id is 0, the create failed
592
593 =cut
594
595 sub CreateRoleGroup {
596     my $self = shift;
597     my %args = ( Instance => undef,
598                  Type     => undef,
599                  Domain   => undef,
600                  @_ );
601
602     unless (RT::Queue->IsRoleGroupType($args{Type})) {
603         return ( 0, $self->loc("Invalid Group Type") );
604     }
605
606
607     return ( $self->_Create( Domain            => $args{'Domain'},
608                              Instance          => $args{'Instance'},
609                              Type              => $args{'Type'},
610                              InsideTransaction => 1 ) );
611 }
612
613
614
615 =head2 Delete
616
617 Delete this object
618
619 =cut
620
621 sub Delete {
622     my $self = shift;
623
624     unless ( $self->CurrentUserHasRight('AdminGroup') ) {
625         return ( 0, 'Permission Denied' );
626     }
627
628     $RT::Logger->crit("Deleting groups violates referential integrity until we go through and fix this");
629     # TODO XXX 
630    
631     # Remove the principal object
632     # Remove this group from anything it's a member of.
633     # Remove all cached members of this group
634     # Remove any rights granted to this group
635     # remove any rights delegated by way of this group
636
637     return ( $self->SUPER::Delete(@_) );
638 }
639
640
641 =head2 SetDisabled BOOL
642
643 If passed a positive value, this group will be disabled. No rights it commutes or grants will be honored.
644 It will not appear in most group listings.
645
646 This routine finds all the cached group members that are members of this group  (recursively) and disables them.
647
648 =cut 
649
650  # }}}
651
652  sub SetDisabled {
653      my $self = shift;
654      my $val = shift;
655      unless ( $self->CurrentUserHasRight('AdminGroup') ) {
656         return (0, $self->loc('Permission Denied'));
657     }
658     $RT::Handle->BeginTransaction();
659     $self->PrincipalObj->SetDisabled($val);
660
661
662
663
664     # Find all occurrences of this member as a member of this group
665     # in the cache and nuke them, recursively.
666
667     # The following code will delete all Cached Group members
668     # where this member's group is _not_ the primary group 
669     # (Ie if we're deleting C as a member of B, and B happens to be 
670     # a member of A, will delete C as a member of A without touching
671     # C as a member of B
672
673     my $cached_submembers = RT::CachedGroupMembers->new( $self->CurrentUser );
674
675     $cached_submembers->Limit( FIELD    => 'ImmediateParentId', OPERATOR => '=', VALUE    => $self->Id);
676
677     #Clear the key cache. TODO someday we may want to just clear a little bit of the keycache space. 
678     # TODO what about the groups key cache?
679     RT::Principal->InvalidateACLCache();
680
681
682
683     while ( my $item = $cached_submembers->Next() ) {
684         my $del_err = $item->SetDisabled($val);
685         unless ($del_err) {
686             $RT::Handle->Rollback();
687             $RT::Logger->warning("Couldn't disable cached group submember ".$item->Id);
688             return (undef);
689         }
690     }
691
692     $self->_NewTransaction( Type => ($val == 1) ? "Disabled" : "Enabled" );
693
694     $RT::Handle->Commit();
695     if ( $val == 1 ) {
696         return (1, $self->loc("Group disabled"));
697     } else {
698         return (1, $self->loc("Group enabled"));
699     }
700
701 }
702
703
704
705
706 sub Disabled {
707     my $self = shift;
708     $self->PrincipalObj->Disabled(@_);
709 }
710
711
712
713 =head2 DeepMembersObj
714
715 Returns an RT::CachedGroupMembers object of this group's members,
716 including all members of subgroups.
717
718 =cut
719
720 sub DeepMembersObj {
721     my $self = shift;
722     my $members_obj = RT::CachedGroupMembers->new( $self->CurrentUser );
723
724     #If we don't have rights, don't include any results
725     # TODO XXX  WHY IS THERE NO ACL CHECK HERE?
726     $members_obj->LimitToMembersOfGroup( $self->PrincipalId );
727
728     return ( $members_obj );
729
730 }
731
732
733
734 =head2 MembersObj
735
736 Returns an RT::GroupMembers object of this group's direct members.
737
738 =cut
739
740 sub MembersObj {
741     my $self = shift;
742     my $members_obj = RT::GroupMembers->new( $self->CurrentUser );
743
744     #If we don't have rights, don't include any results
745     # TODO XXX  WHY IS THERE NO ACL CHECK HERE?
746     $members_obj->LimitToMembersOfGroup( $self->PrincipalId );
747
748     return ( $members_obj );
749
750 }
751
752
753
754 =head2 GroupMembersObj [Recursively => 1]
755
756 Returns an L<RT::Groups> object of this group's members.
757 By default returns groups including all subgroups, but
758 could be changed with C<Recursively> named argument.
759
760 B<Note> that groups are not filtered by type and result
761 may contain as well system groups and others.
762
763 =cut
764
765 sub GroupMembersObj {
766     my $self = shift;
767     my %args = ( Recursively => 1, @_ );
768
769     my $groups = RT::Groups->new( $self->CurrentUser );
770     my $members_table = $args{'Recursively'}?
771         'CachedGroupMembers': 'GroupMembers';
772
773     my $members_alias = $groups->NewAlias( $members_table );
774     $groups->Join(
775         ALIAS1 => $members_alias,           FIELD1 => 'MemberId',
776         ALIAS2 => $groups->PrincipalsAlias, FIELD2 => 'id',
777     );
778     $groups->Limit(
779         ALIAS    => $members_alias,
780         FIELD    => 'GroupId',
781         VALUE    => $self->PrincipalId,
782     );
783     $groups->Limit(
784         ALIAS => $members_alias,
785         FIELD => 'Disabled',
786         VALUE => 0,
787     ) if $args{'Recursively'};
788
789     return $groups;
790 }
791
792
793
794 =head2 UserMembersObj
795
796 Returns an L<RT::Users> object of this group's members, by default
797 returns users including all members of subgroups, but could be
798 changed with C<Recursively> named argument.
799
800 =cut
801
802 sub UserMembersObj {
803     my $self = shift;
804     my %args = ( Recursively => 1, @_ );
805
806     #If we don't have rights, don't include any results
807     # TODO XXX  WHY IS THERE NO ACL CHECK HERE?
808
809     my $members_table = $args{'Recursively'}?
810         'CachedGroupMembers': 'GroupMembers';
811
812     my $users = RT::Users->new($self->CurrentUser);
813     my $members_alias = $users->NewAlias( $members_table );
814     $users->Join(
815         ALIAS1 => $members_alias,           FIELD1 => 'MemberId',
816         ALIAS2 => $users->PrincipalsAlias, FIELD2 => 'id',
817     );
818     $users->Limit(
819         ALIAS => $members_alias,
820         FIELD => 'GroupId',
821         VALUE => $self->PrincipalId,
822     );
823     $users->Limit(
824         ALIAS => $members_alias,
825         FIELD => 'Disabled',
826         VALUE => 0,
827     ) if $args{'Recursively'};
828
829     return ( $users);
830 }
831
832
833
834 =head2 MemberEmailAddresses
835
836 Returns an array of the email addresses of all of this group's members
837
838
839 =cut
840
841 sub MemberEmailAddresses {
842     my $self = shift;
843     return sort grep defined && length,
844         map $_->EmailAddress,
845         @{ $self->UserMembersObj->ItemsArrayRef };
846 }
847
848
849
850 =head2 MemberEmailAddressesAsString
851
852 Returns a comma delimited string of the email addresses of all users 
853 who are members of this group.
854
855 =cut
856
857
858 sub MemberEmailAddressesAsString {
859     my $self = shift;
860     return (join(', ', $self->MemberEmailAddresses));
861 }
862
863
864
865 =head2 AddMember PRINCIPAL_ID
866
867 AddMember adds a principal to this group.  It takes a single principal id.
868 Returns a two value array. the first value is true on successful 
869 addition or 0 on failure.  The second value is a textual status msg.
870
871 =cut
872
873 sub AddMember {
874     my $self       = shift;
875     my $new_member = shift;
876
877
878
879     # We should only allow membership changes if the user has the right 
880     # to modify group membership or the user is the principal in question
881     # and the user has the right to modify his own membership
882     unless ( ($new_member == $self->CurrentUser->PrincipalId &&
883               $self->CurrentUserHasRight('ModifyOwnMembership') ) ||
884               $self->CurrentUserHasRight('AdminGroupMembership') ) {
885         #User has no permission to be doing this
886         return ( 0, $self->loc("Permission Denied") );
887     }
888
889     $self->_AddMember(PrincipalId => $new_member);
890 }
891
892 # A helper subroutine for AddMember that bypasses the ACL checks
893 # this should _ONLY_ ever be called from Ticket/Queue AddWatcher
894 # when we want to deal with groups according to queue rights
895 # In the dim future, this will all get factored out and life
896 # will get better       
897
898 # takes a paramhash of { PrincipalId => undef, InsideTransaction }
899
900 sub _AddMember {
901     my $self = shift;
902     my %args = ( PrincipalId => undef,
903                  InsideTransaction => undef,
904                  @_);
905     my $new_member = $args{'PrincipalId'};
906
907     unless ($self->Id) {
908         $RT::Logger->crit("Attempting to add a member to a group which wasn't loaded. 'oops'");
909         return(0, $self->loc("Group not found"));
910     }
911
912     unless ($new_member =~ /^\d+$/) {
913         $RT::Logger->crit("_AddMember called with a parameter that's not an integer.");
914     }
915
916
917     my $new_member_obj = RT::Principal->new( $self->CurrentUser );
918     $new_member_obj->Load($new_member);
919
920
921     unless ( $new_member_obj->Id ) {
922         $RT::Logger->debug("Couldn't find that principal");
923         return ( 0, $self->loc("Couldn't find that principal") );
924     }
925
926     if ( $self->HasMember( $new_member_obj ) ) {
927
928         #User is already a member of this group. no need to add it
929         return ( 0, $self->loc("Group already has member: [_1]", $new_member_obj->Object->Name) );
930     }
931     if ( $new_member_obj->IsGroup &&
932          $new_member_obj->Object->HasMemberRecursively($self->PrincipalObj) ) {
933
934         #This group can't be made to be a member of itself
935         return ( 0, $self->loc("Groups can't be members of their members"));
936     }
937
938
939     my $member_object = RT::GroupMember->new( $self->CurrentUser );
940     my $id = $member_object->Create(
941         Member => $new_member_obj,
942         Group => $self->PrincipalObj,
943         InsideTransaction => $args{'InsideTransaction'}
944     );
945     if ($id) {
946         return ( 1, $self->loc("Member added: [_1]", $new_member_obj->Object->Name) );
947     }
948     else {
949         return(0, $self->loc("Couldn't add member to group"));
950     }
951 }
952
953
954 =head2 HasMember RT::Principal|id
955
956 Takes an L<RT::Principal> object or its id returns a GroupMember Id if that user is a 
957 member of this group.
958 Returns undef if the user isn't a member of the group or if the current
959 user doesn't have permission to find out. Arguably, it should differentiate
960 between ACL failure and non membership.
961
962 =cut
963
964 sub HasMember {
965     my $self    = shift;
966     my $principal = shift;
967
968     my $id;
969     if ( UNIVERSAL::isa($principal,'RT::Principal') ) {
970         $id = $principal->id;
971     } elsif ( $principal =~ /^\d+$/ ) {
972         $id = $principal;
973     } else {
974         $RT::Logger->error("Group::HasMember was called with an argument that".
975                           " isn't an RT::Principal or id. It's ".($principal||'(undefined)'));
976         return(undef);
977     }
978     return undef unless $id;
979
980     my $member_obj = RT::GroupMember->new( $self->CurrentUser );
981     $member_obj->LoadByCols(
982         MemberId => $id, 
983         GroupId  => $self->PrincipalId
984     );
985
986     if ( my $member_id = $member_obj->id ) {
987         return $member_id;
988     }
989     else {
990         return (undef);
991     }
992 }
993
994
995
996 =head2 HasMemberRecursively RT::Principal|id
997
998 Takes an L<RT::Principal> object or its id and returns true if that user is a member of 
999 this group.
1000 Returns undef if the user isn't a member of the group or if the current
1001 user doesn't have permission to find out. Arguably, it should differentiate
1002 between ACL failure and non membership.
1003
1004 =cut
1005
1006 sub HasMemberRecursively {
1007     my $self    = shift;
1008     my $principal = shift;
1009
1010     my $id;
1011     if ( UNIVERSAL::isa($principal,'RT::Principal') ) {
1012         $id = $principal->id;
1013     } elsif ( $principal =~ /^\d+$/ ) {
1014         $id = $principal;
1015     } else {
1016         $RT::Logger->error("Group::HasMemberRecursively was called with an argument that".
1017                           " isn't an RT::Principal or id. It's $principal");
1018         return(undef);
1019     }
1020     return undef unless $id;
1021
1022     my $member_obj = RT::CachedGroupMember->new( $self->CurrentUser );
1023     $member_obj->LoadByCols(
1024         MemberId => $id, 
1025         GroupId  => $self->PrincipalId
1026     );
1027
1028     if ( my $member_id = $member_obj->id ) {
1029         return $member_id;
1030     }
1031     else {
1032         return (undef);
1033     }
1034 }
1035
1036
1037
1038 =head2 DeleteMember PRINCIPAL_ID
1039
1040 Takes the principal id of a current user or group.
1041 If the current user has apropriate rights,
1042 removes that GroupMember from this group.
1043 Returns a two value array. the first value is true on successful 
1044 addition or 0 on failure.  The second value is a textual status msg.
1045
1046 =cut
1047
1048 sub DeleteMember {
1049     my $self   = shift;
1050     my $member_id = shift;
1051
1052
1053     # We should only allow membership changes if the user has the right 
1054     # to modify group membership or the user is the principal in question
1055     # and the user has the right to modify his own membership
1056
1057     unless ( (($member_id == $self->CurrentUser->PrincipalId) &&
1058               $self->CurrentUserHasRight('ModifyOwnMembership') ) ||
1059               $self->CurrentUserHasRight('AdminGroupMembership') ) {
1060         #User has no permission to be doing this
1061         return ( 0, $self->loc("Permission Denied") );
1062     }
1063     $self->_DeleteMember($member_id);
1064 }
1065
1066 # A helper subroutine for DeleteMember that bypasses the ACL checks
1067 # this should _ONLY_ ever be called from Ticket/Queue  DeleteWatcher
1068 # when we want to deal with groups according to queue rights
1069 # In the dim future, this will all get factored out and life
1070 # will get better       
1071
1072 sub _DeleteMember {
1073     my $self = shift;
1074     my $member_id = shift;
1075
1076     my $member_obj =  RT::GroupMember->new( $self->CurrentUser );
1077     
1078     $member_obj->LoadByCols( MemberId  => $member_id,
1079                              GroupId => $self->PrincipalId);
1080
1081
1082     #If we couldn't load it, return undef.
1083     unless ( $member_obj->Id() ) {
1084         $RT::Logger->debug("Group has no member with that id");
1085         return ( 0,$self->loc( "Group has no such member" ));
1086     }
1087
1088     #Now that we've checked ACLs and sanity, delete the groupmember
1089     my $val = $member_obj->Delete();
1090
1091     if ($val) {
1092         return ( $val, $self->loc("Member deleted") );
1093     }
1094     else {
1095         $RT::Logger->debug("Failed to delete group ".$self->Id." member ". $member_id);
1096         return ( 0, $self->loc("Member not deleted" ));
1097     }
1098 }
1099
1100
1101
1102 sub _Set {
1103     my $self = shift;
1104     my %args = (
1105         Field => undef,
1106         Value => undef,
1107         TransactionType   => 'Set',
1108         RecordTransaction => 1,
1109         @_
1110     );
1111
1112     unless ( $self->CurrentUserHasRight('AdminGroup') ) {
1113         return ( 0, $self->loc('Permission Denied') );
1114         }
1115
1116     my $Old = $self->SUPER::_Value("$args{'Field'}");
1117     
1118     my ($ret, $msg) = $self->SUPER::_Set( Field => $args{'Field'},
1119                                           Value => $args{'Value'} );
1120     
1121     #If we can't actually set the field to the value, don't record
1122     # a transaction. instead, get out of here.
1123     if ( $ret == 0 ) { return ( 0, $msg ); }
1124
1125     if ( $args{'RecordTransaction'} == 1 ) {
1126
1127         my ( $Trans, $Msg, $TransObj ) = $self->_NewTransaction(
1128                                                Type => $args{'TransactionType'},
1129                                                Field     => $args{'Field'},
1130                                                NewValue  => $args{'Value'},
1131                                                OldValue  => $Old,
1132                                                TimeTaken => $args{'TimeTaken'},
1133         );
1134         return ( $Trans, scalar $TransObj->Description );
1135     }
1136     else {
1137         return ( $ret, $msg );
1138     }
1139 }
1140
1141
1142
1143
1144
1145 =head2 CurrentUserHasRight RIGHTNAME
1146
1147 Returns true if the current user has the specified right for this group.
1148
1149
1150     TODO: we don't deal with membership visibility yet
1151
1152 =cut
1153
1154
1155 sub CurrentUserHasRight {
1156     my $self = shift;
1157     my $right = shift;
1158
1159
1160
1161     if ($self->Id && 
1162                 $self->CurrentUser->HasRight( Object => $self,
1163                                                                                    Right => $right )) {
1164         return(1);
1165    }
1166     elsif ( $self->CurrentUser->HasRight(Object => $RT::System, Right =>  $right )) {
1167                 return (1);
1168     } else {
1169         return(undef);
1170     }
1171
1172 }
1173
1174
1175 =head2 CurrentUserCanSee
1176
1177 Always returns 1; unfortunately, for historical reasons, users have
1178 always been able to examine groups they have indirect access to, even if
1179 they do not have SeeGroup explicitly.
1180
1181 =cut
1182
1183 sub CurrentUserCanSee {
1184     my $self = shift;
1185     return 1;
1186 }
1187
1188
1189 =head2 PrincipalObj
1190
1191 Returns the principal object for this user. returns an empty RT::Principal
1192 if there's no principal object matching this user. 
1193 The response is cached. PrincipalObj should never ever change.
1194
1195
1196 =cut
1197
1198
1199 sub PrincipalObj {
1200     my $self = shift;
1201     unless ( defined $self->{'PrincipalObj'} &&
1202              defined $self->{'PrincipalObj'}->ObjectId &&
1203             ($self->{'PrincipalObj'}->ObjectId == $self->Id) &&
1204             (defined $self->{'PrincipalObj'}->PrincipalType && 
1205                 $self->{'PrincipalObj'}->PrincipalType eq 'Group')) {
1206
1207             $self->{'PrincipalObj'} = RT::Principal->new($self->CurrentUser);
1208             $self->{'PrincipalObj'}->LoadByCols('ObjectId' => $self->Id,
1209                                                 'PrincipalType' => 'Group') ;
1210             }
1211     return($self->{'PrincipalObj'});
1212 }
1213
1214
1215 =head2 PrincipalId  
1216
1217 Returns this user's PrincipalId
1218
1219 =cut
1220
1221 sub PrincipalId {
1222     my $self = shift;
1223     return $self->Id;
1224 }
1225
1226
1227 sub BasicColumns {
1228     (
1229         [ Name => 'Name' ],
1230         [ Description => 'Description' ],
1231     );
1232 }
1233
1234
1235 =head1 AUTHOR
1236
1237 Jesse Vincent, jesse@bestpractical.com
1238
1239 =head1 SEE ALSO
1240
1241 RT
1242
1243 =cut
1244
1245
1246
1247
1248
1249 =head2 id
1250
1251 Returns the current value of id.
1252 (In the database, id is stored as int(11).)
1253
1254
1255 =cut
1256
1257
1258 =head2 Name
1259
1260 Returns the current value of Name.
1261 (In the database, Name is stored as varchar(200).)
1262
1263
1264
1265 =head2 SetName VALUE
1266
1267
1268 Set Name to VALUE.
1269 Returns (1, 'Status message') on success and (0, 'Error Message') on failure.
1270 (In the database, Name will be stored as a varchar(200).)
1271
1272
1273 =cut
1274
1275
1276 =head2 Description
1277
1278 Returns the current value of Description.
1279 (In the database, Description is stored as varchar(255).)
1280
1281
1282
1283 =head2 SetDescription VALUE
1284
1285
1286 Set Description to VALUE.
1287 Returns (1, 'Status message') on success and (0, 'Error Message') on failure.
1288 (In the database, Description will be stored as a varchar(255).)
1289
1290
1291 =cut
1292
1293
1294 =head2 Domain
1295
1296 Returns the current value of Domain.
1297 (In the database, Domain is stored as varchar(64).)
1298
1299
1300
1301 =head2 SetDomain VALUE
1302
1303
1304 Set Domain to VALUE.
1305 Returns (1, 'Status message') on success and (0, 'Error Message') on failure.
1306 (In the database, Domain will be stored as a varchar(64).)
1307
1308
1309 =cut
1310
1311
1312 =head2 Type
1313
1314 Returns the current value of Type.
1315 (In the database, Type is stored as varchar(64).)
1316
1317
1318
1319 =head2 SetType VALUE
1320
1321
1322 Set Type to VALUE.
1323 Returns (1, 'Status message') on success and (0, 'Error Message') on failure.
1324 (In the database, Type will be stored as a varchar(64).)
1325
1326
1327 =cut
1328
1329
1330 =head2 Instance
1331
1332 Returns the current value of Instance.
1333 (In the database, Instance is stored as int(11).)
1334
1335
1336
1337 =head2 SetInstance VALUE
1338
1339
1340 Set Instance to VALUE.
1341 Returns (1, 'Status message') on success and (0, 'Error Message') on failure.
1342 (In the database, Instance will be stored as a int(11).)
1343
1344
1345 =cut
1346
1347
1348 =head2 Creator
1349
1350 Returns the current value of Creator.
1351 (In the database, Creator is stored as int(11).)
1352
1353
1354 =cut
1355
1356
1357 =head2 Created
1358
1359 Returns the current value of Created.
1360 (In the database, Created is stored as datetime.)
1361
1362
1363 =cut
1364
1365
1366 =head2 LastUpdatedBy
1367
1368 Returns the current value of LastUpdatedBy.
1369 (In the database, LastUpdatedBy is stored as int(11).)
1370
1371
1372 =cut
1373
1374
1375 =head2 LastUpdated
1376
1377 Returns the current value of LastUpdated.
1378 (In the database, LastUpdated is stored as datetime.)
1379
1380
1381 =cut
1382
1383
1384
1385 sub _CoreAccessible {
1386     {
1387
1388         id =>
1389                 {read => 1, sql_type => 4, length => 11,  is_blob => 0,  is_numeric => 1,  type => 'int(11)', default => ''},
1390         Name =>
1391                 {read => 1, write => 1, sql_type => 12, length => 200,  is_blob => 0,  is_numeric => 0,  type => 'varchar(200)', default => ''},
1392         Description =>
1393                 {read => 1, write => 1, sql_type => 12, length => 255,  is_blob => 0,  is_numeric => 0,  type => 'varchar(255)', default => ''},
1394         Domain =>
1395                 {read => 1, write => 1, sql_type => 12, length => 64,  is_blob => 0,  is_numeric => 0,  type => 'varchar(64)', default => ''},
1396         Type =>
1397                 {read => 1, write => 1, sql_type => 12, length => 64,  is_blob => 0,  is_numeric => 0,  type => 'varchar(64)', default => ''},
1398         Instance =>
1399                 {read => 1, write => 1, sql_type => 4, length => 11,  is_blob => 0,  is_numeric => 1,  type => 'int(11)', default => ''},
1400         Creator =>
1401                 {read => 1, auto => 1, sql_type => 4, length => 11,  is_blob => 0,  is_numeric => 1,  type => 'int(11)', default => '0'},
1402         Created =>
1403                 {read => 1, auto => 1, sql_type => 11, length => 0,  is_blob => 0,  is_numeric => 0,  type => 'datetime', default => ''},
1404         LastUpdatedBy =>
1405                 {read => 1, auto => 1, sql_type => 4, length => 11,  is_blob => 0,  is_numeric => 1,  type => 'int(11)', default => '0'},
1406         LastUpdated =>
1407                 {read => 1, auto => 1, sql_type => 11, length => 0,  is_blob => 0,  is_numeric => 0,  type => 'datetime', default => ''},
1408
1409  }
1410 };
1411
1412 RT::Base->_ImportOverlays();
1413
1414 1;