Oracle® Retail Merchandising System Custom Flex Attribute Solution Implementation Guide Release 15.0 E65438-01 |
|
![]() Previous |
![]() Next |
This chapter describes the validation routines in the CFAS user interface. It also highlights the simple and complex validations concepts. It includes the following topics:
For validations requiring more than the basic validations the CFAS framework provides, the CFAS can invoke stored procedures to validate the passed in data in any of the following levels:
Entity - Entity level validation is the highest level and triggered by the pre-enabled base RMS forms usually via the OK button in the form (to check if there are missing required attributes).
Group Set - At this level, the validation is triggered when the users exits out of the CFAS user interface to check the data integrity between attributes across all groups within the group set. This validation can optionally be set up in the CFA_ATTRIB_GROUP_SET for each group set.
Group - This level of validation is triggered when shifting from one attribute group to another (navigating the groups in the attribute group multi-record block). This is optionally set in the CFA_ATTRIB_GROUP metadata table for each group.
Attribute - This is the lowest level of validation in the CFAS user interface. The validation happens when the user moves out of an attribute field. The validation is optionally defined in the CFA_ATTRIB table.
Starting off with the lowest level validation, the attribute validation works as follows:
During startup, the CFAS user interface populates the attribute content (values) collection with the values fetched from the extension table. The user interface uses this collection to populate the physical fields in the user interface via the query procedure of the attribute block.
Once the user updates the field (in case of a field level validation), the WHEN-VALIDATE-ITEM trigger runs and calls the generic FORM_VALIDATION.VALIDATE_FIELD passing in the STORAGE_COL name the field physically maps to in the extension table. This is used as a guide as to determine the metadata information to be used from the attribute configuration collection. At this point the new data is not yet stored to the content collection.
Note: The attribute configuration collection is indexed by VIEW_COL_NAME. To get the right index to the configuration collection, another collection is used to map out the STORAGE_COL_NAME to the VIEW_COL_NAME. This is called the mapping collection (FLEX_UI. LP_strg_vw_tbl). |
The VALIDATE_FIELD function then calls the CFA_VALIDATE_SQL.VALIDATE_ATTRIB which does both the simple and complex validations. CFA_VALIDATE_SQL.VALIDATE_ATTRIB gets the metadata information from the configuration collection for the passed attribute (VIEW_COL_NAME) namely, the required and min max information, and if there is complex validation routine.
For the simple validations, the input value (coming directly from the user interface) is validated against the set values from the metadata. Simple validations checks for the following:
Data length for VARCHAR2 and NUMBER data types.
Lowest/Highest allowable value for NUMBER and DATE data types.
Once the input data passes the simple validations, it is then saved to the content collection (but not to the database yet).
If there is a complex validation defined for the attribute in the metadata, it executes the function dynamically (EXEC_FUNC). The validation functions have only
O_error_message as the parameter. The input and output values are defined differently from usual RMS user interface. These rely heavily on the values stored in the content collection.
The following CFAS functions are used to get and set values from this collection:
CFA_SQL.GET_VALUE - this function is used to retrieve the value of a particular attribute from the content collection. The input to this collection is the VIEW_COL_NAME and returns the value, description if any and the data type. This is used as replacement to the usual input function parameters and preferred rather than using limited generic parameters.
CFA_SQL.SET_OUTPUT - this function is used to set the value of a particular attribute in the content collection. It can also be used to set the corresponding description fields used by RG type fields. This not only updates the content collection but also builds the return collection. The return collection signals the CFAS UI to update the physical fields on the UI with the values from the content collection. This return collection contains the attributes that were changed by validation function. Only attributes in any group within the attribute group set can be set using this function.
Note: When you choose to set up a validation function at the attribute group level, you must use the following Return function in the validation function. It sets the error field where the validation has failed:CFA_SQL.SET_RETURN_FIELD( O_error_message IN OUT RTK_ERRORS.RTK_TEXT%TYPE, I_field IN GP_FIELD_ITEM%TYPE) Where, the To use this function, you will add lines of code similar to the following: else if not CFA_SQL.SET_RETURN_FIELD(O_error_message,'I_field') then return FALSE; end if; |
Basic Sections of the Custom Complex Validation
The body of a validation function can be subdivided into the following three areas:
Input Section - This section acts as the input parameter for the function. The section may have multiple calls to CFA_SQL.GET_VALUE to get the parameters needed for the validation. Values using this function are limited to the header field values (or the CFA_EXT_ENTITY_KEY.KEY_COL) and the attribute fields values in any group within the group set (or the CFA_ATTRIB.VIEW_COL_NAME). If the function requires other values (other than these such as system options or values from the main RMS base table, and so on), the function needs to define a cursor to fetch these information.
Validation Logic Section - This section is where the actual complex validation takes place. The validation logic can be written out directly or make calls to regular RMS package functions.
Output Section - If the validation logic function returns a value that needs to be used to update a field on the form, such as description or other fields that are defaulted, calls to the CFA_SQL.SET_OUTPUT are done in this section.
The following sample code illustrates how a validation function is written:
FUNCTION GET_ITEM_DESC ( O_error_message IN OUT RTK_ERRORS.RTK_TEXT%TYPE) RETURN BOOLEAN AS L_program VARCHAR2(62) := 'CUSTOM_CFA_DEMO_SQL.GET_ITEM_DESC'; L_field CFA_SQL.GP_FIELD_ITEM%TYPE := 'ITEM'; L_item ITEM_MASTER.ITEM%TYPE; L_desc ITEM_MASTER.ITEM_DESC%TYPE; L_data_type CFA_SQL.GP_DATA_TYPE%TYPE; BEGIN ----------------------------------------------------------------------------- -- Get keys and/or attribute value inputs in this section. ----------------------------------------------------------------------------- if NOT CFA_SQL.GET_VALUE(O_error_message, L_item, L_desc, -- initially NULL L_data_type, L_field) then return FALSE; end if; ----------------------------------------------------------------------------- -- Validation logic in this section. It can be a call to an RMS package -- function. ----------------------------------------------------------------------------- if L_desc is NULL then if NOT ITEM_ATTRIB_SQL.GET_DESC(O_error_message, L_desc, L_item) then return FALSE; end if; end if; ----------------------------------------------------------------------------- -- If there are outputs set each in this section ----------------------------------------------------------------------------- if NOT CFA_SQL.SET_OUTPUT(O_error_message, CFA_SQL.CFA_KEY, L_field, L_item, L_desc) then return FALSE; end if; return TRUE; EXCEPTION when OTHERS then O_error_message := SQL_LIB.CREATE_MSG('PACKAGE_ERROR', SQLERRM, L_program, to_char(SQLCODE)); return FALSE; END GET_ITEM_DESC; …
The sample function above gets the description for the item. It uses the CFA_SQL.GET_VALUE to get the item value from the content collection. If more parameters are required, several calls to this function are required for each parameter.
The validation logic section can be any business validation written directly in the section or called from another package.
If the validation needs to output something like a description or update another attribute field in any group within the group set, a call to CFA_SQL.SET_OUTPUT can be made. In the above example, the item description is returned by the RMS function ITEM_ATTRIB_SQL.GET_DESC. The CFA_SQL.SET_OUTPUT takes the description value and updates the content collection.
The following example illustrates how other attributes fields are set:
FUNCTION CHK_STOCK_SUPPLIER (O_error_message IN OUT RTK_ERRORS.RTK_TEXT%TYPE) RETURN BOOLEAN AS L_program VARCHAR2(62) := 'CUSTOM_CFA_DEMO_SQL.CHK_STOCK_SUPPLIER'; L_supplier SUPS.SUPPLIER%TYPE; L_field CFA_SQL.GP_FIELD_ITEM%TYPE := 'SELL_ON'; L_field_value CFA_SQL.GP_FIELD_VALUE%TYPE; L_sell_qty NUMBER; L_data_type CFA_SQL.GP_DATA_TYPE%TYPE; L_desc CFA_SQL.GP_FIELD_DESC_VALUE%TYPE; BEGIN ----------------------------------------------------------------------------- -- Get the current attribute value ----------------------------------------------------------------------------- if NOT CFA_SQL.GET_VALUE(O_error_message, L_field_value, L_desc, -- initially NULL L_data_type, 'STOCK_SUPPLIER') then return FALSE; end if; if L_field_value is NOT NULL then L_supplier := to_number(L_field_value); end if; --- if NOT CFA_SQL.GET_VALUE(O_error_message, L_field_value, L_desc, -- initially NULL L_data_type, 'SELL_QTY') then return FALSE; end if; if L_field_value is NOT NULL then L_sell_qty := to_number(L_field_value); end if; ----------------------------------------------------------------------------- -- do processing ----------------------------------------------------------------------------- if L_supplier is NOT NULL then if NOT SUPP_ATTRIB_SQL.GET_SUPP_DESC(O_error_message, L_supplier, L_desc) then return FALSE; end if; end if; ----------------------------------------------------------------------------- -- set output values ----------------------------------------------------------------------------- if NOT CFA_SQL.SET_OUTPUT(O_error_message, CFA_SQL.CFA_EXT, 'STOCK_SUPPLIER', L_supplier, L_desc) then return FALSE; end if; --- if L_sell_qty is NULL then if NOT CFA_SQL.SET_OUTPUT(O_error_message, CFA_SQL.CFA_EXT, 'SELL_QTY', 15) then return FALSE; end if; end if; return TRUE; EXCEPTION when OTHERS then O_error_message := SQL_LIB.CREATE_MSG('PACKAGE_ERROR', SQLERRM, L_program, to_char(SQLCODE)); return FALSE; END CHK_STOCK_SUPPLIER;
The above example does a couple of things. It sets the description of the stock supplier and sets the default value of the SELL_QTY attribute to 15, if not populated.
Validation of the data does not end here. It is up to the CFAS user interface to handle whatever is returned back by these validation functions.
For attribute validation, a return collection is set if there are fields updated (or defaulted) other than the validated field. This collection is returned to the user interface. The user interface loops through this, sets the individual fields on the form with the new value from the content collection, and updates the: GLOBAL variables related to the set fields.
Higher level validations follow the same pattern as the attribute validation with some key differences as described below:
Group level:
The validation is triggered when the user changes the attribute group in the multi-record block.
Simple validation only checks for required attributes.
In some RMS user interfaces, when an error is encountered, the focus is set to the field that failed. CFAS user interface adopts the same functionality. The validation package function returns the error attribute's STORAGE_COL_NAME which maps out to a field on the form. A navigational procedure intended for CFAS (FLEX_UI_WIDGET.GO_ATTRIB_ITEM) is used to set the focus to the user interface field. The usual error message is displayed. To set the return field, use the stored function CFA_SQL.SET_RETURN_FIELD.
Group set level:
The validation is triggered when clicking the OK button on the CFAS user interface.
Like the group validation, simple validation checks for all required attributes, but at the group set level (all groups within the group set).
Unlike the group validation, the group set validation does not set the focus to the error field. The group validation handles this for the current group.
Entity level:
Validation is triggered when clicking the OK button on the base RMS form (not the CFAS user interface).
Since the entity level validation is run outside the CFAS user interface, no data is loaded to the CFA collection (where all the validation and data manipulation occurs). Consider the following before running an entity level validation:
Any qualifier rules must be run before running the validation rules.
Since the entity level validation occurs outside the CFAS user interface, the CFA_SQL.GET_VALUE or CFA_SQL.SET_OUTPUT functions cannot be run. It is recommended to use the access views to retrieve the CFAS records.
These higher level validations also support complex business validations. These stored procedures are written with the same patterns as the attribute level validation.