#####
Group
#####


****
NAME
****


Kernel::System::Group - group and roles lib


***********
DESCRIPTION
***********


All group and roles functions. E. g. to add groups or to get a member list of a group.


****************
PUBLIC INTERFACE
****************


new()
=====


Don't use the constructor directly, use the ObjectManager instead:


.. code-block:: perl

     my $GroupObject = $Kernel::OM->Get('Kernel::System::Group');



GroupLookup()
=============


get id or name for group


.. code-block:: perl

     my $Group = $GroupObject->GroupLookup(
         GroupID => $GroupID,
     );
 
     my $GroupID = $GroupObject->GroupLookup(
         Group => $Group,
     );



GroupAdd()
==========


to add a group


.. code-block:: perl

     my $ID = $GroupObject->GroupAdd(
         Name    => 'example-group',
         Comment => 'comment describing the group',   # optional
         ValidID => 1,
         UserID  => 123,
     );



GroupGet()
==========


returns a hash with group data


.. code-block:: perl

     my %GroupData = $GroupObject->GroupGet(
         ID => 2,
     );


This returns something like:


.. code-block:: perl

     %GroupData = (
         'Name'       => 'admin',
         'ID'         => 2,
         'ValidID'    => '1',
         'CreateTime' => '2010-04-07 15:41:15',
         'ChangeTime' => '2010-04-07 15:41:15',
         'Comment'    => 'Group of all administrators.',
     );



GroupUpdate()
=============


update of a group


.. code-block:: perl

     my $Success = $GroupObject->GroupUpdate(
         ID      => 123,
         Name    => 'example-group',
         Comment => 'comment describing the group',   # optional
         ValidID => 1,
         UserID  => 123,
     );



GroupList()
===========


returns a hash of all groups


.. code-block:: perl

     my %Groups = $GroupObject->GroupList(
         Valid => 1,   # (optional) default 0
     );


the result looks like


.. code-block:: perl

     %Groups = (
         '1' => 'users',
         '2' => 'admin',
         '3' => 'stats',
         '4' => 'secret',
     );



GroupDataList()
===============


returns a hash of all group data


.. code-block:: perl

     my %GroupDataList = $GroupObject->GroupDataList();


the result looks like


.. code-block:: perl

     %GroupDataList = (
         1 => {
             ID         => 1,
             Name       => 'Group 1',
             Comment    => 'The Comment of Group 1',
             ValidID    => 1,
             CreateTime => '2014-01-01 00:20:00',
             CreateBy   => 1,
             ChangeTime => '2014-01-02 00:10:00',
             ChangeBy   => 1,
         },
         2 => {
             ID         => 2,
             Name       => 'Group 2',
             Comment    => 'The Comment of Group 2',
             ValidID    => 1,
             CreateTime => '2014-11-01 10:00:00',
             CreateBy   => 1,
             ChangeTime => '2014-11-02 01:00:00',
             ChangeBy   => 1,
         },
     );



RoleLookup()
============


get id or name for role


.. code-block:: perl

     my $Role = $GroupObject->RoleLookup(
         RoleID => $RoleID,
     );
 
     my $RoleID = $GroupObject->RoleLookup(
         Role => $Role,
     );



RoleGet()
=========


returns a hash with role data


.. code-block:: perl

     my %RoleData = $GroupObject->RoleGet(
         ID => 2,
     );


This returns something like:


.. code-block:: perl

     %RoleData = (
         'Name'       => 'role_helpdesk_agent',
         'ID'         => 2,
         'ValidID'    => '1',
         'CreateTime' => '2010-04-07 15:41:15',
         'ChangeTime' => '2010-04-07 15:41:15',
         'Comment'    => 'Role for help-desk people.',
     );



RoleAdd()
=========


to add a new role


.. code-block:: perl

     my $RoleID = $GroupObject->RoleAdd(
         Name    => 'example-role',
         Comment => 'comment describing the role',   # optional
         ValidID => 1,
         UserID  => 123,
     );



RoleUpdate()
============


update of a role


.. code-block:: perl

     my $Success = $GroupObject->RoleUpdate(
         ID      => 123,
         Name    => 'example-group',
         Comment => 'comment describing the role',   # optional
         ValidID => 1,
         UserID  => 123,
     );



RoleList()
==========


returns a hash of all roles


.. code-block:: perl

     my %Roles = $GroupObject->RoleList(
         Valid => 1,
     );


the result looks like


.. code-block:: perl

     %Roles = (
         '1' => 'role_helpdesk_agent',
         '2' => 'role_systemsmanagement_agent',
         '3' => 'role_otrs_admin',
         '4' => 'role_faq_manager',
     );



RoleDataList()
==============


returns a hash of all role data


.. code-block:: perl

     my %RoleDataList = $GroupObject->RoleDataList();


the result looks like


