####### Backend ####### **** NAME **** Kernel::System::DynamicField::Backend *********** DESCRIPTION *********** DynamicFields backend interface **************** PUBLIC INTERFACE **************** new() ===== create a DynamicField backend object. Do not use it directly, instead use: .. code-block:: perl my $BackendObject = $Kernel::OM->Get('Kernel::System::DynamicField::Backend'); EditFieldRender() ================= creates the field HTML to be used in edit masks. .. code-block:: perl my $FieldHTML = $BackendObject->EditFieldRender( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, LayoutObject => $LayoutObject, PossibleValuesFilter => { # Optional. Some backends may support this. 'Key1' => 'Value1', # This may be needed to realize ACL support for ticket masks, 'Key2' => 'Value2', # where the possible values can be limited with and ACL. }, Template => { # Optional data structure of GenericAgent etc. Owner => 2, # Value is accessable via field name (DynamicField_ + field name) Title => 'Generic Agent Job was here', # and could be a scalar, Hash- or ArrayRef # ... DynamicField_ExampleField1 => 'Value 1' }, Value => 'Any value', # Optional Mandatory => 1, # 0 or 1, Class => 'AnyCSSClass OrOneMore', # Optional ServerError => 1, # 0 or 1, ErrorMessage => $ErrorMessage, # Optional or a default will be used in error case UseDefaultValue => 1, # 0 or 1, 1 default OverridePossibleNone => 1, # Optional, 0 or 1. If defined orverrides the Possible None # setting of all dynamic fields (where applies) with the # defined value ConfirmationNeeded => 0, # Optional, 0 or 1, default 0. To display a confirmation element # on fields that apply (like checkbox) AJAXUpdate => 1, # Optional, 0 ir 1. To create JS code for field change to update # the form using ACLs triggered by the field. UpdatableFields => [ # Optional, to use if AJAXUpdate is 1. List of fields to display a 'NetxStateID', # spinning wheel when reloading via AJAXUpdate. 'PriorityID', ], MaxLength => 100 # Optional, defines the maximum number of characters on fields # where applies (like TextArea) ); Returns { Field => $HTMLString, Label => $LabelString, }; DisplayValueRender() ==================== creates value and title strings to be used in display masks. Supports HTML output and will transform dates to the current user's timezone. .. code-block:: perl my $ValueStrg = $BackendObject->DisplayValueRender( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Value => 'Any value', # Optional HTMLOutput => 1, # or 0, default 1, to return HTML ready # values ValueMaxChars => 20, # Optional (for HTMLOutput only) TitleMaxChars => 20, # Optional (for HTMLOutput only) LayoutObject => $LayoutObject, ); Returns $ValueStrg = { Title => $Title, Value => $Value, Link => $Link, LinkPreview => $LinkPreview, } ValueSet() ========== sets a dynamic field value. .. code-block:: perl my $Success = $BackendObject->ValueSet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField # OR DynamicFieldName => 'MyField', # Implicitly fetches config of dynamic field ObjectID => $ObjectID, # ID of the current object that the field # must be linked to, e. g. TicketID ObjectName => $ObjectName, # Name of the current object that the field # must be linked to, e. g. CustomerUserLogin # You have to give either ObjectID OR ObjectName Value => $Value, # Value to store, depends on backend type UserID => 123, ); ValueIsDifferent() ================== compares if two dynamic field values are different. This function relies on Kernel::System::VariableCheck::DataIsDifferent() but with some exceptions depending on each field. .. code-block:: perl my $Success = $BackendObject->ValueIsDifferent( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField # must be linked to, e. g. TicketID Value1 => $Value1, # Dynamic Field Value Value2 => $Value2, # Dynamic Field Value ); ValueDelete() ============= deletes a dynamic field value. .. code-block:: perl my $Success = $BackendObject->ValueDelete( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ObjectID => $ObjectID, # ID of the current object that the field # must be linked to, e. g. TicketID UserID => 123, ); AllValuesDelete() ================= deletes all values of a dynamic field. .. code-block:: perl my $Success = $BackendObject->AllValuesDelete( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField UserID => 123, ); ValueValidate() =============== validates a dynamic field value. .. code-block:: perl my $Success = $BackendObject->ValueValidate( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Value => $Value, # Value to store, depends on backend type UserID => 123, ); FieldValueValidate() ==================== Validates a dynamic field possible value. .. code-block:: perl my $Success = $BackendObject->FieldValueValidate( DynamicFieldConfig => $DynamicFieldConfig, # Complete config of the DynamicField. Value => $Value, # Value to validate from possible options. UserID => 1, ); ValueGet() ========== get a dynamic field value. .. code-block:: perl my $Value = $BackendObject->ValueGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ObjectID => $ObjectID, # ID of the current object that the field # must be linked to, e. g. TicketID ObjectName => $ObjectName, # Name of the current object that the field # must be linked to, e. g. CustomerUserLogin # You have to give either ObjectID OR ObjectName ); Return $Value # depends on backend type, i. e. # Text, $Value = 'a string' # DateTime, $Value = '1977-12-12 12:00:00' # Checkbox, $Value = 1 SearchSQLGet() ============== returns the SQL WHERE part that needs to be used to search in a particular dynamic field. The table must already be joined. .. code-block:: perl my $SQL = $BackendObject->SearchSQLGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField TableAlias => $TableAlias, # the alias of the already joined dynamic_field_value table to use SearchTerm => $SearchTerm, # What to look for. Placeholders in LIKE searches must be passed as %. Operator => $Operator, # One of [Equals, Like, GreaterThan, GreaterThanEquals, SmallerThan, SmallerThanEquals] # The supported operators differ for the different backends. ); SearchSQLOrderFieldGet() ======================== returns the SQL field needed for ordering based on a dynamic field. .. code-block:: perl my $SQL = $BackendObject->SearchSQLOrderFieldGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField TableAlias => $TableAlias, # the alias of the already joined dynamic_field_value table to use ); EditFieldValueGet() =================== extracts the value of a dynamic field from the param object. .. code-block:: perl my $Value = $BackendObject->EditFieldValueGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, # the current request data LayoutObject => $LayoutObject, # used to transform dates to user time zone TransformDates => 1, # 1 || 0, default 1, to transform the dynamic fields that # use dates to the user time zone (i.e. Date, DateTime # dynamic fields) Template => $Template, ReturnValueStructure => 0, # 0 || 1, default 0 # Returns special structure # (only for backend internal use). ReturnTemplateStructure => 0, # 0 || 1, default 0 # Returns the structured values as got from the http request ); Returns $Value; # depending on each field type e.g. # $Value = 'a text'; # $Value = '1977-12-12 12:00:00'; # $Value = 1; my $Value = $BackendObject->EditFieldValueGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, # the current request data TransformDates => 0, # 1 || 0, default 1, to transform the dynamic fields that # use dates to the user time zone (i.e. Date, DateTime # dynamic fields) Template => $Template, # stored values from DB like Search profile or Generic Agent job ReturnTemplateStructure => 1, # 0 || 1, default 0 # Returns the structured values as got from the http request # (only for backend internal use). ); Returns $Value; # depending on each field type e.g. # $Value = 'a text'; # $Value = { Used => 1, Year => '1977', Month => '12', Day => '12', Hour => '12', Minute => '00' }, # $Value = 1; EditFieldValueValidate() ======================== validate the current value for the dynamic field .. code-block:: perl my $Result = $BackendObject->EditFieldValueValidate( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField PossibleValuesFilter => { # Optional. Some backends may support this. 'Key1' => 'Value1', # This may be needed to realize ACL support for ticket masks, 'Key2' => 'Value2', # where the possible values can be limited with and ACL. }, ParamObject => $Self->{ParamObject} # To get the values directly from the web request Mandatory => 1, # 0 or 1, ); Returns $Result = { ServerError => 1, # 0 or 1, ErrorMessage => $ErrorMessage, # Optional or a default will be used in error case } SearchFieldRender() =================== creates the field HTML to be used in search masks. .. code-block:: perl my $FieldHTML = $BackendObject->SearchFieldRender( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, Profile => $ProfileData, # search template data to load PossibleValuesFilter => { # optional. Some backends may support this. 'Key1' => 'Value1', # This may be needed to realize ACL support for ticket masks, 'Key2' => 'Value2', # where the possible values can be limited with and ACL. }, DefaultValue => $Value, # optional, depending on each field type e.g # $Value = a text'; # $Value # = 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartYear=1977;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMonth=12;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartDay=12;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartHour=00;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMinute=00;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartSecond=00;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopYear=2011;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMonth=09;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopDay=29;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopHour=23;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMinute=59;' # . 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopSecond=59;'; # # $Value = 1; ConfirmationCheckboxes => 0, # or 1, to dislay confirmation checkboxes UseLabelHints => 1, # or 0, default 1. To display seach hints in labels Type => 'some type', # search preference type ); Returns { Field => $HTMLString, Label => $LabelString, }; SearchFieldValueGet() ===================== extracts the value of a dynamic field from the param object or search profile. .. code-block:: perl my $Value = $BackendObject->SearchFieldValueGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, # the current request data Profile => $ProfileData, # the serach profile ReturnProfileStructure => 0, # 0 || 1, default 0 # Returns the structured values as got from the http request Type => 'some type', # search preference type ); Returns $Value; # depending on each field type e.g. # $Value = 'a text'; # $Value = { # 'DynamicField_' . $DynamicFieldConfig->{Name} => 1, # ValueStart { # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartYear' => '1977', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMonth' => '12', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartDay' => '12', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartHour' => '00', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMinute' => '00', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartSecond' => '00', # }, # ValueStop { # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopYear' => '2011', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMonth' => '09', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopDay' => '29', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopHour' => '23', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMinute' => '59', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopSecond' => '59', # }, # }, # $Value = 1; my $Value = $BackendObject->SearchFieldValueGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ParamObject => $ParamObject, # the current request data Profile => $ProfileData, # the serach profile ReturnProfileStructure => 1, # 0 || 1, default 0 # Returns the structured values as got from the http request ); Returns $Value; # depending on each field type e.g. # $Value = { # 'DynamicField_' . $DynamicFieldConfig->{Name} => 'a text'; # }; # $Value = { # 'DynamicField_' . $DynamicFieldConfig->{Name} => 1, # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartYear' => '1977', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMonth' => '12', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartDay' => '12', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartHour' => '00', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartMinute' => '00', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StartSecond' => '00', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopYear' => '2011', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMonth' => '09', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopDay' => '29', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopHour' => '23', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopMinute' => '59', # 'DynamicField_' . $DynamicFieldConfig->{Name} . 'StopSecond' => '59', # }; # $Value = { # 'DynamicField_' . $DynamicFieldConfig->{Name} = 1; # }; SearchFieldPreferences() ======================== Returns the search field preferences of the backend. .. code-block:: perl my $SearchFieldPreferences = $BackendObject->SearchFieldPreferences( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ); Returns (example for Date and DateTime): $SearchFieldPreferences = [ { Type => 'TimePoint', LabelSuffix => 'before/after', }, { Type => 'TimeSlot', LabelSuffix => 'between', }, ]; SearchFieldParameterBuild() =========================== build the search parameters to be passed to the search engine. .. code-block:: perl my $DynamicFieldSearchParameter = $BackendObject->SearchFieldParameterBuild( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField LayoutObject => $LayoutObject, # optional Profile => $ProfileData, # the search profile Type => 'some type', # search preference type ); Returns $DynamicFieldSearchParameter = { Parameter { Equals => $Value, # Available operatiors: # Equals => 123, # Like => 'value*', # 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', }, Display => $DisplayValue, # the value to be displayed in the search terms section }; ReadableValueRender() ===================== creates value and title strings to be used for storage (e. g. TicketHistory). Produces text output and does not transform time zones of dates. .. code-block:: perl my $ValueStrg = $BackendObject->ReadableValueRender( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Value => 'Any value', # Optional ValueMaxChars => 20, # Optional TitleMaxChars => 20, # Optional ); Returns $ValueStrg = { Title => $Title, Value => $Value, } TemplateValueTypeGet() ====================== gets the value type (SCALAR or ARRAY) for a field stored on a template, like a Search Profile or a Generic Agent job .. code-block:: perl my $ValueType = $BackendObject->TemplateValueTypeGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField FieldType => 'Edit', # or 'Search' or 'All' ); returns $ValueType = { 'DynamicField_ . '$DynamicFieldConfig->{Name} => 'SCALAR', } my $ValueType = $Self->{BackendObject}->TemplateValueTypeGet( DynamicFieldConfig => $DynamicFieldConfig, FieldType => 'Search', ); returns $ValueType = { 'Search_DynamicField_' . $DynamicFieldConfig->{Name} => 'ARRAY', } my $ValueType = $Self->{BackendObject}->TemplateValueTypeGet( DynamicFieldConfig => $DynamicFieldConfig, FieldType => 'All', ); returns $ValueType = { 'DynamicField_ . '$DynamicFieldConfig->{Name} => 'SCALAR', 'Search_DynamicField_' . $DynamicFieldConfig->{Name} => 'ARRAY', } RandomValueSet() ================ sets a dynamic field random value. .. code-block:: perl my $Result = $BackendObject->RandomValueSet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ObjectID => $ObjectID, # ID of the current object that the field # must be linked to, e. g. TicketID UserID => 123, ); returns: $Result { Success => 1, # or undef Value => $RandomValue # or undef } HistoricalValuesGet() ===================== returns the list of database values for a defined dynamic field. This function is used to calculate ACLs in Search Dialog .. code-block:: perl my $HistorialValues = $BackendObject->HistoricalValuesGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ); Returns: $HistoricalValues = { '1' => '1', 'Item1' => 'Item1', 'Item2' => 'Item2', } ValueLookup() ============= returns the display value for a value key for a defined Dynamic Field. This function is meaningful for those Dynamic Fields that stores a value different than the value that is shown ( e.g. a Dropdown field could store Key = 1 and Display Value = One ) other fields return the same value as the value key .. code-block:: perl my $Value = $BackendObject->ValueLookup( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Key => 'sotred value', # could also be an array ref for # MultipleSelect fields LanguageObject => $LanguageObject, # optional, used to get value translations ); Returns: $Value = 'value to display'; HasBehavior() ============= checks if the dynamic field has a specific behavior .. code-block:: perl my $Success = $BackendObject->HasBehavior( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Behavior => 'Some Behavior', # 'IsACLReducible' to be reduded by ACLs # and updatable via AJAX # 'IsNotificationEventCondition' to be used # in the notification events as a # ticket condition # 'IsSortable' to sort by this field in # "Small" overviews # 'IsStatsCondition' to be used in # Statistics as a condition # 'IsCustomerInterfaceCapable' to make # the field usable in the customer # interface # 'IsHTMLContent' to indicate that there is # 'IsCustomerInterfaceCapable' to make # HTML content (avoid duble cnversion to HTML) ); Returns: $Success = 1; # or undefined (if the dynamic field does not have that behavior) Functions For IsACLReducible Behavior ===================================== The following functions should be only used if the dynamic field has IsACLReducible behavior PossibleValuesGet() =================== returns the list of possible values for a dynamic field .. code-block:: perl my $PossibleValues = $BackendObject->PossibleValuesGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField ); Returns: $PossibleValues = { '' => '-', # 'none' value if defined in the dynamic field configuration '1' => 'Item1', '2' => 'Item2', } BuildSelectionDataGet() ======================= returns the list of possible values for a dynamic field as needed for BuildSelection or BuildSelectionJSON if TreeView parameter is set in the DynamicFieldConfig the result will be an ArrayHashRef, otherwise the result will be a HashRef. .. code-block:: perl my $DataValues = $BackendObject->BuildSelectionDataGet( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField PossibleValues => $PossibleValues, # field possible values (could be reduced # by ACLs) Value => $Value, # optional scalar, ArrayRef or HashRef # depending on dynamic field the ); Returns: $DataValues = { '' => '-', '1' => 'Item1', '2' => 'Item2', } or $DataValues = [ { Key => '', Value => '-', }, { Key => '1', Value => 'Item1', }, { Key => '1::A', Value => 'Item1-A', Disabled => 1, }, { Key => '1::A::1', Value => 'Item1-A-1', Selected => 1, }, { Key => '2', Value => 'Item2', }, ]; Functions For IsStatsCondition Behavior ======================================= The following functions should be only used if the dynamic field has IsStatsCondition behavior StatsFieldParameterBuild() ========================== .. code-block:: perl my $DynamicFieldStatsParameter = $BackendObject->StatsFieldParameterBuild( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField PossibleValuesFilter => ['value1', 'value2'], # Optional. Some backends may support this. # This may be needed to realize ACL support for ticket masks, # where the possible values can be limited with and ACL. ); returns $DynamicFieldStatsParameter = { Values => { $Key1 => $Value1, $Key2 => $Value2, }, Name => 'DynamicField_' . $DynamicFieldConfig->{Label}, Element => 'DynamicField_' . $DynamicFieldConfig->{Name}, TranslatableValues => 1, TimePeriodFormat => 'DateInputFormat', Block => 'InputField', # or 'MultiselectField' or 'Time' }; StatsSearchFieldParameterBuild() ================================ build the search parameters to be passed to the search engine within the stats module. .. code-block:: perl my $DynamicFieldStatsSearchParameter = $BackendObject->StatsSearchFieldParameterBuild( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Value => $Value, # the serach profile ); Returns $DynamicFieldStatsSearchParameter = { Equals => $Value, # Available operatiors: # Equals => 123, # Like => 'value*', # 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', }, }; Functions For IsNotificationEventCondition Behavior =================================================== The following functions should be only used if the dynamic field has IsNotificationEventCondition behavior ObjectMatch() ============= return if the current field values matches with the value got in an objects attribute structure ( like the result of a TicketGet() ) .. code-block:: perl my $Match = $BackendObject->ObjectMatch( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Value => $Value, # single value to match ObjectAttributes => $ObjectAttributes, # the complete set of attributes from an object # ( i.e. the result of a TicketGet() ) ); Returns: $Match # 1 or 0 Functions For IsFiltrable Behavior ================================== The following functions should be only used if the dynamic field has IsFiltrable behavior ColumnFilterValuesGet() ======================= get the list distinct values for a dynamic field from a list of tickets .. code-block:: perl my $ColumnFilterValues = $BackendObject->ColumnFilterValuesGet( DynamicFieldConfig => $DynamicFieldConfig, #DynamicField configuraction LayoutObject => $LayoutObject, TicketIDs => [23, 1, 56, 74], # array ref list of ticket IDs ); Returns: $HistoricalValues{ ValueA => 'ValueA', ValueB => 'ValueB', ValueC => 'ValueC' }; ValueSearch() ============= Searches/fetches dynamic field value. .. code-block:: perl my $Value = $BackendObject->ValueSearch( DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField Search => 'search term', ); Returns [ { ID => 437, FieldID => 23, ObjectID => 133, ValueText => 'some text', ValueDateTime => '1977-12-12 12:00:00', ValueInt => 123, }, ];