# Chapter 4 - Events: Directing Execution
# 4.1) General
Workflow Ascendant provides the mechanisms to control every aspect of the document cycle. Controls at a more global level such as where a document is routed and who can modify a document at a particular state are treated in Chapter 2 -- Process: Routing Documents and Chapter 3 - Constraints: Specifying Users. This chapter deals with what occurs when a workflow document is opened, modified and saved (sent in the workflow) including:
Initializing the document
Controlling who can modify which field or section of the document
Validating field values and blocking a state advance for user data entry errors
Validating field values prior to selecting the Send button (i.e., while the document is still being modified)
In addition to this, you can specify what events take place when a document has gone past a certain amount of days for a given state (or for a given section of the workflow for that matter).
Modification and validation rules are dependent by user and by state. What is modifiable and/or obligatory at one point in the process may or may not be at a different point in the process. To that end, Workflow Ascendant provides generic subroutines which are included in script library WA Application Specific; you complement these with your own application specific code and reference both in State documents (by rule - which implies by user and by what action is to be taken). These routines use the following two fields for all error handling:
WAErrorMessage -- any text put in this field will be displayed as an error and block the workflow document from changing state.
FieldError -- if field WAErrorMessage is not empty, then any field names put in this field will result in a red circle being displayed next to those fields (provided you follow the conventions in 5.3 Fields).
You can of course choose to use your own mechanisms.
# 4.2) Initialization
Purpose
Workflow Ascendant provides multiple ways to initialize field values in workflow documents. To do so, you simply complement the built-in mechanisms that Workflow Ascendant itself uses with your own. Call application specific routines in the pertinent State document using field The document will be initialized with the following stocked subroutine(s). Any subroutines included in this list (each name must be preceded by #) will be executed when a user modifies a workflow document at that state -- provided that the corresponding code is duly created in script library WAApplicationSpecific. In the example below, the Title field is automatically updated with stocked text when document DOC208 is first created (state $created$). Note that if your code updates field WAErrorMessage with text, it will be displayed as an error message when the document is opened (in a Notes client, the opening of the document is also blocked).
What it looks like
How to make it happen
Additional Notes / References
For updating document fields at state change, reference section Actions (Comments).
Video: 4.2 Initialization
Application: WAApplication02.nsf, Process DOC208
# 4.3) Modification Control (Field)
Purpose
Workflow Ascendant provides ways to control who can modify which fields in a document. In the Workflow tab of a State document further below, fields under Users are set dynamically by #waSetUsersRole and fields under Modifiable Fields are used dynamically by #waInitModFields. To render these definitions effective, you will need to add XPages and/or Notes controls for each field which operate independently (meaning use one or the other or both depending on the clients you use to access the application). In example DOC209 below, only Marketing can modify Field04.
What it looks like
How to make it happen
Additional Notes / References
Reference Section 4.2 for explications regarding workflow document initialization.
Video: 4.3 Modification Control (Field)
Application: WAApplication02.nsf, Process DOC209
# 4.4) Modification Control (Panel/Section)
Purpose
Workflow Ascendant provides ways to control who can modify which portions of a document. In the Workflow tab further below, fields under Users are set dynamically by #waSetUsersRole and panels under Modifiable Tabs are used dynamically by #waInitModTabs. To render these definitions effective, you will need to add XPages and/or Notes controls for each panel/section which operate independently (meaning implement those applicable to the clients you use to access the application). In example DOC209 below, only CEO can modify Tab03.
What it looks like
How to make it happen
Additional Notes / References
Reference Section 4.2 for explications regarding workflow document initialization. isTabReadOnly(this.getId())
Video: 4.4 Modification Control (Panel/Section)
Application: WAApplication02.nsf, Process DOC209
# 4.5) Validation Control (General)
Purpose
Workflow Ascendant provides a general, built-in field validation mechanism. It verifies by state that designated fields contain a value - but only if the current user has the ability to modify those fields. To that end, this mechanism must be used in conjunction with Modification Control (Field). Should this not meet your requirements, reference the following section Validation Control (Custom). In the example DOC210 below, the Field04 field must contain a value for the document to advance. Note that [WAManager] is not controlled by default!
What it looks like
How to make it happen
Additional Notes / References
Video: 4.5 Validation Control (General)
Application: WAApplication02.nsf, Process DOC210
# 4.6) Validation Control (Custom)
Purpose
Workflow Ascendant provides for custom validation mechanisms. Call your application specific subroutines in the pertinent State document using field The document will be blocked from advancing if.... Any subroutines included in this list will be executed when the Send button is selected at that state - provided that the corresponding code is duly created in script library WAApplicationSpecific. In the example below, Field 1 and Field 2 must contain identical values when document DOC211 is forwarded (state $created$).
What it looks like
How to make it happen
Additional Notes / References
For information regarding the ItemList class, reference Appendix E - List Classes.
Video: 4.6 Validation Control (Custom)
Application: WAApplication02.nsf, Process DOC211
# 4.7) In-State Controls
Purpose
Workflow Ascendant provides a template from which you can control events which occur outside of a state change. The agent myInStateFieldControl is provided as a model you can use to customize for your own specific application requirements. In example DOC211 below, an error condition is flagged when button Test Fields is selected if fields Field07 and Field08 do not contain identical values.
What it looks like
How to make it happen
Additional Notes / References
For additional information on the field configuration of the "red circle" mechanism, refer to Section 5.3.
Video: 4.7 In-State Controls
Application: WAApplication02.nsf, Process DOC211
# 4.8) Timed Events
Purpose
Workflow Ascendant provides the capability to launch events based on elapsed time. These are defined in Time Trigger documents in the Workflow -- Time Triggers view. In example DOC211 below, the application log is updated by agent (WA Test Agent) when the document remains in state CEO for 3 days. In addition to launching agents, you can specify stocked subroutines (the names of which to be preceded by #) in script library WA Application Specific.
What it looks like
How to make it happen
Additional Notes / References
Video: 4.8 Timed Events
Application: WAApplication02.nsf,Process DOC211