Creating Functional Rules

The section describes how to create functional Rules.

Access the Rules Engine Manager Define Rule page (Set up SACR, and then System Administration, and then Rules Engine, and then Rules Engine Manager, select Add a New Rule, Define Rule).

This example illustrates the fields and controls on the Define Rule page. You can find definitions for the fields and controls later on this page.

Note:

For Rules delivered with the system and that have System Data displayed in the Rules Engine user interfaces, only the Long Description can be modified.

Field or Control	Description
Rule ID	Displays a unique ID generated by the system. When adding a new value the default value is NOID. The unique ID is generated when the Rule is saved. The Rule ID is created by combining prefix SCC_RULE_ID_ with the system date and time stamp in format YYYYMMDDHHMMSS.
Action	Note: The list of available Actions is dynamic depending upon the Rule Status. Note: For System-delivered Rules, only the Build Rule, Create New Group from Rule, Create New Rule from Rule, and Update Status Information (if Rule Status is Not Built) Actions are available. Select an Action for this Rule Group: Activate Rule – An In Progress Rule can be activated using the Activate Rule Action. Build Rule – Opens the Build Rule window. Create New Group from Rule – Selecting this Action transfers you to the Rule Group component. This Action is only available when a Rule is Active and not used by another Rule. The parameters for the new Rule Group are predefined based on the Rule from which it is being created. Create New Rule from Rule – This action clones the current Rule and creates a new Rule using the values from this Rule. Note: The Name of the new Rule is copied exactly from the current Rule so your first action should be to rename the Rule. Create New Version of Rule – Use this Action to introduce changes to Active Rules. By design, Rules are versioned rather than effective dated. Only one Version of a Rule can be active at any given time. This Action creates a new Version of the Rule with status In Progress. Activating the newest Version inactivates the previous Version automatically. Delete Rule – Rules can be deleted. When choosing this Action, a warning is displayed, and, after choosing “OK”, the Rule is deleted. Inactivate Rule – An In Progress Rule can be inactivated using the Inactivate Rule Action. Remove Base Entity – Use this Action to remove the Base Entity from this Rule. This Action is available when Rules have a status of In Progress or Active. For Active rules, the setup option to allow changes to active rules must be selected. If the Rule has references to any Entity or Property which is logically part of the Base Entity Hierarchy structure, for example a child Entity or Property, then a warning is displayed. Note: The Base Entity cannot be removed if the Rule is attached to a Rule Group. Remove Rule Group from Rule – If you use this Action, create new version of Rule and deselect the “Available in Other Rules” check box in the old Version/inactivated version. This Action is only available when a Rule is part of a Rule Group and has a Rule Status of In Progress. Note: Concerning the effects of adding a New Rule Group to an existing Rule: When a Rule Group needs to change and new Input or Output Parameters need to be added or removed, the process requires that you create a new copy (clone) of the Rule Group. New Parameters and Fields are then added to the New Rule Group. As the Rule Group provides the template for Rule Input and Output, all Rules associated with the old Rule Group need to move to the new Rule Group. This can be done using the following steps: 1. Deselect the Available in Other Rules option of the Rule attached to old Rule Group. 2. Create a new Version of the Rule attached to the old Rule Group. This action creates a new Version of the Rule with a Rule Status of In Progress. 3. Remove the Rule Group attached to the new Version of the Rule. 4. Add a new Rule Group to the new Version of the Rule. When a Rule Group is removed using the Remove Rule Group from Rule option, a new Rule Group can be added using the Rule Group Name prompt search. When adding a Rule Group to a Rule, the Rule must have the same or fewer input and output parameters than the Rule Group. New input and output Parameters can be added from the Rule Group to a Rule. In the case where there are input or output parameters defined on the Rule which do not exist in the Rule Group, they must be removed from the Rule first before adding it to the Rule Group. Make any other needed changes to the new Version of the Rule, build the Rule, and test all changes. Then, activate the new Version of the Rule. The old version of the Rule is automatically deactivated. Test Rule – Opens the Test Rule window. For more information, see Testing Rules. Update Status Information – Use this Action to refresh page information and view the latest Rule Build Status.
Version	Displays the Version number of the Rule. Rules are automatically versioned. The first version of a Rule is 1. Only one version of a Rule can be active at any given time. The Action drop down can be used to inactivate an Active Rule and to create a new Rule Version. When creating a new Version, the previous Version automatically becomes Inactive.
Rule Status	Displays the Rule Status Active Inactive In Progress. This is the initial Rule Status assigned when creating a Rule.
Rule Build Status	Displays the Rule Build Status. Values are: Rule Not Built – The Rule has never been built. Build Not Current – A change has been made to this Rule since the last build which may warrant a rebuild.) Build Failed – The build/compilation process for the Rule ran to error. Consult the process scheduler message log to view the error. Build Successful — The Rule was built without errors.
Status Last Date/Time	Displays the Last Date/Time of the Rule Build Status in native format including an indication of time zone. This field does not display until after an attempt to build this Rule.
Rule Name	Enter a Rule Name. The Rule Name is used when searching for a Rule and for display.
Long Description	Enter descriptive text explaining the function of the Rule.
Rule Category Name	Enter the Rule Category Name. The Rule Category restricts access to Rule Usages, Rule Categories, and Entities. Available Rule Categories are limited to those for which you have been authorized. This is determined by a Role or our User ID. If you have access to multiple Rule Categories, you should choose the Rule Category that is most appropriate considering the data that the Rule needs to access and any Functions that the Rule may need to call. Functional Expert users who create Rules may not necessarily be familiar with how to create Rule Categories so should be provided with instructions by Rules Engine Administrators about the Rule Categories for which they have been authorized. For example, depending on your institution's policy, Functional Experts may only be authorized to use a single Rule Category.
Rule Group Name	Enter a Rule Group Name if this Rule needs to conform to a specific template with predefined input and output Variables and a predetermined Base Entity. Note: Oracle recommends adding a Rule Group Name directly after you have created your Rule or Function and before adding Entity Profiles, Rule Usages, or Variables as they may conflict with those that are defined in the Rule Group. If you select a Rule Group that has Variables, a Rule Usage, or Base Entity that conflicts with the Rules you are creating, a warning message appears and the Rule Group is not added.
Rule Usage	Select a Rule Usage of Function, Rule, or Trigger. The available Rule Usages are limited to those for which the user has been authorized through Rule Category setup. The selected Rule Usage impacts availability of Rules Engine Manager functionality as follows: Rule: The Criteria grid, the Variables Grid, and Evaluations and Calculations grids are available. Function or Trigger: The Variables grid and Evaluations and Calculations grids are available. The Criteria grid is not available. Selection of Rule Usage needs to consider how this Rule is used and what tasks it needs to perform. Rule – Rules can be used stand-alone (when executed from the Rules Tester), called from other Rules, or called from a Batch Process. Rules need criteria in order for the correct data to be selected from the system. Trigger – Triggers are meant to be tied to a specific system event using the Trigger component. Triggers which are delivered with the System can be versioned; unlike other Rules or Functions. This means that when a Trigger has been attached to a Trigger component and marked as System, you can create a new Version of the Trigger which can subsequently be edited. Function – A Function is a reusable Rule that performs a specific task, often performed in the context of a larger Rule. For example, when creating a Rule that evaluates whether Total Credit is greater than a specific Credit amount, first the Sum of all Credit needs to be established. The “Add” Function could be used to do nothing other than add retrieved Credit to a Credit total. The “Add” Function could be used to add any numeric value in the system, not just Credit, making it very reusable. A Function does not need specific criteria in order to determine an exact set of data. In this Rule Creation example, it only needs a numeric input to perform its task. When a Function uses a Base Entity, information to determine an exact set of data is passed from the calling Rule to the called Function using Contextual Reference. See Understanding Contextual Referencing. This example is using a Rule Usage of Rule and Skill Level of Expert to demonstrate the use of Criteria to identify a specific set of data. The Criteria in this example are used to identify the exact student Academic Progress Tracker data from the Base Entity as chosen by selecting an Entity Name. If data from other application areas is needed, it can be collected using other Functions.
Entity Name	Enter the Entity to use as the Base Entity for the Rule. The Base Entity controls which application data you have access to when creating a Rule, Function, or Trigger. The Entities available are limited to those for which user has been authorized by attaching Entity Profiles to Rule Categories in the Rule Category setup. Identifying which data to use by designating the Base Entity can be considered the “starting point” of the creation of a functional Rule. Further, using the designated Base Entity with the Rule Criteria makes it possible to identify the exact record to use in the Rule. For a Function that uses a Base Entity, the exact data needed is passed from caller to called Function using Contextual Reference. In this example, a Rule is being created that look at Student Progression; therefore, the Rule needs to access Student Results Data as stored in the Academic Progress Tracker (APT) records. The APT data is represented in the Entity APT Header. By selecting the APT Header as the Base Entity, you can access all of the data associated with the APT Header Entity Tree. This means that you have access to all logical child Entities in that Tree structure like APT Program of Study, APT Course List, and APT Course as well as other data associated with those Entities. As with Rule Categories, Functional Expert users should be provided with instructions on selecting Base Entities. Also consider that since the available Base Entity is determined by the selected Rule Category, it could be that only one Base Entity is presented for selection. For more information, refer to Defining Rule Category Security and Understanding Contextual Referencing. See Setting Up Entity Registry.
View Entity Hierarchy	Click this link to display the Entity Hierarchy view for the Base Entity attached to the Rule.
Skill Level	Select the Skill Level required for creating this Rule: Expert – This Skill Level has access to all features delivered with Rules Engine. Developer – This Skill Level has limited access to Rules Engine features. A user accessing the Rules Engine Manager and selecting Developer Skill Level is assumed to create Rules using Application Package PeopleCode. The Criteria Grid and Evaluations and Statements Grid are not available with Developer Skill Level. In this example, a functional Rule is being created and there is no “coding” occurring. Therefore, a Skill Level of Expert is being used to demonstrate the Statement, Operator, Function, and Variable features.
Rule Application Class	Note: This field is available and required when Skill Level is Developer. Enter or select a Rule Application Class. A Rule Application Class can be selected from a list of Extension Application Classes. Warning! Developer Rules should be built by Developers/Programmers who have extensive experience with Application Package/Class PeopleCode programming. Developers working with the Rules Engine should be familiar with Entity Registry concepts.
Entity Data Load Option	Note: This field is available and required when the Rule Usage is Rule and an Entity Name has been entered. Select the Data Load Option when creating a Rule. Select Data by Criteria: This is the default option. The Criteria grid is available. Data from the attached Entity is selected according to Criteria provided. Select All Data: The Criteria grid is not available. All data is retrieved from attached Entity and brought into the Rule. Select No Data: The Criteria grid is not available. No data is retrieved from the attached Entity. Use this option when the intent is to insert a new row of data into the Base Entity using the CREATE-ENTITY statement without first retrieving data.
Logging Level	Select the Logging Level to use when testing this Rule: Error Messages – The first level of logging. This option only show errors. Informational Messages – This option shows all informational messages. No Message Logging – Turns off logging at the build level. Note: Oracle recommends that all Rules run on a production environment have this setting to optimize performance. Trace Logging – Show all errors, warning, errors, information messages, and the following: Note: Oracle recommends using the Trace Logging option to see correct trace results when testing Rules. Statements Descriptions from the Rules Engine for every Statement that is run. If the internal Function has Trace Logging, its Statements are also shown. An internal Function is a Function which is called by the main Rule. If the Function itself does not have Trace Logging settings, no trace options are shown for the called Function. Variable Maps The complete Variable Map, every variable and its value, is shown at the beginning and the end of each run along with any Variable Map for any called Function or Rule if Trace Logging for that Function or Rule is turned on. A Variable map example is Assign V_StudentID = ‘SSRN0012’ as an example to where a Variable is assigned. Call Statements All arguments sent in and all returns received in the log file. XML Dump of the Entity Before Rule Execution The XML Dump is created for rules with Entity Processing. The XML Dump contains a dump of the Base Entity prior to Entity processing. XML Dump of the Entity after Rule Execution The XML Dump is created for rules with Entity Processing. The XML Dump contains a dump of the Base Entity after Entity processing has completed. Any changes to the Entity (inserted or updated data) are reflected in the Entity Dump. Warning Messages – This options shows all errors and warnings. Write to Log – Select this option to create a log file when processing Rules in Batch. Write to Log can be used in combination with Statement “Write To Log” Note: Oracle recommends using the Trace Logging option to see correct trace results when testing Rules.
Available To Be Used	Select this check box if you want to allow this Rule or Function to be available for use by other Rules or feature functionality. If you do select this check box, it is recommended that you do so after adding Variables and Criteria to the Rule and finalizing the functionality for your Rule.

Note:

Save the Rule after completing the first portion of the Definition tab (everything above the Available in Other Rules check box) and before adding Variables and Criteria. At this point the Rule Status is In Progress, and the Rule can still be changed and retested.

Note:

You cannot version Rules with a Rule Usage of Rule or Function that are delivered with the System and that have System Data displayed in the Rules Engine user interfaces. These Rules must be copied (cloned) and a new Rule or Function created.

You can version Rules with a Rule Usage of Trigger that are delivered with the System and have System Data displayed in the Rules Engine user interfaces.