NAME

Kernel::System::DynamicField – Dynamic field management class.

DESCRIPTION

This class takes care about handling dynamic field definitions or related object instances. It is possible to lookup, list, create, retrieve, update and delete those dynamic field definitions. Apart from handling dynamic field objects or definitions directly, this class contains functions to control the mapping between dynamic fields and other objects, like tickets, articles etc.

Guidelines

Retrieving dynamic field objects

Dynamic field objects can be retrieved by using the method FieldGet, which either expects a matching id or a name.

If the dynamic field is existing, the method will instantiate and return a driver object, which can be used to handle the related data, for example:

    my $FieldObject = $Kernel::OM->Get('Kernel::System::DynamicField')->FieldGet( ID => 123 );
    $FieldObject->ValueSet('My new value');
    print $FieldObject->ValueGet( ObjectID => 123 );

Retrieving multiple dynamic field objects

The field listing methods can be used to search for dynamic fields by filter values. FieldList returns either matching dynamic field id's or id's and their corresponding names for further usage. FieldListGet expects the same parameters as FieldList, but instantiates and returns a set of dynamic field objects instead.

Enclosed an example for a normal field listing and further usage:

    my $DynamicFieldManager = $Kernel::OM->Get('Kernel::System::DynamicField');

    my $FieldList = $DynamicFieldManager->FieldList(
        ResultType => 'ARRAY',
        Filter     => {
            Valid => 1,
        },
    );

    for my $FieldID ( @{$FieldList} ) {
        print $DynamicFieldManager->FieldGet( ID => $FieldID )->ValueGet( ObjectID => 123 );
    }

And here an example with the same purpose, but using FieldListGet:

    my $DynamicFieldManager = $Kernel::OM->Get('Kernel::System::DynamicField');

    my $FieldList = $DynamicFieldManager->FieldListGet(
        ResultType => 'ARRAY',
        Filter     => {
            Valid => 1,
        },
    );

    for my $Field ( @{$FieldList} ) {
        print $Field->ValueGet( ObjectID => 123 );
    }

The usage of names and id's vs. the usage of objects

During the calls of methods like FieldAdd, FieldUpdate, FieldDelete etc. it's of course possible to use parameters like ID, Name etc., which still might be practical and feasible, depending on the current situation, but in some cases it might be useful to use already instantiated objects directly. Using objects for method calls is possible for a set of available methods.

Enclosed an example of updating a dynamic field, by manipulating and using a field object:

    my $DynamicFieldManager = $Kernel::OM->Get('Kernel::System::DynamicField');

    my $Field = $DynamicFieldManager->FieldGet( ID => 123 );

    # we're going to update the dynamic field name and related configuration
    $Field->Name('MyNewName');
    $Field->Config({
        PossibleValues => [1, 2, 3],
        Description    => 'New description.',
    });

    $DynamicFieldManager->FieldUpdate( Object => $Field );

Re-using the already existing field object for management tasks might be a good way of keeping the code as simple and understandable as possible. The related methods calls the needed values from the given object directly, but it's anytime possible to call those methods with regular parameters as well.

PUBLIC INTERFACE

has CacheTTL

Attribute that holds the time to live value for the caching mechanism.

FieldLookup()

Lookup the id or name for a dynamic field

    my $FieldName = $DynamicFieldManager->FieldLookup(
        ID => $FieldID,
    );

    my $FieldID = $DynamicFieldManager->FieldLookup(
        Name => $FieldName,
    );

FieldList()

Get a list of dynamic field id's and names, ordered by the their corresponding field order.

    my $FieldList = $DynamicFieldManager->FieldList(

        # optional, 'ARRAY' or 'HASH', defaults to 'ARRAY'
        ResultType => 'HASH',

        # optional, filter by field parameters
        Filter => {

            # optional, defaults to 1
            Valid      => 0,

            # optional, can be either a string or an array reference of strings
            ObjectType => 'Ticket',
            ObjectType => ['Ticket', 'Article'],

            # optional, can be either a string or an array reference of strings
            FieldType => 'Text',
            FieldType => ['Text', 'Textarea'],

            # optional, only active fields (non 0) will be returned
            FieldDisplay => {
                DynamicFieldNameOne   => 1,
                DynamicFieldNameTwo   => 2,
                DynamicFieldNameThree => 1,
                DynamicFieldNameFour  => 1,
                DynamicFieldNameFive  => 0,
            },
        },
    );

