Project has left GitHub

It is now here: https://codeberg.org/a-j-wood/rt-extension-filterrules

This project was briefly hosted on GitHub. GitHub is a proprietary, trade-secret system that is not Free and Open Source Software (FOSS).

Read about the Give up GitHub campaign from the Software Freedom Conservancy to understand some of the reasons why GitHub is not a good place to host FOSS projects.

Any use of this project's code by GitHub Copilot, past or present, is done without permission. The project owner does not consent to GitHub's use of this project's code in Copilot.

NAME

RT::Extension::FilterRules - Filter incoming tickets through rule sets

DESCRIPTION

This extension provides a way for non-technical users to set up ticket filtering rules which perform actions on tickets when they arrive in a queue.

Filter rules are grouped into filter rule groups. The RT administrator defines the criteria a ticket must meet to be processed by each filter rule group, and defines which RT groups can manage the filter rules in each rule group.

For each applicable filter rule group, the rules are checked in order, and any actions for matching rules are performed on the ticket. If a matching rule says that processing must then stop, processing of the rules in that filter rule group will end, and the next rule group will then be considered.

Filter rules are managed under Tools - Filter rules.

REQUIREMENTS

Requires Email::Address and HTML::FormatText.

RT VERSION

Known to work with RT 4.2.16, 4.4.4, and 5.0.1.

INSTALLATION

• perl Makefile.PL

• make

• make install

  May need root permissions.

• Set up the database

  After running make install for the first time, you will need to create the database tables for this extension. Use etc/schema-mysql.sql for MySQL or MariaDB, or etc/schema-postgresql.sql for PostgreSQL.

• Edit your /opt/rt4/etc/RT_SiteConfig.pm

  Add this line:

    Plugin('RT::Extension::FilterRules');
  

• Clear your Mason cache

    rm -rf /opt/rt4/var/mason_data/obj
  

• Restart your web server

• Add the processing scrip

  Create a new global scrip under Admin - Global - Scrips:

  • Description:

    Filter rule processing

  • Condition:

    User Defined

  • Action:

    User Defined

  • Template:

    Blank

  • Stage:

    Normal

  • Custom condition:

      return 0 if (not $RT::Extension::FilterRules::VERSION);
      return RT::Extension::FilterRules->ScripIsApplicable($self);
    

  • Custom action preparation code:

      return 0 if (not $RT::Extension::FilterRules::VERSION);
      return RT::Extension::FilterRules->ScripPrepare($self);
    

  • Custom action commit code:

      return 0 if (not $RT::Extension::FilterRules::VERSION);
      return RT::Extension::FilterRules->ScripCommit($self);
    

  No filter rules will actually perform any actions until this scrip is created and enabled.

  Note that the return 0 lines are only there to prevent errors if you later remove this extension without disabling the scrip.

• Set up some filter rule groups

  Rule groups are set up by the RT administrator under Admin - Filter rule groups.

TUTORIAL

For the purposes of this tutorial, we assume that you have these queues:

• "General" - for general queries;
• "Technical" - for more technical matters to be escalated to.

We also assume that you have these user-defined groups set up:

• "Service desk" - containing all first-line analysts;
• "Service desk management" - containing the leadership team for the service desk;
• "Third line" - containing all technical teams.

These are only examples for illustration, there is no need for your system to be set up this way to use it with this extension.

Create a new filter rule group

1. As a superuser, go to Admin - Filter rule groups - Create.

2. Provide a name for the new filter rule group, such as "General inbound message filtering", and click on the Create button.

3. Now that the filter rule group has been created, you can define the queues and groups it can use.

   Next to Queues to allow in match rules, select your General queue and click on the Add queue button.

4. You will see the General queue is now listed next to Queues to allow in match rules. If you select it and click on the Save Changes button, the queue will be removed from the list.

   If you tried that, add it back again before the next step.

5. Rules in this filter rule group need to be able to transfer tickets into the Technical queue, so next to Queues to allow as transfer destinations, select your Technical queue and click on the Add queue button.

6. Add the Service desk and Third line groups to Groups to allow in rule actions to be able to use them in filter rules, such as sending notifications to members of those groups.

After saving your changes, go back to Admin - Filter rule groups, and you will see your new filter rule group and its settings.

Once you have more than one, you can move them up and down in the list to control the order in which they are processed, using the Up and Down links at the right.

Set the requirements for the filter rule group

A filter rule group will not process any messages unless its requirements are met. Each one starts off with no requirements, so will remain inactive until you define some.

From Admin - Filter rule groups, click on your new filter rule group, and then choose Requirements from the page menu at the top.

Click on the Create new requirement rule button to create a new requirement rule for that filter rule group.

1. Give the requirement rule a name, such as "Created in the General queue".

2. Set the trigger type. This rule will be processed when an event of this type occurs, and skipped over otherwise. The available trigger types are "On ticket creation" and "When a ticket moves between queues"; for this example, select "On ticket creation".

3. Choose the conflict conditions. If any of these conditions are met, the rule will not match. For this example, leave this empty.

4. Choose the requirement conditions. All of these conditions must be met for the rule to match. Click on the Add condition button, choose "In queue", and select the "General" queue.

   For each condition, although all of the conditions must be met, you can specify multiple values for each condition using the Add value button for that condition. This means that the condition will be met if any one of its values matches.

