Forms processing is a core function for a tax authority. When forms are processed, the system needs to verify that the information is correct and update or create the appropriate taxpayer details and transactions.
Form rules provide business users with the ability to configure processing rules for a form type.
Contents
Understanding Form Rule Administration
The Big Picture of Rule Processing
The Big Picture of Validation Rules
The Big Picture of Processing Rules
Setting Up Exception Categories
Designing Your Form Rules and Groups
This section describes concepts and common tasks related form rule administration.
Contents
A form rule is combination of configuration data and processing logic that applies a business rule. The configuration that controls the form rule logic is defined on the form rule business object. The form rule BO has an associated Apply Rule algorithm to execute the logic of the rule.
When forms are defined, each form section and line must reference a business name that is unique for that form type. As form changes are introduced, these business names remain constant.
Many form types within a given set of forms also have common information such as taxpayer identification, income and credit lines and so on. The validation and processing rules are typically the same for these common components.
Form rules may be designed to reference section and line business names rather than specific form lines. If a section / line exists in the form from one year to the next, its rules can be reused. Form lines that are common across form types can utilize the same rules provided the business names are the same.
Refer to Designing Your Form Rules and Groups for information about designing your rules.
A form rule group is a uniquely named group of rules. You can predefine a set of rules common to a particular form section or set of form lines that can be selected and associated with a form type. For example, predefined rule groups can be used to verify that all taxpayer identification details have been filled in on a form or complete the actions required when a form is posted.
Form rule groups have an associated reference form type. Reference form types are used to determine the section and line business names that may be used by rules in this group to reference the form data. The sections and line names defined in the reference form type must be common to all form types that use this rule group.
Form rule groups are also used to define the form rules for a form type. A form type can define one or more form rule groups to be executed during certain steps in the form lifecycle (defined by a rule event). Sequence numbers are used so that multiple form rule groups executed for the same rule event are done in an appropriate order. Note that the system looks to the specific form type for the form being processed to determine which rules to execute, not the reference form type on the rule group. This means that the rules to be executed can be tailored to the different form types within a broader category of forms.
Refer to for The Big Picture of Rule Processing for more information about processing different rule events.
An exception category is a broad categorization of exceptions that can be reported by form validation rules. An exception category must be specified on a form exception.
As a form transitions through the states in its lifecycle, various rules need to be executed. The following sections describe the way in which the base system processes rules.
The following section highlights the logic in the base algorithm type C1-FRM-APPRL. It has been designed to call the algorithms plugged into the Apply Rule plug-in spot for each rule linked to the form type for a given rule event. This algorithm type should be plugged into the Business Object Status - Enter plug-in spot for each state that requires rules to be executed.
At a high level, the base algorithm follows these steps
· Read the form data and store it in memory
· Find the form rule groups linked to the input form type and rule event. For each group in sequence order, retrieve its Active rules in sequence order.
· For each rule,
· Execute its Apply Rule algorithm
· Check the returned value of Rule Action. If the action is Terminate, terminate overall processing; otherwise continue on to the next rule.
· When processing is complete,
· Update the form using the data updated in memory by the rule algorithms
· If exception processing applies and the exception list is populated,
· Compare the current list of exceptions to the existing exceptions for the form, if any. Any exceptions that are no longer in the current list are closed. Add any newly-reported exceptions to the form exception table.
No updates. The rules processing algorithms provided in the base product do not do any updates to the database. These algorithms simply update the internal form and exception information with new values. The rules processing algorithm is responsible for updating the form and creating or closing form exceptions.
Contents
Verifying Form Data Using Form Rules
Stopping Form Processing When There Are Issues
Validation rules determine if the information supplied on the form can be processed. This usually includes checking that required information is supplied and validating that the data is in the correct formats. In some cases, it may mean correcting the form data within certain tolerance limits. Validation rules are responsible for reporting any issues on a form that may require correction.
Most forms have a lifecycle that includes a validation step. The base package provides a sample tax form C1-ParentTaxForm that has a Validate status. This status has an enter-plug in that uses the base C1-FRM-APPRL algorithm type to execute rules for the Validation rule event and process any exceptions reported.
Algorithms that perform validation rules are responsible for reporting any issues as a form exception. Form exceptions details must include the form rule group and rule that detected the issue, an exception category and an exception class. The base package includes exception class values of Notification, Waiting for Information and Suspense. Your implementation can add further classes as appropriate for your business rules.
A form can suspend if there are errors that a tax authority user needs to review or fix.
If the form is missing key information, the form can go into a 'waiting' state until the tax authority receives the information from the taxpayer.
The exception class attribute can be used to determine what state a form should move to if there are open issues after validation. The base package algorithm type C1-FRE-TROEX is designed to transition a form to a waiting state if open exceptions of class Waiting for Information exist or to a suspended state if there are open exceptions of the class Suspense. This algorithm type should be plugged into the Business Object Status - Enter plug-in spot after the Apply Form Rules algorithm.
Contents
Processing Form Data Using Form Rules
Processing Rules Create Other Objects
Processing Rules Do Not Report Exceptions
Once a form's data has been verified, it may be posted into the system. A posted form may subsequently be adjusted to correct information, transferred to another obligation or account or reversed altogether. At each of these steps in the lifecycle, other actions need to take place. The system may need to create taxpayers, accounts and obligations, create financial details, create overpayment processes or possibly reverse the effect of previous updates.
The base package algorithm type C1-FRM-APPRL is designed to be used on any state that requires rules processing. To use this algorithm type to execute processing rules, you need to define a rule event applicable to that state and plug in an algorithm configured to execute rules for that event. The base package includes the following pre-configured rule events and associated algorithms; Suspend, Waiting for Info, Post, Adjust, Transfer and Reverse. The base package provides a sample tax form C1-ParentTaxForm that may be used as an example of a form that implements rule processing using these rule events.
Algorithms that perform processing rules are responsible for any data updates that affect other objects in the system such as accounts, obligations, adjustments and others. As such, they are also responsible for creating form log entries that link those objects to the form being processed. Refer to the base algorithm C1-FR-CRASMT for an example of a rule algorithm that creates an assessment adjustment and its associated log entry.
In a typical form lifecycle, the actions that take place when a form is posted, adjusted, transferred or reversed are interrelated. If one of these actions is not successful, an error should be reported and the form should remain in the same state as before the updates took place. For this reason, the system does not support exception handling after processing rules are executed. Any issues that are encountered should be reported using standard error handling.
When a form’s data is validated the system may identify errors which it stores as exceptions. You can use exception categories to group these exceptions. The exceptions for the forms can then be viewed on the Exceptions tab of the form’s maintenance portal. To maintain an existing Exception Category, select Admin Menu, Exception Category.
The topics in this section describe the base-package zones that appear on the Exception Category portal.
Contents
The Exception Category List zone lists every Exception Category. The following functions are available:
Click the broadcast icon to open other zones that contain more information about the adjacent Exception Category.
The standard actions of Edit and Deleteare available for each Exception Category.
Click the Add link in the zone's title bar to add a new Exception Category.
This is a standard actions zone. The Edit and Delete actions are available.
The Exception Category zone contains display-only information about an Exception Category. This zone appears when an Exception Category has been broadcast from the Exception Category List zone or if this portal is opened via a drill down from another page.
Please see the zone's help text for information about this zone's fields.
A form rule is designed to implement one specific rule used in processing a form. Examples of form rules include taxpayer existence rules, form line validation, calculation and auto-correction rules, tolerance checking, and posting logic.
To set up a form rule, open Admin Menu, Form Rule.
Contents
Use the query portal to search for an existing form rule. Once a form rule is selected, you are brought to the maintenance portal to view and maintain the selected record.
You can also click the Add link in the query zone's title bar to add a new form rule.
This portal appears when a form rule has been selected from the Form Rule Search results.
Note: When the Form Rule portal is used the context-sensitive Rules on Group zone appears in the dashboard. This zone lists the other form rules in the same group as the rule in context. From this dashboard zone you can add a new form rule to the group, or go to the maintenance portal for the other rules in the group
The topics in this section describe the base-package zones that appear on the Form Rule portal.
Contents
This is a standard actions zone. The Edit, Duplicate, and Delete actions are available.
The Form Rule zone contains display-only information about a form rule. This zone appears when a form rule has been selected from the Form Rule Search results, or if this portal is opened via a drill down from another page.
Please see the zone's help text for information about this zone's fields.
Follow this link to open the data dictionary where you can view the tables that reference CI_FORM_RULE.
Form rules are logically grouped together in a form rule group. The rules are executed in the following order: Each rule group linked to the form type is executed in sequential order. The rules in each group are executed in sequential order.
To set up a form rule group, open Admin Menu, Form Rule Group.
Contents
Use the query portal to search for an existing form rule group. Once a form rule group is selected, you are brought to the maintenance portal to view and maintain the selected record.
You can also click the Add link in the query zone's title bar to add a new form rule group.
This portal appears when a form rule has been selected from the Form Rule Group Search results.
The topics in this section describe the base-package zones that appear on this portal.
Contents
This is a standard actions zone. The Edit, Duplicate, and Delete actions are available.
The Form Rule Group zone contains display-only information about a form rule group. This zone appears when a form rule group has been selected from the Form Rule Group Search results, or if this portal is opened via a drill down from another page.
Please see the zone's help text for information about this zone's fields.
Follow this link to open the data dictionary where you can view the tables that reference CI_FORM_RULE_GRP.
The Form Rule List zone provides a summarized view of all form rules for a form rule group. A row is displayed for every form rule linked to the form rule group. The rules are shown in sequential order. The list includes the form rule information and a hyperlink to the rule's maintenance portal.
The standard actions of Edit, Duplicate and Deleteare available for each form rule.
Click the Add link in the zone's title bar to add a new form rule.
This zone displays all form types that reference the form rule group. This zone only appears if a form rule group exists in the portal context. The list includes the name of the form type and a link to the form type’s maintenance portal.
The base product provides a generic BO for Form Rule Group - C1-FormRuleGroup. Your implementation can add additional business rules to this BO as required.
The base product provides a parent BO for Form Rule - C1-FormRule. This BO defines the common elements for all form rules. It is not intended to be used stand-alone. Your implementation can include this BO in each rule BO and add the additional components such as custom UI Maps as required.
The base product supplies a number of BOs that apply particular Form Rules. Refer to the business objects that reference the Form Rule maintenance object C1-FORMRULE for a complete list.
Your implementation can define additional form rule BOs as required. The following points highlight the important configuration for this business object:
· Develop the appropriate rule processing algorithm to perform the rule logic.
· For any configuration required by the rule processing algorithm, consider whether it should be defined when configuring the form rule by a business user. If so, include the appropriate elements in the form rule business object's schema.
· For a rule that performs validation, consider whether the rule exception information, which includes the Exception Category should be defined when configuring the form rule by a business user. If so, include the appropriate elements in the form rule business object's schema.
· Consider what logical grouping this rule belongs to. Note that a group of rules is always executed in the context of a single rule event. Rules should be grouped according to common actions that make take place for a particular event or set of events.
The base product provides a Form Rule BO that is designed handle a large range of conditional validation - C1-CondElementValidation.
The Conditional Element Validation BO allows a business user to define a series of conditions that apply to sections and lines of a form. The conditions are defined as basic mathematical expressions that have a result of true or false. Your implementation should consider using this rule BO when defining a rule that validates a form line value in relation to other supporting lines on the form.
The following topics highlight some of the available features for conditional expressions. Other mathematical operators and functions are supported but these are not normally used for calculations that are common to forms validation.
Contents
Variable identifiers must be a character between a-z except x. Variable x is always used to refer to the form line that this rule applies to. Variable identifiers are case sensitive.
The following types of expression operators are supported.
Contents
Operators of *, /, %, +, - are allowed. Examples of expression using these operators are:
· x = a + b + c where the value of x should equal the sum of the values a, b and c
· x = a * r where r is a rate factor variable
Operators of =, != (not equal), <, >, <= and >= are allowed. Examples of expression using these operators are:
· x > a where the value of x should be greater than the value of a
· x != 0 where x must have a non-zero value
Parentheses may be used to formulate expressions with sub-computations. An example of an expression using grouping is:
· x = (a + b) / c where the value of x should be equal to the result of adding values a and b then dividing by the value of c
The following examples show the use of the most common supported functions:
Contents
· x = ceiling ( a* b) where x should equal the result of multiplying the value of a by the value of b and rounding up to the nearest whole number
· x = floor (a* b) where x should equal the result of multiplying the value of a by the value of b and rounding down to the nearest whole number
· x = round (a* b) where x should equal the result of multiplying the value of a by the value of b and rounding the nearest whole number. A result of 1.5 would round to 2 and a result of 1.4 would round to 1.
· any [value in a | value !=''] where a is a value from a repeating line and the condition is true if any of the values of a are not blank
· all [value in a | value !=''] where a is a value from a repeating line and the condition is true if none of the values of a are blank