Returns either a hash reference:

    $List = {
        123 => 'DynamicFieldNameOne',
        234 => 'DynamicFieldNameTwo',
        345 => 'DynamicFieldNameThree',
        456 => 'DynamicFieldNameFour',
    };

or an array reference:

    $List = [
        123,
        234,
        345,
        456
    ];

FieldListGet()

Get a list of dynamic field objects, ordered by the their corresponding field order. This method accepts the same parameters as FieldList, but returns an either an array reference or a hash reference of instantiated objects.

    my $Fields = $DynamicFieldManager->FieldListGet(

        # optional, 'ARRAY' or 'HASH', defaults to 'ARRAY'
        ResultType => 'HASH',

        # optional, filter by field parameters
        Filter => {

            # optional, defaults to 1
            Valid      => 0,

            # optional, can be either a string or an array reference of strings
            ObjectType => 'Ticket',
            ObjectType => ['Ticket', 'Article'],

            # optional, can be either a string or an array reference of strings
            FieldType => 'Text',
            FieldType => ['Text', 'Textarea'],

            # optional, only active fields (non 0) will be returned
            FieldDisplay => {
                DynamicFieldNameOne   => 1,
                DynamicFieldNameTwo   => 2,
                DynamicFieldNameThree => 1,
                DynamicFieldNameFour  => 1,
                DynamicFieldNameFive  => 0,
            },
        },
    );

Returns either a hash reference:

    $List = {
        123 => FieldObject1(),
        234 => FieldObject2(),
        345 => FieldObject3(),
        456 => FieldObject4(),
    };

or an array reference:

    $List = [
        FieldObject1(),
        FieldObject2(),
        FieldObject3(),
        FieldObject4()
    ];

FieldAdd()

Creates a new dynamic field.

    my $FieldObject = $DynamicFieldManager->FieldAdd(
        InternalField => 0,                 # optional, 0 or 1, internal fields are protected
        Name          => 'NameForField',    # mandatory
        Label         => 'a description',   # mandatory, label to show
        FieldOrder    => 123,               # mandatory, display order
        FieldType     => 'Text',            # mandatory, selects the DF backend to use for this field
        ObjectType    => 'Article',         # this controls which object the dynamic field links to
                                            # allow only lowercase letters
        Config        => $ConfigHashRef,    # it is stored on YAML format
                                            # to individual articles, otherwise to tickets
        Reorder       => 1,                 # or 0, to trigger reorder function, default 1
        ValidID       => 1,
        UserID        => 123,
    );

or

    my $FieldObject = $DynamicFieldManager->FieldAdd( Object => $MyCustomFieldObject );

Returns an object of the added dynamic field.

FieldGet()

get Dynamic Field attributes

    my $FieldObject = $DynamicFieldManager->FieldGet(
        ID   => 123,
        Name => 'MyDynamicField',
    );

Returns an object of the requested dynamic field.

FieldUpdate()

update Dynamic Field content into database

returns 1 on success or undef on error

    my $Success = $DynamicFieldManager->FieldUpdate(
        ID          => 1234,            # mandatory
        Name        => 'NameForField',  # mandatory
        Label       => 'Description',   # mandatory, label to show
        FieldOrder  => 123,             # mandatory, display order
        FieldType   => 'Text',          # mandatory, selects the DF backend to use for this field
        ObjectType  => 'Article',       # this controls which object the dynamic field links to
                                        # allow only lowercase letters
        Config      => $ConfigHashRef,  # it is stored on YAML format
                                        # to individual articles, otherwise to tickets
        ValidID     => 1,
        Reorder     => 1,               # or 0, to trigger reorder function, default 1
        UserID      => 123,
    );

    or

    my $Success = $DynamicFieldManager->FieldUpdate(
        Object  => $MyCustomFieldObject,    # Object, e.g. retrieved by C<FieldGet>
        Reorder => 1,                       # or 0, to trigger reorder function, default 1
        UserID  => 123,
    );