5. Click on the Create button to create the new requirement rule.

In the list of requirement rules, click on a rule's number or name to edit it.

Add as many requirement rules as you need. They can be switched off temporarily by marking them as disabled.

Delegate control of the filter rule group

In this example, the new filter rule group you created above, called General inbound message filtering, is going to be managed by the service desk management team. This means that you want them to be able to create, update, and delete filter rules within that group with no assistance.

We will also allow the service desk team to view the filter rules, so that they have visibility of what automated processing is being applied to tickets they are receiving.

1. From Admin - Filter rule groups, click on your new filter rule group, and then choose Group Rights from the page menu at the top.
2. In the text box under ADD GROUP at the bottom left, type "Service desk management" but do not hit Enter.
3. On the right side of the screen, under Rights for Staff, select all of the rights so that the management team can fully control the filter rules in this filter rule group.
4. Click on the Save Changes button at the bottom right to grant these rights.
5. In the text box under ADD GROUP at the bottom left, type "Service desk" but do not hit Enter.
6. On the right side of the screen, under Rights for Staff, select only the View filter rules right, so that the service desk analysts can only view these filter rules, not edit them.
7. Click on the Save Changes button at the bottom right to grant these rights.

Members of the Service desk management group will now be able to manage the filter rules of the General inbound message filtering filter rule group, under the Tools - Filter rules menu.

Members of the Service desk group will be able to see those rules there too, but will not be able to modify them.

Creating filter rules

RT super users can edit filter rules by starting from Admin - Filter rule groups - Select, choosing a filter rule group, and then choosing Filters from the page menu at the top.

Members of the groups you delegated access to in the steps above can edit the filter rules by going to Tools - Filter rules. If they have access to more than one filter rule group, they can then choose which one's rules to edit from the list provided.

Click on the Create new filter rule button to create a new filter rule.

1. Give the filter rule a name, such as "Escalate desktop wallpaper requests".

2. Set the trigger type, as with the requirement rule above. For this example, select "On ticket creation".

3. Choose the conflict conditions, as with the requirement rule above. For this example, click on the Add condition button, choose "Subject or message body contains", and type paste into the box next to it.

4. Choose the requirement conditions, as with the requirement rule above. For this example:

   • Click on the Add condition button, choose a "In queue", and select the "General" queue.
   • Click on the Add condition button again, choose "Subject or message body contains", and type wallpaper into the box next to it.
   • Click on the Add value button underneath the box containing wallpaper and type background into the box that appears.
   • Click on the Add condition button again, choose "Subject or message body contains", and type desktop into the box next to it.

5. Choose the actions to perform when this rule is matched. For this example, click on the Add action button, choose "Move to queue", and select the "Technical" queue.

6. Choose whether to stop processing any further rules in this filter rule group when this particular filter rule is matched.

   By default, this is set to "No", which means that even if this rule matches, the rules after it will still be checked too.

   For this example, leave it set to "No".

Click on the Create button to create the new filter rule. You will see a message something like Filter rule 15 created. Click on the Back button below that message to return to the list of filter rules.

Your new rule will be shown in the list. The conflicts, requirements, and actions are detailed in the list. You will see that this new rule:

• Will never match, if the subject or message body contains the word paste.
• Will match otherwise, if the ticket was created in the General queue, and its subject or message body contains either of the words wallpaper or background, and its subject or message body contains the word desktop.
• When the rule matches, it will move the ticket to the Technical queue.

For example, if someone creates a ticket in the General queue mentioning desktop wallpaper or desktop background, the ticket will be moved to the Technical queue, but if they mention desktop wallpaper paste, the ticket will not be moved because of the conflict condition about the word paste.

Usually you would not actually move tickets based on keyword matches, this is just an example - though you may want to send notification emails when certain words appear, or set custom field values or priorities, for instance.

Filter rules are processed in order. In the list of filter rules, use the [Up] and [Down] links to move filter rules up and down.

Testing filter rules

Filter rules can be tested without having to really create new tickets or move them between queues, but you will need an existing ticket to use as a point of reference.

From either Tools - Filter rules or Admin - Filter rule groups, choose the Test option from the page menu at the top right.

1. Choose a ticket to test against. This is used in rules regarding ticket subject, message body, and so on.
2. Choose which filter rule group to test against, or "All" to run the test against all filter rule groups you have access to.
3. Select the type of triggering event to simulate.
4. Choose the queue or queues involved in the simulation. For instance, if you are simulating ticket creation, choose which queue to pretend it is being created in.
5. Choose whether to include disabled rules in the test. This can be useful if you would like to set up new filter rules and test them before using them - you can create them but leave them disabled, then run this test with disabled rules included.

Click on the Test button to run the test; the results will be shown in the Results section below the input form.

The test will not make any changes to tickets or to filter rules.

For each filter rule group, the requirement rules will be processed, and a detailed breakdown of the steps involved will be displayed.

If any requirement rules matched, then a breakdown the filter rules will be shown, followed by the actions which those filter rules would give rise to.

The Rule, Match type, and Outcome of test columns show the overall outcome of each rule. The Conflict conditions and Requirement conditions columns give details of all of the individual conditions within each rule.

