Difference between revisions of "Submit Logic"
From SmartWiki
(→Accessing the Submit Logic Function) |
|||
| (61 intermediate revisions by 11 users not shown) | |||
| Line 1: | Line 1: | ||
| − | * This feature provides for the creation of any number of submission rules that control a submission process. | + | {{MySQL Syntax}} |
| + | * This feature works in conjunction with the [[Submit Buttons]], and provides for the creation of any number of submission rules that control a submission process. | ||
* When a submission process is controlled by submission logic, then values at other levels can be validated. | * When a submission process is controlled by submission logic, then values at other levels can be validated. | ||
* Values are validated based on the sequence defined within the submission logic. | * Values are validated based on the sequence defined within the submission logic. | ||
* From Level 1 the submission rules can access any field at Level 1, account/contact fields, as well as aggregated fields at Level 2 and/or Level 3. | * From Level 1 the submission rules can access any field at Level 1, account/contact fields, as well as aggregated fields at Level 2 and/or Level 3. | ||
| − | * The '''Submit Logic''' feature is associated with a particular [[status]]. Associating the conditions with each [[status]] allows for different statuses to control sets of '''Submit Logic''' rules. | + | * The '''Submit Logic''' feature is associated with a particular [[status]] and submit button. Associating the conditions with each [[status]] and button allows for different statuses to control sets of '''Submit Logic''' rules. |
| − | ==Accessing | + | NOTE: Focus here is on basic Submit Logic validation using Submit Buttons. Details on how Submit Buttons interact with SmartCheck validation will be covered in the [[SmartCheck_Validation#Add_SmartCheck_Validation_to_Submit_Button|SmartCheck Validation article.]] |
| + | |||
| + | ==Accessing Submit Logic == | ||
To access the '''Submit Logic''' feature: | To access the '''Submit Logic''' feature: | ||
| − | Click the '''Settings''' tab within the UTA, then on the | + | * Click the '''Settings''' tab within the UTA, then access the Level 1, 2 or 3 settings page as appropriate. |
| + | |||
| + | * Click on the '''Submit & Save Buttons''' link in the settings page. | ||
| + | [[Image:SubmitLogic1.png|800px]] | ||
| − | The '''Submit | + | |
| + | * The '''Submit & Save Buttons''' page is displayed. It should list all existing Submit buttons, and have a option for [[Submit_buttons#Creating_A_Save_.26_Submit_Button|creating new submit buttons]] at the top of the screen. | ||
| − | [[Image: | + | [[Image:SubmitLogic2.png|800px]] |
| + | |||
| + | |||
| + | * Click on the Edit icon for one of the listed Submit & Save Button options. You will be brought to the Submit Button configuration screen. | ||
| + | |||
| + | [[Image:SubmitLogic3.png|800px]] | ||
| + | |||
| + | |||
| + | * Click on the Submit Logic tab. You will be brought to the Submit Logic configuration screen, which should list all existing Submit logic, and have a option for creating new Submit Logic at the top of the screen. | ||
| − | Click | + | [[Image:SubmitLogic4.png|800px]] |
| − | + | ||
| − | [[Image: | + | |
| + | * Click the New button to begin adding new Submit Logic. | ||
| + | |||
| + | [[Image:SubmitLogic5.png|800px]] | ||
| + | |||
Each '''Condition''' consists of the following fields: | Each '''Condition''' consists of the following fields: | ||
| − | * '''Order''' - the order in which the condition can be executed. | + | |
| − | * '''Name''' - a narrative name for the condition. | + | *'''Order''' - the order in which the condition can be executed. Each condition is executed in sequence based on the order. When all conditions have executed, any failed conditions will stop the submission process and all messages for failed conditions will be displayed in a consolidated fashion. |
| − | * '''Description''' - narrative description of the condition. | + | *'''Name''' - a narrative name for the condition. |
| − | * '''Condition''' - stores the expression that represents the condition.[[Entity]] does not change status when condition evaluates as false . | + | *'''Description''' - narrative description of the condition. |
| − | * '''Message''' - stores the message to be displayed if the condition is not met. | + | *'''Condition''' - stores the expression that represents the condition. [[Entity]] does not change status when condition evaluates as false. |
| + | *'''Message''' - stores the message to be displayed if the condition is not met. | ||
| + | |||
| + | |||
==Condition Construction== | ==Condition Construction== | ||
| − | Conditions consist of references to fields and aggregate functions and use the same syntax as the [[Template / Type Formula]]. | + | Conditions consist of references to fields and aggregate functions and use the same syntax as the [[Template / Type Formula]]. |
| − | + | ||
| − | + | '''''Conditions'' should be constructed so that they evaluate as TRUE when you want the record to be submitted.''' | |
| + | |||
| + | '''The ''Message'' will display when the condition evaluates as FALSE, and the record will not be submitted.''' | ||
| + | |||
| + | The following examples illustrate various examples of the '''submit logic''': | ||
| + | |||
| + | 1. '''Criteria''': The '''Reviewer Comments''' field at level 2 must not be left blank. | ||
| + | '''"@level2.Reviewer Comments.length@"*1 > 0''' | ||
| + | ''OR'' | ||
| + | '''CONVERT("@level2.Reviewer Comments.length@",SIGNED INTEGER) > 0''' | ||
| + | |||
| + | <pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">Note that the above is the best practice for testing for empty fields, as opposed to using "@level2.Reviewer Comments@"!=""</pre> | ||
| + | |||
| + | 2. '''Criteria''': a '''minimum of three''' level 2 items (''of any type'') are required to submit the level 1 item. | ||
'''@level2.count(*)@>2''' | '''@level2.count(*)@>2''' | ||
| − | + | 3. '''Criteria''': a '''minimum of three''' level 2 items '''where the type is email''' are required to submit the level 1 item. | |
'''@level2.count(*):typename='email'@>2''' | '''@level2.count(*):typename='email'@>2''' | ||
| − | + | 4. '''Criteria''': a '''minimum of three''' level 2 items '''where the type is email''' and the '''status is closed''' (''for both items''). | |
'''@level2.count(*):typename='email' and statusname='closed'@>2''' | '''@level2.count(*):typename='email' and statusname='closed'@>2''' | ||
| − | + | 5. '''Criteria''': the '''submission cut-off date and time has not passed''' | |
| − | + | "@datetime(currentdate)@"<"@datetime(level1.Contract Start Date)@" | |
:'''Note''' you will need to create a [[System Variable]] that stores the cut-off date and time in the following format: '''yyyy-mm-dd hh:mm:ss''' (24 hour clock) | :'''Note''' you will need to create a [[System Variable]] that stores the cut-off date and time in the following format: '''yyyy-mm-dd hh:mm:ss''' (24 hour clock) | ||
| − | + | ||
| + | |||
| + | 6. '''Criteria''': an '''XML table node is not blank''' | ||
| + | "<ssEscape>@level1.xml.Budget.comment-section.row.comment.nodevalue@</ssEscape>" != "" | ||
| + | |||
'''Additional examples''': | '''Additional examples''': | ||
| + | * '''CONVERT("@level1.''fieldname''.length@",SIGNED INTEGER) > 0''' - Ensures that ''fieldname'' is not empty. | ||
* '''@company.commission rate@ > 0.3''' - the commission rate for the associated company must be greater than 0.3 (30%). | * '''@company.commission rate@ > 0.3''' - the commission rate for the associated company must be greater than 0.3 (30%). | ||
* '''@branch.name@ = 'xyz'''' - the associated branch name must be 'xyz'. | * '''@branch.name@ = 'xyz'''' - the associated branch name must be 'xyz'. | ||
* '''@total salaries@ < 400000''' - the total salaries field in the [[Level 1 Entity]] is less than 400,000. | * '''@total salaries@ < 400000''' - the total salaries field in the [[Level 1 Entity]] is less than 400,000. | ||
* '''@level2.sum(megawatts)@ > 5''' - the sum of the megawatts field in all level 2 is greater than 5. | * '''@level2.sum(megawatts)@ > 5''' - the sum of the megawatts field in all level 2 is greater than 5. | ||
| − | * '''@level2.sum( | + | * '''@level2.sum(#12345#)@ > 5''' - same as previous example but using the [[Custom Field|custom field]] ID. |
| − | * ''''@opportunity.peopleid@ | + | * '''"@level1.Anticipated Project End Date@" BETWEEN "@rootcompany.Project Start Date@" AND "@rootcompany.Project End Date@"''' - the date entered into the ''Anticipated Project End Date'' field is between the system-wide Project Start and End Dates (see [[Root Company Variable]]s) |
| − | * ''' | + | * '''"@opportunity.peopleid@"!="0"''' - Ensure that a contact has been added to the Level 1 Person standard field. |
| − | * ''' | + | * '''"@contacts.count(*):rolename='Supervisor'@"="1"''' - Ensure there is exactly 1 contact at Level 1 with the role of Supervisor. |
| − | * ''' | + | * '''"@companies.count(*):rolename='Funding Agency'@"<"3"''' - Ensures there are less than 3 Funding Agencies in the Companies section. |
| + | * '''"@contact.supervisor.email@"!="@contact.referee.email@"''' - Ensure that the contact assigned at Level 1 with the role of Supervisor is not also assigned with the role Referee. | ||
| + | * '''"@level1.Proposal.filename@"!=""''' - Ensures you have a Proposal uploaded in the single file upload on the Level 1. | ||
| + | * '''"@level1.Plan Details.numofpages@"<=6''' - Ensures the number of pages for a PDF file upload field is not more than six pages | ||
| + | * '''"@level1.Multiple File Uploads.numoffiles@">0''' - Ensures the number of files uploaded to a Multiple Files upload field is greater than 0 | ||
| + | * '''"@level1.type@"!="New Grant"||"@level1.xml.ExternalPeers.peer.peer.nodecount@">2''' - Ensures that the level 1 type is 'New Grant' and number of nodes/items entered in the XML worksheet is greater than 2 items. | ||
| + | * '''"@level1.Amount Awarded.value@" <= 500000''' - Ensures that the ''Amount Awarded'' field is under $500,000. The ''.value'' is necessary when the ''Amount Awarded'' field is stored in currency format. | ||
| + | * ''' INSTR("@level1.[#(?object=activity::criteria=typename='Referee Form' and statusname='Submitted' and eownerid=@me.userid@)~index~#]@","1")=0''' - Ensures the current user can't submit more than 1 review | ||
| + | * ''' @level1.Grant Amount@>=@level1.level2.sum(#1478912.value#)@+@level2.#1478912.value#@''' - Confirms the payment total does not exceed the approved total. | ||
| + | * ''' LENGTH("@level1.Check Boxes@")-LENGTH(REPLACE("@level1.Check Boxes@",";",""))+1>=3 ''' - Confirms that at least 3 checkboxes have been selected in a [[Custom Field Type: Select Many – Check Boxes|Select Many - Check Boxes]] field. | ||
| + | |||
| + | <pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">Note that semicolons cannot be included in submit logic criteria. If using list syntax, employ double colons ("::") to separate arguments.</pre> | ||
==Message Construction== | ==Message Construction== | ||
* Messages are created for each condition providing the [[User|user]] with specific details as to the condition requirement that was not met. | * Messages are created for each condition providing the [[User|user]] with specific details as to the condition requirement that was not met. | ||
| − | * Field names and aggregate functions | + | * The messages display in a pop-up window upon a failed submit logic condition when the user's attempts to submit. If multiple submit logic conditions fail, the messages will be shown in a consolidated pop-up window. |
| − | + | * Field names and aggregate functions can be used in the same manner as with the condition construction. | |
| − | + | :* For example, using the first condition example shown above, a message can be added such as: | |
| − | + | ''At least three appendices are required to submit this proposal but only '''@level2.count(*)@''' were found, please check and then submit the proposal again.'' | |
| − | ''At least three appendices are required to submit this proposal but only '''@level2.count(*)@''' were found, please check and then submit the proposal again.'' | + | :* This message will display if the ''@level2.count(*)@>2'' evaluates to ''false'' |
| − | + | :* The message will appear as follows:<br /> | |
| + | :[[Image:SubmitLogicMsg.png|link=|600 px]] | ||
==See Also== | ==See Also== | ||
| + | * [[Submit buttons]] | ||
* [[Status]] | * [[Status]] | ||
* [[Template / Type Formula]] - for more examples of syntax to be used | * [[Template / Type Formula]] - for more examples of syntax to be used | ||
| − | * [[savefunc]] | + | * [[savefunc]] or [[sbfunc]] |
| + | * [[Obtain Server Date and Time]] | ||
| + | * [[Submit Logic on Save or Save Draft Buttons]] | ||
| − | [[Category:Universal Tracking Application]] | + | [[Category:Universal Tracking Application]][[Category:Validation]][[Category:Process Flow]] |
Latest revision as of 15:22, 23 October 2017
| This feature uses MariaDB syntax |
- This feature works in conjunction with the Submit Buttons, and provides for the creation of any number of submission rules that control a submission process.
- When a submission process is controlled by submission logic, then values at other levels can be validated.
- Values are validated based on the sequence defined within the submission logic.
- From Level 1 the submission rules can access any field at Level 1, account/contact fields, as well as aggregated fields at Level 2 and/or Level 3.
- The Submit Logic feature is associated with a particular status and submit button. Associating the conditions with each status and button allows for different statuses to control sets of Submit Logic rules.
NOTE: Focus here is on basic Submit Logic validation using Submit Buttons. Details on how Submit Buttons interact with SmartCheck validation will be covered in the SmartCheck Validation article.
Accessing Submit Logic
To access the Submit Logic feature:
- Click the Settings tab within the UTA, then access the Level 1, 2 or 3 settings page as appropriate.
- Click on the Submit & Save Buttons link in the settings page.
- The Submit & Save Buttons page is displayed. It should list all existing Submit buttons, and have a option for creating new submit buttons at the top of the screen.
- Click on the Edit icon for one of the listed Submit & Save Button options. You will be brought to the Submit Button configuration screen.
- Click on the Submit Logic tab. You will be brought to the Submit Logic configuration screen, which should list all existing Submit logic, and have a option for creating new Submit Logic at the top of the screen.
- Click the New button to begin adding new Submit Logic.
Each Condition consists of the following fields:
- Order - the order in which the condition can be executed. Each condition is executed in sequence based on the order. When all conditions have executed, any failed conditions will stop the submission process and all messages for failed conditions will be displayed in a consolidated fashion.
- Name - a narrative name for the condition.
- Description - narrative description of the condition.
- Condition - stores the expression that represents the condition. Entity does not change status when condition evaluates as false.
- Message - stores the message to be displayed if the condition is not met.
Condition Construction
Conditions consist of references to fields and aggregate functions and use the same syntax as the Template / Type Formula.
Conditions should be constructed so that they evaluate as TRUE when you want the record to be submitted.
The Message will display when the condition evaluates as FALSE, and the record will not be submitted.
The following examples illustrate various examples of the submit logic:
1. Criteria: The Reviewer Comments field at level 2 must not be left blank.
"@level2.Reviewer Comments.length@"*1 > 0
OR
CONVERT("@level2.Reviewer Comments.length@",SIGNED INTEGER) > 0
Note that the above is the best practice for testing for empty fields, as opposed to using "@level2.Reviewer Comments@"!=""
2. Criteria: a minimum of three level 2 items (of any type) are required to submit the level 1 item.
@level2.count(*)@>2
3. Criteria: a minimum of three level 2 items where the type is email are required to submit the level 1 item.
@level2.count(*):typename='email'@>2
4. Criteria: a minimum of three level 2 items where the type is email and the status is closed (for both items).
@level2.count(*):typename='email' and statusname='closed'@>2
5. Criteria: the submission cut-off date and time has not passed
"@datetime(currentdate)@"<"@datetime(level1.Contract Start Date)@"
- Note you will need to create a System Variable that stores the cut-off date and time in the following format: yyyy-mm-dd hh:mm:ss (24 hour clock)
6. Criteria: an XML table node is not blank
"<ssEscape>@level1.xml.Budget.comment-section.row.comment.nodevalue@</ssEscape>" != ""
Additional examples:
- CONVERT("@level1.fieldname.length@",SIGNED INTEGER) > 0 - Ensures that fieldname is not empty.
- @company.commission rate@ > 0.3 - the commission rate for the associated company must be greater than 0.3 (30%).
- @branch.name@ = 'xyz' - the associated branch name must be 'xyz'.
- @total salaries@ < 400000 - the total salaries field in the Level 1 Entity is less than 400,000.
- @level2.sum(megawatts)@ > 5 - the sum of the megawatts field in all level 2 is greater than 5.
- @level2.sum(#12345#)@ > 5 - same as previous example but using the custom field ID.
- "@level1.Anticipated Project End Date@" BETWEEN "@rootcompany.Project Start Date@" AND "@rootcompany.Project End Date@" - the date entered into the Anticipated Project End Date field is between the system-wide Project Start and End Dates (see Root Company Variables)
- "@opportunity.peopleid@"!="0" - Ensure that a contact has been added to the Level 1 Person standard field.
- "@contacts.count(*):rolename='Supervisor'@"="1" - Ensure there is exactly 1 contact at Level 1 with the role of Supervisor.
- "@companies.count(*):rolename='Funding Agency'@"<"3" - Ensures there are less than 3 Funding Agencies in the Companies section.
- "@contact.supervisor.email@"!="@contact.referee.email@" - Ensure that the contact assigned at Level 1 with the role of Supervisor is not also assigned with the role Referee.
- "@level1.Proposal.filename@"!="" - Ensures you have a Proposal uploaded in the single file upload on the Level 1.
- "@level1.Plan Details.numofpages@"<=6 - Ensures the number of pages for a PDF file upload field is not more than six pages
- "@level1.Multiple File Uploads.numoffiles@">0 - Ensures the number of files uploaded to a Multiple Files upload field is greater than 0
- "@level1.type@"!="New Grant"||"@level1.xml.ExternalPeers.peer.peer.nodecount@">2 - Ensures that the level 1 type is 'New Grant' and number of nodes/items entered in the XML worksheet is greater than 2 items.
- "@level1.Amount Awarded.value@" <= 500000 - Ensures that the Amount Awarded field is under $500,000. The .value is necessary when the Amount Awarded field is stored in currency format.
- INSTR("@level1.[#(?object=activity::criteria=typename='Referee Form' and statusname='Submitted' and eownerid=@me.userid@)~index~#]@","1")=0 - Ensures the current user can't submit more than 1 review
- @level1.Grant Amount@>=@level1.level2.sum(#1478912.value#)@+@level2.#1478912.value#@ - Confirms the payment total does not exceed the approved total.
- LENGTH("@level1.Check Boxes@")-LENGTH(REPLACE("@level1.Check Boxes@",";",""))+1>=3 - Confirms that at least 3 checkboxes have been selected in a Select Many - Check Boxes field.
Note that semicolons cannot be included in submit logic criteria. If using list syntax, employ double colons ("::") to separate arguments.
Message Construction
- Messages are created for each condition providing the user with specific details as to the condition requirement that was not met.
- The messages display in a pop-up window upon a failed submit logic condition when the user's attempts to submit. If multiple submit logic conditions fail, the messages will be shown in a consolidated pop-up window.
- Field names and aggregate functions can be used in the same manner as with the condition construction.
- For example, using the first condition example shown above, a message can be added such as:
At least three appendices are required to submit this proposal but only @level2.count(*)@ were found, please check and then submit the proposal again.
- This message will display if the @level2.count(*)@>2 evaluates to false
- The message will appear as follows:
See Also
- Submit buttons
- Status
- Template / Type Formula - for more examples of syntax to be used
- savefunc or sbfunc
- Obtain Server Date and Time
- Submit Logic on Save or Save Draft Buttons
