Introduction

In the Regent Document Assignment Tool, users can select documents to be assigned to a group of students in bulk, based on the results of a selected, predefined Query.

Overview

The Smart Form Manager Tool is available in the Regent Tools menu for users with the ‘Smart Form Manager Tool’ permission enabled.

The Document Assignment Tool is comprised of a top section with selection options for Institution Name and Query Name and a bottom section for the selection of Documents to be assigned.

NOTE: This tool is designed to be used at the Institution level. Only one Campus per Institution should be configured.

Getting Started

Schools will need to:

1. Be on or upgrade to the Regent Award 6.5.0.0 Release or a subsequent Release

2. Update Enterprise Permission

3. Create Smart Form

4. Update Document Tracking Setup

Smart Form Manager Tool

A tree-view menu displays on the left-hand side of the Smart Form Manager tab on the Smart Form Manager screen.

The following options are available in the tree-view menu:

• + Create Smart Form

  • Used to begin the creation of a new smart form.

• + Import Smart Form

  • Used to import/load a Smart Form from one environment to another.

• → Active Smart Forms

  • Used to access an existing 'Active Smart Form. A Smart Form is considered ‘Active’ if today’s date falls within the effective Start Date and End Date defined on the Smart Form Information tab.

• → Inactive Smart Forms

  • Used to access an existing ‘Inactive’ Smart Form. A Smart Form is considered ‘Inactive’ if today’s date does not fall within the effective Start and End Date defined on the Smart Form Information tab.

Creation or Editing of a Smart Form

Sections

Section names display on the Smart Form menu in the Student Portal. Sections display in numerical order from lowest to highest based on the number entered in the Section Sort Order field.

Groups

Groups are used within each Section to categorize questions. Each group is comprised of one or more questions. All questions contained within a group are organized beneath the Group name defined and displayed within each Section. Groups display in numerical order from lowest to highest based on the number entered in the Group Sort Order field.

Questions

Questions are displayed within each Group to categorize questions. Each group is comprised of one or more questions. All questions contained within a group are organized beneath the Group name defined and displayed within each Section. Questions display in numerical order from lowest to highest based within the Group on the number entered in the Question Sort Order field.

Dependency Logic and Validations

Dependency Logic

Overview

Smart Forms can be designed to use conditional logic to tailor each question to an individual applicant and minimize the number of questions an applicant is required to answer by using Dependency logic. Dependencies use dynamic logic for Sections, Groups, and Questions to make Visible or hide based off of responses to Questions within the Smart Form. Dependencies also control if a Question is Required when made Visible or not. For example, a Dependency can be created to Hide a Question, make a Question Visible and Required, or make a Question Visible and Not Required.

A Section, Group, or Question can have one or more Dependencies. Each Dependency is comprised of one or more rules.

• Dependency can be of an "AND" or "OR" types. The "AND" type dependency indicates that the dependency will be triggered only when all its rules are triggered. The "OR" type dependency indicates that the dependency will be triggered when at least one of its rules is triggered.

• If no dependencies are applied, then the section/group/question goes back to its default visibility/required state as defined in the questionnaire.

• A Single Dependency record can be attached to a multiple objects (sections, groups or questions).

• The Dependency information is stored in the SnapDependency table, and it contains the description and the type information of a dependency.

• Section dependency information is stored in a SnapSectionDependency table, and it links the SnapDependency and SnapSection tables.

• Group dependency information is stored in a SnapGroupDependency table, and it links the SnapDependency and SnapGroup tables.

• Question dependency information is stored in a SnapQuestionDependency table, and it links the SnapDependency and SnapQuestion tables.

💡

Tip: It's recommended that you set a Section/Groups/Questions visibility to a base visibility, and then only create rules which change the visibility. This way you do not have conflicting dependencies or dependency rules (one rule which makes it hidden, and another rule which makes it visible). If both rules evaluate to true, then it can be more complicated to determine which rules visibility applies. For instance, perhaps you set a Section's visibility to hidden, and then only create dependencies/dependency rules that make it visible. See the "Competing Dependencies Example" in Examples section below.