Within the rule processing steps, the Event value refers to the value taken from the event - for instance, in a subject matching condition, this would be the ticket's subject. The Target value refers to the value the condition is looking for - that is, the values you entered into the form when creating the filter rules.

INTERNAL FUNCTIONS

These functions are used internally by this extension. They should all be called as methods, like this:

return RT::Extension::FilterRules->ScripIsApplicable($self);

ScripIsApplicable $Condition

The "is-applicable" condition of the scrip which applies filter rules to tickets. Returns true if it is appropriate for this extension to investigate the action associated with this scrip.

ScripPrepare $Action

The "prepare" action of the scrip which applies filter rules to tickets. Returns true on success.

ScripCommit $Action

The "commit" action of the scrip which applies filter rules to tickets. Returns true on success.

ConditionTypes $UserObj

Return an array of all available condition types, with the names localised for the given user.

Each array entry is a hash reference containing these keys:

• ConditionType

  The internal name for this condition type; this should follow the naming convention for variables - start with a letter, no spaces, and so on - and it must be unique

• Name

  Localised name, to be displayed to the operator

• TriggerTypes

  Array reference listing the trigger actions with which this condition can be used (as listed under the TriggerType attribute of the RT::FilterRule class below), or an empty array reference (or undef) if this condition type can be used with all trigger types

• ValueType

  Which type of value the condition expects as a parameter - one of None, String, Integer, Email, Queue, or Status

• Function

  If present, this is a code reference which will be called to check this condition; this code reference will be passed an RT::CurrentUser object and a hash of the parameters from inside an RT::FilterRule::Condition object (including TargetValue), as it will be called from the TestSingleValue method of RT::FilterRule::Condition - like TestSingleValue, it should return ( $matched, $message, $eventvalue ).

If Function is not present, the TestSingleValue method of RT::FilterRule::Condition will attempt to call an RT::FilterRule::Condition method of the same name as ConditionType with _ prepended, returning a failed match (and logging an error) if such a method does not exist.

Note that if ConditionType contains the string CustomField, then the condition will require the person creating the condition to select an applicable custom field.

ActionTypes $UserObj

Return an array of all available action types, with the names localised for the given user.

Each array entry is a hash reference containing these keys:

• ActionType

  The internal name for this action type; this should follow the naming convention for variables - start with a letter, no spaces, and so on - and it must be unique

• Name

  Localised name, to be displayed to the operator

• ValueType

  Which type of value the action expects as a parameter - one of None, String, Integer, Email, Group, Queue, Status, or HTML

• Function

  If present, this is a code reference which will be called to perform this action; this code reference will be passed an RT::CurrentUser object and a hash of the parameters from inside an RT::FilterRule::Action object, as it will be called from the Perform method of RT::FilterRule::Action - it should return ( $ok, $message )

If Function is not present, the Perform method of RT::FilterRule::Action will attempt to call an RT::FilterRule::Action method of the same name as ActionType with _ prepended, returning a failed action (and logging an error) if such a method does not exist.

Note that:

• If ActionType contains the string CustomField, then a custom field must be selected by the person creating the action, separately to the value, and this will populate the RT::FilterRule::Action's CustomField attribute;
• If ActionType contains the string NotifyEmail, then an email address must be entered by the person creating the action, separately to the value, and this will populate the RT::FilterRule::Action's Notify attribute;
• If ActionType contains the string NotifyGroup, then an RT group must be selected by the person creating the action, separately to the value, and this will populate the RT::FilterRule::Action's Notify attribute.

AddConditionProvider CODEREF

Add a condition provider, which is a function accepting an RT::CurrentUser object and returning an array of the same form as the ConditionTypes method.

The ConditionTypes method will call the provided code reference and append its returned values to the array it returns.

Other extensions can call this method to add their own filter condition types.

AddActionProvider CODEREF

Add an action provider, which is a function accepting an RT::CurrentUser object and returning an array of the same form as the ActionTypes method.

The ActionTypes method will call the provided code reference and append its returned values to the array it returns.

Other extensions can call this method to add their own filter action types.

Internal package RT::FilterRuleGroup

This package provides the RT::FilterRuleGroup class, which describes a group of filter rules through which a ticket will be passed if it meets the basic requirements of the group.

The attributes of this class are:

• id

  The numeric ID of this filter rule group

• SortOrder

  The order of processing - filter rule groups with a lower sort order are processed first

• Name

  The displayed name of this filter rule group

• CanMatchQueues

  The queues which rules in this rule group are allowed to use in their conditions, as a comma-separated list of queue IDs (also presented as an RT::Queues object via CanMatchQueuesObj)

• CanTransferQueues

  The queues which rules in this rule group are allowed to use as transfer destinations in their actions, as a comma-separated list of queue IDs (also presented as an RT::Queues object via CanTransferQueuesObj)

• CanUseGroups

  The groups which rules in this rule group are allowed to use in match conditions and actions, as a comma-separated list of group IDs (also presented as an RT::Groups object via CanUseGroupsObj)

• Creator

  The numeric ID of the creator of this filter rule group (also presented as an RT::User object via CreatorObj)

• Created

  The date and time this filter rule group was created (also presented as an RT::Date object via CreatedObj)

