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:
my $BackendObject = $Kernel::OM->Get('Kernel::System::DynamicField::Backend');
EditFieldRender()#
creates the field HTML to be used in edit masks.
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.
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.
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.
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.
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.
my $Success = $BackendObject->AllValuesDelete(
DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField
UserID => 123,
);
ValueValidate()#
validates a dynamic field value.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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
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.
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
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
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
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
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.
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()#
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.
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() )
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
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.
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,
},
];