If using a stored procedure data link, it should specify any input fields that may be required (i.e. the input fields submitted by the user) as parameters for the stored procedure. This can be done by first creating the stored procedure data link, then using the Free-form Data Link Entry form to allow the parameters to be entered. The parameter names used must be the actual field names from the underlying CATSWeb database table, rather than the field captions which are arbitrarily assigned in the field definition pages. See Field Mapping below for a variety of techniques to determine what these field names are. ActiveX DLL and Web Service data links require no input parameter specification at all, since all of the fields will be passed to the implementation.

Back to Top

Common Settings (General Information Section)

When adding or editing an event hook, the following common settings are available:

• Title - A title for the event hook that uniquely identifies it within the collection of event hooks for the form or entity (255 characters max). The title is only displayed in the list of event hooks, and is not used for any other purpose.
• Description - A description of the event hook.
• Data Link - The data link that implements the event hook. Only ActiveX DLL, Web Service, and Stored Procedure data links may be used.
• Skip Indexed Properties - Event Hook processing performance is improved if event hooks don't return indexed properties and this box is checked for ALL event hooks for an event.
  
  The Skip Indexed Properties check box value of the last event hook executed is used for downstream processing.

  The simplest way to configure the Skip Indexed Property check box is:
  If ANY event hooks return indexed properties for an event :
  Uncheck the Skip Indexed Properties check box for ALL event hooks for that event.
  If ALL event hooks don't return indexed properties for an event :
  Check the Skip Indexed Properties check box for ALL event hooks for that event.
  
  How do you know if event hooks are adding indexed properties?
  
  If you are programming configurable actions to modify form field properties, then the property names in the 'Name' column of the table below are available to you from the 'Property' drop down list of the 'Edit Form Field Property' page. If you are modifying any of these, uncheck the Skip Indexed Properties check box for ALL event hooks for that event.
  
  If you are writing an ActiveX DLL event hook, the implementation is a little different. You would be adding values to the colHTML collection with keys that have either the constants (Programmatic Constant) listed below or their string values (Value) appended to the field name. Uncheck the Skip Indexed Properties check box for ALL event hooks for that event.
  Example - Change the Text1 Caption to bold text
  colHTML.Add "<strong>","Text1_CTHB1"
  colHTML.Add "</strong>","Text1_CTHA1"

  Indexed Properties

  Name	Programmatic Constant	Value
  Caption Tag HTML After	CWEB_SUFFIX_CAPTION_TAG_HTML_AFTER$	_CTHA
  Caption Tag HTML Before	CWEB_SUFFIX_CAPTION_TAG_HTML_BEFORE$	_CTHB
  Field Tag Attributes	CWEB_SUFFIX_FIELD_TAG_ATTRIBUTES$	_ATRB
  Field Tag HTML After	CWEB_SUFFIX_FIELD_TAG_HTML_AFTER$	_FTHA
  Field Tag HTML Before	CWEB_SUFFIX_FIELD_TAG_HTML_BEFORE$	_FTHB
  Form Body HTML After	CWEB_FLD_FORM_DATA_AFTER$	FormDataAfter
  Form Body HTML Before	CWEB_FLD_FORM_DATA_BEFORE$	FormDataBefore
  Main Submit Button HTML After	CWEB_FLD_MAIN_SUBMIT_AFTER$	MainSubmitAfter
  Main Submit Button HTML Before	CWEB_FLD_MAIN_SUBMIT_BEFORE$	MainSubmitBefore

  
  For Enhanced Skip Indexed Properties (ESIP) processing that offers a better performance improvement when adding indexed properties, see the New Feature Pack for Service Pack 16Q.
