Public API

Contents

SQL Return Codes

Standard Business Methods

Business Entity Public Methods

Maintenance Class Public Methods

UI Javascript User Exits

Java User Exits (interceptors) Interfaces and Classes

RequestContext Methods

Data Objects

SQL Return Codes

The framework generally returns the database-specific return codes from SQL execution.  However, the framework returns SPL-specific return codes for commonly-used SQL execution result messages.  These SPL-specific return codes are the same regardless of the database.  This allows programs to be portable across different databases.

The following lists the SPL-specific return codes:

SQL Execution Result

SPL Return Code

OK

0

* Unnumbered SQL Error

999999990

Warning

999999991

End / no (more) row retrieved

999999992

Duplicate / unique index violation

999999993

More / multiple rows retrieved in single-row select

999999994

Deadlock

999999995

No connection

999999996

* Application Error

999999997

* Hibernate Error

999999998

* Programmatic Error

999999999

 

Note.  The SQL return codes marked with an asterisk ("*") are for errors peripheral to the actual execution of the SQL and do not have equivalent database return codes.

Standard Business Methods

In general, classes that are created to implement business logic, including change handlers, business entities, maintenances, and business components have access to standard methods intended to give application code access to framework functionality.  Commonly, these classes extend the GenericBusinessObject class within their inheritance hierarchy.  Below are some general descriptions of the provided methods.  Please refer to the JavaDocs for more detail.

·         createQuery(String)—Create an HQL query.

·         createPreparedStatement(String)—Create a “raw” SQL statement.  It is preferable to use the createQuery method.

·         getActiveContextLanguage()/getActiveContextUser()—Get the language and user associated with the current request.

·         createDTO(Class)—Create a new DataTransferObject instance for the entity corresponding to the provided business interface class.

·         getDynamicComponent(various)—Get a Business Component instance corresponding to the input business interface for the component.

·         getSystemDateTime()—Get the current DateTime instance appropriate for business logic.

·         IsNull(Object)/notNull(Object)—Methods that answer the question if an object is null or is equivalent to null.

·         isNullOrBlank(String)/notBlank(String)—Methods that answer the question if a String reference is null, zero length, or all blank.

·         startChanges()/saveChanges()—Used to defer validation when making complex changes to entities.  It may be the case where a valid entity can only be constructed by passing through one or more invalid states.  By calling startChanges() at the beginning of the set of changes and saveChanges() at the end, some validations may be deferred until the entire coherent change is complete.

Business Entity Public Methods

BusinessEntity classes implement a combination of methods inherited from their generated superclasses as well as the framework classes that those generated superclasses extend.  The generated methods are typically “convenience” methods based on the specific features of the entity.  The framework methods are ones implemented by many or all entities.  Similarly, some methods are expected to be invoked from other objects (public methods) and others are to facilitate business logic coded into the entities’ business methods themselves.

Contents

Public Methods

Protected Methods

Data Transfer Object Methods

Id Methods

Public Methods

These methods are exposed via the generated “business interface” of the entity.

·         registerChange(Change)—Allows for another entity to register the fact that that entity has changed so that any dependant change handler logic in this entity may fire.  This is most useful in situations where the changed object and the dependant object (the one needing to know about the change) are not directly related by parent-child relationships.

·         getDTO()—Get a DataTransferObject representing the current state of the entity.

·         setDTO(DataTransferObject)—Update the state of the entity based on the passed values in the DTO.

·         getId()—Each entity has a method by this name with retrieves and Id instance of the appropriate class for the entity.

·         getFoo()—Get the value of the persistent property “foo”.

·         fetchBar()—Convenience method that will fetch the value of “bar” where “bar” is a parent entity referenced by an optional foreign key refernce.  The word “fetch” is used to denote that navigation to that entity is not provided from within HQL.

·         getBazzes()—Get the EntityList containing members of the entity “baz”.  For example, a getPersonNames() method on the “person” entity might return an instance of an EntityList containing PersonName instances.

Protected Methods

These methods are exposed via the extended generated superclass of an entity (the “_Gen” class) for the use of business methods implemented on the entity.  With few exceptions, the methods exposed as public methods on business entities are also exposed “within” the entity as protected methods for the convenience of business logic.  Additionally, the following methods are added:

·         thisEntity()—Returns the instance of the current entity.  Generally, this is used when an entity needs to pass itself as an argument in a method call.

·         addError(ServerMessage)—Add an error relating to the current entity.

·         addError(ServerMessage, Property)—Add an error relating to the passed property on the current entity.

·         addWarning(ServierMessage)—Add a warning to the current warning list.

Data Transfer Object Methods

DataTransferObjects (or DTOs) are transient objects meaning that changes to their state are not directly persisted.  They provide a mechanism where the set of properties of an entity can be passed around in business logic without the implication that changes to their values will be transparently persisted to the database.

