rt4-doc-html 4.0.19-1 / usr / share / doc / rt4-doc-html / RT / Group.html

<ul id="index">
  <li><a href="#NAME">NAME</a></li>
  <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="#METHODS">METHODS</a>
    <ul>
      <li><a href="#AddRights-RIGHT-DESCRIPTION">AddRights RIGHT, DESCRIPTION [, ...]</a></li>
      <li><a href="#AvailableRights">AvailableRights</a></li>
      <li><a href="#RightCategories">RightCategories</a></li>
      <li><a href="#AddRightCategories-RIGHT-CATEGORY">AddRightCategories RIGHT, CATEGORY [, ...]</a></li>
      <li><a href="#SelfDescription">SelfDescription</a></li>
      <li><a href="#Load-ID">Load ID</a></li>
      <li><a href="#LoadUserDefinedGroup-NAME">LoadUserDefinedGroup NAME</a></li>
      <li><a href="#LoadACLEquivalenceGroup-PRINCIPAL">LoadACLEquivalenceGroup PRINCIPAL</a></li>
      <li><a href="#LoadSystemInternalGroup-NAME">LoadSystemInternalGroup NAME</a></li>
      <li><a href="#LoadTicketRoleGroup-Ticket-TICKET_ID-Type-TYPE">LoadTicketRoleGroup { Ticket =&gt; TICKET_ID, Type =&gt; TYPE }</a></li>
      <li><a href="#LoadQueueRoleGroup-Queue-Queue_ID-Type-TYPE">LoadQueueRoleGroup { Queue =&gt; Queue_ID, Type =&gt; TYPE }</a></li>
      <li><a href="#LoadSystemRoleGroup-Type">LoadSystemRoleGroup Type</a></li>
      <li><a href="#Create">Create</a></li>
      <li><a href="#Create1">_Create</a></li>
      <li><a href="#CreateUserDefinedGroup-Name-name-Description-Description">CreateUserDefinedGroup { Name =&gt; &quot;name&quot;, Description =&gt; &quot;Description&quot;}</a></li>
      <li><a href="#ValidateName-VALUE">ValidateName VALUE</a></li>
      <li><a href="#ValidateUserDefinedName-VALUE">_ValidateUserDefinedName VALUE</a></li>
      <li><a href="#CreateACLEquivalenceGroup-Principal">_CreateACLEquivalenceGroup { Principal }</a></li>
      <li><a href="#CreateRoleGroup-Domain-DOMAIN-Type-TYPE-Instance-ID">CreateRoleGroup { Domain =&gt; DOMAIN, Type =&gt; TYPE, Instance =&gt; ID }</a></li>
      <li><a href="#Delete">Delete</a></li>
      <li><a href="#SetDisabled-BOOL">SetDisabled BOOL</a></li>
      <li><a href="#DeepMembersObj">DeepMembersObj</a></li>
      <li><a href="#MembersObj">MembersObj</a></li>
      <li><a href="#GroupMembersObj-Recursively-1">GroupMembersObj [Recursively =&gt; 1]</a></li>
      <li><a href="#UserMembersObj">UserMembersObj</a></li>
      <li><a href="#MemberEmailAddresses">MemberEmailAddresses</a></li>
      <li><a href="#MemberEmailAddressesAsString">MemberEmailAddressesAsString</a></li>
      <li><a href="#AddMember-PRINCIPAL_ID">AddMember PRINCIPAL_ID</a></li>
      <li><a href="#HasMember-RT::Principal-id">HasMember RT::Principal|id</a></li>
      <li><a href="#HasMemberRecursively-RT::Principal-id">HasMemberRecursively RT::Principal|id</a></li>
      <li><a href="#DeleteMember-PRINCIPAL_ID">DeleteMember PRINCIPAL_ID</a></li>
      <li><a href="#CurrentUserHasRight-RIGHTNAME">CurrentUserHasRight RIGHTNAME</a></li>
      <li><a href="#CurrentUserCanSee">CurrentUserCanSee</a></li>
      <li><a href="#PrincipalObj">PrincipalObj</a></li>
      <li><a href="#PrincipalId">PrincipalId</a></li>
    </ul>
  </li>
  <li><a href="#AUTHOR">AUTHOR</a></li>
  <li><a href="#SEE-ALSO">SEE ALSO</a>
    <ul>
      <li><a href="#id">id</a></li>
      <li><a href="#Name">Name</a></li>
      <li><a href="#SetName-VALUE">SetName VALUE</a></li>
      <li><a href="#Description">Description</a></li>
      <li><a href="#SetDescription-VALUE">SetDescription VALUE</a></li>
      <li><a href="#Domain">Domain</a></li>
      <li><a href="#SetDomain-VALUE">SetDomain VALUE</a></li>
      <li><a href="#Type">Type</a></li>
      <li><a href="#SetType-VALUE">SetType VALUE</a></li>
      <li><a href="#Instance">Instance</a></li>
      <li><a href="#SetInstance-VALUE">SetInstance VALUE</a></li>
      <li><a href="#Creator">Creator</a></li>
      <li><a href="#Created">Created</a></li>
      <li><a href="#LastUpdatedBy">LastUpdatedBy</a></li>
      <li><a href="#LastUpdated">LastUpdated</a></li>
    </ul>
  </li>
