OTRS 8.0 API Reference Perl

Description manuals and libraries
OTRS 8.0 API Reference Perl > Perl Modules > Kernel::System::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:

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

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

        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 user preferences

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

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
    );