·         getFoo()/setFoo(Bar)—Get or set the value of the property “foo”.

·         newEntity()—Create a new persistent entity based on the values currently held in the DTO.

Id Methods

Entities generally have an Id class created for them by the artifact generator.  This provides clarity in the application code as to what “kind” of Id is being held or passed.  Likewise, there are useful methods on these Id classes.  Id instances are immutable.

·         getEntity()—Get the business entity that this Id refers to or null if no such entity instance exists.

·         getFoo()—In the case where the Id contains a persistent entity “foo”, return that entity.

·         getBarId()—Get the contained Id referring to the entity “bar”.

·         newDTO()—Create a new DTO instance with the Id property already set to this Id’s value.

Maintenance Class Public Methods

 

Please refer to the Javadocs for the public API.

UI Javascript User Exits

The client-side external user exits are designed to give implementers flexibility and power to extend the user interface of a SPL products.  Implementers have the ability to add additional business logic without changing SPL product html files.  These user exits were developed such that developers can create an include-like file based on external user exit templates.

There are two types of client user exits available.  There are process-based user exits that wrap the similar product user exit code with pre- and post- external user exit calls, and there are also data-based user exits that simply allow the implementer to add/delete data from the product returned data.

Both types of external user exit are only called if the function exists in the implementers external include JSP file.  All available user exits are listed online in the system through the relative URL: /code/availableUserExits.jsp, with definition examples and links to the framework code that executes the call.

UI Available User Exits – Online Reference

 

The location of the external JSP file is the \cm directory under the web application root directory:

 

This document assumes that you are familiar with the framework architecture and its UI program component templates (XSLT) and that you know how the base exits work.  It also assumes that you are proficient in JavaScript and HTML.

Contents

Client User Exit Flow

External User Exit Templates

Create An External User Exit

Field-level Security Client-Side User Exit Example

How-To

Client User Exit Flow

The following flowcharts illustrate the most common user exit functions used to modify the user interface.  The flowcharts are designed to help you see the coordination of processing between the client and the server as well as where the pre and post external user exits can be used.

The following diagram explains the shapes used on subsequent flowcharts:

Flowchart Legend

Whenever you see a request for a server-side page service, you can refer to the Page Maintenance Program flowchart to see the server-side processing.  You can determine the Page Action based on the service being requested:  Read, Add, Change, Delete, or Default.

Contents

Read Page

Delete Page

Save Page

Refresh Page

Prepare Model For Add

Update Field

Read Page

The Read Page function is executed whenever data needs to  be presented from the database to the user.  It is called after a root item is selected from a search page or when navigating to another transaction via a Go To button or a Context menu.

Delete Page

The Delete Page function is executed when the user clicks the Delete icon.

Save Page

The Save Page function is called whenever a user clicks the save icon (or the associated accelerator key).  If the user has displayed an existing object on a maintenance page, the Action Flag and therefore the Change Page Service is requested.  If an existing object is not displayed on a maintenance page and the user presses save (i.e., they are adding a new object to the database), the Action Flag does not equal change and therefore the Add Page Service is called. 

Refresh Page

The Refresh Page function is called from the Read, Delete, and Save page processes.  It is also called when the user clicks the Refresh Page icon (or the related accelerator key) or when the user navigates to a different tab page.

 

The pre/post Tab Page Window Load user exit is a good place to implement Field Level Security logic.  By using the getFieldLevelSecurityInfo() function found on the "top" object (please refer to the Free Functions section found within the Technical Background chapter of the Development Tools documentation), an implementer can extend the behavior or look of the window.  For example, a field can be made "read-only" if the user's Field Level security is lower than the required security level.  This prevents the user from changing the value of the field.

You can use pre/post List Grid Row Processing exit to manipulate fields within the grid.  For example, you can calculate the default value of a column depending on the values of other columns.

Prepare Model For Add

Prepare Model for Add is called when a user enters a page in Add mode (i.e., they click the + button next to a menu item).  It is also called by Delete Page to load an empty model, which displays page with empty fields.  

Update Field

The Update Field function is called when a user changes the focus from one field on the page to another (i.e. when a user tabs out of a field or clicks on another field).

The pre/post After Field Update user exit is a good place to manipulate HTML elements (e.g., hiding / unhiding or enabling / disabling) depending on the value entered by a user.

External User Exit Templates

Below is the list of all available external template files.  They are located under the "\cm_templates" folder of the application root directory. 

Note.  The flowcharts above illustrate user exits in the Tab Page and List Grid templates only; these are the templates in which most of your customizations will occur.

Accordion:        accordionPage.jsp

Graph Panel:     graphPanelExit.jsp

List Grid:           listGridExit.jsp

Search Data:     newSearchDataExit.jsp

Search Page:    newSearchPageExit.jsp

