• External custom fields
  • Description
  • Introduction into writing source of values
  • Configuration
  • How to write custom source

External custom fields

Description

External custom fields is extension to custom fields that allow you to define CF with a dynamic list of values. Loading values into this custom fields requires writing a little Perl code to fetch the data from the external source; the code that we added to RT 3.7 allows it to load data from arbitrary external sources.

Introduction into writing source of values

For each type of data source that you want, you'll need to put a file in /opt/rt3/local/lib/RT/CustomFieldValues/ (or equivilent if you installed RT someplace other than /opt/rt3). To get a sense of the code that you'll need to write, take a look at the code in "opt/rt3/lib/RT/CustomFieldValues/Groups.pm" for a simple example which just uses RT's API to pull in a list of RT's groups.

Running perldoc /opt/rt3/lib/RT/CustomFieldValues/External.pm will show you the documentation for the API that needs to be fulfilled, by copying and editing the Groups example is probably a fine place to start.

Later in this doc we'll describe the example a little bit more.

Configuration

After the custom code is written, you need to tell RT about its existence by adding something like following to your RT_SiteConfig.pm: Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource");

The value in quotes should be the name of the class that you created.

Stop and start your web server to enable any config changes. Open the web interface with as an administrative user (such as root) create new custom field. In order to use a custom source of values, you should select a custom field type that lets users pick values from a list, for example it could be Select * or a type with autocompletion. It shouldn't be Enter one value type as this type doesn't allow user to choose values. Other types that don't have a defined list of values are also unacceptable.

Save the changes, now you have ability to select a "source" for values. Choose the class you wrote from the list and save changes.

How to write custom source

You have to implement a subclass of RT::CustomFieldValues::External. There are two main methods you want to override:

SourceDescription

This method should return a string describing the data source; this is the identifier which the adimistrator will see in the dropdown in the web interface. See "Configuration".

ExternalValues

This method should return an array reference of hash references. The hash references should contain keys for name, description, and sortorder. name is most important one. The others are optional

Here's a simple static example:

  package RT::CustomFieldValues::MySource;
  
  # define class inheritance
  use base qw(RT::CustomFieldValues::External);

  # admin friendly description, the default valuse is the name of the class
  sub SourceDescription {
      return 'My Source';
  }
  
  # actual values provider method
  sub ExternalValues {
      # return reference to array ([])
      return [
          # each element of the array is a reference to hash that describe a value
          # possible keys are name, description and sortorder
          { name => 'value1', description => 'external value', sortorder => 1 },
          { name => 'value2', description => 'another external value', sortorder => 2 },
          # values without description are also valid, the default description is empty string
          { name => 'value3', sortorder => 3 },
          # you can skip sortorder too, but note that the default sortorder is 0 (zero)
          { name => 'value3' },
      ];
  }
  
  1; # don't forget to return some true value

That's all. Install and configure your class as described in the "Configuration" section.