Colleague Financial Aid Rule Writing & Troubleshooting Presented by: Colleen Olsen Financial Aid Coordinator Elmhurst College May 21, 2013 1 Introduction to FA Rule Writing • • • • • Where rules are used in FA module How rules are evaluated Elements required to write rules Rules versus Rule Tables Define the steps used to write rules – Decide on the rule that needs to be written – Conduct research to find the data needed – Map out the rules needed and code them in the system – Test the rules with test data 2 What are Rules? • They allow institutions to customize a method of action in the FA Module within Colleague. • Rules can often be used instead of custom programming, keeping IT out of the process • They can be a means of interpreting an institution’s policy so that Colleague can understand and react to that policy. • Depending on how complex the rules are, they fall anywhere between reporting and custom programming. • They are used where is flexibility is needed due to the variety of institutional policies that are present. 3 Where are rules used in FA? General Set-Up LCRL- Location Rule Table FRCP- FA Registration Credit Rules PATR- Attendance Pattern Rule Table FPRL- Full/Part Time Rules GEC- Global Eligibility Rules AEC- Award Eligibility Rules BDRL- Budget Definition Rules screen) SBRD- Student Budget Rules AAXL- Award AR Transmit Limits AAD- Award Amount Definition Communication Management: CRA- Correspondence Request Assignment CRRD- Correspondence Request Definition DOC- Document Paragraph Rules Packaging: PDRL- Packaging Definition Rule Table PCRL- Packaging CB/Inst. Rules (sub- PERL- Packaging Eligibility Rules (sub-screen) PARL- Packaging Amount Rules (sub-screen) PCTR- Packaging Percent Rules (sub-screen) PGRL- Packaging Group Rules (sub-screen) PYRL- Packaging Years (sub-screen) Electronic Loan Processing: HRRL- Loan/Hold Release LTRL- Loan Processing Rule Table Satisfactory Academic Progress: SPTD- SAP Type Definition (Multiple Rules) Web Advisor/Awards: ADRL- Award Letter ALRT- Award Letter Rule Table 4 How are rules evaluated? • The result initially from the evaluation of a rule is either Pass or Fail, no matter how complicated the rule. • In FA, there are processes that require multiple rules to be evaluated. (Example: Budget Rules, Eligibility Rules, Correspondence Request Rules) • Three ways that Colleague deals with multiple rules: The first rule is passed and the attached result is assigned; therefore the order of your rules is extremely important. All of the rules are evaluated and then the results of all passed rules are assigned. All of the rules are evaluated and must pass in order for any results to be assigned. 5 FIRST TRUE RULE…ex. PATR/SPTD/BDRL We have 12 SAP Status Rules which assign an associated status Once the student passes a SAP Rule, they are assigned this Status and will not be evaluated against any rules further down into the table 6 Our SAP rules: These are all of the possible 12 rules that a student could be evaluated against at our institution until they passed one rule, and then they would be assigned the appropriate SAP Status. SAP Status Rules SAP Status FASSAT (SPTD) SAP SAT S Satisfactory FASAP2 (SPTD) Acad Prob2 AP2 Acad. Probation Plan Term2 FASAP3 (SPTD) AP 3 AP3 Acad. Probation Plan Term3 FASTERM (SPTD) Terminated T Terminated FASMAX (SPTD) MAX TIMEFRAME MAX Maximum Time Frame Exceeded FASNMX (SPTD) NEAR MAX TIMEFRA FASSB (SPTD) SAP SUS BOTH NMX Nearing Max Time Frame SB Susp Both GPA CMPL Rate FASSG (SPTD) SUSP GPA SG Suspend GPA FASSP (SPTD)SAP PASS RATE SC Suspend Completion Rate FASWB (SPTD) SAP WARN BOTH WB Warn Both GPA CMPL Rate FASWG (SPTD) SAP WARN GPA WG Warn GPA FASWP (SPTD) WARN PASS WC Warn Completion Rate 7 ALL TRUE RULES…ex SBRD/CRRD/DOC All of the rules are evaluated and then the results of all passed rules are assigned. 8 All Rules must PASS…ex AEC/FRCP/GEC Award “GSL” contains 3 Rules 9 Elements required to write rules • Primary File View: determines the data elements available to us in writing the rule – using co-files, pointers and computed columns allow access to data from other files • Rule Connectives: determine how the rule is processed – WITH, AND, EVERY, OR, WE (WITHEVERY), ORWITH, OREVERY, OWE (ORWITHEVERY) • Left Hand Expression: must be a Field in the Run-Time Central Data Dictionary (CDD) – available fields determined by Primary File View • Relation: how to associate the Left Hand Expression to the Right Hand Expression • Right Hand Expression: may be a literal value in quotation marks or a field from the Run-Time CDD (no quotation marks) 10 How do you determine the Primary File View? Write rules from within the FA process where the rules will be evaluated. If you do a “Look Up” (…) on the field for the Primary File View on your rule, your view will be limited to the files from which you SHOULD choose! For example, rules on the Award Eligibility Criteria (AEC) form are limited to the TA.ACYR or TL.ACYR files for the Primary File View. The typical files used in the FA module as the Primary File View are the *.ACYR file suite files, FIN.AID SA.ACYR or CS.ACYR --Budgets (SBRD), Attendance Pattern (PATR), Packager (PERL, PARL) CS.ACYR-- (Correspondence Request rules (CRRD), MAILING (Paragraph rules for DOC) TA.ACYR --(Transmittal rules (GEC/AEC) 11 Co-Files in Colleague Primary File Views used in FA: Sample Co-Files CS.ACYR: PERSON, FIN.AID, SA.ACYR, MAILING, etc. (any file keyed by the Colleague ID number) TA.ACYR: No Co-files SAP.RESULTS: No Co-files MAILING: PERSON, FIN.AID, CS.ACYR, SA.ACYR, etc. (any file keyed by the Colleague ID number) You may use any data element from any co-file in your rule. 12 Co-file rule example: Primary file view is CS.ACYR, but field is in a co-file 13 Co-file rule example: Age is in the PERSON file, a co-file of CS.ACYR AGE can be used in this rule, as could any other data element in PERSON, or any other co-file 14 Pointers in Colleague • If you can’t use a co-file, use a pointer! • Pointers get us from the “Primary file view” to another file which contains data we need, and whose “key” is different from our primary file. • Can be single-valued (X), or multivalued (Q) • You may need to build pointers in RDEL on occasion, or simply “reset” a pointer by pulling it up on RDEL and saving out. 15 Pointers in Colleague Frequently needed in the “USING” field on the RLDT form (detail from RLDE) – If you are taken to this detail form when writing a rule, you MUST enter some pointer value in the “USING” field or your rule will not return a value (the system does not know how to find the necessary value) – Do a “lookup” to find the available pointers from which you should choose 16 Pointers in Colleague, example • CS.ACYR ISIR.FAFSA – CS.ACYR contains CS.FED.ISIR.ID, type X • The SINGLE key to the current Federally Flagged ISIR on NASU • The CS.FED.ISIR.ID is a pointer to ALL ISIR files (they all use the same key) – CS.ACYR contains CS.ISIR.TRANS.IDS, type Q • The keys to ALL imported ISIRs for this student for ALL ISIR files 17 SNIP 18 Data Element, delivered X pointer Note that this pointer points to multiple files 19 Data Element, delivered Q pointer 20 Virtual Field, custom pointer FA.ACAD.LEVELS Computed Column Code string[] xlResult1; key xKeyStudents for file Students; xKeyStudents = vFaStudentId; xlResult1 = vlStuAcadLevels; return xlResult1; 21 Rules vs Rule Tables Rules • Stored in the RULES file • Not inherently year specific • Rules file is shared by all modules • One or more pass/fail statements Rule Tables • Stored in the RULE.TABLE.ACYR File • Year- specific • Used by the Financial Aid module only • One or more rules OR a default value 22 Developing Rules Five Necessary Steps to proper rule Development 1. Articulate the rule 2. Research your data elements using provided tools 3. Write the rule in English statements 4. Code the rule in the system 5. Test, test, test! 23 Step 1: Articulate the rule • What is the purpose of the rule? • Write down exactly what you want from the rule – Computers do not make assumptions, you must clearly define your expectations • Define your rule in English statements 24 Step 2: Research your data elements • How do you identify fields in FA? – FIELD HELP while on the field you need • Colleague File & File Suites – Information on file suites is in the learning guide • Know the commonly used FA files used in rules – CS.ACYR (person ID key) – TA.ACYR – SA.ACYR – And all co-files 25 Step 2: Research—field help 26 Step 2: Research—field NAME 27 Step 2: Research—RFEI • RFEI is the data structure of the file – File key (you can determine any co-files) – Data elements – virtual fields/computed columns Recognize all associated fields, single and multi-value pointers, etc. 28 Step 2: Research—RFEI 29 Step 3: Write the rule in English • Writing out the rule in plain English is the most efficient way to begin • It provides back-up documentation if the rule needs to be reconstructed 30 Step 4: Code the rules--RLDE • Accessing the RLDE form from the mnemonic that drives the rule ensures that the rule will be created from the correct view • Recommend entering the “English statement” rule in the comments area for completeness, or at the very least, the “purpose” for the rule – Allows those coming behind you to see the intent of the rule if someone modifies your rule. 31 RLDE—FAAECRED sample rule 32 RLDE—Context for primary file! From AEC, we have 2 files when we “lookup” our primary file view. Note that if we go straight in from RLDE how that changes 33 34 RLDE--Rule example--FABRON Not in my file, this is an APPLICATION field—need a pointer! 35 Rule detail form, RLDT Enter your “using” pointer value here 36 Rule example from AEC example, above **This First Rule in “GSL” is checking the RULE ID FAAECRED to see if the student is registered at least half-time 37 Example from AEC, rule 2 **This Second Rule within “GSL” is checking Rule Id FAAEENTI to see if a student has completed “Entrance Counseling” 38 Example from AEC, rule 3 Rule ID FAAEMPN **This last rule within “GSL” is for checking to see if a student has an MPN. 39 Step 5: Test, Test, Test! • • • • RLTD and RTVF VES for transmittals (detail on failed rule) SBGT or SBRV PKCR in ERV mode 40 RLTD—Rule Test and Debug • Must have a key to the primary file • If the rule is written from an ACYR file, you must enter the year – Pay attention to the primary file – Errors out if you enter a year for a non-acyr file • Valid field if ‘passes’ • Invalid field if it does not 41 RLTD—Rule test and debug 42 RLTD—Primary file and Record ID 43 RLTD—passing example 44 RLTD—failure 45 RTVF—Virtual Field Test & Debug • Am I getting the proper result from my virtual field? • Enter Data Element • If an ACYR Primary file, enter year • Enter Record ID from Primary file – Remember if a co-file of PERSON, you must enter the 7 digit ID including leading zeros 46 RTVF—Virtual field test and debug 47 RTVF—Data returned 48 RTVF—No data returned 49 VES—Test Transmittal Rules • Transmittal rules entered on AEC & GEC • Failed transmittal rules on FATR – FATR doesn’t tell you WHY, only the rule that failed – You can use RLTD on individual rules OR • VES for the Award Period – Pass/Fail status for all awards (AEC) – Indicates whether the student passed global (GEC) 50 Testing AEC/GEC rules via VES Enter year, student ID and award period 51 VESAWED Detail on a “failed” award to determine the rules the student is not passing. You can further detail to see the results of the rule on REDT 52 Budgets • SBGT in Detailed Rule mode gives pass/fail on budget rules – Does not show all lines in rule, but does display student “return” values – Shows Pass/Fail value for rule • SBRV—Budget Validation – Shows details and return values, as well as columns for pass/fail for the condition – Shows Pass/Fail value for rule 53 SBGT—Detailed Rule information 54 SBGT with Detailed Rule Information = Yes Feb 01 2013 09:58AM 0094058 Batch FA Budget Assignment Budget Year: 2012 Budget Duration Override: *** SIMULATION MODE - NO FILES ARE UPDATED *** Page 1 Que, Susie Rule ID: FABGRSFT Graduate Full-Time 4 Components: GRBKFT,GRFEES,GRTUM,GRHO Rule Failed Connector Left-hand Expression Value Re Right-hand Expression Value Eval --------- ---------------------------- --------------------------- -- ------------------------------------------------------------------------------------------ --------------------------- ---WITH STU.CURRENT.RESIDENCY.STATUS UG EQ "GR","CS" Fail ORWITH STU.CURRENT.RESIDENCY.STATUS UG EQ "" Fail Rule ID: FABUGFT Ug D/I Full-Time Resident UGBKFT UGFEES UGHR 1 Components: UGTUBLK "UG" "D", "I" "1" Rule Passed Pass Pass Pass Rule ID: FABUGFLP Ug Dep With Parent 5 Components: UGTUBLK,UGFEES,UGBKFT,UGFTOC,UGBCD Rule Failed Connector Left-hand Expression Value Re Right-hand Expression Value Eval --------- ---------------------------- --------------------------- -- ---------------------------- ------------------------------------------------------------------------------------------ ---WITH STU.CURRENT.RESIDENCY.STATUS UG EQ "UG" Pass AND IFAF.DEPENDENCY D EQ "D" Pass AND CS.ISIR.HOUSING.CODE 1 EQ "2" Fail ORWITH STU.CURRENT.RESIDENCY.STATUS UG EQ "" Fail ***** INDIVIDUAL WAS ASSIGNED A BUDGET AND HAS EXISTING AWARDS ***** MULTIPLIERS ------------Type Factor ---- ------ | | | Zero |Component --------- YR TR MO CR NF | | | | | 1 2 9.00 24.00 5 Component Codes -------------------------- - CB INST ---------------------- ---------------------Frozen Status Cost Type Amt Ovr Cost Type Amt Ovr ----- ------ ----- ---- ----- ----- ----- ---- ----- ----- ----- ----- UGTUBLK UG Tuition FT Bloc UGBKFT Ug Books-Ft UGFEES UG Required Fees UGHR Ug Resident Housing UGBRD Ug Resident Board Ft UGFTRO Ug Other Costs-Ft A A A A A A 14040 500 650 3635 2825 650 TR TR TR TR TR TR 28080 14040 TR 28080 1000 500 TR 1000 1300 650 TR 1300 7270 3635 TR 7270 5650 2825 TR 5650 1300 650 TR 1300 ===== ===== Total Expenses: 44600 44600 55 PELL ----------Amt Ovr 28080 1000 1300 7270 5650 1300 ===== 44600 SBRV—Budget Rule Verification Mar 01 2013 12:11PM 0094058 Student Rule Verification Academic Year: 2012 Pa ge 1 Susie Que Rule ID: FABGRSFT Graduate Full-Time Connector Left-hand Expression --------- ---------------------------WITH STU.CURRENT.RESIDENCY.STATUS ORWITH STU.CURRENT.RESIDENCY.STATUS AND APPL.RESIDENCY.STATUS 4 Components: GRBKFT,GRFEES,GRTUM,GRHO Rule Failed Value Re Right-hand Expression Value Eval --------------------------- -- ---------------------------- --------------------------- ---UG EQ "GR","CS" Fail UG EQ "","UG" Pass UG EQ "GR","CS" Fail Rule ID: FABUGFT Ug D/I Full-Time Resident 6 Components: UGTUBLK,UGBKFT,UGFEES,UGHR,UGBRD,UGFTRO Rule Passed Connector Left-hand Expression Value Re Right-hand Expression Value Eval --------- ---------------------------- --------------------------- -- ---------------------------- --------------------------- ---WITH STU.CURRENT.RESIDENCY.STATUS UG EQ "UG" Pass AND CS.ISIR.HOUSING.CODE 1 EQ "1" Pass AND APPL.TERM.REPORTING.YEAR 2012 NE CS.YEAR Fail ORWITH STU.CURRENT.RESIDENCY.STATUS UG EQ "","UG" Pass AND APPL.RESIDENCY.STATUS UG EQ "UG" Pass AND CS.ISIR.HOUSING.CODE 1 EQ "1" Pass AND APPL.TERM.REPORTING.YEAR 2012 EQ CS.YEAR Pass Rule ID: FABUGFLP Ug Dep With Parent Connector Left-hand Expression --------- ---------------------------WITH STU.CURRENT.RESIDENCY.STATUS AND IFAF.DEPENDENCY AND CS.ISIR.HOUSING.CODE ORWITH STU.CURRENT.RESIDENCY.STATUS AND APPL.RESIDENCY.STATUS AND IFAF.DEPENDENCY AND APPL.HOUSING.DESIRED.FLAG 5 Components: UGTUBLK,UGFEES,UGBKFT,UGFTOC,UGBCD Rule Failed Value Re Right-hand Expression Value Eval --------------------------- -- ---------------------------- --------------------------- ---UG EQ 'UG' Pass D EQ 'D','X' Pass 1 EQ '2' Fail UG EQ '','UG' Pass UG EQ 'UG' Pass D EQ 'D','X' Pass Y EQ 'N' No Fail Rule ID: FABUGFOC Ug Full-Time Dependent Off-Campus 5 Components: UGBKFT,UGFEES,UGTUBLK,UGFTOC,UGHOCD Rule Failed Connector Left-hand Expression Value Re Right-hand Expression Value Eval --------- ---------------------------- --------------------------- -- ---------------------------- --------------------------- ---WITH STU.CURRENT.RESIDENCY.STATUS UG EQ 'UG' Pass AND IFAF.DEPENDENCY D EQ 'D','X' Pass AND CS.ISIR.HOUSING.CODE 1 EQ '3' Fail ORWITH STU.CURRENT.RESIDENCY.STATUS UG EQ '','UG' Pass AND APPL.RESIDENCY.STATUS UG EQ 'UG' Pass AND IFAF.DEPENDENCY D EQ 'D','X' Pass AND CS.ISIR.HOUSING.CODE 1 EQ '3' Fail 56 PKCR—ERV (Expanded Rule Validation) • To find packager related issues, ERV mode provides all rules with pass/fail on LINES only. • No “pass/fail” at the rule level – RESULTS, though from each section • Global eligibility, Packaging Group, Need/Gift Percent, Category eligibility, Award eligibility, Amount rules, etc. • Take care not to “print”, report can be very large depending on your rules 57 PKCR—ERV (Expanded Rule Validation) 58 PKCR in ERV mode—can be a LONG report, use caution when printing (excerpt of a 20 page report for one student) March 06 2012 10:19 AUTOMATIC PACKAGING REPORT Page 1 STUDENT PACKAGING SECTION - REPORT ONLY MODE (NOT UPDATED) *************************************************Student ID: 0570322*** Student Name Soc Sec No. Packaging Group Attendance Pattern 0570322 Susie Que xxx-xx-xxxx NEWTF New Traditiona TFFD Trad Ft Fa/Spr Dormitory ****Original Package**** *******New Package******* Award Amount Comment Award Amount Origination PELL 1300.00 Packaged PHEAA 3924.00 Packaged CATH 2000.00 Packaged OUTD 2000.00 Packaged CROSN 2000.00 Packaged CSCHN 12000.00 Packaged DSUB 3500.00 Packaged SEOG 960.00 Packaged OFFWS 1500.00 Packaged DUSUB 2000.00 Packaged ========================================INITIALIZATION Student ID: 0570322 Susie Que======================================== Packaging Definition Pkg Def Rule Table ID: DFLTPKDF from Default Results: FIRST From Recalculations - Rule: DFLTPKDF from Default ****Rule: Rule ID Connect Left-Hand Dictionary Element Left Rslt Operator Right-Hand Dict. Element Right Rslt PorF Rule Rslt ** 1.1 : FPK_FRST WITH APPL.ADMIT.STATUS TF EQ 'TT','RTT' TT,RTT Fail FIRST ** 1.2 : AND APPL.TERM.REPORTING.YEAR 2012 EQ SA.YEAR 2012 Pass ** 1.3 : AND APPL.ACAD.LEVEL UG EQ 'UG' UG Pass ** 1.4 : AND APPL.STUDENT.TYPE TRAD EQ 'TRAD' TRAD Pass ** 1.5 : ORWITH APPL.ADMIT.STATUS TF EQ 'TF','RTF' TF,RTF Pass ** 1.6 : AND APPL.TERM.REPORTING.YEAR 2012 EQ SA.YEAR 2012 Pass ** 1.7 : AND APPL.RATING 120 NE '' Pass ** 1.8 : AND APPL.ACAD.LEVEL UG EQ 'UG' UG Pass ** 1.9 : AND APPL.STUDENT.TYPE TRAD EQ 'TRAD' TRAD Pass ** 2.1 : FPK_OTRD WITH STU.CURRENT.TYPE EQ 'TRAD' TRAD Fail OTRAD ** 2.2 : AND FA.SA.YEARS 2012 NE SA.YEAR 2012 Fail ** 2.3 : AND C00.FA.COUNT.SA 1 GE '1' 1 Pass ** 2.4 : AND FA.CRED.COMP GT '1' 1.00 Fail Results: TFFD Results: FIRST 59 PKCR cont. Global Eligibility: FIRST_GLOB ****Rule: Rule ID Connect Left-Hand Dictionary Element ** 1.1 : F_NO_REJ WITH CS.FED.DEPENDENCY ** 2.1 : FPK_EFC WITH CS.FC ** 2.2 : AND CS.FC ** 3.1 : FPK_BDGT WITH CS.COMP.ID ** 4.1 : FPK_ADMT WITH APPL.TERM.REPORTING.YEAR ** 5.1 : FPK_ATH WITH APP.RECRUIT.PURPOSES ** 5.2 : ORWITH APP.RECRUIT.PURPOSES ** 5.3 : AND APP.MISC1 ** 5.4 : AND APP.MISC1 ** 6.1 : FPKRATED WITH APPL.RATING ** 6.2 : AND APPL.TERM.REPORTING.YEAR Results: Eligible (MUST PASS ALL RULES) Package Group From Packaging Rule: PGR_FIRST ****Rule: Rule ID Connect Left-Hand Dictionary Element ** 1.1 : FA_NEWTF WITH APPL.ADMIT.STATUS ** 1.2 : AND APPL.TERM.REPORTING.YEAR ** 2.1 : FA_NEWTT WITH APPL.ADMIT.STATUS ** 2.2 : AND APPL.TERM.REPORTING.YEAR Results: NEWTF (FIRST TRUE RULE) Attendance Pattern From Student: TFFD Year in College Campus Bases CB Cost From Student Budget..: 35780.00 CB FC ..........................: 4233.00 CB Need ........................: 31547.00 Institutional Inst Cost From Student Budget..: 32760.00 Inst FC ........................: 4233.00 Inst Need ......................: 28527.00 Gift Gift Cost Percent No Rule - use 100.00%: 100.00 Gift Need Percent From Packaging Rule: NEED_PCT Left Rslt D 4233 4233 BKSPFT,TUF 2012 ADCAT,ADOU ADCAT,ADOU 120 2012 Operator EQ NE GE NE EQ EQ NE NE UNLIKE NE EQ Right-Hand Dict. Element 'I','D' '' '0' ‘' CS.YEAR ‘' ‘' '' 'AD...' ‘' CS.YEAR Right Rslt PorF Rule Rslt I,D Pass Pass 0 Pass Pass 2012 Pass Pass Fail Pass AD... Pass Pass 2012 Pass Left Rslt TF 2012 TF 2012 Operator Right-Hand Dict. Element EQ 'TF','RTF' EQ SA.YEAR EQ 'TT','RTT' EQ SA.YEAR Right Rslt PorF Rule Rslt TF,RTF Pass NEWTF 2012 Pass TT,RTT Fail NEWTT 2012 Pass ****Rule record had no rules or subroutine - use default Results: 90.00 60 Resources!! • The “Financial Aid Learning Guide” – Someone on your campus very likely went to FA training…find the manual • Rules and Rule Tables Chapter • The ENTIRE appendix • • • AnswerNet document 2909 Session Handouts (from ellucianLive 2013, presented with Sheri Johnson, ellucian) – Where rules are used spreadsheet – Sample Rules spreadsheet Session 1864 Handouts from ellucianLive 2013 – Understanding the Architecture of Colleague FA 61 Questions? • Colleen Olsen – FA Coordinator, Elmhurst College – olsenc@elmhurst.edu Thank you! 62