NAME
Kernel::System::DynamicField::Driver::Base – Base dynamic field driver implementation.
DESCRIPTION
This is the base class that all drivers should inherit from. All the basic methods necessary are implemented here or require that the driver implement them.
Guidelines
- Create a new driver
-
To create a new driver you need to inherit from this class and at least use one of the roles
Kernel::System::DynamicField::Driver::Role::HasValueType::*.With the
HasValueTyperole you indicate which kind of data you will be storing and in which database column, e.g:package DummyDriver; use Moose; extends 'Kernel::System::DynamicField::Driver::Base'; with qw( Kernel::System::DynamicField::Driver::Role::HasValueType::Int );If your driver needs to support other behaviour e.g 'ACL' permissions or the 'Like' operator, you can just include the following roles to your driver:
- Kernel::System::DynamicField::Driver::Role::Behaviour::SupportsACLs - Kernel::System::DynamicField::Driver::Role::Behaviour::SupportsLikeOperatorPlease check other behaviours/roles at
Kernel/System/DynamicField/Driver/Role.The OTRS system already provides some base drivers ready to be inherited from, so, before create your own from scratch, please check the following ones:
- Kernel::System::DynamicField::Driver::Base::Text - Kernel::System::DynamicField::Driver::Base::DateTime - Kernel::System::DynamicField::Driver::Base::SelectFor ready to use, check the ones in
Kernel::System::DynamicField::Driver::*. - Basic usage
-
Get values associated to the dynamic field
# with no filters my $List = $DynamicField->ValueList(); # with filters my $List = $DynamicField->ValueList( Filters => { ... }, );Get value for object
my $Value = $DynamicField->ValueGet( ObjectID => '...', );Set value for object
# set a new value for the object my $Result = $DynamicField->ValueSet( Value => '...', ObjectID => '...', UserID => '...', ); # clean the current value for the object my $Result = $DynamicField->ValueSet( Value => undef, # can be an empty string also '' ObjectID => '...', UserID => '...', );Delete values
# delete all the values for the dynamic field my $Result = $DynamicField->ValueDelete(); # delete passing filters my $Result = $DynamicField->ValueDelete( Filters => { ... } );
PUBLIC INTERFACE
has ID
Attribute that holds record id.
has ObjectType
Attribute that holds record object type instance.
has FieldType
Attribute that holds record field type.
has Name
Attribute that holds record name.
has Label
Attribute that holds record label.
has Order
Attribute that holds record order.
has Config
Attribute that holds record config.
has ValidID
Attribute that holds record valid id.
has CreateTime
Attribute that holds record create date-time.
has CreateTime
Attribute that holds record create by.
has ChangeTime
Attribute that holds record change date-time.
has ChangeBy
Attribute that holds record change by.
has Internal
Attribute that holds internal flag (it means if it's an internal field or not).
IndexableValueGet()
Gets the value for the specific object id in a prepared format, that can be used by related document search drivers. This method expects the same parameters as ValueGet.
my $IndexableValue = $Driver->IndexableValueGet(
ObjectID => 123,
);The return value is a hash reference, containing at least the value to be indexed and might contain a field name to be used in the related document and a possible pipeline name to be used during the indexing process:
{
Type => 'Text',
Value => 'My value',
}
or
{
Type => 'Text',
Value => [ 'My value', 'Another value' ],
}
or
{
Pipeline => 'Attachment',
Field => 'Attachments',
Value => [
{
data => 'PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTg[...]',
filename => 'myfile.pdf',
},
{
data => 'PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTg[...]',
filename => 'anotherfile.pdf',
},
],
}For more information about document search drivers and their indexing behavior, please take a look at Kernel::System::DocumentSearch::BaseDriver.
ValueGet()
Gets the value for the specific object id.
my $Value = $Driver->ValueGet(
ObjectID => '...',
);Returns
Depends on the driver, could just a scalar 'string', '2019-01-01 12:00:00'
or also an arrayref if the driver supports multiple values.ValueSet()
Sets the value for the specific object id.
# set a new value
my $Value = $Driver->ValueSet(
ObjectName => '...',
or
ObjectID => '...',
Value => '...',
UserID => '...',
);
# clean the current value
my $Value = $Driver->ValueSet(
ObjectName => '...',
or
ObjectID => '...',
Value => undef,
UserID => '...',
);Returns
C<undef> - in case any error occurs
1 - in case of successValueList()
Get the list of values.
my $Value = $Driver->ValueList(
Filters => {
ObjectName => '...', # optional
ObjectID => '...', # optional
Value => '...', # optional
},
);Returns
C<undef> - in case any error occurs
[] - in case no value was found
[
{
ObjectID => '...',
Value => '...',
},
]ValueDelete()
Delete the field values.
my $Success = $Driver->ValueDelete(
Filters => {
UserID => '...' # required
ObjectID => '...' # optional
Value => '...' # optional
},
);Returns
C<undef> - in case any error occurs
1 - in case of successValueValidate()
Check if the value is valid.
my $Valid = $Driver->ValueValidate(
Value => '...' # required
);Returns
C<undef> - in case if is invalid
1 - in caseif is validValueHistory()
Get all distinct values from a field stored on the database.
my $History = $Driver->ValueHistory();Returns
$History = {
ValueA => 'ValueA',
ValueB => 'ValueB',
ValueC => 'ValueC'
};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(
Key => 'stored value', # could also be an array ref for
# MultipleSelect fields
);Returns
$Value = 'value to display';ValueIsDifferent()
Checks if two raw values are equal.
# Checking two simple scalar (different).
my $IsDifferent = $DynamicField->ValueIsDifferent(
Value1 => '11',
Value2 => '12'
);
# Checking 'undef' and empty array (not different).
my $IsDifferent = $DynamicField->ValueIsDifferent(
Value1 => undef,
Value2 => [],
);
# Checking 'undef' and empty string (not different).
my $IsDifferent = $DynamicField->ValueIsDifferent(
Value1 => undef,
Value2 => '',
);ValueMatch()
Checks if two raw values match.
# Checking two simple scalar (no match).
my $Match = $DynamicField->ValueMatch(
Value1 => '11',
Value2 => '12'
);
# Checking two simple scalar (match).
my $Match = $DynamicField->ValueMatch(
Value1 => '11',
Value2 => '11'
);
# Checking 'undef' and empty array (match).
my $Match = $DynamicField->ValueMatch(
Value1 => undef,
Value2 => [],
);
# Checking 'undef' and empty string (match).
my $Match = $DynamicField->ValueMatch(
Value1 => undef,
Value2 => '',
);
# Checking simple scalar exists in array (match).
my $Match = $DynamicField->ValueMatch(
Value => 2,
Match => [ 2, 3 ],
);
# Checking if any of the values in the array matches (match).
my $Match = $DynamicField->ValueMatch(
Value => [ 5, 2 ],
Match => [ 2, 3 ],
);
# Checking if any of the values in the array matches with simple scalar (match).
my $Match = $DynamicField->ValueMatch(
Value => [ 5, 3 ],
Match => 3,
);MultipleRecordsPerValue()
Indicates if is a multiple value or not.
my $Multiple = $Driver->MultipleRecordsPerValue();Returns
0 - not multiple records per value
1 - multiple records per valueHasBehavior()
Indicates if the driver has the given Behavior role.
my $HasBehavior = $Driver->HasBehavior('SupportsLikeOperator');Returns
0 - has not the behavior role
1 - has the behavior roleSearchSQLGet()
Returns the sql condition to the value column.
my $SQL = $Driver->SearchSQLGet(
TableAlias => '...', # required
Operator => '...', # required
SearchTerm => '...', # optional
);SearchSQLOrderFieldGet()
Returns the sql column.
my $SQL = $Driver->SearchSQLOrderFieldGet(
TableAlias => '...', # required
);SearchConditionGet()
Build the search conditions to be passed to the search engine.
my $SearchCondition = $Driver->SearchConditionGet(
FilterValues => { ... }, # required
FilterValueType => '...', # optional
Operator => '...', # optional, TODO not implemented in the functions at the moment, should this be possible?
);Returns
{
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',
}FormFieldSchema()
Returns the field schema to use in the form objects.
my $FieldSchema = $Driver->FormFieldSchema(
Name => '...', # optional
Mandatory => '...', # optional
Label => '...', # optional
Description => '...', # optional
Hint => '...', # optional
Placeholder => '...', # optional
DefaultValue => '...', # optional
RequestData => {}, # Mandatory, an empty hash ref as minimum
Context => 'agent' # Mandatory, contains 'agent' or 'customer'
);Returns
{
Type => '...',
Name => '...',
Required => '...',
Label => '...',
Description => '...',
Hint => '...',
Placeholder => '...',
Validators => [...],
Default => '...',
}DisplayValueData()
Returns the display value data to use this in the output.
my $DisplayValueData = $Driver->DisplayValueData(
Value => 'Example',
);Returns
{
Value => '...',
Link => '...',
LinkPreview => '...',
TranslatableValues => '0|1',
}DisplayExportValue()
Returns the display export value data to use this in the export output (e.g. transformed date value or translated value).
my $DisplayExportValue = $Driver->DisplayExportValue(
Value => 'Example',
LanguageObject => $LanguageObject, # optional (for translation and localization).
);Returns
$Value = 'Test Value';RandomValueSet()
Inserts a random value.
my $ValueObject = $DynamicField->RandomValueSet(
ObjectID => '...',
);Returns
C<undef> - in case any error occurs
1 - in case of successValueToString()
Returns the value as type string.
my $Str = $DynamicField->ValueToString(
ObjectID => '...',
);
my $Str = $DynamicField->ValueToString(
Value => '...',
);Returns
C<undef> - in case any error occurs
String - in case of successPossibleObjectTypesGet()
Returns all configured object types. If certain driver has no its own PossibleObjectTypesGet(), all types will be allowed because of this function.
ToHash()
Returns the field configuration information in a HashRef.
my $HashRef = $Field->ToHash();Returns
{
'ChangeTime' => '2021-01-12 18:40:02',
'Name' => 'Unittesttest2136007680200002',
'FieldOrder' => 123,
'Label' => 'unittest',
'Internal' => 0,
'InternalField' => 0,
'CreateBy' => 10,
'Config' => {
'RegExList' => [
{
'ErrorMessage' => 'unit test',
'Value' => '^unittest(-\\d+)?$'
},
],
'DefaultValue' => 'unit-test',
'LinkPreview' => 'https://localhost',
'Link' => 'https://localhost'
},
'ValidID' => 1,
'CreateTime' => '2021-01-12 18:40:02',
'ObjectType' => 'Ticket',
'FieldType' => 'Text',
'ChangeBy' => 10
}PRIVATE INTERFACE
has _ObjectType
Attribute that holds the object type name.
_BuildObjectType()
Returns the object type module associated to the dynamic field.
_CreateValue()
Creates the final value representation.
my $Value = $DynamicField->_CreateValue(
Values => [
{
ObjectID => '...',
Value => '...',
}
];
);Returns
- a simple scalar
- an arrayref in case of multiple values._ValueColumn()
Should return the column value of the driver.
_ValueDBColumn()
Returns the database column where the value is stored.
_GetSetConfigKey()
Get/Sets values of the config keys. Drivers could implement something like:
sub DefaultValue {
my ( $Self, %Param, ) = @_;
return $Self->_GetSetConfigKey(
Key => 'DefaultValue',
Args => \%Param,
);
}
# Then the instance could do:
# Get value.
my $DefaultValue = $DynamicField->DefaultValue();
# Set Value.
my $DefaultValue = $DynamicField->DefaultValue( Value => 'something', );_GetObjectIDFromObjectName()
Get the object id from the given object name.
my $Value = $DynamicField->_GetObjectIDFromObjectName(
ObjectName => 'xyz',
);Returns
$ObjectID = 123;_MethodNotImplementedError()
Just calls a die saying that the method does not exist.
$DynamicField->_MethodNotImplementedError(
Method => 'Test',
);_ValueValidatePrimitive()
Should perform the basic validation according to the value type.
_BuildFilters()
Build the filters structure that is used in methods like 'ValueList', according to the supported params to filter and the dynamic field instance.
_ValueIsDifferentNormalizeValue()
Normalizes the value to be compared.
my $Value = $Self->_ValueIsDifferentNormalizeValue( Value => $Value );