############
DynamicField
############


****
NAME
****


Kernel::System::DynamicField


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


DynamicFields backend


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


new()
=====


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


.. code-block:: perl

     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


.. code-block:: perl

     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:


.. code-block:: perl

     $ID = 567;



DynamicFieldGet()
=================


get Dynamic Field attributes


.. code-block:: perl

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


Returns:


.. code-block:: perl

     $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


.. code-block:: perl

     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


.. code-block:: perl

     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


.. code-block:: perl

     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:


.. code-block:: perl

     $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


.. code-block:: perl

     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:


.. code-block:: perl

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


.. code-block:: perl

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


Returns:


.. code-block:: perl

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



DynamicFieldOrderCheck()
========================


checks for duplicate order numbers and gaps in the numbering.


.. code-block:: perl

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


Returns:


.. code-block:: perl

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



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.


.. code-block:: perl

     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.


.. code-block:: perl

     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.


.. code-block:: perl

     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.


.. code-block:: perl

     $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:


.. code-block:: perl

     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:


.. code-block:: perl

     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:


.. code-block:: perl

     my $Success = 1;