.. code-block:: perl

     %RoleDataList = (
         1 => {
             ID         => 1,
             Name       => 'Role 1',
             Comment    => 'The Comment of Role 1',
             ValidID    => 1,
             CreateTime => '2014-01-01 00:20:00',
             CreateBy   => 1,
             ChangeTime => '2014-01-02 00:10:00',
             ChangeBy   => 1,
         },
         2 => {
             ID         => 2,
             Name       => 'Role 2',
             Comment    => 'The Comment of Role 2',
             ValidID    => 1,
             CreateTime => '2014-11-01 10:00:00',
             CreateBy   => 1,
             ChangeTime => '2014-11-02 01:00:00',
             ChangeBy   => 1,
         },
     );



PermissionCheck()
=================


Check if a user has a certain permission for a certain group.


.. code-block:: perl

     my $HasPermission = $GroupObject->PermissionCheck(
         UserID    => $UserID,
         GroupName => $GroupName,
         Type      => 'move_into', # ro|move_into|create|note|owner|priority|rw
     );



PermissionUserInvolvedGet()
===========================


returns a list of users with the given permissions


.. code-block:: perl

     my %Users = $GroupObject->PermissionUserInvolvedGet(
         UserID => $ID,
         Type   => 'move_into', # ro|move_into|create|note|owner|priority|rw
     );



PermissionUserGet()
===================


Get groups of the given user.


.. code-block:: perl

     my %Groups = $GroupObject->PermissionUserGet(
         UserID => $ID,
         Type   => 'move_into', # ro|move_into|create|note|owner|priority|rw
     );



PermissionGroupGet()
====================


Get users of the given group.


.. code-block:: perl

     my %Users = $GroupObject->PermissionGroupGet(
         GroupID => $ID,
         Type    => 'move_into', # ro|move_into|create|note|owner|priority|rw
     );



PermissionGroupUserAdd()
========================


add new permissions or update existing one to the given group of a given user


.. code-block:: perl

     my $Success = $GroupObject->PermissionGroupUserAdd(
         GID => 12,
         UID => 6,
         Permission => {
             ro        => 1,
             move_into => 1,
             create    => 1,
             note      => 1,
             owner     => 1,
             priority  => 0,
             rw        => 0,
         },
         UserID => 123,
     );



PermissionGroupUserGet()
========================


returns a list with all users of a group


.. code-block:: perl

     my %UserList = $GroupObject->PermissionGroupUserGet(
         GroupID => $GroupID,
         Type    => 'move_into',  # ro|move_into|create|note|owner|priority|rw
     );
 
     %UserList = (
         1 => 'User1',
         2 => 'User2',
         3 => 'User3',
     );



PermissionUserGroupGet()
========================


returns a list of groups a user is member of


.. code-block:: perl

     my %GroupList = $GroupObject->PermissionUserGroupGet(
         UserID => 123,
         Type   => 'move_into',  # ro|move_into|create|note|owner|priority|rw
     );
 
     %GroupList = (
         1 => 'Group1',
         2 => 'Group2',
         3 => 'Group3',
     );



PermissionGroupRoleAdd()
========================


add new permissions or update existing one to the given group of a given role


.. code-block:: perl

     my $Success = $GroupObject->PermissionGroupRoleAdd(
         GID => 12,
         RID => 6,
         Permission => {
             ro        => 1,
             move_into => 1,
             create    => 1,
             note      =  1,
             owner     => 1,
             priority  => 0,
             rw        => 0,
         },
         UserID => 123,
     );



PermissionGroupRoleGet()
========================


returns a list with all roles of a group


.. code-block:: perl

     my %RoleList = $GroupObject->PermissionGroupRoleGet(
         GroupID => $GroupID,
         Type    => 'move_into',  # ro|move_into|create|note|owner|priority|rw
     );
 
     %RoleList = (
         1 => 'Role1',
         2 => 'Role2',
         3 => 'Role3',
     );



PermissionRoleGroupGet()
========================


returns a list with all groups of a role


.. code-block:: perl

     my %GroupList = $GroupObject->PermissionRoleGroupGet(
         RoleID => 12,
         Type   => 'move_into',  # ro|move_into|create|note|owner|priority|rw
     );
 
     %GroupList = (
         1 => 'Group1',
         2 => 'Group2',
         3 => 'Group3',
     );



PermissionRoleUserAdd()
=======================


add new permissions or update existing one to the given group of a given role


.. code-block:: perl

     my $Success = $GroupObject->PermissionRoleUserAdd(
         UID    => 12,
         RID    => 6,
         Active => 1,
         UserID => 123,
     );



PermissionRoleUserGet()
=======================


returns a list with all users of a role


.. code-block:: perl

     my %UserList = $GroupObject->PermissionRoleUserGet(
         RoleID => $RoleID,
     );
 
     %UserList = (
         1 => 'User1',
         2 => 'User2',
         3 => 'User3',
     );



PermissionUserRoleGet()
=======================


returns a list with all roles of a user


.. code-block:: perl

     my %RoleList = $GroupObject->PermissionUserRoleGet(
         UserID => $UserID,
     );
 
     %RoleList = (
         1 => 'Role1',
         2 => 'Role2',
         3 => 'Role3',
     );



