A rule is a statement of automated business logic that Agiloft executes.
For example: "Email the sales manager whenever a new lead arrives" or "Do not allow a bug report to be deleted unless it has been closed"
Agiloft provides a GUI for defining a wide variety of rules, and custom scripts may be used when the necessary functions are not supported by the GUI. For example a script might "verify the registration key provided by the customer against the list of valid keys kept in an external database".
There are three kinds of rules available:
- This type of rule is applied when a record is created, edited or deleted. In a typical KB, most rules are event-specific.
- Time based rules are applied at specified time intervals. This type of rule can be used to automate actions that should occur when nothing is happening. For example, "Notify the support manager if an open case of severity Critical or greater from a customer with a valid support contract has been left open for more than 1 day"
- On a shared hosted Agiloft server, time-based rules have a minimum run interval of ten minutes. Decreasing this interval increases server load, so 10 minutes is the default on shared servers.
- Users with a dedicated server running their own instance of
Agiloft may decrease this interval. The Admin console options allow the administrator to set the shortest interval used for time-based rules.
- To change the minimum interval option, log in to the Admin console, and go to Knowledgebases. Select the knowledgebase, click Edit, and click the Options tab. Select a Frequency for "Shortest time interval allowed for time-based searches (in minutes)".
- Aggregate rules are applied based on the number of table entries meeting a specified condition at specified time intervals. For example, "Notify the Sales Manager if the number of Leads expected to close next month is less than 20 or more than 40".
- In all cases additional conditions may be applied using a saved search. The Schedule tab allows you to control when the rule is active, for instance to limit it to the working hours for a particular team.
By default, only one time-based or aggregate rule is allowed to run in a KB at any one time. You can modify this by customizing the Max Timer Rules per KB global variable. Note that time-based and aggregate rules run sequentially when they are not allowed to run simultaneously.
Creating, editing, and deleting rules
To create, edit, or delete rules, go to Setup > Rules.
It is not necessary to delete a Rule if you think you might need it in future.
To deactivate a rule:
- Navigate to Setup > Rules.
- Select the rule in question and open it for editing.
- Click Action.
- Select all actions in Active Actions window.
- Move them to Inactive Actions.
Rules can be named to make them easier to group in the Rule wizard. For instance, it is useful to group the time-based rules by using the syntax
Ticket TB - Name of rule for a time-based rule on the Ticket table.
Rules can easily get out of hand and grow in number, and if they are all done separately, it can be hard to control their order of execution. The best practice is to group automation into a smaller number of rules. In general, any table with lots of automation will typically have the following "parent" rules:
all new record actions
All edit validations. Usually customers who start setting up validation criteria end up having several of them and so we group them all into one rule. If there is only a single edit validation, then it can go in one of the other rules below.
Edit actions when power users update.
Edit actions when end user updates.
Parent-child handling. If complex, this may need its own separate rule with all actions in an if-then; if not, it might go into one of the above rules.
Rule 6 - infinity:
Rules that must be defined separately from other ones in order to be triggered by changes made by the others, or rules that should not include API when the rule they might otherwise go in includes it, or which must include API when a possible containing rule omits it.
For instance, a rule based on customer updates should never include API changes because since other rules run currently in name of last updater, if any other rule fires, the system will think the customer has updated again and will re-trigger that rule. That is why it us usually suggested to separate customer update rule actions from staff edit actions. There may be some staff edit actions that must be separate too because of a need to include or exclude API triggers.
Rule 7 - infinity:
Time based rules - It is usually preferable to combine them whenever possible into if-then conditions, but sometimes it is cleaner to make a separate rule for each one, unless there are 10s or hundreds of them, as long as they are named so you can sort them and see them all together, i.e. named for "table name TB - description".
The basic goal is to have as few rules as possible per table. Otherwise, a complex system will have hundreds of rules which can make sorting laborious, and they become much more difficult to troubleshoot, prioritize, and document.
- When you create a rule, you assign it a priority number.
- When you create multiple actions for a rule, you move them up or down to define their order of execution.
- Rules execute in priority order relative to other rules with the rule with the lowest number executing first. For example a rule with a priority of 1 executes before a rule with a priority of 2.
A given rule can execute multiple actions and these actions execute in the order that they are listed.
Create a rule for new tickets, then add an action that changes the Assigned to field based on values in the ticket, then add a second action to the same rule that emails the assignee and a third action that emails the customer the fields of the ticket, including the assignee field.
Where possible, try to combine rules for a given table into a few, or even a single if-then-else rule. A few if-then-else rules are both more efficient and easier to manage than a swarm of independent rules.
Order of Execution in Saving
Many checks are run on a record when it is saved. There may be field validation, rules, workflow actions and guards, and custom scripts run as a result of saving. It is important to understand the order that these actions execute. In order, they are:
- Form validation is run on any validated fields.
- Dynamic default values are updated, the Updated By and Date Updated fields are populated.
- Rules based on record modification are executed in priority order.
- Workflow guards are executed. If they fail, the record is returned to its former pre-saved condition.
- Workflow actions are executed.
- Any scripts associated with rule or workflow actions are executed with the associated rule or workflow, and if their validation fails, the record is returned to its pre-saved condition.
Please note that, by default, you will see a warning before running a rule that matches more than 100,000 records. If you choose to run such a rule, it will only affect the first 100,000 matching records. You can change this behavior at both the Admin or KB level by setting new values for the following global variables:
Rules that Trigger other Rules
Changes made by one Rule can trigger the execution of other rules.
Edits made by a Rule are defined as API actions, and do not change the Updated By field.
Prevent a Rule from being triggered by the actions of other Rules by unchecking the API box which is found at Setup > Rules > edit rule > Condition tab.
In a normal business process, Agiloft sends email to the assignee of a customer ticket every time the ticket record is updated. This rule would send an email every time the customer updates their record, but also when the record is changed by any other means. Say, for instance, that the ticket aged past a certain SLA goal, so the system updated it to increase the severity. On this edit, the assignee would get an email. If the increase in severity then triggered several other rules, the assignee would get an email for every single one of these rule-triggered edits. That can add up to a lot of email to dig through!
To prevent the tech being overwhelmed with autogenerated emails, the admin edits the Rule, unchecking API so that an email notification is not sent after a rule-triggered (API) change.
Alternately, the admin may create a single, more complicated if-then-else rule to replace the several simpler rules.
The Condition tab of the Rules wizard contains the options to define when the rule should be applied. For example, if you select Edited and Web, the rule will only be applied if an Approval was edited using the Web interface.
The possible triggers for a rule include:
- Email - all updates from inbound email.
- Web - user interactions with records through the web portal; REST and Web Service calls, because the Web Service call creates a user session and performs edits on behalf of a named user.
- API triggers include:
- Record edits by a rule or workflow action
- Automatic calculation field updates
- Synchronization actions, including automatically triggered updates such as creation of Twitter responses
- Record creation in cases where the user does not interact with the record form, for example during data imports from files and silent conversion actions.
Rules based on the Activity Logs table
The Activity Log table can be used as the trigger for rules. For example, if you wanted to run a rule that updates a user record when they log in, or that notifies you if someone changes a workflow, you can now create a rule to do that when the relevant record is created in the Activity Log.