NAME

Kernel::System::CustomerUser – customer user lib

DESCRIPTION

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

PUBLIC INTERFACE

BUILD()

Moose post-constructor method, that is executed right after instantiation of the object. During the instantiation of the object, the event handling will be initialized. For the Customer User the backend module must be configured

CustomerSourceList()

return customer source list

    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

    # 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.

    my $CustomerUserIDsRef = $CustomerUserObject->CustomerSearchDetail(

        # all search fields possible which are defined in CustomerUserSearchFields
        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 CustomerUserSearchFields)

        # 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

        Valid => 1,                                                    # (optional)
        # default: 1, return only valid customer users

        Limit => 100,                                                  # (optional)
        # ignored if the result type is 'COUNT'
    );

Returns:

Result: 'ARRAY'

    @CustomerUserIDs = ( 1, 2, 3 );

Result: 'COUNT'

    $CustomerUserIDs = 10;

CustomerUserSearchFields()

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

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

Returns an array of hash references.

    @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',
        },
    );

CustomerUserFields()

Get a list of the defined fields for the given source.

    my @Fields = $CustomerUserObject->CustomerUserFields(
        Source => 'CustomerUser',
    );

Returns an array of hash references.

    @Fields = (
        {
            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.

    my %FieldConfig = $CustomerCompanyObject->GetFieldConfig(
        FieldName => 'CustomerCompanyName',
        Source    => 'CustomerCompany', # optional
    );

Returns some field config information:

    my %FieldConfig = (
        Label         => 'Name',
        DatabaseField => 'name',
        StorageType   => 'var',
    );

GetFieldSelections()

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

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

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

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

CustomerIDList()

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

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

CustomerName()

get customer user name

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

CustomerIDs()

get customer user customer ids

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

CustomerUserDataGet()

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

    my %User = $CustomerUserObject->CustomerUserDataGet(
        User => 'franz',
        NoSensitive   => 1,       # not required -> 0|1 (default 0)
                                  # returns data without sensitive information
        AvatarFile    => 1,       # not required -> 0|1 (default 0)
                                  # returns Avatar image content if present
    );

CustomerUserAdd()

to add new customer users

    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

    $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

    $CustomerUserObject->SetPassword(
        UserLogin              => 'some-login',
        PW                     => 'some-new-password',
        SetPasswordLastSetTime => 1,                   # (optional) default 1
    );

GenerateRandomPassword()

generate a random password

    my $Password = $CustomerUserObject->GenerateRandomPassword();

    or

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

IsPasswordChangeable()

Check if the password is changeable for the current user.

    my $PasswordChangeable = $CustomerUserObject->IsPasswordChangeable(
        UserLogin => 'some-login',
    );

Return true if the password is changeable and otherwise false.

GetPasswordPolicyRules()

Collect the current password policy for the given customer user.

    my %PasswordPolicyRules = $CustomerUserObject->GetPasswordPolicyRules(
        UserLogin => 'customer',
    );

Returns hash ref of the current password policy rules.

    %PasswordPolicyRules = {
        PasswordMinSize                   => 8,
        PasswordMin2Lower2UpperCharacters => 1,
        PasswordNeedDigit                 => 1,
    };

CheckPasswordHistory()

Check the password history for a new password.

    my $Result = $CustomerUserObject->CheckPasswordHistory(
        UserLogin   => 'tt',
        NewPassword => 'test-password',
    );

Returns true if the password is allowed and false, if the password was already used in the last time.

UpdatePasswordHistory()

Update the password history for a new password, if needed.

    my $Result = $CustomerUserObject->UpdatePasswordHistory(
        UserLogin   => 'tt',
        NewPassword => 'test-password',
    );

Returns true if the password history was updated and false if not.

SetPreferences()

set customer user preferences

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

GetPreferences()

get customer user preferences

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

SearchPreferences()

search in customer user preferences

    my %UserList = $CustomerUserObject->SearchPreferences(
        Key    => 'UserSomeKey',
        Value  => 'SomeValue',   # optional, limit to a certain value/pattern
        Limit  => 1000,          # optional, limit the amount of result entries
        Offset => 0,             # optional, paginate the results
    );

DeletePreferences()

delete keys from user preferences for customer users

    my $Success = $CustomerUserObject->DeletePreferences(
        Keys    => ['AvatarLocation', 'UserComment', 'UserLastLogin', 'UserLoginFailed'],
        UserIDs => ['customer-123', 'customer-456', 'customer-789'],
        SkipPushEvent => 1,
    );

TokenGenerate()

generate a random token

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

TokenCheck()

check password token

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

CustomerUserCacheClear()

clear cache of customer user data

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

CustomerUserCustomerMemberAdd()

to add a customer user to a customer

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

CustomerUserCustomerMemberList()

get related customer IDs of a customer user

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

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

get related customer users of a customer ID

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

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

GetAvatar()

get avatar image and store it into cache.

_AvatarFileGet()

Get user's avatar file content.

    my $AvatarFile = $CustomerUserObject->_AvatarFileGet(
        FileLocation => $ReturnData{AvatarLocation},
    );

Returns avatar file content:

    $AvatarFile = '<binary-content>';

Please note this function will return an empty string in case not avatar file was found.

_CustomerUserDataGetDeleteCache()

Deletes the short-lived cache of the method CustomerUserDataGet.

    $CustomerUserObject->_CustomerUserDataGetDeleteCache(
        User => '...', # User login
    );