• Field Mapping - If the event hook's data link returns data, a mapping must be defined between the field names being returned and the destination fields in the CATSWeb form or record. Field pairs are designated using this format:
  
  DestinationTableFieldName=SourceFieldName
  
  Multiple field pairs may be included, and each pair is separated by the "|" character. The Destination field names used must be the actual field names from the underlying CATSWeb database tables, rather than the field captions which are arbitrarily assigned in the field definition pages. The SourceFieldName must be the actual field names in the recordset returned from the ActiveX DLL or stored procedure, typically specified in the Select clause of underlying SQL.

  There are several methods of determining what the destination field names are:

  • Field Definition Page - View the field definition page for the desired field and use the value stated for the Table Field.
  • Query Form - An ad-hoc query can be entered and submitted with the optional Show SQL statement generated box checked. Be sure to enter data in the query field of interest. The query output will show the actual SQL statement generated, which will include the SQL WHERE clause with the actual table field names.
  • Other Tools - Database management utilities, Microsoft Access, and many other tools allow the underlying table structure to be viewed.
    
    
• Execution Order - Determines the order of execution when multiple event hooks are defined for the same form or entity. Lower numbers get executed first. Each event hook uses the user inputs and any results returned from previous event hooks as inputs.
• Active - Check the box to make the event hook active.
• Apply Changes to All Categories - When adding a new event hook, checking this box causes it to be copied to all categories for the form type. When editing an event hook, checking this box causes all event hooks with the same title in the same type of form to be updated (i.e. changes are copied across all categories for the form type). The box has no effect on event hooks for managerial data entities.

Back to Top

Conditions Section

The Conditions section is available when the Conditional box has been checked, and allows a variety of optional conditions to be specified. The event hook only executes if the specified conditions have been met. Note that if no conditions have been specified, or the Conditional box is not checked, the event hook will always run during its specified events.

With the exception of the Changed Fields condition, SQL is used to specify the conditions. Instead of the SQL being interpreted by the DBMS server, as it is with Functional Restriction Conditions, it is instead interpreted by the ADO.NET Datatable.Select() method on the local Web server (the SQL is actually set to the Datatable.Select() method which uses the same syntax as the  DataColumn.Expression() property). This provides higher performance, but means that some DBMS-specific SQL constructs may not be used. It also means that the allowed expressions may vary somewhat from Functional Restriction Conditions.

See here for more information on syntax constraints, and review the condition examples below to see how many of these constraints can be circumvented.

The condition settings are:

• Session Record - These conditions apply to the current user's session record, and can be used to limit the Event Hook execution to particular users or collections of users. The following fields are often used: EmployeeName, EmployeeID, Personality, Department, HomeDepartment and Group_Name. For example:
  
  Personality='Administrator' Or Personality='Full User'
  
  The Session Record condition operates during all events.
  
  

• Initial Current Record Data - The initial current record is the version of the record being operated on that is already stored in the database. For example, if a Note is being edited, the version of the Note that existed immediately before the edit is the initial current record. There is no current record (and this condition cannot be used) for Add or Form Load Add events. It is also not usable during Reload events that reload a form that is in Add mode.
  
  The Initial Current Record Data condition operates during form load, reload and the pre-process phase of submissions, but cannot be used when the current record is being added.
  
  

• Initial Main Record Data - If the current record is a child record such as a Note, File Attachment or Signature, the main record is that record's parent (e.g., Issue, Action or Subtask). If the current record is an Issue, Action or Subtask, then the main record and the current record are the same thing. The initial main record is the version of the main record that was in the database immediately before the event began.
  
  For example, if a Signature is being added to an Action record, the initial main record is the Action record just before the signature is added. There is no initial main record (and this condition cannot be used) for Add or Form Load Add events that apply to Issues, Actions or Subtasks. It is also not usable during Reload events that reload an Issue, Action or Subtask form that is in Add mode.
  
  The Initial Main Record Data condition operates during form load, reload and the pre-process phase of submissions, but cannot be used when the main record is being added.
  
  

• Form Data - Form data is the data present in the form during the event. For example, if an Issue record is being edited, the form data will be the same as the initial current data when the edit form first loads. But when the edit is submitted, the form data will be the Issue data as edited by the user. If the user modifies data in a form and then reloads it, this condition will operate on the latest data that is in the form.
  
  The Form Data condition operates during form load, reload and the pre-process phase of submissions.
  
  