Sub Panel:        subPanelExit.jsp

Tab Page:         tabPageExit.jsp

Tree Page:        treePageExit.jsp

Contents

Template Structure

Design Approach

Using The External User Exit Templates

Template Structure

Each template has three main sections into which you insert your code.

·         User Variable Declaration contains global variable declarations.  (Do not declare any global variables unless it is absolutely necessary.)

·         User Function Declarations contains your own functions.  Your own functions are not called from the corresponding JSP file.  Take coupling and cohesion into consideration when you design your functions.

·         Functions Called from the Corresponding HTML page contains functions that are called from the HTML page.  Uncomment the functions you need to use and add your code.  You can find more technical information about the behavior of these functions in the external template files.

Design Approach

Examine the partial template below to see how the external include file looks.  As you might notice everything is commented out.  If you want to call a certain function, you have to uncomment the functions and/or sections.  Please note that only declared functions in the external files can be called from the HTML Page.  To see the entire external file templates or available functions, examine the  "\cm_templates" folder under the application root directory.

 

<%@page contentType="text/html;charset=UTF-8"%>

<%@ taglib uri="spl.tld" prefix="spl" %>

<spl:initializeLocale/>

 

<!--

        ******************************************************************

        *                                                                *

        * Copyright (c) 2000, 2007, Oracle. All rights reserved.         *

        *                                                                *

        ******************************************************************

        *                                                                *

$#BSES* REVISION-INFO Start Exit, Do not modify - Dev. Only.

      *  $DateTime: 2010/04/21 12:54:16 $

      *  $File: //Tools/V4.0.0/SDK/SDKSetup/help/ENG/02Developer Guide/03PublicAPI.html $

      *  $Revision: #1 $

$#BSEE* REVISION-INFO End Exit, Do not modify - Dev. Only.

        ******************************************************************

-->

 

<script type="text/javascript">

 

//                          User Variable Declarations

//-----------------------------------------------------------------------------

 

/*

Replace With Your Code

*/

 

//                          User Function Declarations

//-----------------------------------------------------------------------------

 

/*

Replace With Your Code

*/

 

//           User Functions That Are CALLED From According JSP File

//-----------------------------------------------------------------------------

 

/*

function extPreOnWindowLoadNoListBefore(){

//This should be used to set values/attributes when the page loads.

//This includes actions after a default.

//

//This function is called BEFORE SPL's internal functions are called

 

// Your Code

}

*/

 

The following discussion explains how the external file is included.  The external file is a JSP file.  This JSP is executed with appropriate HTTP request header data from within the XSLT engine that creates the HTML from the UI meta-data.  The XSLT engine will output the rendered JSP code textually into the final HTML.  If the file does not exist the server will not include the external file, otherwise every defined function (uncommented) in the file will be included and called at the appropriate times.

Using The External User Exit Templates

All the external user exit templates are located in the \cm_templates directory. Once the UI Program to be extended is known, the appropriate user exit template can be selected from the templates directory.

·         Use any editor that supports the JSP file editing and open the approprite user exit.

·         Determine the base user exit around which to insert your external user exit.  

·         Uncomment the necessary functions, and add your code.

·         Save the external user exit file as ext_<JSPfilename>.jsp under the \cm directory.  Where JSPfilename is the JSP file you want to extend.

·         Test.

 

Create An External User Exit

The following example shows the process of creating an external user exit.  In this example, we would like to disable the Start Date on the Pay Plan page and default it to “today’s” date.

Contents

Find The Name of The JSP File

Determine The Base User Exit

Uncomment The Function And Add Code

Test Your Code

Find The Name of The JSP File

In Utilities CC&B, navigate to the Pay Plan Maintenance page (Main Menu -> Credit & Collection -> Pay Plan) and find the section where the Start Date field is displayed. From the screenshot below we can see that Start Date is under the main section of the page.

Pay Plan Maintenance Page

Determine the name of the program component we need to extend.  Right click on the page and select the menu option View Source.

 

 

Pay Plan Maintenance Page – View Source

View Source would open the page source in a text editor.

JSP Source Code View - payPlanMaintPlanPage

 

From the menu bar or the program file information section you can identify the program name as payPlanMaintPlanPage (look for the Program name in the source code comments).

Determine The Base User Exit

For this example, we want to disable the input element corresponding to the start date and display a message that the start date is disabled. This means we want to disable the field when the page loads; and therefore we want to insert our code inside the onWindowLoad() function.  The external user exit function that allows us to do this is the extPostOnWindowLoad() function.