• LastUpdatedBy

  The numeric ID of the user who last updated the properties of this filter rule group (also presented as an RT::User object via LastUpdatedByObj)

• LastUpdated

  The date and time this filter rule group's properties were last updated (also presented as an RT::Date object via LastUpdatedObj)

• Disabled

  Whether this filter rule group is disabled; the filter rule group is active unless this property is true

The basic requirements of the filter rule group are defined by its GroupRequirements, which is a collection of RT::FilterRule objects whose IsGroupRequirement attribute is true. If any of these rules match, the ticket is eligible to be passed through the filter rules for this group.

The filter rules for this group are presented via FilterRules, which is a collection of RT::FilterRule objects.

Filter rule groups themselves can only be created, modified, and deleted by users with the SuperUser right.

The following rights can be assigned to individual filter rule groups to delegate control of the filter rules within them:

• SeeFilterRule

  View the filter rules in this filter rule group

• ModifyFilterRule

  Modify existing filter rules in this filter rule group

• CreateFilterRule

  Create new filter rules in this filter rule group

• DeleteFilterRule

  Delete filter rules from this filter rule group

These are assigned using the rights pages of the filter rule group, under Admin - Filter rule groups.

RT::FilterRuleGroup METHODS

Note that additional methods will be available, inherited from RT::Record.

Create Name => Name, ...

Create a new filter rule group with the supplied properties, as described above. The sort order will be set to 1 more than the highest current value so that the new item appears at the end of the list.

Returns ( $id, $message ), where $id is the ID of the new object, which will be undefined if there was a problem.

CanMatchQueues

Return the queues which rules in this rule group are allowed to use in their conditions, as a comma-separated list of queue IDs in a scalar context, or as an array of queue IDs in a list context.

CanMatchQueuesObj

Return the same as CanMatchQueues, but as an RT::Queues object, i.e. a collection of RT::Queue objects.

CanTransferQueues

Return the queues which rules in this rule group are allowed to use as transfer destinations in their actions, as a comma-separated list of queue IDs in a scalar context, or as an array of queue IDs in a list context.

CanTransferQueuesObj

Return the same as CanTransferQueues, but as an RT::Queues object, i.e. a collection of RT::Queue objects.

CanUseGroups

Return the groups which rules in this rule group are allowed to use in match conditions and actions, as a comma-separated list of group IDs in a scalar context, or as an array of group IDs in a list context.

CanUseGroupsObj

Return the same as CanUseGroups, but as an RT::Groups object, i.e. a collection of RT::Group objects.

SetCanMatchQueues id, id, ...

Set the queues which rules in this rule group are allowed to use in their conditions, either as a comma-separated list of queue IDs, an array of queue IDs, an array of RT::Queue objects, or an RT::Queues collection.

Returns ( $ok, $message ).

SetCanTransferQueues id, id, ...

Set the queues which rules in this filter rule group are allowed to use as transfer destinations in their actions, either as a comma-separated list of queue IDs, an array of queue IDs, an array of RT::Queue objects, or an RT::Queues collection.

Returns ( $ok, $message ).

SetCanUseGroups id, id, ...

Set the groups which rules in this rule group are allowed to use in match conditions and actions, either as a comma-separated list of group IDs, an array of group IDs, an array of RT::Group objects, or an RT::Groups collection.

Returns ( $ok, $message ).

GroupRequirements

Return an RT::FilterRules collection object containing the requirements of this filter rule group - if an event matches any of these requirement rules, then the caller should process the event through the FilterRules for this group.

AddGroupRequirement Name => NAME, ...

Add a requirement rule to this filter rule group; calls the RT::FilterRule Create method, overriding the FilterRuleGroup and IsGroupRequirement parameters, and returns its output.

FilterRules

Return an RT::FilterRules collection object containing the filter rules for this rule group.

AddFilterRule Name => NAME, ...

Add a filter rule to this filter rule group; calls the RT::FilterRule Create method, overriding the FilterRuleGroup and IsGroupRequirement parameters, and returns its output.

Delete

Delete this filter rule group, and all of its filter rules. Returns ( $ok, $message ).

CheckGroupRequirements RuleChecks => [], TriggerType => ...,

For the given event, append details of checked group requirements to the RuleChecks array reference.

A Ticket should be supplied, either as an ID or as an RT::Ticket object.