</ul>

<h1 id="NAME"><a href="#___top">NAME</a></h1>

<pre><code>  RT::Group - RT&#39;s group object</code></pre>

<h1 id="SYNOPSIS"><a href="#___top">SYNOPSIS</a></h1>

<p>use RT::Group; my $group = RT::Group-&gt;new($CurrentUser);</p>

<h1 id="DESCRIPTION"><a href="#___top">DESCRIPTION</a></h1>

<p>An RT group object.</p>

<h1 id="METHODS"><a href="#___top">METHODS</a></h1>

<h2 id="AddRights-RIGHT-DESCRIPTION"><a href="#___top">AddRights <code>RIGHT</code>, <code>DESCRIPTION</code> [, ...]</a></h2>

<p>Adds the given rights to the list of possible rights. This method should be called during server startup, not at runtime.</p>

<h2 id="AvailableRights"><a href="#___top">AvailableRights</a></h2>

<p>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</p>

<h2 id="RightCategories"><a href="#___top">RightCategories</a></h2>

<p>Returns a hashref where the keys are rights for this type of object and the values are the category (General, Staff, Admin) the right falls into.</p>

<h2 id="AddRightCategories-RIGHT-CATEGORY"><a href="#___top">AddRightCategories <code>RIGHT</code>, <code>CATEGORY</code> [, ...]</a></h2>

<p>Adds the given right and category pairs to the list of right categories. This method should be called during server startup, not at runtime.</p>

<h2 id="SelfDescription"><a href="#___top">SelfDescription</a></h2>

<p>Returns a user-readable description of what this group is for and what it&#39;s named.</p>

<h2 id="Load-ID"><a href="#___top">Load ID</a></h2>

<p>Load a group object from the database. Takes a single argument. If the argument is numerical, load by the column &#39;id&#39;. Otherwise, complain and return.</p>

<h2 id="LoadUserDefinedGroup-NAME"><a href="#___top">LoadUserDefinedGroup NAME</a></h2>

<p>Loads a system group from the database. The only argument is the group&#39;s name.</p>

<h2 id="LoadACLEquivalenceGroup-PRINCIPAL"><a href="#___top">LoadACLEquivalenceGroup PRINCIPAL</a></h2>

<p>Loads a user&#39;s acl equivalence group. Takes a principal object or its ID. ACL equivalnce groups are used to simplify the acl system. Each user has one group that only he is a member of. Rights granted to the user are actually granted to that group. This greatly simplifies ACL checks. While this results in a somewhat more complex setup when creating users and granting ACLs, it _greatly_ simplifies acl checks.</p>