You can check the field names under the payPlanMaintPlanPage’s Labels section.

    * Program name:      payPlanMaintPlanPage

    * Program location:  /ci/payPlan

    * Program version:   68

    * Program template:  UIXTP

    * Template file:     //FW/2.2.0/Code/modules/web/source/root/WEB-INF/uiXSL/tabPage2.xsl

    * Template revision: 4

    * Included XSL versions:

    *   common          

    *   commonPage       

    *   commonPageSingleRecord 3

    *

    * Labels:

    *     Table$Field  -  label   (element type, js_name)

    *     $PP_LBL  -  Pay Plan   (element type='L' , jsName='PP_LBL')

    *     ...

    * Widget Info: 

    *     Widget_ID , Element Type - label info - label

    *     ...

    *     START_DT, IT - $START_DT -  Start Date

    *     PAY_METH_CD, IS - $PAY_METH_CD -  Pay Method

    *     ...

 

The two important pieces of information in this source view are:

  1. The Program name definition – payPlanMainPlanPage in this example;
  2. The Template file definition – tabPage2.xsl in this example.
Uncomment The Function And Add Code

Once the program name to be extended (e.g. payPlanMainPlanPage) and the template (e.g. tabPage2.xsl) to use are known, the associated template jsp file can be copied from the web application source’s /cm_templates directory to the /cm directory and renamed to have the form ext_XXXX.jsp, where “XXXX” is the name of the program to be extended.

For example, in this case the jsp user exit template ./cm_examples/tabPageExit.jsp would be copied and renamed to ./cm/ext_payPlanMaintPlanPage.jsp.  The following coding change inside the extPostOnWindowLoad() function would then be made for the modified behavior.

function extPostOnWindowLoad(){

//This should be used to set values/attributes when the page loads.

//This includes actions after a default.

//This function is called AFTER SPL's internal functions are called

 

protectField("START_DT");

alert ("Start Date Field is disabled. Defaulted to Current Date.");

 

}

Test Your Code

Now let's see if it works. First make sure that the user exit file is copied under the \cm folder of the application root directory.  Reload the page by right clicking on the page and choosing refresh.

NOTE: It may also be necessary to delete the cache of the browser before refreshing the page.

Pay Plan Main Page after implementing External User Exit

 

Field-level Security Client-Side User Exit Example

Field level security information is exposed on the browser side.

Use the following function to retrieve a user's field level security for a given service or Navigation Key:  

top.getFieldLevelSecurityInfo(serviceNameOrNavigationKey)  ---> returns an Object keyed by security type. 

The following example illustrates how to implement security for adjustment amount on the client.  In the example, User Group 1 is authorized to freeze adjustments less than $10,000, and User Group 2 can authorize any adjustment. We want to disable the Freeze button, if the user's security doesn't meet the condition. There is a security type ADJAMT defined for the Adjustment Maintenance.

The following example code would be added to the extPreOnWindowLoad user exit:

var secInfo = top.getFieldLevelSecurityInfo("adjustmentMaint");

var adjAmtSecInfo = secInfo["ADJAMT"];

if (adjAmtSecInfo < "2" && parseFloat(model.getValue("ADJ_AMT")) > 10000 ) {

   //disable the field

   protectField("FREEZE_SW")

}

 

How-To

The following are some how-to examples of typical behavior utilizing some of the standard user exits.

The examples are written for cases of modifying new CM transaction pages, where the function definitions are put into “extended JavaScipt” files (.xjs) that are meant to contain JavaScript user exits directly for a page.

If, on the other hand, an implementer wishes to modify the behavior of a shipped product page, each of the function below have a corresponding “ext” function that can defined in a /cm/extXXX.jsp file corresponding to the desired page that will fire after any product function call (see above example of hiding the Sequence column in the algorithm maintenance page).

Contents

How do I control the Initial Focus within Tab Pages/Grids/Search Pages?

How do I mark fields that won't make the model dirty?

How do I control the triggering of defaults after a search?

How do I avoid automatically setting fields to uppercase?

How Can I Force the Save Button to be Enabled?

How Can I Override the Processing After a Change/Add?

How Do I Prevent the System from Setting Focus to a Widget after an Error?

How Do I Prevent Attributes From Being Copied Into New List Elements?

How Do I Customize New List Elements?

How can I get my sequence numbers to default in an appropriate and consistent manner on

How Do I Override the Tab Page Shown After An Error in a List (Grid/Scroll)?

How Do I Disregard Unwanted Criteria From a Search Triggered Search by a Search Button?

How Do I Disregard Unwanted Search Result Columns?

How do I format a value based on a given format?

How do I control the Initial Focus within Tab Pages/Grids/Search Pages?

The system automatically places the initial focus on an appropriate widget (generally input fields) within a Tab Page/Search Page/Grid.

By default it will place focus on the first enabled field with a data class defined on it. (If input fields do not have the Field Name / Table Name defined within Meta Data they will have no data class)

If there are no fields satisfying this criteria within the tab page it will continue to look (recursively) into all the contained frames (i.e. list grids etc.)

If no field is found then no element receives focus.

