Rule Types

Last updated
Save as PDF

You may create several different types of rules in TeamConnect:

Security Rules—Protect records when they are in certain states. For example, when users open a matter record that is in a certain phase, no one may be able to modify it except for a certain group of users.
Pre-population Rules—Populate fields with predefined values. For example, a filing date field may be populated when the Lawsuit category is added to a dispute record. You may define pre- population rules in conjunction with templates, which you may create through Designer without the need for class files or JavaScript.
Validation Rules—Confirm the conditions that exist in a record at the time an action is attempted. For example, when a user clicks save, determine whether the appropriate custom fields are filled out for each category. If not, prompt the user with a message and do not save the changes.
Approval Rules—Send requests for approval to specified users before an action is completed, such as posting an invoice. The requests then appear in each of those users' My Approvals screen.
Custom Action Rules—Perform custom actions according to the needs of your organization. These actions are defined in class files or JavaScript or through the use of a template.
Scheduled Action Rules—Custom action rules with parameters set through Designer to schedule when and how often an action is executed. Unlike custom action rules, scheduled actions do not support templates.
Audit Rules—Capture and log events by creating history records that contain information about user activities in TeamConnect.
Post Commit Rules—Perform a task after an action has completed successfully. For example, send an email notification to associated users after a record has been updated.

These types of rules may be categorized into the following groups based on the actions that they may perform:

Predefined actions—Defined through Designer, security, pre-population, validation, approval, and audit rules have predefined actions such as the following:
- Deny an operation.
- Send the operation on a route for approval.
- Populate fields based on values in a template.
- Record user activities in history records.
Custom and scheduled actions—Defined by creating class files or JavaScript and the TeamConnect API, custom action rules may perform any action written in Java or JavaScript.

Scheduled action rules use custom Java or JavaScript actions that you may schedule using certain parameters in Designer.

Custom action rules also support templates, whereas scheduled action rules do not. However, the predefined actions defined by a template are not custom actions.

By default, TeamConnect does not perform duplicate contact checking if custom code creates or updates contacts. See the ContactService.readDuplicateContacts() method in the API Javadocs to use duplicate contact checking functionality.

Page transitions—Defined on wizard screens, you may create rules to govern how users enter information in a wizard. For more details about page transition rules, see Creating Page Transition Rules.

Security Rules

Security rules prevent an operation (such as creating, updating, or deleting) from being completed under specified circumstances and based on the original values of the record when it was opened by the user. When the user tries to alter a record, if the original values match the qualifier specified in the rule, the rule prevents the operation and displays a message to the user.

Keep the following points in mind when working with security rules:

When a user attempts an operation, TeamConnect executes any applicable security rules before executing other types of rules.
Security rules compare the rule qualifier to the conditions of the record when the user first opened it, so they prevent a user from changing values in the record to get around the rule. Qualifiers such as isChanged, Item Deleted, Item Modified, or Item Added will not have any effect on the rule's actions, since the rule is checked before any changes have occurred.
Security rules do not provide field-level security. For example, you cannot specify that a certain field's value may not be changed. Security rules may only prevent the user from updating or deleting the entire record based on certain specific, pre-existing conditions in the record.
You may use security rules to control the Delete and Update operations for existing records belonging to any object, or for the Phase Change operation in a custom object. For a complete list of operations that may trigger security rules, see the Rule Triggers table.
You may define security rules for specific user accounts and user groups. For example, if the current user is not a member of the Adjusters group, that user cannot update the record while it is in a specified phase.

Pre-population Rules

Pre-population rules may populate fields, sub-objects, or related objects with values predefined in a template, which you may access or create on the Templates tab of the object definition. Once you create a template, you may select it from the Action tab of your pre-population rule screen.

Note: In addition to pre-population rules, you may use templates with custom action rules and wizards.

With templates, you may create rules that:

Populate fields of existing records
Create a new record and populate its fields
Create a related record for the current object, and populate its fields
Populate assignees and attendees and specify the main assignee by role
Perform phase changes
Populate the default category of a record
Specify the default category with a static value

The available triggers and qualifiers for pre-population rules are the same as validation rules. For a complete list of triggering operations, see the Rule Triggers table.

For information about defining templates for object definitions, see Using Templates.

Validation Rules

