Master to 4.2.8

[usit-rt.git] / docs / initialdata.pod

diff --git a/docs/initialdata.pod b/docs/initialdata.pod
index 0ed73f477184937d6a26d2d1ec5b6be3849e3be7..ac55dcf170c9319aa826d4fc65e34591d719ad35 100644 (file)
--- a/docs/initialdata.pod
+++ b/docs/initialdata.pod
@@ -80,55 +80,19 @@ For a full list of fields, read the documentation for L<RT::User/Create>.
     push @Groups, {
         Name        => 'Example Employees',
         Description => 'All of the employees of my company',
+        Members     => { Users =>  [ qw/ alexmv trs falcone / ],
+                         Groups => [ qw/ extras / ] },
     };
 
 Creates a new L<RT::Group> for each hashref.  In almost all cases you'll want
 to follow the example above to create a group just as if you had done it from
 the admin interface.
 
-Additionally, the C<MemberOf> field is specially handled to make it easier to
-add the new group to other groups.  C<MemberOf> may be a single value or an
-array ref.  Each value should be a user-defined group name or hashref to pass
-into L<RT::Group/LoadByCols>.  Each group found will have the new group
-added as a member.
-
-Unfortunately you can't specify the I<members> of a group at this time.  As a
-workaround, you can push a subref into C<@Final> which adds members to your new
-groups.  An example, using a convenience function to avoid repeating yourself:
-
-    push @Final, sub {
-        add_members('My New Group Name' => qw(trs alex ruslan));
-        add_members('My Second Group'   => qw(jesse kevin sunnavy jim));
-    };
-
-    sub add_members {
-        my $group_name = shift;
-        my @members    = @_;
-
-        my $group = RT::Group->new( RT->SystemUser );
-        $group->LoadUserDefinedGroup($group_name);
-
-        if ($group->id) {
-            for my $name (@members) {
-                my $member = RT::User->new( RT->SystemUser );
-                $member->LoadByCols( Name => $name );
-
-                unless ($member->Id) {
-                    RT->Logger->error("Unable to find user '$name'");
-                    next;
-                }
-
-                my ($ok, $msg) = $group->AddMember( $member->PrincipalObj->Id );
-                if ($ok) {
-                    RT->Logger->info("Added member $name to $group_name");
-                } else {
-                    RT->Logger->error("Unable to AddMember $name to $group_name: $msg");
-                }
-            }
-        } else {
-            RT->Logger->error("Unable to find group '$group_name'!");
-        }
-    }
+In addition to the C<Members> option shown above, which can take both
+users and groups, the C<MemberOf> field may be a single value or an
+array ref.  Each value should be a user-defined group name or hashref to
+pass into L<RT::Group/LoadByCols>.  Each group found will have the new
+group added as a member.
 
 =head2 C<@Queues>
 
@@ -315,6 +279,14 @@ granted.  This is B<different> than the user/group/role receiving the right.
     CF      => 'Name',
     Queue   => 'Name',
 
+=item Granted on a custom field applied to some other object
+
+    # This finds the CF named "Name" applied to Articles in the
+    # "Responses" class
+    CF         => 'Name',
+    LookupType => RT::Article->CustomFieldLookupType,
+    ObjectId   => 'Responses',
+
 =item Granted on some other object (article Classes, etc)
 
     ObjectType => 'RT::Class',
@@ -455,8 +427,33 @@ L<RT::Template/Create> for the fields you can use.
 
 An array of L<RT::Attribute>s to create.  You likely don't need to mess with
 this.  If you do, know that the key C<Object> is expected to be an
-L<RT::Record> object on which to call C<AddAttribute>.  If you don't provide
-C<Object> or it's undefined, C<< RT->System >> will be used.
+L<RT::Record> object or a subroutine reference that returns an object on which
+to call C<AddAttribute>.  If you don't provide C<Object> or it's undefined,
+C<< RT->System >> will be used.
+
+Here is an example of using a subroutine reference as a value for Object:
+
+    @Attributes = ({
+        Name        => 'SavedSearch',
+        Description => 'New Tickets in SomeQueue',
+        Object      => sub {
+            my $GroupName = 'SomeQueue Group';
+            my $group     = RT::Group->new( RT->SystemUser );
+    
+            my( $ret, $msg ) = $group->LoadUserDefinedGroup( $GroupName );
+            die $msg unless $ret;
+    
+            return $group;
+        },
+        Content     => {
+            Format =>  <<'        END_OF_FORMAT',
+    ....
+            END_OF_FORMAT
+            Query   => "Status = 'new' AND Queue = 'SomeQueue'",
+            OrderBy => 'id',
+            Order   => 'DESC'
+        },
+    });
 
 =head2 C<@Initial>