You can override the default behavior at each level via the provision of a focusWidgetOverride() function within the user exit file which will return the Name of the Field to receive the focus or null.

If null is returned it will ignore all fields within this document and continue to search in lower level documents.

E.G.

From within a Tab Page (If you want focus to go on to a sub document)

 

function focusWidgetOverride() {

  return null;

}

 

From within a List Grid

function focusWidgetOverride() {

  return "TD_TYPE_DRLKY:0$TBL_NAME";

}

 

from within a Search Page

function focusWidgetOverride() {

   return "LAST_NAME";

}

 

Note.  These functions can be as simple or complicated as you want.  You could conditionally return a field name or null and this code will run each time the window loads.  Also, if a tab page has a popup window or a search window open as it is loading then the initial focus will not be set to the tab page but stay with the popup window

How do I mark fields that won't make the model dirty?

In certain windows, we have a concept of a "locator" field which typically acts as a filter on some lists of the object you're looking at. Examples are user group's filter on description, and several IB windows filter by date.

With the warning about loss of data when throwing away a dirty model, this results in the use of locator fields giving this warning, which wouldn't be expected. In order to avoid this warning on locator fields, you can add a function like the one that follows that enumerates the locator fields:

 

function ignoreModifiedFields(){

    return ['START_DTTM']

}

 

You can include any number of fields in the array, e.g.

return ['FIELD_1', 'FIELD_2', 'FIELD_3']

 

How do I control the triggering of defaults after a search?

If a search returns multiple fields and more than one of these fields can trigger default, then it might be more efficient to only have one of these fields trigger the defaulting.

This is accomplished by creating a new function called overrideDefaultTriggersFor_SEARCHGROUP within the tab page that contains the search.  Where SEARCHGROUP is the name of the searchGroup you want to override.

The function must return an object with the triggering field(s) are attributes with a true value.

For example

 

function overrideDefaultTriggersFor_SRCH1() {

   var triggers = {};

 

   triggers["ACCT_ID"] = true;

            triggers["SA_ID"]=true;

 

   return triggers;

}

 

How do I avoid automatically setting fields to uppercase?

Model attributes that are also key fields are automatically coerced to be in uppercase.  You can block this behavior on a field-by-field basis by defining the notUppercaseFields() function in your TabMenu’s user exit file to return an array of field names that should not be converted.

Example:

 

 

function notUppercaseFields() {

   return ['ELEM_ATT$AT_NAME']

}

 

 

 

You can also provide a “global” override for an entire TabMenu by setting the shouldNotAutoUppercase variable to true:

 

var shouldNotAutoUppercase = true;

 

How Can I Force the Save Button to be Enabled?

The save button usually synchronizes itself to the state of the model such that if it hasn’t been “dirtied” the button is disabled.  You may wish to control the state of the save button e.g. because a save should always/never be allowed.

Simply define the function saveButtonEnablingOverride() on your TabMenu user exit file to return a boolean indicating whether the save button should be enabled.  You can simply return a literal boolean, or perform any desired processing to determine the return value.

Example:

 

function saveButtonEnablingOverride() {

  return false;

}

 

How Can I Override the Processing After a Change/Add?

If you need to intervene in the processing after the system successfully completes a Change or Add operation, define the function privatePostChangeSucceeded() or privatePostAddSucceeded() in your TabMenu user exit file.  The function should return a boolean to indicate whether the system should refresh the UI with the newly returned server data.  You’d want to return false if e.g. you navigate to a different TabMenu.

Example :

function privatePostAddSucceeded() {

    var model = parent.model;

    var modeFlag = model.getValue('COMPL_NAV_MODE_FLG');

    var navKey = model.getValue('COMPL_NAV_KEY');

    var complSw = model.getValue('CMPLT_CLICKED_SW');

    if (complSw && model.getValue('ENRL_STATUS_FLG') == '30') {

        if (modeFlg && navKey){

             if (modeFlag == 'G') {

                parent.tabPage.gotoContext(navKey);

                return false;

             } else if(modeFlag == 'A') {

                parent.tabPage.addContext(navKey);

                return false;

             }

        }

   }

   return true;

}

 

How Do I Prevent the System from Setting Focus to a Widget after an Error?

When a service receives an error and shows a message after calling a back-end service, the browser attempts to set focus to the relevant widget in error.  If you don’t need this behavior, you can define the TabMenu variable dontSetFocusOnError to boolean “true.

Example:

var dontSetFocusOnError = true;

How Do I Prevent Attributes From Being Copied Into New List Elements?

Key fields are automatically copied (based on name matching) from a parent list element into new child elements (e.g. created by using the scroll ‘+’ button), in order to keep their prime keys consistent.  If you want to inhibit this operation for certain fields, define the TabMenu function dontCopyKeyNames_<LIST NAME> to return an array of fields that should not be copied into new elements of the list named LIST_NAME