Returns ( $Matched, $Message, $EventValue, $TargetValue ), where $Matched will be true if there were any requirement rule matches (meaning that the caller should pass the event through this filter rule group's FilterRules), false if there were no matches. The other returned values will relate to the last requirements rule matched.

If IncludeDisabled is true, then even rules marked as disabled will be checked. The default is false.

If DescribeAll is true, then all conditions for all requirement rules will be added to RuleChecks regardless of whether they influenced the outcome; this can be used to present the operator with details of how an event would be processed.

If RecordMatch is true, then the fact that a rule is matched will be recorded in the database (see RT::FilterRuleMatch). The default is not to record the match.

A Cache should be provided, pointing to a hash reference to store information in while processing this event, which the caller should share with the CheckFilterRules method and other instances of this class, for the same event.

See the RT::FilterRule TestRule method for more details of these return values, for the structure of the RuleChecks and Actions array entries, and for the event structure.

CheckFilterRules RuleChecks => [], Actions => [], TriggerType => ...,

For the given event, append details of matching filter rules to the RuleChecks array reference, and append details of the actions which should be performed due to those matches to the Actions array reference.

A Ticket should be supplied, either as an ID or as an RT::Ticket object.

If IncludeDisabled is true, then even rules marked as disabled will be checked. The default is false.

If DescribeAll is true, then all conditions for all filter rules will be added to RuleChecks regardless of whether they influenced the outcome; this can be used to present the operator with details of how an event would be processed.

If RecordMatch is true, then the fact that a rule is matched will be recorded in the database (see RT::FilterRuleMatch). The default is not to record the match.

A Cache should be provided, pointing to a hash reference to store information in while processing this event, which the caller should share with the CheckGroupRequirements method and other instances of this class, for the same event.

Returns ( $Matched, $Message, $EventValue, $TargetValue ), where $Matched will be true if there were any filter rule matches, false otherwise, and the other parameters will be related to the last rule matched.

See the RT::FilterRule TestRule method for more details of these return values, for the structure of the RuleChecks and Actions array entries, and for the event structure.

MoveUp

Move this filter rule group up in the sort order so it is processed earlier. Returns ( $ok, $message ).

MoveDown

Move this filter rule group down in the sort order so it is processed later. Returns ( $ok, $message ).

Move OFFSET

Change this filter rule group's sort order by the given OFFSET.

_Set Field => FIELD, Value => VALUE

Set the value of a field, recording a transaction in the process if appropriate. Returns ( $ok, $message ).

CurrentUserCanSee

Return true if the current user has permission to see this object.

_CoreAccessible

Return a hashref describing the attributes of the database table for the RT::FilterRuleGroup class.

Internal package RT::FilterRuleGroups

This package provides the RT::FilterRuleGroups class, which describes a collection of filter rule groups.

Internal package RT::FilterRule

This package provides the RT::FilterRule class, which describes a filter rule - the conditions it must meet, the conditions it must not meet, and the actions to perform on the ticket if the rule matches.

The attributes of this class are:

• id

  The numeric ID of this filter rule

• FilterRuleGroup

  The numeric ID of the filter rule group to which this filter rule belongs (also presented as an RT::FilterRuleGroup object via FilterRuleGroupObj)

• IsGroupRequirement

  Whether this is a filter rule which describes requirements for the filter rule group as a whole to be applicable (true), or a filter rule for processing an event through and performing actions if matched (false).

  This is true for requirement rules under a rule group's GroupRequirements, and false for filter rules under a rule group's FilterRules.

  This attribute is set automatically when a RT::FilterRule object is created via the AddGroupRequirement and AddFilterRule methods of RT::FilterRuleGroup.

• SortOrder

  The order of processing - filter rules with a lower sort order are processed first

• Name

  The displayed name of this filter rule

• TriggerType

  The type of action which triggers this filter rule - one of:

  • Create

    Consider this rule on ticket creation

  • QueueMove

    Consider this rule when the ticket moves between queues

• StopIfMatched

  If this is true, then processing of the remaining rules in this filter rule group should be skipped if this rule matches (this field is unused for filter rule group requirement rules, i.e. where IsGroupRequirement is 1)

• Conflicts

  Conditions which, if any are met, mean this rule cannot match; this is presented as an array of RT::FilterRule::Condition objects, and stored as a Base64-encoded string encoding an array ref containing hash refs.

• Requirements

  Conditions which, if all are met, mean this rule matches, so long as none of the conflict conditions above have matched; this is also presented as an array of RT::FilterRule::Condition objects, and stored in the same way as above.

• Actions

  Actions to carry out on the ticket if the rule matches (this field is unused for filter rule group requirement rules, i.e. where IsGroupRequirement is 1); it is presented as an array of RT::FilterRule::Action objects, and stored as a Base64-encoded string encoding an array ref containing hash refs.

• Creator

  The numeric ID of the creator of this filter rule (also presented as an RT::User object via CreatorObj)

• Created

  The date and time this filter rule was created (also presented as an RT::Date object via CreatedObj)

• LastUpdatedBy

  The numeric ID of the user who last updated the properties of this filter rule (also presented as an RT::User object via LastUpdatedByObj)

• LastUpdated

  The date and time this filter rule's properties were last updated (also presented as an RT::Date object via LastUpdatedObj)

• Disabled

  Whether this filter rule is disabled; the filter rule is active unless this property is true

RT::FilterRule METHODS

Note that additional methods will be available, inherited from RT::Record.

Create Name => Name, ...

Create a new filter rule with the supplied properties, as described above. The sort order will be set to 1 more than the highest current value so that the new item appears at the end of the list.

Returns ( $id, $message ), where $id is the ID of the new object, which will be undefined if there was a problem.

FilterRuleGroupObj

Return an RT::FilterRuleGroup object containing this filter rule's filter rule group.

Conflicts

Return an array of RT::FilterRule::Condition objects describing the conditions which, if any are met, mean this rule cannot match.

SetConflicts CONDITION, CONDITION, ...

Set the conditions which, if any are met, mean this rule cannot match. Expects an array of RT::FilterRule::Condition objects.

DescribeConflicts

Return HTML, localised to the current user, describing the conflict conditions. Uses DescribeConditions.

Requirements

Return an array of RT::FilterRule::Condition objects describing the conditions which, if all are met, mean this rule matches, so long as none of the conflict conditions above have matched.

SetRequirements CONDITION, CONDITION, ...

Set the conditions which, if all are met, mean this rule matches, so long as none of the conflict conditions above have matched. Expects an array of RT::FilterRule::Condition objects.

DescribeRequirements

Return HTML, localised to the current user, describing the requirement conditions. Uses DescribeConditions.

DescribeConditions AGGREGATOR, CONDITION, ...

Return HTML, localised to the current user, describing the given conditions, with the given aggregator word (such as "or" or "and") between each one.

This is called by DescribeConflicts and DescribeRequirements.

Uses $HTML::Mason::Commands::m's notes method for caching, as this is only expected to be called from user-facing components.

Actions

Return an array of RT::FilterRule::Action objects describing the actions to carry out on the ticket if the rule matches.

SetActions ACTION, ACTION, ...

Set the actions to carry out on the ticket if the rule matches; this field is unused for filter rule group requirement rules (where IsGroupRequirement is 1). Expects an array of RT::FilterRule::Action objects.

DescribeActions

Return HTML, localised to the current user, describing this filter rule's actions.

Uses $HTML::Mason::Commands::m's notes method for caching, as this is only expected to be called from user-facing components.

Delete

Delete this filter rule, and all of its history. Returns ( $ok, $message ).

MatchHistory

Return an RT::FilterRuleMatches collection containing all of the times this filter rule matched an event.

TestRule RuleChecks => [], Actions => [], TriggerType => TYPE, From => FROM, To => TO, DescribeAll => 0

Test the event described in the parameters against the conditions in this filter rule, returning ( $Matched, $Message, $EventValue, $TargetValue ), where $Matched is true if the rule matched, $Message describes the match, $EventValue is the value from the event that led to the result, and $TargetValue is the value the event was checked against which let to the result.

Details of this rule and the checked conditions will be appended to the RuleChecks array reference, and the actions this rule contains will be appended to the Actions array reference.

The TriggerType should be one of the valid TriggerType attribute values listed above in the RT::FilterRule class attributes documentation.

For a TriggerType of Create, indicating a ticket creation event, the To parameter should be the ID of the queue the ticket was created in.

For a TriggerType of QueueMove, indicating a ticket moving from one queue to another, the From parameter should be the ID of the queue the ticket was in before the move, and the To parameter should be the ID of the queue the ticket moved into.

If DescribeAll is true, then all conditions for this filter rule will be added to RuleChecks regardless of whether they influenced the outcome; this can be used to present the operator with details of how an event would be processed.

For instance, when DescribeAll is false, if the rule did not match because of a conflict condition, then only the conflict conditions up to and including the first match will be included.

A Cache should be provided, pointing to a hash reference shared with other calls to this method for the same event.

One entry will be added to the RuleChecks array reference, consisting of a hash reference with these keys:

• Matched

  Whether the whole rule matched

• Message

  Description associated with the whole rule match status

• EventValue

  The value from the event which led to the whole rule match status

• TargetValue

  The value, in the final condition which led to the whole rule match status, which was tested against the EventValue

• FilterRule

  This RT::FilterRule object

• MatchType

  The type of condition which caused this rule to match - blank if the rule did not match, or either Conflict or Requirement (see the Conditions MatchType description beolow)

• Conflicts

  An array reference containing one entry for each condition checked from this filter rule's Conflicts, each of which is a hash reference of condition checks as described below.

• Requirements

  An array reference containing one entry for each condition checked from this filter rule's Requirements, each of which is a hash reference of condition checks as described below.

The conditions check hash reference provided in each entry of the Conflicts and Requirements array references contain the following keys:

• Condition

  The RT::FilterRule::Condition object describing this condition

• Matched

  Whether this condition matched (see the note about DescribeAll above)

• Checks

  An array reference containing one entry for each value checked in the condition (since conditions can have multiple OR values), stopping at the first match unless DescribeAll is true; each entry is a hash reference containing the following keys:

  • Matched

    Whether this check succeeded

  • Message

    Description associated with this check's match status

  • EventValue

    The value from the event which led to this check's match status

  • TargetValue

    The target value that the event was checked against

Each entry added to the Actions array reference will be a hash reference with these keys:

• FilterRule

  This RT::FilterRule object

• Action

  The RT::FilterRule::Action object describing this action

RecordMatch Ticket => ID

Record the fact that an event relating to the given ticket matched this filter rule.

MatchCount HOURS

Return the number of times this rule has matched in the past HOURS hours, or the number of times it has ever matched if HOURS is zero.

MoveUp

Move this filter rule up in the sort order so it is processed earlier. Returns ( $ok, $message ).

MoveDown

Move this filter rule down in the sort order so it is processed later. Returns ( $ok, $message ).

Move OFFSET

Change this filter rule's sort order by the given OFFSET.

_Set Field => FIELD, Value => VALUE

Set the value of a field, recording a transaction in the process if appropriate. Returns ( $ok, $message ).

CurrentUserCanSee

Return true if the current user has permission to see this object.

_CoreAccessible

Return a hashref describing the attributes of the database table for the RT::FilterRule class.

Internal package RT::FilterRule::Condition

This package provides the RT::FilterRule::Condition class, which describes a condition in a filter rule and provides methods to match an event on a ticket against that condition.

Objects of this class are not stored directly in the database, but are encoded within attributes of RT::FilterRule objects.

RT::FilterRule::Condition METHODS

This class inherits from RT::Base.

new $UserObj[, PARAMS...]

Construct and return a new object, given an RT::CurrentUser object. Any other parameters are passed to Set below.

Set Key => VALUE, ...

Set parameters of this condition object. The following parameters define the condition itself:

• ConditionType

  The type of condition, such as InQueue, FromQueue, SubjectContains, and so on - see the RT::Extension::FilterRules method ConditionTypes.

• CustomField

  The custom field ID associated with this condition, if applicable

• Values

  Array reference containing the list of values to match against, any one of which will mean this condition has matched

The following parameters define the event being matched against:

• TriggerType

  The action which triggered this check, such as Create or QueueMove

• From

  The value the ticket is changing from

• To

  The value the ticket is changing to (the same as From on ticket creation)

• Ticket

  The RT::Ticket object to match the condition against

Finally, Cache should be set to a hash reference, which should be shared across all Test or TestSingleValue calls for this event; lookups such as ticket subject, custom field ID to name mappings, and so on, will be cached here so that they don't have to be done multiple times.

This method returns nothing.

TestCondition [PARAMS, Checks => ARRAYREF, DescribeAll => 1]

Test the event described in the parameters against this condition, returning ( $Matched, $Message, $EventValue, $TargetValue ), where $Matched is true if the condition matched, $Message describes the match, $EventValue is the value from the event that led to the result, and $TargetValue is the value the event was checked against which let to the result.

Appends details of the checks performed to the Checks array reference, where each addition is a hash reference of Matched, Message, EventValue, TargetValue, as described above and in the RT::FilterRule TestRule method.

If additional parameters are supplied, they are run through Set above before the test is performed.

The DescribeAll parameter, and the contents of the Checks array reference, are described in the documentation of the RT::FilterRule TestRule method.

TestSingleValue PARAMS, TargetValue => VALUE

Test the event described in the parameters against this condition, returning ( $matched, $message, $eventvalue ), where only the specific VALUE is tested against the event's From/To/Ticket - the specific event value tested against is returned in $eventvalue.

This is called internally by the Test method for each of the value checks in the condition.

Properties

Return the properties of this object as a hash reference, suitable for serialising and storing.

ConditionType

Return the condition type.

CustomField

Return the custom field ID associated with this condition.

Values

Return the value array associated with this condition.

TriggerType

Return the trigger type of the event being tested against this condition.

From

Return the moving-from value of the event being tested against this condition.

To

Return the moving-to value of the event being tested against this condition.

TicketQueue

Return the ticket queue ID associated with the ticket being tested, caching it locally.

TicketSubject

Return the ticket subject associated with the event being tested, caching it locally.

TicketPriority

Return the priority of the ticket associated with the event being tested, caching it locally.

TicketStatus

Return the status of the ticket associated with the event being tested, caching it locally.

TicketCustomFieldValue CUSTOMFIELDID

Return the value of the custom field with the given ID attached to the ticket associated with the event being tested, caching it locally.

TicketRequestorEmailAddresses

Return an array of the requestor email addresses of the event's ticket, caching it locally.

TicketRecipientEmailAddresses

Return an array of the recipient email addresses of the event's ticket, caching it locally.

TicketFirstCommentText

Return the first comment of the event's tickets, in text, caching it locally. If the first comment is in HTML, it is converted to plain text.

_All

Return the results of an "All" condition check.

_InQueue

Return the results of an "InQueue" condition check.

_FromQueue

Return the results of a "FromQueue" condition check.

_ToQueue

Return the results of a "ToQueue" condition check.

_RequestorEmailIs

Return the results of a "RequestorEmailIs" condition check.

_RequestorEmailDomainIs

Return the results of a "RequestorEmailDomainIs" condition check.

_RecipientEmailIs

Return the results of a "RecipientEmailIs" condition check.

_SubjectContains

Return the results of a "SubjectContains" condition check.

_SubjectOrBodyContains

Return the results of a "SubjectOrBodyContains" condition check.

_BodyContains

Return the results of a "BodyContains" condition check.

_HasAttachment

Return the results of a "HasAttachment" condition check.

_PriorityIs

Return the results of a "PriorityIs" condition check.

_PriorityUnder

Return the results of a "PriorityUnder" condition check.

_PriorityOver

Return the results of a "PriorityOver" condition check.

_CustomFieldIs

Return the results of a "CustomFieldIs" condition check.

_CustomFieldContains

Return the results of a "CustomFieldContains" condition check.

_StatusIs

Return the results of a "StatusIs" condition check.

Internal package RT::FilterRule::Action

This package provides the RT::FilterRule::Action class, which describes an action to perform on a ticket after matching a rule.

Objects of this class are not stored directly in the database, but are encoded within attributes of RT::FilterRule objects.

RT::FilterRule::Action METHODS

This class inherits from RT::Base.

new $UserObj[, PARAMS...]

Construct and return a new object, given an RT::CurrentUser object. Any other parameters are passed to Set below.

Set Key => VALUE, ...

Set parameters of this action object. The following parameters define the action itself:

• ActionType

  The type of action, such as SetSubject, SetQueue, and so on - see the RT::Extension::FilterRules method ActionTypes.

• CustomField

  The custom field ID associated with this action, if applicable (such as which custom field to set the value of)

• Value

  The value associated with this action, if applicable, such as the queue to move to, or the contents of an email to send, or the email address or group ID to add as a watcher

• Notify

  The notification recipient associated with this action, if applicable, such as a group ID or email address to send a message to

The following parameters define the ticket being acted upon:

• Ticket

  The RT::Ticket object to perform the action on

Finally, Cache should be set to a hash reference, which should be shared across all Test or TestSingleValue calls for this event; lookups such as ticket subject, custom field ID to name mappings, and so on, will be cached here so that they don't have to be done multiple times.

This method returns nothing.

Perform FILTERRULE, TICKETOBJ

Perform the action described by this object's parameters, returning ( $ok, $message ), checking that the associated ticket has not recently been touched by the same filter rule to avoid recursion.

IsNotification

Return true if this action is of a type which sends a notification, false otherwise. This is used when carrying out actions to ensure that all other ticket actions are performed first.

Properties

Return the properties of this object as a hash reference, suitable for serialising and storing.

ActionType

Return the action type.

CustomField

Return the custom field ID associated with this action.

Value

Return the value associated with this action.

Notify

Return the notification email address or group ID associated with this action.

Ticket

Return the ticket object that this action is being performed on.

_None

Return ( $ok, $message ) after performing the "None" action.

_SubjectPrefix

Return ( $ok, $message ) after performing the "SubjectPrefix" action.

_SubjectSuffix

Return ( $ok, $message ) after performing the "SubjectSuffix" action.

_SubjectRemoveMatch

Return ( $ok, $message ) after performing the "SubjectRemoveMatch" action.

_SubjectSet

Return ( $ok, $message ) after performing the "SubjectSet" action.

_PrioritySet

Return ( $ok, $message ) after performing the "PrioritySet" action.

_PriorityAdd

Return ( $ok, $message ) after performing the "PriorityAdd" action.

_PrioritySubtract

Return ( $ok, $message ) after performing the "PrioritySubtract" action.

_StatusSet

Return ( $ok, $message ) after performing the "StatusSet" action.

_QueueSet

Return ( $ok, $message ) after performing the "QueueSet" action.

_CustomFieldSet

Return ( $ok, $message ) after performing the "CustomFieldSet" action.

_RequestorAdd

Return ( $ok, $message ) after performing the "RequestorAdd" action.

_RequestorRemove

Return ( $ok, $message ) after performing the "RequestorRemove" action.

_CcAdd

Return ( $ok, $message ) after performing the "CcAdd" action.

_CcAddGroup

Return ( $ok, $message ) after performing the "CcAddGroup" action.

_CcRemove

Return ( $ok, $message ) after performing the "CcRemove" action.

_AdminCcAdd

Return ( $ok, $message ) after performing the "AdminCcAdd" action.

_AdminCcAddGroup

Return ( $ok, $message ) after performing the "AdminCcAddGroup" action.

_AdminCcRemove

Return ( $ok, $message ) after performing the "AdminCcRemove" action.

_Reply

Return ( $ok, $message ) after performing the "Reply" action.

_NotifyEmail

Return ( $ok, $message ) after performing the "NotifyEmail" action.

_NotifyGroup

Return ( $ok, $message ) after performing the "NotifyGroup" action.

Internal package RT::FilterRules

This package provides the RT::FilterRules class, which describes a collection of filter rules.

Internal package RT::FilterRuleMatch

This package provides the RT::FilterRuleMatch class, which records when a filter rule matched an event on a ticket.

The attributes of this class are:

• id

  The numeric ID of this event

• FilterRule

  The numeric ID of the filter rule which matched (also presented as an RT::FilterRule object via FilterRuleObj)

• Ticket

  The numeric ID of the ticket whose event matched this rule (also presented as an RT::Ticket object via TicketObj)

• Created

  The date and time this event occurred (also presented as an RT::Date object via CreatedObj)

RT::FilterRuleMatch METHODS

Note that additional methods will be available, inherited from RT::Record.

Create FilterRule => ID, Ticket => ID

Create a new filter rule match object with the supplied properties, as described above. The FilterRule and Ticket can be passed as integer IDs or as RT::FilterRule and RT::Ticket objects.

Returns ( $id, $message ), where $id is the ID of the new object, which will be undefined if there was a problem.

FilterRuleObj

Return an RT::FilterRule object containing this filter rule match's matching filter rule.

TicketObj

Return an RT::Ticket object containing this filter rule match's matching ticket.

_CoreAccessible

Return a hashref describing the attributes of the database table for the RT::FilterRuleMatch class.

Internal package RT::FilterRuleMatches

This package provides the RT::FilterRuleMatches class, which describes a collection of filter rule matches.

AUTHOR

Andrew Wood

All bugs should be reported via email to bug-RT-Extension-FilterRules@rt.cpan.org or via the web at rt.cpan.org.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2021 by Andrew Wood

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991