Based on the values in the record, validation rules prevent users from creating or updating the records, or changing project phases. If the qualifier in the rule is met, the rule prevents the operation and displays a message to the user.

Points To Remember

When a user attempts an operation, validation rules execute after all applicable security rules and pre-population rules, as described in the execution order listed in Points to Remember.
Validation rules compare their qualifiers to the values in the record at the time when the user attempts an operation, not when the record was opened.
Validation rules may control the Create or Update operations for any object, or for the Phase Change operation in a custom object. See Rule Triggers for a complete set of triggers according to each object.
Page Transition rules in wizards function like validation rules. They "validate" the information that the user enters in each wizard page to ensure that the data is entered properly. They also use this information to determine which wizard page to display next. For more information, see Creating Wizards.

Validation Rule Example

For example, you might write a validation rule for involved party records of the Dispute object, which checks:

Whether the current user who is attempting to update a dispute record is a member of the Dispute Attorney group
Whether the involved party record has the Outside Counsel Firm category
Whether the Involvement Date field of the involved party record is empty (has a null value)

If all of these conditions are present, the rule prevents the record from being updated and displays a message to the user such as Involvement date of the involved party cannot be empty.

This is a validation rule rather than a security rule because the value in the Involvement Date field when the user opened the record is irrelevant. The purpose of the rule is to make sure that the Involvement Date field has a value when it is saved.

Complementary Validation Rules

When writing a validation rule for the Create operation, make sure that you also write a validation rule for the Update operation that complements the Create rule, if necessary. This action ensures that the conditions you specify are met at all times.

For example, if you want to ensure that dispute records are always saved with at least one assignee, you must create two identical validation rules: one for Create and one for Update. If only the Create rule is used, a user may open an existing record and save (update) it after that user has deleted the assignee. To prevent this action, write a rule that requires an assignee when users update the record.

Approval Rules

Approval rules designate certain users who must approve an operation before it may be completed. For example, you may define approval rules to require permission to post invoices, deactivate accounts, change the phase of a matter. The Rule Triggers table lists the available operations for approval rules.

Use approval rules in conjunction with routes to define approval processes. A Route specifies a logical sequence of approvers used in an approval process. These approvers are included in routes through their user group memberships, since routes are based on groups, not individual users. For more details about routes, see Creating Routes.

TeamConnect performs the following operations when an approval rule is triggered:

When a user attempts a triggering operation, TeamConnect executes applicable approval rules after all security and validation rules for the operation are executed, as described in the execution order listed in Points to Remember.

For example, if there is a security rule preventing users from deleting a record when it is in a certain phase, this rule is executed before the approval rule sends the deletion for approval.

If the qualifier defined in the approval rule is met, the operation (also known as a request) is put into a pending status.
The specified message appears at the top of the record, such as This object has an action that is pending approval and it cannot be modified.
The approval request goes through the specified route of approvers. As each approver receives the request, it appears on his or her My Approvals screen.
If the required users approve the operation, TeamConnect completes the requested operation.
If the required users reject the operation, TeamConnect does not do the requested operation.
During the approval process, decisions are listed on the Workflow tab of the record. If the needed approval is for deleting the record, the decisions cannot be accessed after the record is deleted.

You may create qualifiers for approval rules so that the user's attempt to perform an operation only goes for approval under certain conditions. For example, you may create an approval rule that requires approval for deleting a closed dispute record only if the deletion is attempted by a user in the Dispute Attorney group.

You may also specify an approval period for approval rules. You must use a value other than zero when specifying the length of an approval process. Otherwise, the approval period expires almost immediately.

If you do not set any qualifier information for an approval rule, the operation requires approval under all circumstances.

If an approval rule is triggered by the only user who is included in the route, the rule still requires that user's approval. The workflow status message immediately appears at the top of the record and the user must approve the operation before it is completed.

Many other actions and events may take place during an approval process.

Custom Action Rules

You may write custom action rules in Java or JavaScript and use Designer to upload the files to TeamConnect and select them for use in the rule. The qualifier for a custom action rule may be defined in Designer, or it may be a custom qualifier created in Java or JavaScript (an automated qualifier). For details, see Writing Automated Actions.

You may define custom actions using a template, which you may access or create on the Templates tab of the object definition. You may select the template from the Action tab of your custom action rule.