<h2 id="LoadSystemInternalGroup-NAME"><a href="#___top">LoadSystemInternalGroup NAME</a></h2>

<p>Loads a Pseudo group from the database. The only argument is the group&#39;s name.</p>

<h2 id="LoadTicketRoleGroup-Ticket-TICKET_ID-Type-TYPE"><a href="#___top">LoadTicketRoleGroup { Ticket =&gt; TICKET_ID, Type =&gt; TYPE }</a></h2>

<p>Loads a ticket group from the database.</p>

<p>Takes a param hash with 2 parameters:</p>

<pre><code>    Ticket is the TicketId we&#39;re curious about
    Type is the type of Group we&#39;re trying to load: 
        Requestor, Cc, AdminCc, Owner</code></pre>

<h2 id="LoadQueueRoleGroup-Queue-Queue_ID-Type-TYPE"><a href="#___top">LoadQueueRoleGroup { Queue =&gt; Queue_ID, Type =&gt; TYPE }</a></h2>

<p>Loads a Queue group from the database.</p>

<p>Takes a param hash with 2 parameters:</p>

<pre><code>    Queue is the QueueId we&#39;re curious about
    Type is the type of Group we&#39;re trying to load: 
        Requestor, Cc, AdminCc, Owner</code></pre>

<h2 id="LoadSystemRoleGroup-Type"><a href="#___top">LoadSystemRoleGroup Type</a></h2>

<p>Loads a System group from the database.</p>

<p>Takes a single param: Type</p>

<pre><code>    Type is the type of Group we&#39;re trying to load: 
        Requestor, Cc, AdminCc, Owner</code></pre>

<h2 id="Create"><a href="#___top">Create</a></h2>

<p>You need to specify what sort of group you&#39;re creating by calling one of the other Create_____ routines.</p>

<h2 id="Create1"><a href="#___top">_Create</a></h2>

<p>Takes a paramhash with named arguments: Name, Description.</p>

<p>Returns a tuple of (Id, Message). If id is 0, the create failed</p>

<h2 id="CreateUserDefinedGroup-Name-name-Description-Description"><a href="#___top">CreateUserDefinedGroup { Name =&gt; &quot;name&quot;, Description =&gt; &quot;Description&quot;}</a></h2>

<p>A helper subroutine which creates a system group</p>

<p>Returns a tuple of (Id, Message). If id is 0, the create failed</p>

<h2 id="ValidateName-VALUE"><a href="#___top">ValidateName VALUE</a></h2>

<p>Enforces unique user defined group names when updating</p>

<h2 id="ValidateUserDefinedName-VALUE"><a href="#___top">_ValidateUserDefinedName VALUE</a></h2>

<p>Returns true if the user defined group name isn&#39;t in use, false otherwise.</p>

<h2 id="CreateACLEquivalenceGroup-Principal"><a href="#___top">_CreateACLEquivalenceGroup { Principal }</a></h2>

<p>A helper subroutine which creates a group containing only an individual user. This gets used by the ACL system to check rights. Yes, it denormalizes the data, but that&#39;s ok, as we totally win on performance.</p>

<p>Returns a tuple of (Id, Message). If id is 0, the create failed</p>

<h2 id="CreateRoleGroup-Domain-DOMAIN-Type-TYPE-Instance-ID"><a href="#___top">CreateRoleGroup { Domain =&gt; DOMAIN, Type =&gt; TYPE, Instance =&gt; ID }</a></h2>

<p>A helper subroutine which creates a ticket group. (What RT 2.0 called Ticket watchers) Type is one of ( &quot;Requestor&quot; || &quot;Cc&quot; || &quot;AdminCc&quot; || &quot;Owner&quot;) Domain is one of (RT::Ticket-Role || RT::Queue-Role || RT::System-Role) Instance is the id of the ticket or queue in question</p>

<p>This routine expects to be called from {Ticket||Queue}-&gt;CreateTicketGroups _inside of a transaction_</p>