https://velocity.apache.org/engine/1.7/user-guide.html

Dependency Rules

• Dependency rules are the rules that describe the Dependency behavior. Every created rule controls the visibility or required (for questions only) states of an object and is attached to a Dependency.

• The individual rules have the flags for visible and required. When different rules in the same dependency have different values for those flags, the first rule that is evaluated will trigger, and all subsequent rules in the dependency will be ignored.

• The dependency rules are evaluated in the order they were added to the database.

• Every rule has the following information:

  • Comparison operator (=, >, <, >=, <=, !, <>, !=)

    • The symbols "<>" and "!=" are interchangeable operators that mean "not equal".

    • The Exclaimation point means logical not.

  • Dependent question option id

  • Expression

  • Required Flag

  • Visible Flag

• Rules can be a two types: question based or expression based

  • Question based rules are the rules that makes target object dependant of the value of another question in the application.

  • Expression based rules are the rules that are evaluated using an expression provided by the user. This expression is based on the javascript language. A single rule expression can be build on one or more dependent questions using various logical and mathematical operations. Question values are referenced by using the following notation {questionCode}

  • There are some properties that can be accessed for use in expression evaluations that are not questionCodes.  The following properties are attributes of the application itself and can be used in the same manner as questionCode values (ie: {property}):

    • UserName

    • YearDescription

    • YearCode

      • This returns a special int which is essentially (max year of FAY)-2010. So for 2018-2019 FAY, the year code would be 9.

    • InstitutionExternalId

    • LocationName

    • CampusName

    • LocationExternalId

    • CampusExternalId

    • SiteName

    • SiteExternalId

    • ProgramName

    • ProgramExternalId

    • ProgramType

  • Logical evaluations can be strung together using logical AND (&&) and logical OR (||).  These kind of conditions allow multiple comparisons to determine the ultimate result of the expression.  The words "AND" and "OR" are interchangeable with "&&" and "||", respectively.

    • SnapUtility.EqualOfAny('hi', 'is', 'hi', 'here') && SnapUtility.IsCurrentDateBefore('01/01/2013') - returns false because both conditions must be true for the expression to be true.

    • SnapUtility.IsCurrentDateBefore('01/01/2013') || SnapUtility.EqualOfAny('hi', 'is', 'hi', 'here') - returns true because at least one of the conditions is true.

  • Several Helper functions are provided:

    • UpperCase - returns string - Converts the argument to UPPER CASE. eg: SnapUtility.UpperCase("upper case") returns "UPPER CASE".

    • Trim - returns string - Removes leading and trailing whitespace.  eg: SnapUtility.Trim("   Hello   ") returns "Hello".

    • TrimUpper - returns string - Performs both UpperCase and Trim commands.

    • EqualOfAny - returns boolean - Performs TrimUpper and checks if the first argument is in the list of remaining arguments (this function is case insensitive).  eg: SnapUtility.EqualOfAny("Hi", "Does", "hi", "exist") returns true.

    • IsNumber - returns number - Checks to see if the first argument is a number.  If it is not, the second argument is returned.  eg: SnapUtility.IsNumber("Dog", -1) returns -1.

    • CheckNumber

    • CompareDate - returns number - Checks to see how two dates compare.  If the first date is after the second date, the function will return a positive number.  If the second date is after the first one, the function will return a negative number.  If the dates are the same, the function will return 0.  If the arguments cannot be resolved to dates, the function returns NaN.  eg: SnapUtility.CompareDate('07/19/2013', '08/01/2013') returns -1.

    • IsCurrentDateBetween - returns boolean - Checks to see if the current date falls in a range (non-inclusive).  eg: SnapUtility.IsCurrentDateBetween('01/01/2013', '01/01/3000') returns true.

    • IsCurrentDateAfter - returns boolean - Checks if the current date falls after a specified date.  eg: SnapUtility.IsCurrentDateAfter('01/01/2013') returns true.

    • IsCurrentDateBefore - returns boolean - Checks if the current date falls before a specified date.  eg: SnapUtility.IsCurrentDateBefore('01/01/2013') returns false.

    • AddDaysToDate - returns Date - Adds a specified number of days to the specified date.  eg: SnapUtility.AddDaysToDate('01/01/2013', 9) returns '01/10/2013'.

  • If a dependant question is hidden (visibleFlag = 0) then the dependency rule is not evaluated and always returns false.

  • For the expression based rules, by placing “@” symbol before the question code in expression points the application to evaluate this question even if it is hidden. (@{studentsMaritalStatus})

  • If one of the dependant questions (in case of an expression based rule) is hidden then the whole expression will not be evaluated.

  • Because visibility / required flags are set on the Rule level it is possible to have one rule which sets something to hidden and another rule which sets something to visible in the same dependency.

    • For AND dependencies, the visibility / required flag of the last rule will be used

    • For OR dependencies, the visibility / reguired flag of the first triggered rule (rule with conditions met) will be used. 

