rt/lib/RT/Extension/ExtractCustomFieldValues.pm

   1 use warnings;
   2 use strict;
   3
   4 package RT::Extension::ExtractCustomFieldValues;
   5
   6 =head1 NAME
   7
   8 RT::Extension::ExtractCustomFieldValues - extract CF values from email headers or body
   9
  10 =cut
  11
  12 our $VERSION = '3.07';
  13
  14 1;
  15
  16 =head1 DESCRIPTION
  17
  18 ExtractCustomFieldValues is based on a scrip action
  19 "ExtractCustomFieldValues", which can be used to scan incoming emails
  20 to set values of custom fields.
  21
  22 =head1 INSTALLATION
  23
  24     perl Makefile.PL
  25     make
  26     make install
  27     make initdb # first time only, not on upgrades
  28
  29 When using this extension with RT 3.8, you will need to add
  30 extension to the Plugins configuration:
  31
  32     Set( @Plugins, qw(... RT::Extension::ExtractCustomFieldValues) );
  33
  34 If you are upgrading this extension from 3.05 or earlier, you will
  35 need to read the UPGRADING file after running make install to add
  36 the new Scrip Action.
  37
  38 =head1 USAGE
  39
  40 To use the ScripAction, create a Template and a Scrip in RT.
  41 Your new Scrip should use a ScripAction of 'Extract Custom Field Values'.
  42 The Template consists of the lines which control the scanner. All
  43 non-comment lines are of the following format:
  44
  45     <cf-name>|<Headername>|<MatchString>|<Postcmd>|<Options>
  46
  47 where:
  48
  49 =over 4
  50
  51 =item <cf-name> - the name of a custom field (must be created in RT) If this
  52 field is blank, the match will be run and Postcmd will be executed, but no
  53 custom field will be updated. Use this if you need to execute other RT code
  54 based on your match.
  55
  56 =item <Headername> - either a Name of an email header, "body" to scan the body
  57 of the email or "headers" to search all of the headers.
  58
  59 =item <MatchString> - a regular expression to find a match in the header or
  60 body if the MatchString matches a comma separated list and the CF is a multi
  61 value CF then each item in the list is added as a separate value.
  62
  63 =item <Postcmd>  - a perl code to be evaluated on C<$value>, where C<$value> is
  64 either $1 or full match text from the match performed with <MatchString>
  65
  66 =item <Options> - a string of letters which may control some aspects.  Possible
  67 options include:
  68
  69 =over 4
  70
  71 =item 'q' - (quiet) Don't record a transaction when adding the custom field value
  72
  73 =item '*' - (wildcard) The MatchString regex should contain _two_ capturing
  74 groups, the first of which is the CF name, the second of which is the value.
  75 If this option is given, the <cf-name> field is ignored.
  76
  77 =back
  78
  79 =back
  80
  81 =head2 Separator
  82
  83 You can change the separator string (initially "\|") during the
  84 template with:
  85
  86     Separator=<anyregexp>
  87
  88 Changing the separator may be necessary, if you want to use a "|" in
  89 one of the patterns in the controlling lines.
  90
  91 =head2 Example and further reading
  92
  93 An example template with some further examples is installed during
  94 "make install" or "make insert-template". See the
  95 CustomFieldScannerExample template for examples and further
  96 documentation.
  97
  98 =head1 AUTHOR
  99
 100 This extension was originally written by Dirk Pape
 101 E<lt>pape@inf.fu-berlin.deE<gt>.
 102
 103 This version is modified by Best Practical for customer use
 104 and maintained by Best Practical Solutions.
 105
 106 =head1 BUGS
 107
 108 Report bugs using L<http://rt.cpan.org> service, discuss on RT's
 109 mailing lists, see also L</SUPPORT>
 110
 111 =head1 SUPPORT
 112
 113 Support requests should be referred to Best Practical
 114 E<lt>sales@bestpractical.comE<gt>.
 115
 116 =cut