Note: By default, duplicate contact checking is not done when custom Java code creates or updates contacts. See the ContactService.readDuplicateContacts() method in the API Javadocs to use duplicate contact checking functionality.

Custom Action Rule Example

Custom action rules define actions that cannot be specified in Designer. For example, you might write a custom action rule in Java to automatically create budgets when a user adds an outside counsel firm to a dispute record. You upload the class file to the appropriate folder in TeamConnect's Documents area and then select it from the list of class files on the rule's Action tab.

Scheduled Action Rules

A scheduled action rule is similar to a custom action rule. You upload custom Java or JavaScript files to use for the rule action. The difference is that when you define these rules in the user interface, you have the option to specify when and how often the action is executed.

For example, your system might need a custom rule requiring, when the qualifiers are met, a task is created every 15 days to remind the user to do something, for a period of 90 days. To accomplish this requirement, a custom Java class might be uploaded to TeamConnect, and you then select this class file in the scheduled action rule. However, the actual number of days between tasks and the number of times that a task must be created are specified on the Action tab of the scheduled action rule.

When a scheduled action rule is triggered, you may view information about actions pending in the Scheduled Actions Monitor, provided that you have the rights to this tool. If necessary, you may also delete (or cancel) pending actions using the Monitor screen.

If the qualifying conditions for a scheduled action rule are true, and the rule is triggered, it will continue to run as scheduled even if the qualifying conditions subsequently become false during the schedule. The qualifiers are only checked the first time the scheduled action rule is invoked.

For more details about the Scheduled Actions Monitor and scheduled action rules, see:

By default, duplicate contact checking is not done when custom Java code has been written to create or update contacts. See the ContactService.readDuplicateContacts() method in the API Javadocs to use duplicate contact checking functionality.

User Invoked Actions

You may define custom actions to be user invoked. Instead of the rule being triggered by an action like the creation or deletion of a record, the user intentionally invokes the action by selecting it from a drop-down list. The qualifier items are then checked and the action is executed if the qualifiers are met.

For example, you could define a user invoked custom action to trigger an email message to be sent containing information from the current record.

You may develop user invoked custom actions to create child records. To do so, you must specify whether the record (and the child record to be created) may be created when the user invoked rule is performed or when the user clicks Save. Either alternative is possible.

The drop-down list for user invoked actions appears to users on the toolbar, as a More Actions button.

To create a user invoked custom action rule

Define the custom action as a Java class or JavaScript file.
Define a custom action rule for the appropriate object definition and set the rule trigger to User Invoke.
When you define a user invoked action, the user invoked action becomes available on the Rights tab of user and group accounts for the corresponding object definition.
Give rights to all groups to whom you want to give access to the custom action.
The next time they log in, members of those groups have the action available to them on the record toolbar.

Audit Rules

Audit rules may keep track of activity in TeamConnect by logging information in history records. You may apply these rules to user actions that are relevant for record keeping or monitoring changes, such as when a user updates one or more system or custom fields in a record. Audit rules provide you with a way to define business rules through Designer rather than developing and testing custom code to record user activity.

Audit rules may create history records that include the name of the user performing an action and how the record was affected. For example, you may create an audit rule to track when a contact record's Social Security Number field is updated. When the rule is triggered, it records the old value, new value, and the user who made the change.

Recording information in history records allows you to control what is recorded and how it appears. For example, you may create a custom description for the event that triggers the audit rule, record information in custom fields, and export data for reporting purposes.

Points To Remember

Keep the following points in mind when creating audit rules:

You may use audit rules to track modifications to data, and the creation or deletion of records.
When an audit rule is triggered and its qualifiers are met, it creates one history record. To define audit rules that are triggered on Update, define qualifiers that only capture information when appropriate. Otherwise, a history record will be created whenever a user updates any part of a record.
Rules with multiple triggers have the potential to execute more than once for a single event. If this happens with an audit rule, then multiple history records will be created.
TeamConnect executes audit rules after all other business rules are applied. That way, operations that are prevented because of another rule will not cause the creation of an audit history record.
The current user's access rights do not affect the creation of an audit history record. For example, even if the current user does not have rights to create related records in matters, the audit rule may still create a history record for the current matter record.
If an audit rule is triggered but a history record cannot be created, for whatever reason, no additional information is logged, and no error is given to the user.