• If there are multiple Dependencies, each with its own set of Dependency Rules then the following evaluation process will take place:

  • All dependencies and its dependency rules are read from the database in the order they were added.

  • Application starts to evaluate dependency rules

  • Application checks the current rule’s dependant question’s status. If a dependant question is hidden then the rule is ignored.

  • In case of an expression based rule, application checks every question’s status that is met in the expression. If one of the questions is hidden and does not have status ignoring symbol then the whole expression is ignored.

Dependency Examples

1. /wiki/spaces/SNAP/pages/8716538

Validations

https://velocity.apache.org/engine/1.7/user-guide.html

https://www.geeksforgeeks.org/javascript-regexpregular-expression/

Document Persistence

Overview

The information on this page includes details about the Document Requirements Persistence features supported in SNAP.

The SNAP Document Requirements Persistence (DRP) feature allows SNAP administrators to configure records that create and update student, document requirements in REM. The DRP configurations are associated with a smart form document and is accessible through the SNAP Administration - Questionnaire Management page. Whenever a smart form document is completed and signed, the DRP records are processed. 

Summary

SNAP can be configured to treat all documents with the same smart form type (per REM's Document Setup) as the same Document Requirement for the student. However, REM's Document Setup option, Enforce Scope Uniqueness, must be turned on.

Examples

A school has multiple versions of a VerificationWorksheet smart form defined in REM's Document Setup: Verification Worksheet (primary); Verification Worksheet - Change (variant); Verification Worksheet-V5 (variant); and Verification Worksheet - Revised Request (variant). REM's smart form document, called "Verification Worksheet." Each document is setup to Enforce Scope Uniqueness.  The school has a 2015 Student Filing Extension Granted by the IRS document setup the Verification Worksheets.

Example 1

1. Student starts a Verification Worksheet smart form application.

2. Student indicates No, I have already filed a tax return SNAP smart form questionnaire.

3. Student completes and signs their Verification Worksheet.

4. A 2015 Student Filing Extension Granted by the IRS document requirement is created for the student.

5. Student starts a Verification Worksheet - Change smart form application.

6. Student indicates No, I have already filed a tax return.

7. Student completes and signs their Verification Worksheet.

8. A 2015 Student Filing Extension Granted by the IRS document requirement does not get created for the student.

Example 2

Given:

1. Verification Worksheet for FAY

   1. W-2 document, scope uniqueness is turned off in REM

   2. Student selects "Will Not File"

   3. Student indicates that they received a W-2 from Employer 1 and provides information for Employer 1

   4. Student indicates that they received a W-2 from Employer 2 and provides information for Employer 2

When:

1. Student completes and signs the Verification Worksheet - Change smart form for same FAY

   1. Student selects "Will Note File"

   2. Student indicates that they received a W-2 from Employer 1 and provides information for Employer 1 (Employer A)

   3. Student indicates that they received a W-2 from Employer 2 and provides information for Employer 2 (Employer B)

   4. Student indicates that they received a W-2 from Employer 3 and provides information for Employer 3 (Employer C)

Then:

1. A new, needed, W-2 document is created in REM, with the reason set to the name of Employer 3 (Employer C)

Example 3

Given:

1. Verification Worksheet for FAY

   1. W-2 document, scope uniqueness is turned off in REM

   2. Student selects "Will Not File"

   3. Student indicates that they received a W-2 from Employer 1 and provides information for Employer 1 (Employer A)

   4. Student indicates that they received a W-2 from Employer 2 and provides information for Employer 2 (Employer B)

When:

1. Student completes and signs the Verification Worksheet - Change smart form for same FAY

   1. Student selects "Will Note File"

   2. Student updates the information for Employer 1 to Employer B

   3. Student updates the information for Employer 2 to Employer C

   4. Student deletes the information for Employer 3

Then:

1. The W-2 for Employer A is waived

2. The W-2 for Employer B remains unchanged

3. The W-2 for Employer C is created with a needed status

Example 4

Given:

1. Verification Worksheet for FAY

   1. W-2 document, scope uniqueness is turned off in REM

   2. Student selects "Will Not File"

   3. Student indicates that they received a W-2 from Employer 1 and provides information for Employer 1 (Employer A)

   4. Student indicates that they received a W-2 from Employer 2 and provides information for Employer 2 (Employer B)

When:

1. User changes W-2 for Employer A to satisfied in REM

2. Student completes and signs the Verification Worksheet - Change smart form for same FAY

   1. Student selects "Will Note File"

   2. Student updates the information for Employer 1 to Employer B

   3. Student updates the information for Employer 2 to Employer C

   4. Student deletes the information for Employer 3

   5. REM

Then:

1. The W-2 for Employer A is unchanged

2. The W-2 for Employer B remains unchanged

3. The W-2 for Employer C is created with a needed status

Technical Details

1. Users need to be able to configure questionnaires so that the following SNAP->REM persistence can occur in a transactional manner

2. Document Requirements - configurable to be able to persist documents in REM. Can be configured to create new documents, update existing documents, or not persist at all, based on the existing docs attached to the student.

3. Configurable fields

4. Name: Must match name of document in REM document setup. If a matching document is not found in REM setup, the following error is thrown at time of application processing: "Document name of 'docname' not found."

5. Special "{fay}" text can be used in name, it will automatically be replaced by the federal award year of the questionnaire (e.g. 2012-2013, 2013-2014, etc)

6. Condition (expression) -> an optional javascript expression, similar to dependency / complex validator expressions which can be set. If it's set, the doc req will only attempt to persist if the expression results in true. Will handle {questionCode} formatting. No special logic for whether questions are hidden, visible, etc.

7. Match configuration - Capability to create, update, or do nothing if a matched document for the student already exists based on the existing doc requirement status. User can select multiple statuses for update vs create. Status selection will be mutually exclusive (a doc status can only exist in one of the following items):

8. Update On Match Statuses: (selected document statuses)

9. Create On Match Statuses: (selected document statuses)

10. Otherwise ignore

11. Can configure to create the document if there is no match

12. Scope: STUDENT or FEDERALAWARDYEAR

13. Status: NEEDED,SATISFIED,UNSATISFIED,RECEIVED,INCOMPLETE,WAIVED

14. Status doc will be saved as if the questionnaire is not an esign questionnaire, or it is an esign questionnaire but user did not esign (they paper signed instead)

15. ESignedStatus: NEEDED,SATISFIED,UNSATISFIED,RECEIVED,INCOMPLETE,WAIVED

16. Document will be created or updated with this status if it's an ESIGN questionnaire and the user did choose to E-sign

17. FEDERALAWARDYEAR will be set to Federal Award Year of questionnaire

18. Supported entry types: AddressRelated, AwardRelated, AuditRelated, COARelated, CODRelated, DisbursementRelated, DocumentRelated, EnrollmentRelated, ISIRRelated, NeedRelated, PLUSRelated, PJRelated, QARelated, ResourceRelated, R2T4Related, SAPRelated, SBLLoad, ServiceRelated, VerificationRelated, CommunicationRelated, Other, ESTRelated, WorkStudyRelated

19. Attachment Type: None, PdfTemplate, FAFSA

20. None - no attachment stored in REM

21. PdfTemplate - Indicates a PDF attachment will be created based on the value of Attachment Template

22. FAFSA - The standard Dept. Of Ed. FAFSA (that matches fed award year of questionnaire) will be pre-populated from the SNAP questionnaire.

10. Attachment File Name: string of file name as stored in REM

11. Attachment Template - string field which will take a named velocity template. Note - this velocity template MUST exist in the theme the questionnaire is processed with, otherwise an "Template 'templatename' does not exist." error will be thrown at time of application processing.

1. Notes about fields which are not configurable

2. Letter correspondence date -> ignored by snap

3. Email correspondence date -> ignored by snap

4. Activity Source Type - STUDENTACTION always used

5. Message - will use the message as set up in REM document setup

6. Reason - will use the reason as set up in REM document setup

7. Received Date - Will rely on REM services automatically setting to current datetime if existing received date is null (or we are creating doc) and status is RECEIVED or SATISFIED

8. Reviewed Date - Will rely on REM services automatically setting to current datetime if existing reviewed date is null (or we are creating doc) and status is SATISFIED

9. This configuration will be included in when a questionnaire is copied, exported, or imported.

10. EFAFSA:

11. Will persist as the current EnableEFAFSAPersistence configuration setting dictates (which can be scoped for the whole snap instance, or scoped to questionnaire which takes precedence)

12. Student demographic fields: These will be handled in another JIRA issue to facilitate testing

13. Management screens in SNAP admin pages (Persistence link/button on questionnaire detail page).

SNAP Administration Page

SNAP Questionnaire Management Page

SNAP Questionnaire Document Requirements Persistence Page

SNAP Document Requirements Persistence Configuration Page

Glossary Terms

Document Name - This is the name of the document in REM that is associated with this DRP configuration.

Scope: This is the document scope associated with the REM document. Available values are Student, Student and Reason, Federal Award Year, and Federal Award Year and Reason.

Default Status: This is the status that the student's document requirement shall be set to upon completion of the smart form associated with this DRP configuration when the smart form is not configured for electronic signatures.

Esigned Status:  This is the status that the student's document requirement shall be set to upon completion of the smart form associated with this DRP configuration when the smart form is configured for electronic signatures.

File Name: The name to use for the file name associated with the student's document requirement record in REM.

Template Name: Used in combination with attachment type and will generate a document using the specified template when persisting the student's document requirement in REM.

Activity Log Entry Type: This is the name of the activity log in REM where a message will be created when the DRP action is completed.

Attachment Type: Used in combination with template name and will generate a document using the specified template when persisting the student's document requirement in REM. Available values are None: PDF Template; and FAFSA.

Condition Expression: Any valid, Boolean expression. Answers to questions in the corresponding smart form can be accessed by wrapping the question code in curly braces. Logical operators, such as, AND (&&), and OR (||) may be used in combination with built-in expressions, such as, SnapUtility.EqualOfAny, and SnapUtility.ReasonEqualToAny. The SnapUtility.ReasonEqualToAny is a special function that can not be used in combination with other expressions and will perform the requested action on existing, student documents where the document reason matches any of the values provided to the function. If an expression did not evaluate to true or false, that means the expression is not valid and contains syntax errors. If the expression is invalid, persistence actions for this document requirement will be ignored.

Create On No Match: If checked, the DRP document will be created in REM even if the smart form document can not be found for the specified create statuses. The document will be created based on the "Attachment Type" field selection.

For Transfer: Used in combination with REM Linked Document flag, and If both are checked, documents persisted in REM will be transferred to the SNAP database.

REM Linked Document: Used in combination with REM Linked Document flag, and If both are checked, documents persisted in REM will be transferred to the SNAP database.

Update Statuses: The DRP student document requirement in REM, will have its status set to the default or esigned status if the smart form document status is in the list of updated statuses.

Available Statuses: The list of available document requirement statuses.

Create Statuses: When the current student document status matches a status in the list of create statuses, a new document is created.

Related Tickets

SNAP-2899 - SNAP questionnaires can be configured to persist document requirements to REM upon app completion

Student Portal: Create new function for Document Requirement Persistence (DRP) Reason Expression