<p>Returns a tuple of (Id, Message). If id is 0, the create failed</p>

<h2 id="Delete"><a href="#___top">Delete</a></h2>

<p>Delete this object</p>

<h2 id="SetDisabled-BOOL"><a href="#___top">SetDisabled BOOL</a></h2>

<p>If passed a positive value, this group will be disabled. No rights it commutes or grants will be honored. It will not appear in most group listings.</p>

<p>This routine finds all the cached group members that are members of this group (recursively) and disables them.</p>

<h2 id="DeepMembersObj"><a href="#___top">DeepMembersObj</a></h2>

<p>Returns an RT::CachedGroupMembers object of this group&#39;s members, including all members of subgroups.</p>

<h2 id="MembersObj"><a href="#___top">MembersObj</a></h2>

<p>Returns an RT::GroupMembers object of this group&#39;s direct members.</p>

<h2 id="GroupMembersObj-Recursively-1"><a href="#___top">GroupMembersObj [Recursively =&gt; 1]</a></h2>

<p>Returns an <a href="../../../rt/latest/RT/Groups.html">RT::Groups</a> object of this group&#39;s members. By default returns groups including all subgroups, but could be changed with <code>Recursively</code> named argument.</p>

<p><b>Note</b> that groups are not filtered by type and result may contain as well system groups and others.</p>

<h2 id="UserMembersObj"><a href="#___top">UserMembersObj</a></h2>

<p>Returns an <a href="../../../rt/latest/RT/Users.html">RT::Users</a> object of this group&#39;s members, by default returns users including all members of subgroups, but could be changed with <code>Recursively</code> named argument.</p>

<h2 id="MemberEmailAddresses"><a href="#___top">MemberEmailAddresses</a></h2>

<p>Returns an array of the email addresses of all of this group&#39;s members</p>

<h2 id="MemberEmailAddressesAsString"><a href="#___top">MemberEmailAddressesAsString</a></h2>

<p>Returns a comma delimited string of the email addresses of all users who are members of this group.</p>

<h2 id="AddMember-PRINCIPAL_ID"><a href="#___top">AddMember PRINCIPAL_ID</a></h2>

<p>AddMember adds a principal to this group. It takes a single principal id. Returns a two value array. the first value is true on successful addition or 0 on failure. The second value is a textual status msg.</p>

<h2 id="HasMember-RT::Principal-id"><a href="#___top">HasMember RT::Principal|id</a></h2>

<p>Takes an <a href="../../../rt/latest/RT/Principal.html">RT::Principal</a> object or its id returns a GroupMember Id if that user is a member of this group. Returns undef if the user isn&#39;t a member of the group or if the current user doesn&#39;t have permission to find out. Arguably, it should differentiate between ACL failure and non membership.</p>

<h2 id="HasMemberRecursively-RT::Principal-id"><a href="#___top">HasMemberRecursively RT::Principal|id</a></h2>

<p>Takes an <a href="../../../rt/latest/RT/Principal.html">RT::Principal</a> object or its id and returns true if that user is a member of this group. Returns undef if the user isn&#39;t a member of the group or if the current user doesn&#39;t have permission to find out. Arguably, it should differentiate between ACL failure and non membership.</p>

<h2 id="DeleteMember-PRINCIPAL_ID"><a href="#___top">DeleteMember PRINCIPAL_ID</a></h2>

<p>Takes the principal id of a current user or group. If the current user has apropriate rights, removes that GroupMember from this group. Returns a two value array. the first value is true on successful addition or 0 on failure. The second value is a textual status msg.</p>

<h2 id="CurrentUserHasRight-RIGHTNAME"><a href="#___top">CurrentUserHasRight RIGHTNAME</a></h2>

<p>Returns true if the current user has the specified right for this group.</p>

<pre><code>    TODO: we don&#39;t deal with membership visibility yet</code></pre>

<h2 id="CurrentUserCanSee"><a href="#___top">CurrentUserCanSee</a></h2>

