############
CustomerUser
############


****
NAME
****


Kernel::System::CustomerUser - customer user lib


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


All customer user functions. E. g. to add and update customer users.


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


new()
=====


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


.. code-block:: perl

     my $CustomerUserObject = $Kernel::OM->Get('Kernel::System::CustomerUser');



CustomerSourceList()
====================


return customer source list


.. code-block:: perl

     my %List = $CustomerUserObject->CustomerSourceList(
         ReadOnly => 0 # optional, 1 returns only RO backends, 0 returns writable, if not passed returns all backends
     );



CustomerSearch()
================


to search users


.. code-block:: perl

     # text search
     my %List = $CustomerUserObject->CustomerSearch(
         Search => '*some*', # also 'hans+huber' possible
         Valid  => 1,        # (optional) default 1
         Limit  => 100,      # (optional) overrides limit of the config
     );
 
     # username search
     my %List = $CustomerUserObject->CustomerSearch(
         UserLogin => '*some*',
         Valid     => 1,         # (optional) default 1
     );
 
     # email search
     my %List = $CustomerUserObject->CustomerSearch(
         PostMasterSearch => 'email@example.com',
         Valid            => 1,                    # (optional) default 1
     );
 
     # search by CustomerID
     my %List = $CustomerUserObject->CustomerSearch(
         CustomerID       => 'CustomerID123',
         Valid            => 1,                # (optional) default 1
     );



CustomerSearchDetail()
======================


To find customer user in the system.

The search criteria are logically AND connected.
When a list is passed as criteria, the individual members are OR connected.
When an undef or a reference to an empty array is passed, then the search criteria
is ignored.

Returns either a list, as an arrayref, or a count of found customer user ids.
The count of results is returned when the parameter \ ``Result = 'COUNT'``\  is passed.


.. code-block:: perl

     my $CustomerUserIDsRef = $CustomerUserObject->CustomerSearchDetail(
 
         # all search fields possible which are defined in CustomerUser::EnhancedSearchFields
         UserLogin     => 'example*',                                    # (optional)
         UserFirstname => 'Firstn*',                                     # (optional)
 
         # special parameters
         CustomerCompanySearchCustomerIDs => [ 'example.com' ],          # (optional)
         ExcludeUserLogins                => [ 'example', 'doejohn' ],   # (optional)
 
         # array parameters are used with logical OR operator (all values are possible which
         are defined in the config selection hash for the field)
         UserCountry              => [ 'Austria', 'Germany', ],          # (optional)
 
         # DynamicFields
         #   At least one operator must be specified. Operators will be connected with AND,
         #       values in an operator with OR.
         #   You can also pass more than one argument to an operator: ['value1', 'value2']
         DynamicField_FieldNameX => {
             Equals            => 123,
             Like              => 'value*',                # "equals" operator with wildcard support
             GreaterThan       => '2001-01-01 01:01:01',
             GreaterThanEquals => '2001-01-01 01:01:01',
             SmallerThan       => '2002-02-02 02:02:02',
             SmallerThanEquals => '2002-02-02 02:02:02',
         }
 
         OrderBy => [ 'UserLogin', 'UserCustomerID' ],                   # (optional)
         # ignored if the result type is 'COUNT'
         # default: [ 'UserLogin' ]
         # (all search fields possible which are defined in
         CustomerUser::EnhancedSearchFields)
 
         # Additional information for OrderBy:
         # The OrderByDirection can be specified for each OrderBy attribute.
         # The pairing is made by the array indices.
 
         OrderByDirection => [ 'Down', 'Up' ],                          # (optional)
         # ignored if the result type is 'COUNT'
         # (Down | Up) Default: [ 'Down' ]
 
         Result => 'ARRAY' || 'COUNT',                                  # (optional)
         # default: ARRAY, returns an array of change ids
         # COUNT returns a scalar with the number of found changes
 
         Limit => 100,                                                  # (optional)
         # ignored if the result type is 'COUNT'
     );


Returns:

Result: 'ARRAY'


.. code-block:: perl

     @CustomerUserIDs = ( 1, 2, 3 );


Result: 'COUNT'


.. code-block:: perl

     $CustomerUserIDs = 10;



CustomerUserSearchFields()
==========================


Get a list of the defined search fields (optional only the relevant fields for the given source).


.. code-block:: perl

     my @SeachFields = $CustomerUserObject->CustomerUserSearchFields(
         Source => 'CustomerUser', # optional, but important in the CustomerSearchDetail to get the right database fields
     );


Returns an array of hash references.


.. code-block:: perl

     @SeachFields = (
         {
             Name          => 'UserEmail',
             Label         => 'Email',
             Type          => 'Input',
             DatabaseField => 'mail',
         },
         {
             Name           => 'UserCountry',
             Label          => 'Country',
             Type           => 'Selection',
             SelectionsData => {
                 'Germany'        => 'Germany',
                 'United Kingdom' => 'United Kingdom',
                 'United States'  => 'United States',
                 # ...
             },
             DatabaseField => 'country',
         },
         {
             Name          => 'DynamicField_SkypeAccountName',
             Label         => '',
             Type          => 'DynamicField',
             DatabaseField => 'SkypeAccountName',
         },
     );