For information about the specific settings available in audit rules, see Defining Actions for Audit Rules.

Updates, Triggers, and Audit Rules

If you choose "use default description" in the Actions tab of an Audit rule, TeamConnect autopopulates the "Text" field in the audit history record. The way in which "Text" is autopopulated differs depending on the nature of the trigger.

For example, the text differs depending on whether an object is being created, updated, or deleted. Here is an example of the "Text" field in an audit history record that is triggered by an Update of a Project object:

[When the action was completed the following information was changed in Matter 'test']

Amount was '10,000' and was changed to '15,000'
Transaction Date was '01/01/05' and was changed to '01/02/06'
Quantity was '25' and was changed to '50'

The default description for an update contains an entry for each field that changed during the update (three fields in this example). However, if you choose a trigger other than "Update", you may not get as much information.

For example, the Account object allows you to define an audit rule that uses the "Withdraw" trigger. The resulting audit history record tells you that a withdrawal took place, but does not specify the actual amount of the withdrawal, whereas an audit history record based on the "Update" trigger would show the change in amount.

You must decide how much detail is required and choose whether one trigger is sufficient or whether you need to associate both triggers with the rule. Here is a more complete syntax for how TeamConnect constructs the default description for an Update trigger:

[When the action was completed the following information was changed in <Record>]

- <Field> was <Old Value> and was changed to <New Value> [For non memo text fields]

- <Field> was changed [For memo text fields]

[List of the changed, added or removed sub-objects and their associated events and fields in separate lines. Note that if there is no change in sub-objects, nothing goes here.]

[A new <Sub-object> was added]

----------------------------------------------

[An existing <Sub-object> was deleted]

----------------------------------------------

[An existing <Sub-object> was updated] [List of all modified sub-object fields]

Audit Default Description

The default description (the value that TeamConnect puts into the "Text" field of an audit history record) is fairly detailed. In most cases, you do not need to override the default description with your own description.

In the case of Update triggers, the description includes changes for not only the fields of the main object, but also changes for some sub-objects. In addition to the sub-objects specifically named in the table below, every category assigned to an object is also considered a sub-object, for purposes of audit history logging.

Objects and their Sub-objects

Main Object	Sub-objects
Account	(none)
Appointment	Attendee Resource
Contact	Address Email Fax Internet Address Phone Rate Skill Territory
Document	(none)
Expense	(none)
History	(none)
Invoice	(none)
Task	Assignee
Custom Object	Assignee Embedded Custom Object
Involved	(none)
Embedded Custom Object	(none)

Configuring History Object Definition for Audit Tracking

If you want the information captured by audit rules to be in custom fields, you must define these fields under a particular category of the History object. Capturing details in separate fields makes it is easier to export that information using Business Objects® reports.

Note: If you are creating audit rules for the User or the Group object definition, you cannot define fields for History categories.

To distinguish audit history records from other history records, create descriptive categories in the History object definition, such as the Information Change - Lawsuit Key Dates category, and then select the appropriate category while configuring audit rules. This technique is also useful if you decide to set security by the category rather than preventing user groups from accessing all history records.

The following table shows examples of History object categories and their custom fields that you may configure to be populated by audit rules.

History Object Definition Category and Custom Field Examples

Category name	Custom fields
Information Change - Lawsuit Key Dates	Old Trial Date New Trial Date
Information Change - Contact	Address Address (old) Contact Rate Contact Rate (old) Email Address Email Address (old) Fax Number Fax Number (old) Phone Number Phone Number (old)

For details about defining categories, see Using Categories. For details on defining custom fields, see Custom Fields.

Post Commit Rules

Unlike the other rule types, which are all executed before the user's actions are completed and committed to the database, post commit rules are only executed when it is confirmed that the triggering event has completed successfully. This prevents cases where, for example, a notification email might be sent out even if a transaction failed to commit for any reason.

The qualifier tab and triggers available to post commit rules are the same as those available for custom action rules.

Keep the following points in mind when creating post commit rules:

Actions in post commit rules are executed outside of a database transaction. No updates to the current record are made within a post commit rule.
The Use template option is not available for post commit rules. The available options are Use automated Action and Notification (when implemented).