Example:

function dontCopyKeyNames_ENRL_FLD() {

   return ['SEQ_NUM']

}

 

How Do I Customize New List Elements?

When you use ‘+’ button on a grid or scroll you get a new, empty list element.  If you want to customize the object, define a function in the TabMenu’s user exit file named initializeNewElement_<LIST_NAME>(newElement).

Example:

function initializeNewElement_ENRL_LOG(newElement) {

    newElement.set(‘ENRL_LOG_TYPE_FLG’, ‘USER’);

    newElement.set(‘USER_INFO’, parent.model.getValue(‘CURRENT_USER_INFO’));

}

How can I get my sequence numbers to default in an appropriate and consistent manner on my List Grid?

If you are working with a List Grid that uses some type of sequence field (e.g. SEQNO, LINE_SEQ, SORT_SEQ) , there is a handy bit of technology that you can use that will cause the UI to do this job for you. 

Just follow the steps below and you'll have the problem solved in no time. The sequence field will be populated in your "empty line" and any elements that are added from then on will have an appropriate value in the sequence field. If the user edits the sequence field at any point, the next element added to the list will incorporate the change without any problems.

Note.  The default Sequence Number functionality will default the next nearest tens value from the highest sequence. The defaulting will do nothing after the sequence reaches the highest number it can hold.

·         1)  In the user exit file of the Tab Menu - not the main Page or the List Grid - copy this JavaScript code:

function initializeNewElement_LIST_NAME(newElement) {

      var myListName = "LIST_NAME";

      var myListSeqName = "FIELD_NAME";

      var myListMaxSeq = 999;

      defaultSequenceNumber(myListName,myListSeqName,myListMaxSeq,newElement)

}     

 

</SCRIPT>

<SCRIPT src="/zz/defaultSequenceNumber/defaultSequenceNumber.js"></SCRIPT>

<SCRIPT>

 

·         For LIST_NAME, substitute your List Grid's list name. Be careful not to lose that underscore [ _ ] just in front of LIST_NAME in the first line! Remember that JavaScript is case-sensitive and make sure that you use all UPPERCASE letters as shown here.

·         For FIELD_NAME, substitute the name of your sequence field, whatever that might be in your List. Don't lose the quotes [ " ] ! Again, use all UPPERCASE letters.

How Do I Override the Tab Page Shown After An Error in a List (Grid/Scroll)?

When an error is received (e.g. after a Save) it attempts to set focus on the relevant widget, which might require flipping to a different tab page.  If the error relates to a list (grid or scroll) the system might not choose the tab page you’d prefer.  In that event you can control the tab page that should be opened by defining the TabMenu function overrideErrorTabPage_<LIST_NAME>().

Example:

function overrideErrorTabPage_BPA() {

    return 'bussProcessAssistantStepPage';

}

 

How Do I Disregard Unwanted Criteria From a Search Triggered Search by a Search Button?

When a search button (currently implemented as an IMG) is pushed, the system launches a search and “pulls” all applicable criteria values from the current model.  It might be that certain criteria fields should be ignored in a particular case.  You can define the function addIgnoreFieldsFor_<triggerFieldName>() on a tab or search page’s user exit file to specify fields to ignore whenever the IMG button named triggerFieldName is pushed on that page.

The function takes a single argument, fields, and you should add key/value pairs where the key is a field name to ignore, and the value is true.

Example:

addIgnoreFieldsFor_ADDRESS1_SRCH = function(fields) {

  fields['CITY_SRCH'] = true

}

 

addIgnoreFieldsFor_PER_ID = function(fields) {

  fields['ENTITY_NAME_SRCH'] = true

}

 

How Do I Disregard Unwanted Search Result Columns?

When you accept the result of a NOLOAD search the system tries to populate the selected search result row into the current model.  Sometimes this doesn’t make sense e.g. because there is no corresponding attribute for a display-only column.  You can exclude a column from being returned as part of a search result by defining the search client’s (Tab Page or Search window) function ignoreResultColumns() in the corresponding page’s user exit file.  Return an object with keys specifying attributes and values all set to boolean “true”.

Example:

function ignoreResultColumns() {

    return { ADDRESS1: true, CITY: true, POSTAL: true };

}

 

Since Searches can be shared by many search clients, it is possible that some clients want to get a specific column, but others don’t.  In that case, define the TabMenu function ignoreResultColumnsFor_<service> as above.

Example:

function ignoreResultColumnsFor_CILCCOPS() {

    return {CONT_OPT_TYPE_CD: true}

}

 

How do I format a value based on a given format?

If you need to format a value based on a given format, for example, on Person ID Number, if you select ID Type as SSN (999-99-9999), you can always format the Person ID Number before committing it to the server.

To do so, you can call the formatValue javascript function.

·         In the user exit file of the tab page include the following lines:

 