GetFieldConfig()
================


This function collect some field config information from the customer user map.


.. code-block:: perl

     my %FieldConfig = $CustomerUserObject->GetFieldConfig(
         FieldName => 'UserEmail',
         Source    => 'CustomerUser', # optional
     );


Returns some field config information:


.. code-block:: perl

     my %FieldConfig = (
         Label         => 'Email',
         DatabaseField => 'email',
         StorageType   => 'var',
     );



GetFieldSelections()
====================


This function collect the selections for the given field name, if the field has some selections.


.. code-block:: perl

     my %SelectionsData = $CustomerUserObject->GetFieldSelections(
         FieldName => 'UserTitle',
     );


Returns the selections for the given field name (merged from all sources) or a empty hash:


.. code-block:: perl

     my %SelectionData = (
         'Mr.'  => 'Mr.',
         'Mrs.' => 'Mrs.',
     );



CustomerIDList()
================


return a list of all known unique CustomerIDs of the registered customer users (no SearchTerm),
or a filtered list where the CustomerIDs must contain a search term.


.. code-block:: perl

     my @CustomerIDs = $CustomerUserObject->CustomerIDList(
         SearchTerm  => 'somecustomer',    # optional
         Valid       => 1,                 # optional
     );



CustomerName()
==============


get customer user name


.. code-block:: perl

     my $Name = $CustomerUserObject->CustomerName(
         UserLogin => 'some-login',
     );



CustomerIDs()
=============


get customer user customer ids


.. code-block:: perl

     my @CustomerIDs = $CustomerUserObject->CustomerIDs(
         User => 'some-login',
     );



CustomerUserDataGet()
=====================


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


.. code-block:: perl

     my %User = $CustomerUserObject->CustomerUserDataGet(
         User => 'franz',
     );



CustomerUserAdd()
=================


to add new customer users


.. code-block:: perl

     my $UserLogin = $CustomerUserObject->CustomerUserAdd(
         Source         => 'CustomerUser', # CustomerUser source config
         UserFirstname  => 'Huber',
         UserLastname   => 'Manfred',
         UserCustomerID => 'A124',
         UserLogin      => 'mhuber',
         UserPassword   => 'some-pass',          # not required
         UserEmail      => 'email@example.com',
         ValidID        => 1,
         UserID         => 123,
     );



CustomerUserUpdate()
====================


to update customer users


.. code-block:: perl

     $CustomerUserObject->CustomerUserUpdate(
         Source        => 'CustomerUser',        # CustomerUser source config
         ID            => 'mh',                  # current user login
         UserLogin     => 'mhuber',              # new user login
         UserFirstname => 'Huber',
         UserLastname  => 'Manfred',
         UserPassword  => 'some-pass',           # not required
         UserEmail     => 'email@example.com',
         ValidID       => 1,
         UserID        => 123,
     );



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


to set customer users passwords


.. code-block:: perl

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



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


generate a random password


.. code-block:: perl

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



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


set customer user preferences


.. code-block:: perl

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



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


get customer user preferences


.. code-block:: perl

     my %Preferences = $CustomerUserObject->GetPreferences(
         UserID => 'some-login',
     );



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


search in user preferences


.. code-block:: perl

     my %UserList = $CustomerUserObject->SearchPreferences(
         Key   => 'UserSomeKey',
         Value => 'SomeValue',   # optional, limit to a certain value/pattern
     );



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


generate a random token


.. code-block:: perl

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



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


check password token


.. code-block:: perl

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



CustomerUserCacheClear()
========================


clear cache of customer user data


.. code-block:: perl

     $CustomerUserObject->CustomerUserCacheClear(
         UserLogin => 'mhuber',
     );



CustomerUserCustomerMemberAdd()
===============================


to add a customer user to a customer


.. code-block:: perl

     my $Success = $CustomerUserObject->CustomerUserCustomerMemberAdd(
         CustomerUserID => 123,
         CustomerID     => 123,
         Active         => 1,        # optional
         UserID         => 123,
     );



CustomerUserCustomerMemberList()
================================


get related customer IDs of a customer user


.. code-block:: perl

     my @CustomerIDs = $CustomerUserObject->CustomerUserCustomerMemberList(
         CustomerUserID => 123,
     );


Returns:


.. code-block:: perl

     @CustomerIDs = (
         '123',
         '456',
     );


get related customer users of a customer ID


.. code-block:: perl

     my @CustomerUsers = $CustomerUserObject->CustomerUserCustomerMemberList(
         CustomerID => 123,
     );


Returns:


.. code-block:: perl

     @CustomerUsers = (
         '123',
         '456',
     );