DynamicField#

NAME#

Kernel::System::DynamicField

DESCRIPTION#

DynamicFields backend

PUBLIC INTERFACE#

new()#

create a DynamicField object. Do not use it directly, instead use:

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

DynamicFieldAdd()#

add new Dynamic Field config

returns id of new Dynamic field if successful or undef otherwise

my $ID = $DynamicFieldObject->DynamicFieldAdd(
    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,
);

Returns:

$ID = 567;

DynamicFieldGet()#

get Dynamic Field attributes

my $DynamicField = $DynamicFieldObject->DynamicFieldGet(
    ID   => 123,             # ID or Name must be provided
    Name => 'DynamicField',
);

Returns:

$DynamicField = {
    ID            => 123,
    InternalField => 0,
    Name          => 'NameForField',
    Label         => 'The label to show',
    FieldOrder    => 123,
    FieldType     => 'Text',
    ObjectType    => 'Article',
    Config        => $ConfigHashRef,
    ValidID       => 1,
    CreateTime    => '2011-02-08 15:08:00',
    ChangeTime    => '2011-06-11 17:22:00',
};

DynamicFieldUpdate()#

update Dynamic Field content into database

returns 1 on success or undef on error

my $Success = $DynamicFieldObject->DynamicFieldUpdate(
    ID          => 1234,            # mandatory
    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
    ValidID     => 1,
    Reorder     => 1,               # or 0, to trigger reorder function, default 1
    UserID      => 123,
);

DynamicFieldDelete()#

delete 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 = $DynamicFieldObject->DynamicFieldDelete(
    ID      => 123,
    UserID  => 123,
    Reorder => 1,               # or 0, to trigger reorder function, default 1
);

DynamicFieldList()#

get DynamicField list ordered by the the “Field Order” field in the DB

my $List = $DynamicFieldObject->DynamicFieldList();

or

my $List = $DynamicFieldObject->DynamicFieldList(
    Valid => 0,             # optional, defaults to 1

    # object  type (optional) as STRING or as ARRAYREF
    ObjectType => 'Ticket',
    ObjectType => ['Ticket', 'Article'],

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

    FieldFilter => {        # optional, only active fields (non 0) will be returned
        ItemOne   => 1,
        ItemTwo   => 2,
        ItemThree => 1,
        ItemFour  => 1,
        ItemFive  => 0,
    },

);

Returns:

$List = {
    1 => 'ItemOne',
    2 => 'ItemTwo',
    3 => 'ItemThree',
    4 => 'ItemFour',
};

or

$List = (
    1,
    2,
    3,
    4
);

DynamicFieldListGet()#

get DynamicField list with complete data ordered by the “Field Order” field in the DB

my $List = $DynamicFieldObject->DynamicFieldListGet();

or

my $List = $DynamicFieldObject->DynamicFieldListGet(
    Valid        => 0,            # optional, defaults to 1

    # object  type (optional) as STRING or as ARRAYREF
    ObjectType => 'Ticket',
    ObjectType => ['Ticket', 'Article'],

    FieldFilter => {        # optional, only active fields (non 0) will be returned
        nameforfield => 1,
        fieldname    => 2,
        other        => 0,
        otherfield   => 0,
    },

);

Returns:

$List = (
    {
        ID            => 123,
        InternalField => 0,
        Name          => 'nameforfield',
        Label         => 'The label to show',
        FieldType     => 'Text',
        ObjectType    => 'Article',
        Config        => $ConfigHashRef,
        ValidID       => 1,
        CreateTime    => '2011-02-08 15:08:00',
        ChangeTime    => '2011-06-11 17:22:00',
    },
    {
        ID            => 321,
        InternalField => 0,
        Name          => 'fieldname',
        Label         => 'It is not a label',
        FieldType     => 'Text',
        ObjectType    => 'Ticket',
        Config        => $ConfigHashRef,
        ValidID       => 1,
        CreateTime    => '2010-09-11 10:08:00',
        ChangeTime    => '2011-01-01 01:01:01',
    },
    # ...
);

DynamicFieldOrderReset()#

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

my $Success = $DynamicFieldObject->DynamicFieldOrderReset();

Returns:

$Success = 1;                        # or 0 in case of error

DynamicFieldOrderCheck()#

checks for duplicate order numbers and gaps in the numbering.

my $Success = $DynamicFieldObject->DynamicFieldOrderCheck();

Returns:

$Success = 1;   # or 0 in case duplicates or gaps in the dynamic fields
                # order numbering

ObjectMappingGet()#

  1. Fetches object ID(s) for given object name(s).

  2. 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 = $DynamicFieldObject->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 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 = $DynamicFieldObject->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 = $DynamicFieldObject->ObjectMappingNameChange(
    OldObjectName => 'customer-1',
    NewObjectName => 'customer-2',
    ObjectType    => 'CustomerUser', # Type of object to change name for
);

Returns 1 on success.

_DynamicFieldReorder()#

re-order the list of fields.

$Success = $DynamicFieldObject->_DynamicFieldReorder(
    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 = $DynamicFieldObject->_DynamicFieldReorder(
    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
);

_SanitizeConfig()#

This function cleans up the config:

Removes JavaScript code from configured regular expression error messages:

my $Success = $DynamicFieldObject->_SanitizeConfig(

    # 'Config' part of a dynamic field config hash returned by DynamicFieldGet()
    # or given to DynamicFieldAdd() and -Update()
    Config => $Config,
);

Removes reserved keywords in link configuration:

my $Success = $DynamicFieldObject->_SanitizeConfig(
    Config => {
        Link => 'https://www.znuny.org/[% Data.Link %]/[% Data.LinkPreview %]/[% Data.Title %]/[% Data.Value %]'
    },
);

$Config->{Link} = 'https://www.znuny.org////';

Return:

my $Success = 1;