</SCRIPT>

<SCRIPT src="/zz/formatValue/formatValue.js"></SCRIPT>

<SCRIPT>

 

·         Now, you can start using the function to format a value. To use this function, you need to pass in both the value and the format into the function.

var phFormat = myData.getValue(pureListName + ‘PHONE_TYPE_FORMAT’);

if (pureFieldName == ‘PHONE’) {

  updateField(pureListName + ‘PHONE’ ,

        formatValue(myData.getValue(pureListName + ‘PHONE’), phFormat));

}

Java User Exits (interceptors) Interfaces and Classes

The following are the interfaces used for Java User Exits (interceptors).

Contents

IAddInterceptor Interface

IChangeInterceptor Interface

IDeleteInterceptor Interface

IReadInterceptor Interface

InterceptorError class

InterceptorWarning class

IAddInterceptor Interface

This interface defines the processing plug-in spots before or after invoking a service in add mode.

Interface com.splwg.base.api.serviceinterception.IAddInterceptor

Methods

Contents

PageBody aboutToAdd(RequestContext, PageBody)

void afterAdd(RequestContext, PageBody)

PageBody aboutToAdd(RequestContext, PageBody)

This method is called before the service is invoked.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – The input page body to be added.

Return value

·         PageBody or null -- If a page body is returned, this is considered the result of the service and the underlying service will not be executed.  If null is returned, the service will run normally.

Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

void afterAdd(RequestContext, PageBody)

This method is called after the service invoked in add mode.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – This contains the information that was added by the underlying service.

Return value

·         Void.

Throws

InterceptorError – throw this exception when an error occurs

InterceptorWarning – throws this exception to signal an application warning

IChangeInterceptor Interface

This interface defines the processing plug-in spots before or after invoking a page service in change mode.

Interface com.splwg.base.api.serviceinterception.IChangeInterceptor

Methods

Contents

PageBody aboutToChange(RequestContext, PageBody)

void afterChange(RequestContext, PageBody)

PageBody aboutToChange(RequestContext, PageBody)

This method is called before the service invoked in change mode.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – this object contains the information that is to be submitted to the underlying service.

Return value

PageBody or null – if a page body is returned, this is considered the result of the invocation and the underlying service will not be called.  If null is returned, the underlying service will be invoked normally.

Throws

InteceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

 

void afterChange(RequestContext, PageBody)

This method is called after change action is invoked in change mode.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – This holds the result of the underlying change service.

Return value

·         Void.

Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

IDeleteInterceptor Interface

This interface defines the processing plug-in spots before or after invoking a service in delete mode.

Interface com.splwg.base.api.serviceinterception.IDeleteInterceptor

Methods

Contents

boolean aboutToDelete(RequestContext, PageBody)

void afterDelete(RequestContext, PageBody)

boolean aboutToDelete(RequestContext, PageBody)

This method is called before the service with a delete action.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – the data to be deleted.

Return value

·         Boolean – indicates whether or not to continue processing of the service.  If true, continue with the normal underlying invocation.  If false, do not continue (but the service returns “success” to the client invoker).

 Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

void afterDelete(RequestContext, PageBody)

This method is called after the service invoked in delete mode.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – the data that was deleted by the underlying service

Return value

·         Void.

Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

IReadInterceptor Interface

This interface defines the processing plug-in spots before or after a service retrieves information.

Interface com.splwg.base.api.serviceinterception.IReadInterceptor

Methods

Contents

PageBody aboutToRead(RequestContext, PageHeader)

void afterRead(RequestContext, PageBody)

PageBody aboutToRead(RequestContext, PageHeader)

This method is called before a service retrieves information.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageHeader – The data describing the information that should be read.

Return value

·         PageBody or null – If a page body is returned, this is considered the result of the service and underlying will not be invoked.  If null is returned, the underlying service will be invoked normally.

Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

void afterRead(RequestContext, PageBody)

This method is called after the service retrieved the information.

Input

·         RequestContext – contains session parameters, such as, language cd, user id and etc.

Input/Output

·         PageBody – result of read service

Return value

·         Void.

Throws

InterceptorError – throw this exception when an error occurs.

InterceptorWarning – throws this exception to signal an application warning

InterceptorError class

The class com.splwg.base.api.serviceinterception.InterceptorError subclasses the java.lang.Exception class.  This class contains information regarding an error condition that occurred during the pre/post processing plug-in.  This exception is caught by the framework and is used to build the appropriate application error object.

Attributes

·         Message Category

·         Message Number

·         List of Parameters (Strings) and types

Methods

Contents

void setMessageNumber(BigInteger messageNumber)

void setMessageCategory(BigInteger messageCategory)

void setMessageParameters(List messageParameters)

void setMessageParameterTypeFlags(List messageParameterTypeFlags)

void setMessageNumber(BigInteger messageNumber)

