####
User
####


****
NAME
****


Kernel::System::User - user lib


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


All user functions. E. g. to add and updated user and other functions.


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


new()
=====


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


.. code-block:: perl

     my $UserObject = $Kernel::OM->Get('Kernel::System::User');



GetUserData()
=============


get user data (UserLogin, UserFirstname, UserLastname, UserEmail, ...)


.. code-block:: perl

     my %User = $UserObject->GetUserData(
         UserID => 123,
     );
 
     or
 
     my %User = $UserObject->GetUserData(
         User          => 'franz',
         Valid         => 1,       # not required -> 0|1 (default 0)
                                   # returns only data if user is valid
         NoOutOfOffice => 1,       # not required -> 0|1 (default 0)
                                   # returns data without out of office infos
     );



UserAdd()
=========


to add new users


.. code-block:: perl

     my $UserID = $UserObject->UserAdd(
         UserFirstname => 'Huber',
         UserLastname  => 'Manfred',
         UserLogin     => 'mhuber',
         UserPw        => 'some-pass', # not required
         UserEmail     => 'email@example.com',
         UserMobile    => '1234567890', # not required
         ValidID       => 1,
         ChangeUserID  => 123,
     );



UserUpdate()
============


to update users


.. code-block:: perl

     $UserObject->UserUpdate(
         UserID        => 4321,
         UserFirstname => 'Huber',
         UserLastname  => 'Manfred',
         UserLogin     => 'mhuber',
         UserPw        => 'some-pass', # not required
         UserEmail     => 'email@example.com',
         UserMobile    => '1234567890', # not required
         ValidID       => 1,
         ChangeUserID  => 123,
     );



UserSearch()
============


to search users


.. code-block:: perl

     my %List = $UserObject->UserSearch(
         Search => '*some*', # also 'hans+huber' possible
         Valid  => 1, # not required
     );
 
     my %List = $UserObject->UserSearch(
         UserLogin => '*some*',
         Limit     => 50,
         Valid     => 1, # not required
     );
 
     my %List = $UserObject->UserSearch(
         PostMasterSearch => 'email@example.com',
         Valid            => 1, # not required
     );


Returns hash of UserID, Login pairs:


.. code-block:: perl

     my %List = (
         1 => 'root@locahost',
         4 => 'admin',
         9 => 'joe',
     );


For PostMasterSearch, it returns hash of UserID, Email pairs:


.. code-block:: perl

     my %List = (
         4 => 'john@example.com',
         9 => 'joe@example.com',
     );



SetPassword()
=============


to set users passwords


.. code-block:: perl

     $UserObject->SetPassword(
         UserLogin => 'some-login',
         PW        => 'some-new-password'
     );



UserLookup()
============


user login or id lookup


.. code-block:: perl

     my $UserLogin = $UserObject->UserLookup(
         UserID => 1,
         Silent => 1, # optional, don't generate log entry if user was not found
     );
 
     my $UserID = $UserObject->UserLookup(
         UserLogin => 'some_user_login',
         Silent    => 1, # optional, don't generate log entry if user was not found
     );



UserName()
==========


get user name


.. code-block:: perl

     my $Name = $UserObject->UserName(
         User => 'some-login',
     );
 
     or
 
     my $Name = $UserObject->UserName(
         UserID => 123,
     );



UserList()
==========


return a hash with all users


.. code-block:: perl

     my %List = $UserObject->UserList(
         Type          => 'Short', # Short|Long, default Short
         Valid         => 1,       # default 1
         NoOutOfOffice => 1,       # (optional) default 0
     );



GenerateRandomPassword()
========================


generate a random password


.. code-block:: perl

     my $Password = $UserObject->GenerateRandomPassword();
 
     or
 
     my $Password = $UserObject->GenerateRandomPassword(
         Size => 16,
     );



SetPreferences()
================


set user preferences


.. code-block:: perl

     $UserObject->SetPreferences(
         Key    => 'UserComment',
         Value  => 'some comment',
         UserID => 123,
     );



GetPreferences()
================


get user preferences


.. code-block:: perl

     my %Preferences = $UserObject->GetPreferences(
         UserID => 123,
     );



SearchPreferences()
===================


search in user preferences


.. code-block:: perl

     my %UserList = $UserObject->SearchPreferences(
         Key   => 'UserEmail',
         Value => 'email@example.com',   # optional, limit to a certain value/pattern
     );



TokenGenerate()
===============


generate a random token


.. code-block:: perl

     my $Token = $UserObject->TokenGenerate(
         UserID => 123,
     );



TokenCheck()
============


check password token


.. code-block:: perl

     my $Valid = $UserObject->TokenCheck(
         Token  => $Token,
         UserID => 123,
     );



_UserFullname()
===============


Builds the user fullname based on firstname, lastname and login. The order
can be configured.


.. code-block:: perl

     my $Fullname = $Object->_UserFullname(
         UserFirstname => 'Test',
         UserLastname  => 'Person',
         UserLogin     => 'tp',
         NameOrder     => 0,         # optional 0, 1, 2, 3, 4, 5
     );




UserLoginExistsCheck()
======================


return 1 if another user with this login (username) already exists


.. code-block:: perl

     $Exist = $UserObject->UserLoginExistsCheck(
         UserLogin => 'Some::UserLogin',
         UserID => 1, # optional
     );