NAME
RT::Extension::ConditionalCustomFields - CF conditioned by the value of
another CF
DESCRIPTION
This plugin provides the ability to display/edit a custom field
the "conditioned by custom field
throughout this documentation – conditioned by the value of another
custom field
"condition custom field
same object, which can be anything that can have custom fields (ticket
The condition can be setup on the Admin page for editing the conditioned
by custom field
version 0.99, any custom field
chosen as the condition custom field
for earlier version, only Select custom fields
eligible), and you can specify which operator is to be applied against
which value(s) for the condition to be met.
Available operators are:
* is
The condition is met if and only if the current value of the
instanciated conditioned by custom field
is equal to the value (or one of the values, see below for
multivalued condition) setup for this condition. With isn't operator
described below, is operator is the only one which is eligible for
selectable custom fields
Select, Combobox or Autocomplete type –, since their values are to
be selected from a set of values. For Date and DateTime custom
fields
operator is named on.
* isn't
The condition is met if and only if the current value of the
instanciated conditioned by custom field
from the value (or none of the values, see below for multivalued
condition) setup for this condition. With is operator described
above, isn't operator is the only one which is eligible for
selectable custom fields
Select, Combobox or Autocomplete type –, since their values are to
be selected from a set of values. For Date and DateTime custom
fields
operator is named not on.
* match
The condition is met if and only if the current value of the
instanciated conditioned by custom field
is included in the value setup for this condition, typically if the
current value is a substring of the condition value. As said above,
selectable custom fields
Select, Combobox or Autocomplete type are not eligible for this
operator. Also, Date and DateTime custom fields
not eligible for this operator.
* doesn't match
The condition is met if and only if the current value of the
instanciated conditioned by custom field
isn't included in the value setup for this condition, typically if
the current value isn't a substring of the condition value. As said
above, selectable custom fields
Select, Combobox or Autocomplete type are not eligible for this
operator. Also, Date and DateTime custom fields
not eligible for this operator.
* less than
The condition is met if and only if the current value of the
instanciated conditioned by custom field
is less than or equal to the value setup for this condition. The
comparison is achieved according to some kind of natural sort order
values are compared as numbers, strings are compared alphabetically,
insensitive to case and accents (a = á, a = A). Moreover, IP
Adresses (IPv4 and IPv6) are expanded to be compared as expected. As
said above, selectable custom fields
Select, Combobox or Autocomplete type are not eligible for this
operator.
* greater than
The condition is met if and only if the current value of the
instanciated conditioned by custom field
is greater than or equal to the value setup for this condition. The
comparison is achieved according to some kind of natural sort order
values are compared as numbers, strings are compared alphabetically,
insensitive to case and accents (a = á, a = A), and dates with or
without times are compared chronogically. Moreover, IP Adresses
(IPv4 and IPv6) are expanded to be compared as expected. As said
above, selectable custom fields
Select, Combobox or Autocomplete type are not eligible for this
operator.
* between
The condition is met if and only if the current value of the
instanciated conditioned by custom field
is greater than or equal to the first value setup for this condition
and is less than or equal to the second value setup for this
condition. That means that when this operator is selected, two
values have to be entered. The comparison is achieved according to
some kind of natural sort order
values are compared as numbers, strings are compared alphabetically,
insensitive to case and accents (a = á, a = A), and dates with or
without times are compared chronogically. Moreover, IP Adresses
(IPv4 and IPv6) are expanded to be compared as expected. As said
above, selectable custom fields
Select, Combobox or Autocomplete type are not eligible for this
operator.
As an exception, IPAddressRange custom fields
eligible as condition custom fields
there is not really any sense in comparing two ranges of IP addresses.
IPAddress custom fields
with between operator, should be sufficient for most cases checking
whether an IP address is included in a range.
If the condition custom field
selectable – with Select, Combobox or Autocomplete type – it can be
multivalued. Then, the condition for an object is met as soon as the
condition is met by at least one value of the instanciated conditioned
by custom field
this object.
If a custom field
on another (parent) custom field
conditioned by, this (child) custom field
course also be conditioned by (with the same condition as its parent).
Nevertheless, there is a caveheat in display mode: the order matters!
That is the parent custom field
have a lower sort order than the child custom field
From version 0.07, the condition can be multivalued, that is: the
conditioned custom field
displayed/edited if the condition custom field
these values (In other words: there is an OR bewteen the values of the
condition). The condition custom field
select custom field with values defined by CustomFieldValues
an external custom field
s.html>.
*Note that version 0.07 is a complete redesign: the API described below
has changed; also, the way that ConditionedBy property is store has
changed. If you upgrade from a previous version, you have to reconfigure
the custom fields which are conditionned by.*
Version 0.99 is also a complete redesign, with API changed, but backward
compatibility with previously configured custom fields
the default condition operator is is.
From version 1.13, HTML custom fields
in RT 5.0.3 can be defined as condition CustomField
RT VERSION
Works with RT 4.2 or greater
INSTALLATION
perl Makefile.PL
make
make install
May need root permissions
Patch your RT
ConditionalCustomFields still requires a small patch to add
necessary Callbacks on versions of RT superior to 4.2.3.
The patch has now been integrated by BestPractical and will be
included in future RT releases strictly greater than 5.0.5. In other
words patching is still needed on versions of RT up to 5.0.5, but
not necessary for versions of RT greater than 5.0.5.
For RT 4.2, apply the included patch:
cd /opt/rt4 # Your location may be different
patch -p1 < /download/dir/RT-Extension-ConditionalCustomFields/patches/4.2-add-callbacks-to-extend-customfields-capabilities.patch
For RT 4.4.1, apply the included patch:
cd /opt/rt4 # Your location may be different
patch -p1 < /download/dir/RT-Extension-ConditionalCustomFields/patches/4.4.1-add-callbacks-to-extend-customfields-capabilities.patch
For RT 4.4.2 or greater, apply the included patch:
cd /opt/rt4 # Your location may be different
patch -p1 < /download/dir/RT-Extension-ConditionalCustomFields/patches/4.4.2-add-callbacks-to-extend-customfields-capabilities.patch
For RT 5.0.0 to 5.0.5, apply the included patch:
cd /opt/rt5 # Your location may be different
patch -p1 < /download/dir/RT-Extension-ConditionalCustomFields/patches/5.0-add-callbacks-to-extend-customfields-capabilities.patch
Edit your /opt/rt5/etc/RT_SiteConfig.pm
If you are using RT 4.2 or greater, add this line:
Plugin('RT::Extension::ConditionalCustomFields');
For RT 4.0, add this line:
Set(@Plugins, qw(RT::Extension::ConditionalCustomFields));
or add RT::Extension::ConditionalCustomFields to your existing
@Plugins line.
Clear your mason cache
rm -rf /opt/rt5/var/mason_data/obj
Restart your webserver
CONFIGURATION
Usually, groupings of custom fields, as defined in $CustomFieldGroupings
configuration variable, is *not* enabled in SelfService. This is the
case if you use RT Core. Anyway, some RT instances could have overridden
this restriction to enable groupings of custom fields in SelfService.
In this case, you should add to your configuration file
(/opt/rt5/etc/RT_SiteConfig.pm) the following line, setting
$SelfServiceCustomFieldGroupings configuration variable to a true value:
Set($SelfServiceCustomFieldGroupings, 1);
METHODS
ConditionalCustomFields adds a ConditionedBy property, that is a
condition CustomField
operator and one or more values, along with the following methods, to
conditioned by CustomField
SetConditionedBy CF, OP, VALUE
Set the ConditionedBy property for this CustomField
CustomField
operator set to OP and value set to VALUE. CF should be an existing
CustomField
the id of an existing CustomField
the name of an unambiguous existing CustomField
should be is, isn't, match, doesn't match, less than, greater than or
between. VALUE should be a string or an anonymous array of strings (for
selectable custom fields
operator). Current user should have SeeCustomField and ModifyCustomField
rights for this conditioned by CustomField
SeeCustomField right for the condition CustomField
(1, 'Status message') on success and (0, 'Error Message') on failure.
ConditionedBy
Returns the current ConditionedBy property for this conditioned by
CustomField
a hash with keys CF containing the id of the condition CustomField
vals containing the condition operator as string, and the condition
value as an array of strings (so we can store several values for
selectable custom fields
operator, but generally the vals array includes only one string). If
neither this conditioned by CustomField
its ancestor is conditioned by the CF condition CustomField
if their ConditionedBy property is not (recursively) defined, returns
undef. Current user should have SeeCustomField right for both this
conditioned by CustomField
condition CustomField
CustomField
conditioned recursively by. *"Recursively"* means that this method will
search for a ConditionedBy property for this CustomField
then for the CustomField
is BasedOn, and so on until it finds an ancestor Category with a
ConditionedBy property or, the CustomField
being looked up, is not based on any ancestor Category.
INITIALDATA
Also, ConditionalCustomFields allows to set the ConditionedBy property
when creating CustomFields
initialdata file, with one of the following syntaxes:
@CustomFields = (
{
Name => 'Condition',
Type => 'SelectSingle',
RenderType => 'Dropdown',
Queue => [ 'General' ],
LookupType => 'RT::Queue-RT::Ticket',
Values => [
{ Name => 'Passed', SortOrder => 0 },
{ Name => 'Failed', SortOrder => 1 },
{ Name => 'Schrödingerized', SortOrder => 2 },
],
Pattern => '(?#Mandatory).',
DefaultValues => [ 'Failed' ],
},
{
Name => 'Conditioned with cf name and value',
Type => 'FreeformSingle',
Queue => [ 'General' ],
LookupType => 'RT::Queue-RT::Ticket',
ConditionedByCF => 'Condition',
ConditionedBy => 'Passed',
},
{
Name => 'Conditioned with cf id and value',
Type => 'FreeformSingle',
Queue => [ 'General' ],
LookupType => 'RT::Queue-RT::Ticket',
ConditionedByCF => 66,
ConditionOp => "isn't",
ConditionedBy => 'Failed',
},
{
Name => 'Conditioned with multiple values',
Type => 'Freeform',
MaxValues => 1,
Queue => [ 'General' ],
LookupType => 'RT::Queue-RT::Ticket',
ConditionedByCF => 'Condition',
ConditionedBy => ['Passed', 'Schrödingerized'],
},
);
This examples creates a Select condition CustomField
Condition and three conditioned by CustomFields
CustomField
should have the value Passed, for CustomField
Conditioned with cf name and value to be displayed or edited.
CustomField
should not have the value Failed for CustomField
Conditioned with cf id and value to be displayed or edited. CustomField
should have one of the values Passed or Schrödingerized for CustomField
Conditioned with multiple values to be displayed or edited.
Additional fields for an element of @CustomFields are:
ConditonedByCF
The condition CustomField
this new CustomField
conditioned by. It can be either the id or the Name of a previously
created CustomField
implies that the condition CustomField
be declared before this one in the initialdata file, or it should
already exist. When ConditionedByCF attribute is set, ConditionedBy
field should always also be set.
ConditonedBy
The value as a string of the condition CustomField
defined by the ConditionedByCF field (which is mandatory).
ConditonOp
The operator as a string to use for comparison, either is, isn't,
match, doesn't match, less than, greater than or between. This field
is optional, defaults to is.
TEST SUITE
ConditionalCustomFields comes with a fairly complete test suite. As for
every RT extention
to run it, you will need a installed RT, set up in development mode
since ConditionalCustomFields operates dynamically to show or hide
custom fields
its magic happens in Javascript. Therefore, the test suite requires a
scriptable headless browser with Javascript capabilities. So you also
need to install PhantomJS <http://phantomjs.org/>, along with
WWW::Mechanize::PhantomJS and Selenium::Remote::Driver.
It should be noted that with version 0.99, the number of cases to test
has exponentially expanded. Not only any object which can have custom
tested. But also, any type of custom fields
Freeform, Text, Wikitext, Image, Binary, Combobox, Autocomplete, Date,
DateTime and IPAddress) should be tested both for condition custom field
conditioned by custom field
both for Single and Multiple versions (when available) of each type of
custom fields
custom fields
also be tested for each render type (Select box, List, Dropdown and also
Chosen when the number of values is greater than ten). Adding to these
required unitary tests, some special cases should also be included, for
instance when a condition custom field
conditioned by another condition custom field
condition custom field
applied to a queue
Eventually, the test suite includes 1929 unitary tests and 64 test
files. Nevertheless some special cases may have been left over, so
you're encourage to fill a bug report, so they can be fixed.
AUTHOR
Gérald Sédrati <gibus@easter-eggs.com>
REPOSITORY
BUGS
All bugs should be reported via email to
bug-RT-Extension-ConditionalCustomFields@rt.cpan.org
<mailto:bug-RT-Extension-ConditionalCustomFields@rt.cpan.org>
or via the web at
rt.cpan.org
alCustomFields>.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2017-2023 by Gérald Sédrati, Easter-Eggs
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007