Set the message number (required)

void setMessageCategory(BigInteger messageCategory)

Set the message category (required)

void setMessageParameters(List messageParameters)

Set the message parameters list

void setMessageParameterTypeFlags(List messageParameterTypeFlags)

Set the message parameter type flags list.  The size should match the message parameters list.

InterceptorWarning class

The class com.splwg.base.api.serviceinterception.InterceptorWarning subclasses the java.lang.Exception class.  This class contains information regarding one or more warning conditions that occurred during the pre/post processing plug-in.  This exception is caught by the framework and is used to build the appropriate application warning object(s).

Attributes

·         List of warning server messages

Constructors

Contents

InterceptorWarning(ServerMessage warningMessage)

InterceptorWarning(List warningMessages)

void addWarningMessage(ServerMessage message)

InterceptorWarning(ServerMessage warningMessage)

Create a new InterceptorWarning with the given warning message as its sole message

InterceptorWarning(List warningMessages)

Create a new InterceptorWarning with the given List of warning messages

Methods

void addWarningMessage(ServerMessage message)

Add the given server message to the list of warning messages

RequestContext Methods

Class com.splwg.base.api.service.RequestContext includes the following accessor methods:

Contents

String getLanguageCode()

String getUserId()

String getLanguageCode()

Returns the current user’s language code

String getUserId()

Return the user id

Data Objects

Both PageHeader and PageBody are "wrappers" on underlying Maps that hold datatypes of various types, keyed by field names (Strings).  The valid field names for a service are described in the service meta info file (an xml document).  Null values are not allowed; use empty strings to represent missing values (e.g. for null date).

Note that most system datatypes are represented in these Java objects as simple Strings.  Note the following:

·         Booleans are represented by the Java Boolean class

·         Date values are represented as Strings in the format YYYY-MM-DD

·         Date/Time values are represented as Strings in the format YYYY-MM-DD-HH:MM:SS

·         Time values are represented as Strings in the format HH:MM:SS

·         BigInteger values are represented as Java BigInteger values

·         BigDecimal and Money values are represented as Java BigDecimal values, with the appropriate scale.

Contents

PageHeader and PageBody Methods

PageHeader

PageBody

ItemList

ListHeader

ListBody

CMServiceConfig.xml structure

PageHeader and PageBody Methods

Both PageHeader and PageBody implement the following methods:

Contents

Object get(String fieldName)

String getString(String fieldName)

boolean getBoolean(String fieldName)

BigInteger getBigInteger(String fieldName)

void put(String fieldName, Object value)

Object get(String fieldName)

Returns the Object value of the field named fieldName (may need to cast the result to the appropriate datatype)

String getString(String fieldName)

Convenience method that returns the String value of the field named fieldName.

boolean getBoolean(String fieldName)

Convenience method that returns the Boolean value of the field named fieldName.

BigInteger getBigInteger(String fieldName)

Convenience method that returns the BigInteger value of the field name fieldName.

void put(String fieldName, Object value)

Set the value at the given fieldName to the given value.

PageHeader

The methods for class com.splwg.base.api.service.PageHeader are described above.

PageBody

Class com.splwg.base.api.service.PageBody implements the methods described above.  In addition, it supports the following methods:

ItemList getList(String name)

Return the ItemList with the given name

ItemList

Class com.splwg.base.api.service.ItemList is the Java representation of a list header and list children objects.  The methods are as follows:

Contents

ListHeader getHeader()

String getName()

List getList()

void setList(List list)

ListHeader getHeader()

Return the list header object.

String getName()

Return the ItemList’s name

List getList()

Return the java.util.List of ListBody child objects.

void setList(List list)

Set the underlying list to the provided list of ListBody instances.

ListHeader

The class com.splwg.base.api.service.ListHeader is functionally equivalent to the class PageHeader, above.

ListBody

The class com.splwg.base.api.service.ListBody is functionally identical to the class PageBody, above.  In addition, it has this useful method:

String getActionFlag()

Return the flag describing the pending action for this ListBody (e.g. add, change, delete).

CMServiceConfig.xml structure

The ServiceConfig.xml and CMServiceConfig.xml will look similar to the following:

<ServiceInterceptors>

    <Service name=”CMLPXXXX”>

        <Interceptor action=”add”>

            com.splwg.interceptor.CMLPXXXXAddInterceptor

        </Interceptor>

        <Interceptor action=”change”>

            com.splwg.interceptor.CMLPXXXXChangeInterceptor

        </Interceptor>

    </Service>

</ServiceInterceptors>

 

The above example illustrates how interceptors are defined for the service CMLPXXXX.  You can define one or more interceptors, depending on the action, for each service.  The valid actions are “add”, “change”, “delete”, and “read”.

Note.  It is valid to have the same interceptor class for more than one action as long as the class implements the corresponding interceptor interface.