GroupMemberAdd()
================


Function for backward compatibility. Redirected to PermissionGroupUserAdd().


GroupMemberList()
=================


Function for backward compatibility. Redirected to PermissionUserGet() and PermissionGroupGet().


GroupMemberInvolvedList()
=========================


Function for backward compatibility. Redirected to PermissionUserInvolvedGet().


GroupGroupMemberList()
======================


Function for backward compatibility. Redirected to PermissionUserGroupGet() and PermissionGroupUserGet().


GroupRoleMemberList()
=====================


Function for backward compatibility. Redirected to PermissionRoleGroupGet() and PermissionGroupRoleGet().


GroupRoleMemberAdd()
====================


Function for backward compatibility. Redirected to PermissionGroupRoleAdd().


GroupUserRoleMemberList()
=========================


Function for backward compatibility. Redirected to PermissionUserRoleGet() and PermissionRoleUserGet().


GroupUserRoleMemberAdd()
========================


Function for backward compatibility. Redirected to PermissionRoleUserAdd().


_DBGroupUserGet()
=================


returns the content of the database table group_user


.. code-block:: perl

     my %Data = $GroupObject->_DBGroupUserGet(
         Type => 'UserGroupPerm',  # UserGroupPerm|UserPermGroup|GroupPermUser
     );
 
     Example if Type is UserGroupPerm:
 
     $Data{$UserID}->{$GroupID}->{$Permission}
 
     %Data = (
         32 => {
             34 => [
                 'create',
                 'move_into',
                 'owner',
                 'ro',
             ],
         },
         276 => {
             277 => [
                 'rw',
             ],
         },
     );
 
     Example if Type is UserPermGroup:
 
     $Data{$UserID}->{$Permission}->{$GroupID}
 
     %Data = (
         32 => {
             owner     => [ 34 ],
             create    => [ 34 ],
             ro        => [ 34 ],
             move_into => [ 34 ],
         },
         276 => {
             rw => [ 277 ],
         },
     );
 
     Example if Type is GroupPermUser:
 
     $Data{$GroupID}->{$Permission}->{$UserID}
 
     %Data = (
         127 => {
             owner     => [ 128 ],
             create    => [ 128 ],
             ro        => [ 128 ],
             move_into => [ 128 ],
         },
         90 => {
             rw => [ 91 ],
         },
     );



_DBGroupRoleGet()
=================


returns the content of the database table group_role


.. code-block:: perl

     my %Data = $GroupObject->_DBGroupRoleGet(
         Type => 'RoleGroupPerm',  # RoleGroupPerm|RolePermGroup|GroupPermRole
     );
 
     Example if Type is RoleGroupPerm:
 
     $Data{$RoleID}->{$GroupID}->{$Permission}
 
     %Data = (
         32 => {
             34 => [
                 'create',
                 'move_into',
                 'owner',
                 'ro',
             ],
         },
         276 => {
             277 => [
                 'rw',
             ],
         },
     );
 
     Example if Type is RolePermGroup:
 
     $Data{$RoleID}->{$Permission}->{$GroupID}
 
     %Data = (
         32 => {
             owner     => [ 34 ],
             create    => [ 34 ],
             ro        => [ 34 ],
             move_into => [ 34 ],
         },
         276 => {
             rw => [ 277 ],
         },
     );
 
     Example if Type is GroupPermRole:
 
     $Data{$GroupID}->{$Permission}->{$RoleID}
 
     %Data = (
         127 => {
             owner     => [ 128 ],
             create    => [ 128 ],
             ro        => [ 128 ],
             move_into => [ 128 ],
         },
         90 => {
             rw => [ 91 ],
         },
     );



_DBRoleUserGet()
================


returns the content of the database table role_user


.. code-block:: perl

     my %Data = $GroupObject->_DBRoleUserGet(
         Type => 'RoleUser',  # UserRole|RoleUser|UserRoleHash
     );
 
     Example if Type is UserRole:
 
     $Data{$UserID}->{$RoleID}
 
     %Data = (
         559 => [ 557 ],
         127 => [ 125 ],
         32  => [ 31 ],
         443 => [ 442 ],
     );
 
     Example if Type is RoleUser:
 
     $Data{$RoleID}->{$UserID}
 
     %Data = (
         559 => [ 560 ],
         127 => [ 128 ],
         32  => [ 33, 34 ],
         443 => [ 444, 445 ],
     );
 
     Example if Type is UserRoleHash:
 
     $Data{$UserID}->{$RoleID} = 1
 
     %Data = (
         559 => {
             557 => 1,
         },
         127 => {
             125 => 1,
         },
         32 => {
             31 => 1,
         },
         443 => {
             442 => 1,
         },
     );



_PermissionTypeList()
=====================


returns a list of valid system permissions.


.. code-block:: perl

     %PermissionTypeList = $GroupObject->_PermissionTypeList(
         Type => 'close',  # (optional)
     );