Kernel::System::DynamicField::Backend
DynamicFields backend interface
new()
create a DynamicField backend object. Do not use it directly, instead use:
use Kernel::System::ObjectManager;
local $Kernel::OM = Kernel::System::ObjectManager->new();
my $DynamicFieldObject = $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,
}
ValueSet()
sets a dynamic field value.
my $Success = $BackendObject->ValueSet(
DynamicFieldConfig => $DynamicFieldConfig, # complete config of the DynamicField
ObjectID => $ObjectID, # ID of the current object that the field
# must be linked to, e. g. TicketID
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 exeptions 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,
);
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
);
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 meaningfull 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 as an specified 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
);
Returns:
$Success = 1; # or undefined (if the dynamic field does not have that 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',
},
];
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',
},
};
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
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'
};
This software is part of the OTRS project (https://otrs.org/).
This software comes with ABSOLUTELY NO WARRANTY. For details, see the enclosed file COPYING for license information (GPL). If you did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.