<p>Always returns 1; unfortunately, for historical reasons, users have always been able to examine groups they have indirect access to, even if they do not have SeeGroup explicitly.</p>

<h2 id="PrincipalObj"><a href="#___top">PrincipalObj</a></h2>

<p>Returns the principal object for this user. returns an empty RT::Principal if there&#39;s no principal object matching this user. The response is cached. PrincipalObj should never ever change.</p>

<h2 id="PrincipalId"><a href="#___top">PrincipalId</a></h2>

<p>Returns this user&#39;s PrincipalId</p>

<h1 id="AUTHOR"><a href="#___top">AUTHOR</a></h1>

<p>Jesse Vincent, jesse@bestpractical.com</p>

<h1 id="SEE-ALSO"><a href="#___top">SEE ALSO</a></h1>

<p>RT</p>

<h2 id="id"><a href="#___top">id</a></h2>

<p>Returns the current value of id. (In the database, id is stored as int(11).)</p>

<h2 id="Name"><a href="#___top">Name</a></h2>

<p>Returns the current value of Name. (In the database, Name is stored as varchar(200).)</p>

<h2 id="SetName-VALUE"><a href="#___top">SetName VALUE</a></h2>

<p>Set Name to VALUE. Returns (1, &#39;Status message&#39;) on success and (0, &#39;Error Message&#39;) on failure. (In the database, Name will be stored as a varchar(200).)</p>

<h2 id="Description"><a href="#___top">Description</a></h2>

<p>Returns the current value of Description. (In the database, Description is stored as varchar(255).)</p>

<h2 id="SetDescription-VALUE"><a href="#___top">SetDescription VALUE</a></h2>

<p>Set Description to VALUE. Returns (1, &#39;Status message&#39;) on success and (0, &#39;Error Message&#39;) on failure. (In the database, Description will be stored as a varchar(255).)</p>

<h2 id="Domain"><a href="#___top">Domain</a></h2>

<p>Returns the current value of Domain. (In the database, Domain is stored as varchar(64).)</p>

<h2 id="SetDomain-VALUE"><a href="#___top">SetDomain VALUE</a></h2>

<p>Set Domain to VALUE. Returns (1, &#39;Status message&#39;) on success and (0, &#39;Error Message&#39;) on failure. (In the database, Domain will be stored as a varchar(64).)</p>

<h2 id="Type"><a href="#___top">Type</a></h2>

<p>Returns the current value of Type. (In the database, Type is stored as varchar(64).)</p>

<h2 id="SetType-VALUE"><a href="#___top">SetType VALUE</a></h2>

<p>Set Type to VALUE. Returns (1, &#39;Status message&#39;) on success and (0, &#39;Error Message&#39;) on failure. (In the database, Type will be stored as a varchar(64).)</p>

<h2 id="Instance"><a href="#___top">Instance</a></h2>

<p>Returns the current value of Instance. (In the database, Instance is stored as int(11).)</p>

<h2 id="SetInstance-VALUE"><a href="#___top">SetInstance VALUE</a></h2>

<p>Set Instance to VALUE. Returns (1, &#39;Status message&#39;) on success and (0, &#39;Error Message&#39;) on failure. (In the database, Instance will be stored as a int(11).)</p>

<h2 id="Creator"><a href="#___top">Creator</a></h2>

<p>Returns the current value of Creator. (In the database, Creator is stored as int(11).)</p>

<h2 id="Created"><a href="#___top">Created</a></h2>

<p>Returns the current value of Created. (In the database, Created is stored as datetime.)</p>

<h2 id="LastUpdatedBy"><a href="#___top">LastUpdatedBy</a></h2>

<p>Returns the current value of LastUpdatedBy. (In the database, LastUpdatedBy is stored as int(11).)</p>

<h2 id="LastUpdated"><a href="#___top">LastUpdated</a></h2>

<p>Returns the current value of LastUpdated. (In the database, LastUpdated is stored as datetime.)</p>

<a href="./../">&larr; Back to index</a>