FieldDelete()

Deletes a dynamic field entry. You need to make sure that all values are deleted before calling this function, otherwise it will fail on DBMS which check referential integrity.

returns 1 if successful or undef otherwise

    my $Success = $DynamicFieldManager->FieldDelete(
        ID      => 123,
        UserID  => 123,
        Reorder => 1,               # or 0, to trigger reorder function, default 1
    );

    or

    my $Success = $DynamicFieldManager->FieldDelete( Object => $MyCustomFieldObject );

FieldOrderReset()

Re-calculates the order of all dynamic fields based on a consecutive number list, starting with at 1. This function will remove duplicate order numbers and gaps in the numbering.

    my $Success = $DynamicFieldManager->FieldOrderReset();

Returns 1 or 0.

FieldOrderCheck()

Checks for duplicate order numbers and gaps in the numbering.

    my $Success = $DynamicFieldManager->FieldOrderCheck();

Returns 0 in case of duplicates or gaps and 1 if the order is clean.

ObjectMappingGet()

(a) Fetches object ID(s) for given object name(s). (b) Fetches object name(s) for given object ID(s).

NOTE: Only use object mappings for dynamic fields that must support non-integer object IDs, like customer user logins and customer company IDs.

    my $ObjectMapping = $DynamicFieldManager->ObjectMappingGet(
        ObjectName            => $ObjectName,    # Name or array ref of names of the object(s) to get the ID(s) for
                                                 # Note: either give ObjectName or ObjectID
        ObjectID              => $ObjectID,      # ID or array ref of IDs of the object(s) to get the name(s) for
                                                 # Note: either give ObjectName or ObjectID
        ObjectType            => 'CustomerUser', # Type of object to get mapping for
    );

Returns for parameter ObjectID:

    $ObjectMapping = {
        ObjectID => ObjectName,
        ObjectID => ObjectName,
        ObjectID => ObjectName,
        # ...
    };

Returns for parameter ObjectName:

    $ObjectMapping = {
        ObjectName => ObjectID,
        ObjectName => ObjectID,
        ObjectName => ObjectID,
        # ...
    };

ObjectMappingCreate()

Creates an object mapping for the given given object name.

NOTE: Only use object mappings for dynamic fields that must support non-integer object IDs, like customer user logins and customer company IDs.

    my $ObjectID = $DynamicFieldManager->ObjectMappingCreate(
        ObjectName => 'customer-1',   # Name of the object to create the mapping for
        ObjectType => 'CustomerUser', # Type of object to create the mapping for
    );

ObjectMappingNameChange()

Changes name of given object mapping.

NOTE: Only use object mappings for dynamic fields that must support non-integer object IDs, like customer user logins and customer company IDs.

    my $Success = $DynamicFieldManager->ObjectMappingNameChange(
        OldObjectName => 'customer-1',
        NewObjectName => 'customer-2',
        ObjectType    => 'CustomerUser', # Type of object to change name for
    );

Returns 1 on success.

PRIVATE INTERFACE

has _DynamicFieldObjects

Attribute that holds all instantiated field objects.

has _ValidateID

Dynamic field list with field ID's as keys. It will be used to validate, if given ID parameters are present in the database.

has _ValidateName

Dynamic field list with field names as keys. It will be used to validate, if given Name parameters are present in the database.

_FieldReorder()

Re-order the list of fields.

    $Success = $DynamicFieldManager->_FieldReorder(
        ID         => 123,              # mandatory, the field ID that triggers the re-order
        Mode       => 'Add',            # || Update || Delete
        FieldOrder => 2,                # mandatory, the FieldOrder from the trigger field
    );

    $Success = $DynamicFieldManager->_FieldReorder(
        ID            => 123,           # mandatory, the field ID that triggers the re-order
        Mode          => 'Update',      # || Update || Delete
        FieldOrder    => 2,             # mandatory, the FieldOrder from the trigger field
        OldFieldOrder => 10,            # mandatory for Mode = 'Update', the FieldOrder before the
                                        # update
    );