Introduction
...
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.
...
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.
...
Information
The Information tab provides basic Smart Form setup information, including the Smart Form Name, Federal Award Year, and valid Effective Start and End Dates.
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| The text entered in this field is displayed in the Smart Form menu as the Menu Section NameSection Name
Template Engine If static is selected, the field content is displayed in the same manner provided. If velocity is selected, a velocity templating engine is used that will allow for dynamic logic and display (see https://velocity.apache.org/engine/1.7/user-guide.html). Required Dropdown
| Sort OrderTextbox
Numberic box Visible If selected, the Section will be visible by default. If unselected, the Section will not be visible by default. Dependency logic can be used to display or hide the Section from its initial default state. Optional Checkbox Section Additional Information and Advanced Settings Section Id A system-generated ID is created and associated when creating a new section. Textbox (Read-only) Created At This is the date upon which a new section is created. Textbox (Read-only) Modified At This is the last date upon which a section was modified. Textbox (Read-only) Section Title The text entered in this field is displayed at the top of the Smart Form page. Optional Textbox Section Information The text entered in this field is displayed at the top of the Smart Form page beneath the Section Title, if configured Optional Text Area | The selection(s) in this section can be used as an identifier or in validation and dependency logic in Parent Information
Unselected | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
...
| Expand | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||
Group Field Name Group Field Description Group Field Type Group Field Options | If static is selected, the field content is displayed in the same manner provided. If velocity is selected, a velocity templating engine is used that will allow for dynamic logic and display Template Engine
| ||||||||||||||||||||||||||||||
Document Persistence
Document Requirements Persistence (DRP) allows school users to create rules using regular expressions (see https://
...
...
...
Dropdown
...
Static (Default)
Velocity
...
Group Name
...
The text entered in this field is displayed as a Group Title for a set of one or more questions in the Smart Form.
...
Textbox
...
Group Instructions
...
The text entered here is displayed as instructional messaging for the questions within the group.
...
Textbox
...
Code
...
The text entered here will be used as a short name to identify the Group in the Smart Form Manager.
...
Textbox
...
Sort Order
...
The number entered here will be used to sort Groups within the Section from the lowest Sort Order to the highest Sort Order.
...
Numeric
...
Visible
...
If selected, the Group will be visible by default. If unselected, the Group will not be visible by default. Dependency logic can be used to display or hide the Group from its initial default state.
...
Checkbox
...
Selected
Not Selected (Default)
...
Page Index
...
Groups can be displayed on different pages within each Section. The number entered here will be used to determine which page the Group is displayed on.
...
Numeric
...
Group Additional Information and Advanced Settings
...
Group Id
...
A system-generated ID is created and associated when creating a new group.
...
Created At
...
This is the date upon which a new group is created.
...
Modified At
...
This is the last date upon which a group was modified.
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.
...
| title | Question Fields |
|---|
...
Question Field Name
...
Required/Optional
...
Question Field Description
...
Question Field Type
...
Question Field Options
...
Field Type
...
Required
...
The selection here will be used to determine the question selection type.
...
Dropdown
...
Textbox
Dropdown
RadioButton
Date
SSN
Autosize Dropdown
MMDDYYYY Dropdown
HyperlinkButton
Text Only
MMYYYY Dropdown Date
Text Area
Checkbox
Currency - Whole Dollar
Phone
...
Data Type
...
Required
...
The Data Type entered here will determine how the value is saved in the database and the available operators in the Regent Query Tool. If this field is not selected, the question is not available as an option in the Regent Query Tool.
...
Dropdown
...
Text
Amount
Date
Number
...
Template Engine
...
Required
...
If static is selected, the field content is displayed in the same manner provided. If velocity is selected, a velocity templating engine is used that will allow for dynamic logic and display (see https://velocity.apache.org/engine/1.7/user-guide.html).
...
Dropdown
...
Static (Default)
Velocity
...
Question
...
Required
...
The text entered in this field is displayed as a Group Title for a set of one or more questions in the Smart Form.
...
Textbox
...
Help Text
...
Optional
...
The text entered here will display as help text beneath the question in the Smart Form.
...
Textbox
...
Code
...
Required
...
The text entered here will be used as a short name to identify the question in the Smart Form Manager.
...
Textbox
Allows alpha-numeric characters without spaces
...
Sort Order
...
Required
...
The number entered here will be used to sort questions within the Group from the lowest Sort Order to the highest Sort Order.
...
Numeric
Pre-populate Question Response from
...
Optional
...
If ‘Prior Smart Form’ is selected, the question response is pre-populated from the most recently completed Smart Form with the same Smart Form Type, regardless of the FAY scope. If ‘Prior Smart Form with same FAY’ is selected, the question response is pre-populated from the most recently completed Smart Form with the same Smart Form Type and the same FAY scope. If ‘None’ is selected, the question response presented in the Smart Form is not pre-populated.
...
Dropdown
...
None (Default)
Prior Smart Form
Prior Smart Form with same FAY
...
Default Question Response
...
Optional
...
The text or input value entered here will be used to pre-populate the response for the question in the Smart Form based on predefined Regent data or one of the available options.
...
Textbox
...
Maximum Number of Characters Allowed in Response
...
Optional
...
The number entered here will be used to as the limit for the number of characters allowed in the user response for this question when completing the Smart Form.
...
Numeric
Maximum Characters: 10
...
Required
...
Optional
...
When this field is selected, the question requires a response in the Smart Form. If selected, this question is always displayed if the section and group are displayed and takes precedence over the ‘visible’ setting for the question. If dependency logic is desired for the question, the ‘visible’ setting should be used to display or hide the question from its initial default state.
...
Checkbox
...
Selected
Not Selected (Default)
...
Visible
...
Optional
...
If selected, the Question will be visible by default. If unselected, the Question will not be visible by default. Dependency logic can be used to display or hide the Question from its initial default state.
...
Checkbox
...
Selected
Not Selected (Default)
...
Read Only
...
Optional
...
When this selection is selected, no question options will be required or available.
...
Checkbox
...
Selected
Not Selected (Default)
...
Group Additional Information and Advanced Settings
...
Question Id
...
A system-generated ID is created and associated when creating a new question.
...
Created At
...
This is the date upon which a new question is created.
...
Modified At
...
This is the last date upon which a question was modified.
...
Reset Response if Hidden
...
Optional
...
When this field is selected, the question response will revert back to the original default response value (e.g. blank, unselected) if the question is subsequently hidden due to smart logic. For example, if a user answers ‘Yes’ to this question then changes a prior question that forces this question to no longer display, the response value is then reverted back to the original default response value.
...
Checkbox
...
Selected
Not Selected (Default)
...
Reset Response if Restarted
...
Optional
...
When this field is selected, the question response will revert back to the original default response value (e.g. blank, unselected) if the question is subsequently displayed after being hidden due to smart logic.
...
Checkbox
...
Selected
Not Selected (Default)
...
Auto Capitalize
...
Optional
...
When this field is selected, the response will be user response in the Smart Form is automatically updated to all capital letters.
...
Checkbox
...
Selected
Not Selected (Default)
...
Options Expression
...
Optional
...
This field allows an expression to be provided by the user when to display an option under the defined conditions. Expressions use JavaScript language (see https://www.geeksforgeeks.org/javascript-regexpregular-expression/) to perform logical and mathematical operations to determine if the expression is true or false.
...
Textbox
...
Secure
...
Optional
...
This is a legacy setting and is no longer used.
...
Checkbox
...
Selected
Not Selected (Default)
Dependency Logic and Validations
Dependency Logic
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
...
Validations
https://velocity.apache.org/engine/1.7/user-guide.html
https://www.geeksforgeeks.org/javascript-regexpregular-expression/
Document Requirement Persistence
Document Requirements Persistence (DRP) allows school users to create rules using regular expressions (see https://www.geeksforgeeks.org/javascript-regexpregular-expression/) to add or update a student document requirement in Regent. Document Requirements are added and updated upon the completion, including signature(s), of the Smart Form. The document requirement is only added or updated if the expression results are true.
For example: For a Filing Status Confirmation Worksheet, if a student indicates, ‘No, I already filed a tax return’ within the Smart Form, DRP can be created to add the student Tax Return document requirement with a status of ‘Needed’.
Document Setup must be considered when adding DRP. If a document is configured to Enforce Scope Uniqueness, a new document is not added if it already exists but the status of an existing document can be updated. If documents are configured to be added upon ISIR import, DRP can be used to update the document status on an existing document(s).
When configuring a DRP, the ‘Name’ must match the name of the document configured in Document Setup. Use caution when Document Names have special characters such as an apostrophe or dash that it is using the identical Document Name and has not been updated by the editor. If no match is found to an existing Document Name configured when executing the DRP expression, an error message is displayed, ‘Document name of <Document Name> is not found'.
...
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.
Shortkeys:
{fay} - Automatically inserts the Federal Award Year of the Smart Form (e.g. 2024-2025).
Will handle {questionCode} formatting.
Expand
| title | Document Requirement Persistence Fields |
|---|
DRP Field Name
DRP Field Description
DRP Field Type
Question Field Options
Required
Document Name
This is the name of the document in REM that is associated with this DRP configuration.
Textbox
Yes
File Name
The name to use fwith the student's document requirement record in REM.or the file name associated
Textbox
Yes
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.
Dropdown
Yes
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.
Textbox
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.
Dropdown
Static
Velocity
Yes
Activity Log Entry Status
This is the name of the activity log in REM where a message will be created when the DRP action is completed.
Dropdown
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.
Textbox
Yes
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.
Dropdown
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.
Textbox
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.
Textbox
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.
Document Reason
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
For example: For a Filing Status Confirmation Worksheet, if a student indicates, ‘No, I already filed a tax return’ within the Smart Form, DRP can be created to add the student Tax Return document requirement with a status of ‘Needed’.
Document Setup must be considered when adding DRP. If a document is configured to Enforce Scope Uniqueness, a new document is not added if it already exists but the status of an existing document can be updated. If documents are configured to be added upon ISIR import, DRP can be used to update the document status on an existing document(s).
When configuring a DRP, the ‘Name’ must match the name of the document configured in Document Setup. Use caution when Document Names have special characters such as an apostrophe or dash that it is using the identical Document Name and has not been updated by the editor. If no match is found to an existing Document Name configured when executing the DRP expression, an error message is displayed, ‘Document name of <Document Name> is not found'.
Shortkey:
{fay} - Automatically inserts the Federal Award Year of the Smart Form (e.g. 2024-2025).
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Student Persistence
Student Persistence updates the Student Portal Authorization fields in Regent based on Student Authorizations and update add or update a student document requirement in Regent. Document Requirements are added and updated upon the completion, including signature(s), of the Smart Form. The document requirement is only added or updated if the expression results are true.
| Expand | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||
|
Parent/Spouse Persistence
Sections
Section names are displayed on the Smart Form menu within the Student Portal. Sections are displayed in numerical order from lowest to highest based on the number entered in the Section Sort Order field.
...
| Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
...
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
...
| Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Dependency Logic and Validations
Dependency Group
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
...
Validations
https://velocity.apache.org/engine/1.7/user-guide.html
https://www.geeksforgeeks.org/javascript-regexpregular-expression/
Document Requirement Persistence
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.
Will handle {questionCode} formatting.
Examples
Example 1
Student starts a Verification Worksheet smart form application.
Student indicates No, I have already filed a tax return SNAP smart form questionnaire.
Student completes and signs their Verification Worksheet.
A 2015 Student Filing Extension Granted by the IRS document requirement is created for the student.
Student starts a Verification Worksheet - Change smart form application.
Student indicates No, I have already filed a tax return.
Student completes and signs their Verification Worksheet.
A 2015 Student Filing Extension Granted by the IRS document requirement does not get created for the student.
...