• Final Current Record Data - The final current record is the final version of the record being operated on following an event. For example, if a Note is being edited, the final version of the Note after the edit is successfully submitted is the final current record. The Final Current Record Data condition only operates during the post-process phase of submissions. If the condition is not met, post-process event hook routines are not executed.
  
  

• Final Main Record Data - If the current record is a child record such as a Note, File Attachment or Signature, the main record is that record's parent (e.g., Issue, Action or Subtask). If the current record is an Issue, Action or Subtask, then the main record and the current record are the same thing. The final main record is the final version of the main record following the successful completion of the event.
  
  For example, if a Signature is being added to an Action record, the final main record is the Action record after the signature is added. If the signature caused a change in the main record by completing a signature controlled operation, the final (changed) main record will be operated on by this condition.
  
  The Final Main Record Data condition only operates during the post-process phase of submissions. If the condition is not met, post-process event hook routines are not executed.
  
  

• Changed Fields - Unlike the other conditions, the Changed Fields condition does not use SQL syntax. It is instead a comma-delimited list of field names (ex: "Field1, Field2, Field3"). CATSWeb checks each of the listed fields for changes during the pre-process phase of submissions.
  
  Field changes are evaluated based on the Changed Fields Rule setting. If this is set to All, then all of the listed fields must be changed for the condition to be met. If set to Any, then the condition is met if any of the fields change. The event hook is allowed to execute if the conditions are met.
  
  
• Condition Data Link - An optional data link that retrieves an arbitrary record for which Data Linked Record Conditions can be specified.
  
  
• Data Linked Record Conditions - Conditions that the data linked record must meet. These conditions operate during all events, except for form pre-load events.

Here are some examples of conditions settings that use SQL syntax (i.e. all but Changed Fields). Note that AssurX testing indicates that literal dates can either be bracketed in a pair of "#" characters (per DataColumn.Expression() property), or via a pair of single quote characters, as would be done in DBMS SQL:

A variety of event settings are grouped in sections below the General Information section. Many of the settings are labelled using terminology defined in the Overview of Events topic above.

The event settings sections are:

• Primary Record - These settings apply to the primary record type for the form. In the case of an Issue, the Issue form itself is the primary record, while the Disposition form is the secondary record. In the case of an Action, the Action form itself is the primary record, while the Effectiveness form is the secondary record. Subtasks, Subforms and managerial data entities are considered primary records and have no secondary record counterpart. Note that the Active on Reload setting in this section is an exception, as it applies to both the primary and secondary records.
  
  
• Secondary Record - These settings apply to Disposition forms and records (CATSWeb does not have event hooks for Effectiveness submissions). The Active on Disposition setting is equivalent to the Active on Edit setting for the primary (Issue) record. Dispositions are actually an editable portion of Issue records, so an Active on Add setting is not applicable.
  
  
• Reassignment - These settings apply to the Reassignment form for Issue, Action and Subtask records.
  
  
• File Attachments, Links, Notes and Signatures - Settings in these sections apply to the specified form for Issue, Action and Subtask records.
  
  
• Component Events - Component events are special events that users trigger by clicking on drill down buttons or links. The buttons or links use URL data links that point at the ComponentEvent or ComponentEventSimple WebClass event in CATSWeb (main.aspx). These allow for ad-hoc actions to be taken by event hook implementations without requiring a record submission or reload.
  
  
• Override User Inputs... This section provides a variety of settings that apply only to Submission or Reload events. They determine whether or not data returned from an event hook implementation will override the data submitted by the user (Submission event), or present in their form (Reload event). When a setting is checked, values returned from the event hook will override (i.e. replace) the user's values. When unchecked, user values will be allowed to remain if the user provided a value for the field. If the user did not provide a value for a field, the value returned from the event hook will be used.
  
  
• Form Pre-load Event Hooks - This section will only be present if the Form Pre-load Event Hooks option is installed. Form Pre-load events are only useful for specialized applications as described in the Overview of Events topic above. If you do not have a specific use for these events, AssurX recommends not installing the feature. When installed, CATSWeb must check for the presence of these event hooks separately. The database query takes a small but finite amount of time, and is best avoided if not needed.

Back to Top