Oracle Mobile Supply Chain Applications

Developers Guide Version 1.0 January 8, 2012

Page 1 of 35

Table of Contents
Table of Contents _____________________________________________________________ 2 Table of Figures ______________________________________________________________ 3 Purpose _____________________________________________________________________ 5 Oracle MSCA Overview ________________________________________________________ 5 MSCA User Interface __________________________________________________________ 6 MSCA Application Framework ___________________________________________________ 7
MSCA Object Beans ________________________________________________________________ 7 MSCA Java Event-Listener Model _____________________________________________________ 8 MSCA Bean APIs ___________________________________________________________________ 9
Bean APIs ________________________________________________________________________________ 9 Sub classes associated with the MWA Bean _____________________________________________________ 9 Menu Item Bean ________________________________________________________________________ 9 Commonly Used Menu Item Bean APIs ______________________________________________________ 9 Page Bean _____________________________________________________________________________ 10 Commonly Used Page Bean APIs___________________________________________________________ 10 Flexfield Bean __________________________________________________________________________ 10 Commonly Used Flexfield APIs ____________________________________________________________ 10 Field Bean _____________________________________________________________________________ 10 Commonly used Field Bean APIs ___________________________________________________________ 11

Field Bean Types and Commonly Used APIs ____________________________________________ 11

Field Bean Sub-class Diagram _______________________________________________________________ 11 InputableFieldBean _____________________________________________________________________ 11 The Commonly used APIs ________________________________________________________________ 11 LOVFieldBean __________________________________________________________________________ 12 Commonly Used APIs ____________________________________________________________________ 12 TextFieldBean__________________________________________________________________________ 13 Commonly Used APIs ____________________________________________________________________ 13 HeadingFieldBean ______________________________________________________________________ 13 Commonly used APIs ____________________________________________________________________ 14 ListFieldBean __________________________________________________________________________ 14 Commonly used APIs ____________________________________________________________________ 14 ButtonFieldBean _______________________________________________________________________ 14 Commonly used APIs ____________________________________________________________________ 14

Form Functions in MSCA ______________________________________________________ 14 MSCA and the AK Repository ___________________________________________________ 15

Defining Labels in the AK Repository _________________________________________________ 15 AK Repository Data Field Identifier (DFI) ______________________________________________ 15 Steps to Create Labels in AK Repository _______________________________________________ 15 Page 2 of 35

Customizing MSCA Oracle Recommended Best Practices ___________________________ 18 Setting Up a Development Environment __________________________________________ 18
Download and Install the Required JDK _______________________________________________ 19 Select and Install a Java IDE _________________________________________________________ 19
NetBeans Installations Special Instructions ____________________________________________________ 19 NetBeans Post Installation Instructions _______________________________________________________ 19

Starting and Stopping the MWA Telnet Server _____________________________________ 21

Start MWA Telnet Server ___________________________________________________________ 21 Stop MWA Telnet Server ___________________________________________________________ 21

Miscellaneous Topics on Customizing MSCA_______________________________________ 21

Identifying Java Class Files for a Menu Item ____________________________________________ 21 Display MSCA Character Mode Form Information _______________________________________ 22 Display MSCA Function and Hot Keys _________________________________________________ 22 About MSCA Fields and Buttons _____________________________________________________ 23 MSCA/MWA Class Types and Locations _______________________________________________ 23

MSCA Customizations Case Studies ______________________________________________ 23

Case 1: XXXXX CR to Add Part Serialization to XXXXX Quick Pick ___________________________ 24
Understand the Functional Requirement ______________________________________________________ 24 Create Test Data Sets ______________________________________________________________________ 24 Identify the XXXXX Quick Pick Current State ____________________________________________________ 25 Identify the XXXXX Quick Pick To Be State ____________________________________________________ 27 Document and Build the Required Changes ____________________________________________________ 27

Case 2: Addition of extra fields on Quick Ship Page to collect FOB terms, freight terms, and document shipset _________________________________________________________________ 28
Understand the Functional Requirement ______________________________________________________ 28 Identify the Quick Ship Current State _________________________________________________________ 28 Identify the Quick Ship To Be State _________________________________________________________ 28 Code Changes and Additions ________________________________________________________________ 29 Create DocumentShipSetLOV Java Class _____________________________________________________ 29 Create CustomEZShipFunction Java Class ____________________________________________________ 31 Create CustomEZShipPage Java Class _______________________________________________________ 31

Index ______________________________________________________________________ 34

Table of Figures
FIGURE 1 ORACLE MSCA INFORMATION FLOW........................................................................................................................5

Page 3 of 35

FIGURE 2 MSCA APPLICATION COMPONENTS .........................................................................................................................6 FIGURE 3 MSCA GRAPHICAL INTERFACE .................................................................................................................................6 FIGURE 4 MSCA CHARACTER MODE INTERFACE ......................................................................................................................6 FIGURE 5 MSCA APPLICATIONS FLOW ...................................................................................................................................7 FIGURE 6 MSCA OBJECT INTER-RELATION MODEL ...................................................................................................................7 FIGURE 7 MSCA JAVA BEAN HIERARCHIES .............................................................................................................................9 FIGURE 8 MSCA FIELD BEAN HIERARCHIES ...........................................................................................................................11 FIGURE 9 UPDATING A FORM FUNCTION ...............................................................................................................................15 FIGURE 10 CREATING AK REPOSITORY ATTRIBUTE ..................................................................................................................16 FIGURE 11 DEFINING A REGION IN THE AK REPOSITORY ...........................................................................................................17 FIGURE 12 LINKING A REGION IN THE AK REPOSITORY .............................................................................................................17 FIGURE 13 DEFINE THE DFI ATTRIBUTES ...............................................................................................................................18 FIGURE 14 SELECTING PROJECT PROPERTIES IN NETBEANS .......................................................................................................20 FIGURE 15 NETBEANS ADD JAR/FOLDER ..............................................................................................................................21 FIGURE 16 GET MSCA FORM INFORMATION ........................................................................................................................22 FIGURE 17 DISPLAYING FUNCTION/HOT KEYS ........................................................................................................................22 FIGURE 18 CURRENT XXXXX QUICK PICK FORM....................................................................................................................24 FIGURE 19 CLASS HIERARCHY DIAGRAM ...............................................................................................................................26 FIGURE 20 "TO BE" STATE SCREEN FLOW .............................................................................................................................27 FIGURE 21 QUICK SHIP CURRENT STATE ...............................................................................................................................28 FIGURE 22 QUICK SHIP FIELD ADDITIONS ..............................................................................................................................28 FIGURE 23 QUICK SHIP CLASS EXTENSIONS............................................................................................................................29

Page 4 of 35

Purpose
This developers guide is intended to provide all of the information necessary to understand and customized the Oracle Mobile Supply Chain Applications (MSCA) within XXXXXs implementation architecture. The content is a compilation (hopefully in an orderly fashion) of Oracle White Papers, worldwide web blogs, independent articles, presentations on the topic, and personal experience obtained while reverse engineering previous customizations to XXXXXs MSCA implementation.

Oracle MSCA Overview

The Oracle Mobile Supply Chain Applications (MSCA) enables automated mobile user operations. This is performed using hand held radio frequency (RF) devices, PDAs, and lift truck mounted RF scanners. It is part of the Oracle Supply Chain Management solution, the integrated suite that streamlines design, planning, manufacturing and fulfillment. With MSCA, Oracle has leveraged standard Internet technologies such as Java, XML, TCP/IP and Telnet to create a device independent technology platform to support these types of applications. In general, these mobile devices will be connected to the network using the radio frequency (RF) standard of 802.11b and will communicate using TCP/IP. The figure below illustrates the communication flow using Mobile Devices.

Figure 1 Oracle MSCA Information Flow

From an application component perspective, MSCAs layered architecture includes (see below): 1. 2. 3. 4. presentation layer consisting handheld devices such as RF Barcode Scanners, laptops, etc, application access via Telnet, application logic comprised of managers and services, and data access through PL/SQL packages, SQL scripts, and EJBs.

Page 5 of 35

Figure 2 MSCA Application Components

MSCA User Interface

The MSCA application provides two user interfaces (UI): GUI and Character Mode (see below).

Figure 3 MSCA Graphical Interface

Figure 4 MSCA Character Mode Interface

The choice of a user interface type is usually driven by the capabilities of the handheld devices being used. At XXXXX, the handheld devices limit the user interface to Character Mode.

Page 6 of 35

MSCA Application Framework

MSCA Object Beans
Oracle has built MSCA/MWA framework in order to develop Mobile Applications. A mobile application, as defined by MSCA, is built using the following Java Beans: 1. A MenuItemBean is needed to attach the mobile application to the Oracle Desktop ERP. It contains no page layout information on its own, but is a necessary conduit to connect the Desktop ERP to mobile transactions. At the leaf node of the FND menu structure lays an FND Form Function that points to the MenuItemBean. The MenuItemBean in itself points to the first page in the application, which is represented by a Page Bean. 2. A PageBean represents the unit of display (i.e. a single screen on a mobile client). To define a new page, the developer must extend the PageBean, and make a new page bean class. Within this new class, the developer must use the new PageBean's constructor to instantiate FieldBeans (graphical components), and add them to the page. 3. The FieldBean is a super class for all data collection/display graphical components that the developer can use in their pages. When the mobile server loads a new page, it calls the user defined PageBean's constructor, which in turn creates all of the graphical components on that page. Examples of FieldBeans are TextFieldBean, ButtonFieldBean, LOVFieldBean, MultiListFieldBean, ListFieldBean, HeadingFieldBean, and SeparatorFieldBean. Within this framework, the MSCA Applications flow follows a consistent pattern as shown in Figure 5 below.

Figure 5 MSCA Applications Flow

Because each of these beans is written in Java, each one can consequently be extended with additional functionality. Customers should have a strong grasp of what a bean is, how the three types of mobile beans relate to each other, and finally how they connect to Oracle Applications Desktop ERP. When constructing a page, it is important to note that ERP forms connect to a MenuItemBean, which in turn links to a PageBean, which in turn contains many FieldBeans, as shown below.

Figure 6 MSCA Object Inter-Relation Model

Page 7 of 35

This model adapts nicely to customization. As indicated in Figure 7 and will be seen in the MSCA customizations examples, MSCA was designed to be customized by extending the base (or seeded) Java classes. The approach capitalizes on the characteristics of object oriented languages; in particular, Java.

MSCA Java Event-Listener Model

As implied in Figure 5 above, the MSCA/MWA Framework is based on the Java Event-Listener Model. An application's runtime logic is specified through the mobile applications event model, a set of interfaces that provide an infrastructure for handling events in an organized and modularized fashion. A listener can be added to any field, page, or application of your mobile transaction. The following is a list of listeners available: 1. FieldEntered this is called when a particular field is entered. For example, prior to entering a particular field, there may be a need to reinitialize some variables. 2. FieldExited this is called when a particular field is exited. The most common of the listeners, this is used for validation of user input. 3. PageEntered called when the page is entered, this can be used to initialize values on the page. 4. PageExited called when the page is exited, this can perform page level validation logic. 5. AppEntered called when the entire transaction is entered, this can be used to initialize transaction level variables. 6. AppExited called when the entire application is exit, an example use can be to close resources. 7. SpecialKeyPressed this is called when the user presses any special character, such as a Control character. Pressing CTRL-G to generate LPNs or Lots is one example of when this gets called.

Page 8 of 35

MSCA Bean APIs

This is the base class for all the beans used in Mobile Applications. It is derived from Java.lang.Object class. It has four main sub classes. They are:

Field Bean FlexField Bean Menu Item Bean Page Bean

Figure 7 MSCA Java Bean Hierarchies

Note: Throughout this document MWA (Mobile Web Applications) and MSCA are used interchangeably. Bean APIs public void addListener(MWAListener) public void removeListener(MWAListener) Add a listener to event listener list Remove a listener from event listener list.

Note: oracle.apps.mwa.eventmodel.MWAListener is an Interface which handles the event and is derived from java.util.EventListener. Sub classes associated with the MWA Bean Menu Item Bean MenuItemBean is the base class for all user developed menu item level beans Commonly Used Menu Item Bean APIs public java.lang.String getFirstPageName() public void setFirstPageName(java.lang.String) public java.lang.String getMenuConfirmMessage() Get name of the first page within the menu item. Set name of the first page within the menu item. get the menu confirmation message

Page 9 of 35

public void setMenuConfirmMessage(java.lang.String)

set the menu confirmation message When the user tries to go to main menu, it asks for confirmation something like, Go to Menu?" This message can be changed using this method

Page Bean The PageBean is the base class for all user developed page level beans. Commonly Used Page Bean APIs public void addFieldBean(FieldBean) public void addFieldBean(int index,FieldBean) public void removeFieldBean(FieldBean) public String getName() public Session getSession() Add the bean at end of page Add the bean at specified index Removes the field bean from the page Get fully qualified class path of the page Get the session of page bean. The return type session(oracle.apps.mwa.container.Session) is derived from the class oracle.apps.mwa.container.BaseSession Sets the session for the page. Get the Page Title Set the Page Title

public void setSession(Session) public String getPrompt() public void setPrompt(java.lang.String)

Flexfield Bean The FlexFieldBean is used to handle the Flex Field beans in Mobile Applications. This implements the following interfaces:

java.util.EventListener oracle.apps.fnd.flexj.event.FlexfieldListener java.io.Serializable

Commonly Used Flexfield APIs public oracle.apps.fnd.flexj.Flexfield getFlexfield() Returns the underlying FlexField or returns null on error protected Boolean addSegmentBean(oracle.apps.fnd.flexj.Segment add a segment to Flex field Seg) protected void removeSegmentBean(oracle.apps.fnd.flexj.Segment removes a segment Seg) Field Bean The FieldBean is the base class for all user developed field level beans. Examples of FieldBeans are TextFieldBean, ButtonFieldBean, LOVFieldBean, MultiListFieldBean, ListFieldBean, HeadingFieldBean, and SeparatorFieldBean.

Page 10 of 35

Commonly used Field Bean APIs public String getName() public void setName(java.lang.String) public String getPrompt() public void setPrompt(java.lang.String) public void setHidden(boolean) Get Unique Id for the field Set Unique Id for the field Get Label for the field. Set Label for the field. Make the field visible or not.

Field Bean Types and Commonly Used APIs

The Field Bean has multiple sub-classes each for the various types of fields that are used to display and input data in MSCA. Field Bean Sub-class Diagram

Figure 8 MSCA Field Bean Hierarchies

InputableFieldBean InputableFieldBean is the base class for all user developed field beans which has a value property to be inputable during "runtime". This class is the super class for Text field, Read only Text field, LOV field. The Commonly used APIs public void setEditable(boolean) Set whether the field is read only or not.

Page 11 of 35

public void Mandatory or not. setRequired(boolean Required) This is used to XXXer the case of the values entered by the user. For public void example, setXXXer ("U") makes the user input to Upper Case after the setXXXer(java.lang.String) user types in the value. public java.lang.String Get the value entered by the user getValue() public void Set the value in the field setValue(java.lang.String) public void Set data stream delimiter setBarcodeDelimiter(char) public int Get data stream delimiter getBarcodeDelimiter() public void Set The DFI - Data Field Indicator setDFIs(java.lang.String[] ) public java.lang.String[] Get the DFI getDFIs() public void Set the DFI required flag setDFIRequired(boolean) As indicated in the class diagram, Inputable beans have Text Field Bean and LOV field Bean as most commonly used subclasses. LOVFieldBean LOV is commonly used component in Oracle Applications. It provides the user with list of values and user has to choose one of them. The common requirements exist for constructing a LOV are: 1. Source for List of values (mostly an SQL query or an PLSQL procedure which returns the query result as REF CURSOR) 2. The various values associated with each selection (e.g., Emp Id, Emp Name, Department, Description) 3. The values displayed in the UI and values used in background (e.g., Usually EMP Name is displayed in the screen, not the EMP Id. But we get the Emp Id of selected Emp Name and use it for further processing) 4. Data types of each parameters passed to SQL Query or PLSQL procedure and their values(if we use bind parameters or IN parameters) 5. An array to get the values associated with the selected value by the user. 6. Criteria for validation check to be performed, if the user manually enters the value in the LOV field rather than selecting one by clicking "torch lite" icon, we can either validate it via an API or accept is just like that. Commonly Used APIs public java.lang.String getlovStatement() Get SQL query or PL/SQL procedure with a reference cursor output parameter. Page 12 of 35

public void setlovStatement(java.lang.String) public java.lang.String[] getSubfieldNames() public void setSubfieldNames(java.lang.String[]) public java.lang.String[] getSubfieldPrompts() public void setSubfieldPrompts(java.lang.String[]) public boolean[] getSubfieldDisplays()

Set SQL query or PL/SQL procedure with a reference cursor output parameter. get unique names of subfields of each value Set Key names of subfields. Get prompts of subfields. Set prompts of subfields. Get display properties of subfields. Set display properties of subfields. This controls which values are displayed in UI. For example, Empid is usually not displayed in UI though it is a part of the LOV)

public void setSubfieldDisplays(boolean[])

public java.lang.String[] getInputParameterTypes() Get parameter data type list. Public void setInputParameterTypes(java.lang.String[]) public java.lang.String[] getInputParameters() public void setInputParameters(java.lang.String[]) public void setSelectedValues(java.util.Vector) public java.util.Vector getSelectedValues() public void setValue(java.lang.String) public void setValidateFromLOV(boolean) Set parameter data type list. Get input parameter list. Set input parameter list. Sets the return vector. obtain a vector of String values for the chosen LOV When we setValue we also have to clear the subfield values for this bean. Set the validateFromLOV property. (Default is true)

TextFieldBean The TextFieldBean is a common means of data input to mobile applications either via scanning a value or by manually typing in to it. This can also be used to display some values by making this field as read only so that user cannot edit or enter any value into this field. Commonly Used APIs public void setIsPassword(boolean IsPassword) Indicates the field to store a password.

HeadingFieldBean The HeadingFieldBean is the base class for all user developed heading field beans. This class is the bean class for two types of headings: HEADING1 and HEADING2. Default heading type is HEADING1. Heading Field is mainly used to set Titles for each regions of a Mobile page.

Page 13 of 35

Commonly used APIs public void setHeadingType(short) public short getAlignment() public void setAlignment(short) ListFieldBean The ListfieldBean is bean which holds a fixed list of values. In OAF, it is called as poplist. Please see the image below for a List Bean. Commonly used APIs public java.lang.String getValue() Get field value. public void setValue(java.lang.String Value) Set field value. public java.lang.String getListSource() public void setListSource(java.lang.String) public void setListSource(java.util.Vector) ButtonFieldBean The ButtonFieldBean is the base class for all user developed button field beans. This class is the bean class for button. Commonly used APIs public java.lang.String getNextPageName() public void setNextPageName(java.lang.String) Get block name of the block to be navigated after button is pressed. Set block name of the block to be navigated after button is pressed. Get list of options with each option separated by comma. Set list of options with each option separated by comma. Set list of options via a vector. Set the type of headings. Value of this property is either FieldBean.HEADING1 or FieldBean.HEADING2. return the heading alignment set the heading alignment value of this property is either HeadingFieldBean.LEFT or HeadingFieldBean.CENTER

*For those who are familiar with OAF, setNextPageName is something like SetForwardURL ()

Form Functions in MSCA

When creating custom classes it is necessary to modify the form functions under the Application Developer responsibility to point to the custom Function instead of the existing one. This can be done by logging into the application developer responsibility and querying the form functions that currently exist.

Page 14 of 35

Figure 9 Updating a Form Function

Referencing Figure 9, Query up the existing functions that suit your menu option and copy the data to a new form function. The WebHTML tab must be modified to point to the new Custom function pages. Also make certain that your new form function is pointed to by some menu structure.

MSCA and the AK Repository

The AK Repository is an active data dictionary that enables you to define inquiry applications for the web, and generates many of the MSCA application's characteristics at runtime. As such, it is an integral element of the MSCA application and any customizations made to it. The data dictionary stores key information about your application, including appearance, language, security requirements, navigation, and data. MSCA/MWA Framework uses AK Repository mainly for two purposes: Defining Labels Defining DFIs

Defining Labels in the AK Repository

When we create a new custom page using MSCA/MWA Framework, we use setPrompt () to set the labels to the fields. In order to support Multi Language Support (MLS), we need to define these labels as Items in AK Repository and link into custom page.

AK Repository Data Field Identifier (DFI)

DFI functionality in Oracle Mobile Applications (MSCA and WMS) allows identification of the type of data that is embedded within a barcode when it is scanned by the mobile device. DFI usually consists of one to three characters that precede the value of the data that is encoded in the barcode. We will see each of them in detail now.

Steps to Create Labels in AK Repository

1. Define Attribute (see Figure 9) Page 15 of 35

a. Navigation: AK Developer ->Define Attributes b. Create record necessary information like Attribute ID, Attribute Name, Label, etc.

Figure 10 Creating AK Repository Attribute

2. Define a Controller Before creating a region in AK Repository, we need to have a controller to associate to the AK Region. Following is a sample controller class for an AK Region package xxx.oracle.apps.inv.utilities; import oracle.apps.fnd.common.VersionInfo; public class CustomInvResourceTable { public CustomInvResourceTable() { } public static final String RCS_ID = "$PkgHeader:$"; public static final boolean RCS_ID_RECORDED = VersionInfo.recordClassVersion ()"$PkgHeader:$", "xxx.oracle.apps.inv.utilities"); public static final String AK_CAR_SIGN = "XXWMS_CAR_SIGN"; .............. } 3. Define a AK Region: a. Navigation: AK Developer ->Define Regions b. Create a record with Region Id, Region Name etc and associate the controller class which we created in the previous step.

Page 16 of 35

Figure 11 Defining a Region in the AK Repository

4. Link AK Regions and AK Attributes (Figure 11) a. Navigation: AK Developer ->Define Regions b. Click on Region Items Button

Figure 12 Linking a Region in the AK Repository

5.

Create new record and link the attribute(s) we created previously. If you plan to use the field as DFI, you have to define the DFI attributes in "Default Varchar2 Value" Column. For example, a value like "DFI=Q REQ=N" means that when a barcode is scanned on that field using the hand held mobile device, Q will be stripped from the barcode and the remaining value will be stored in the field. In this case, The Barcode should have the value like "Q123456" (see Figure 13).

Page 17 of 35

Figure 13 Define the DFI Attributes

Using the AK Repository allows attribute and DFI values to be retrieved using the various MSCA APIs discussed earlier. Specific examples are provided in the Case Studies section of this document.

Customizing MSCA Oracle Recommended Best Practices

Before getting into details of how to customize MSCA, it is important to understand when and why customizations should be made. In 2002, Oracle published a white paper on Customizing MSCA. Much of the White Papers content is included in this User Guide. Of particular interest in the paper is oracles publication of MSCA Customizations Best Practices. The Oracle Recommended best practices are quite brief and are listed below. 1. Dont perform the customization if it can be avoided. 2. Modification of our Java classes and PL/SQL packages directly should be the last resort. Any change made to existing classes and packages may be overwritten every time Oracle releases a new patch. In Java it is always best to extend existing classes and modify functionality. In PL/SQL, it is best to create new packages. 3. Addition of logic and layout is far easier to do versus removal or logic and layout. Therefore, properly evaluate your business needs, see if a workaround exists, and if possible, add logic to obtain the desired result.

Setting Up a Development Environment

Choice of development method for customized Java and PL/SQL code is left to the application developers discretion. There is no certified or best development method for creating custom code. Therefore, it is left to the programmer. Possible methods range from a full-fledged Integrated Development Environments, such as Oracle JDeveloper and NetBeans, to simple editors such as VI or EMACS. Page 18 of 35

Download and Install the Required JDK

Since MSCA application installed with Oracles EBS 11.5.10 was compiled using the Java JDK 1.5.18, that is the JDK version that must be installed on an MSCA development workstation. This version of the JDK can be downloaded from the Oracle Technology Network (OTD) download site. The link to the download site is: http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-javase5419410.html

Select and Install a Java IDE

As previously indicated, there are multiple options for Java development tools that can be used to customize MSCA. The tool used when creating this guide was Oracles NetBeans 6.5.1. NetBeans, and in particular version 6.5.1 was chosen because it meets the following requirements: 1. Must be able to add class libraries to projects. 2. Must be compatible with Javas JDK 1.5.18. This is the JDK version used to compile the MSCA class files in Oracle EBS 11.5.10. NetBeans 6.5.1 can be downloaded from http://netbeans.org/downloads/6.5.1/index.html. NetBeans Installations Special Instructions 1. During the NetBeans installations, you will be prompted for the location of the JDK NetBeans will use. Select the JDK 1.5.18 folder from wherever you installed the JDK (this will typically be C:\Program Files\Java\JDK 1.5.18). NetBeans Post Installation Instructions 1. On you workstation create a directory named MSCALib with the following sub-directory structure: MSCALib -- oracle --- apps ---- inv ---- fnd ---- mwa 2. Establish an SCP session with XXXP and navigate to $JAVA_TOP/oracle/apps/inv and copy the entire contents (files and sub-directories) to the inv directory created in 2 above. 3. Establish an SCP session with XXXP and navigate to $JAVA_TOP/oracle/apps/mwa and copy the entire contents (files and sub-directories) to the mwa directory created in 2 above. 4. Establish an SCP session with XXXP and navigate to $JAVA_TOP/oracle/apps/fnd and copy the entire contents (files and sub-directories) to the fnd directory created in 2 above. 5. Start NetBeans and create a shell project (name the project something like MSCACustomizations. The project type should be Java Application. Page 19 of 35

6. Within the Project Navigator, select the project you created, right mouse click on it, and select properties (see below).

Figure 14 Selecting Project Properties in NetBeans

7. The Project Properties pop-up window will appear (see Figure 8). From within the pop-up window, select Libraries from the categories region (left side) and then click the Add Jar/Folder button. This will open a file selection dialog window.

Page 20 of 35

Figure 15 NetBeans Add Jar/Folder

8. From the file selection dialog window, navigate to and select the MSCALib folder and click Open. Then click OK from the Project Properties window. The class files you will likely need to reference in any new or modified Java classes will now be available.

Starting and Stopping the MWA Telnet Server

To access the MSCA application (Character Mode or GUI Mode, the MWA Telnet Server must be running. To start and stop the server, establish an SSH session with the appropriate middle tier. In the case of working in XXXD, that server is: COSUAOR20. Once the session is established, enter the following commands at the Linux command prompt to start and stop the MWA Telnet Server respectively:

Start MWA Telnet Server

$ su - applXXXd Password: [enter applXXXd password] $ cd $MWA_TOP/bin $ startMWA

Stop MWA Telnet Server

$ su - applXXXd Password: [enter applXXXd password] $ cd $MWA_TOP/bin $ stopMWA

Miscellaneous Topics on Customizing MSCA

There are a few loose thread topics that dont really fit into any other category so this section was created as a place holder. These topics are not in any particular order but they are very helpful when working to customize MSCA.

Identifying Java Class Files for a Menu Item

The first task when customizing MSCA a developer must perform is to identify the starting point from a code module (i.e., Java Class). This is necessary to identify any special menu, page, or field characteristics. There are two basic ways to identify the starting point. The first is to go into the AK

Page 21 of 35

Repository and run queries to traverse the repository elements and get the name of the Java class file. A second way is a simple query that is as effective and a little quicker. The following is a query that takes a menu label (the actual text of the label) and returns information about the menu item including the underlying Java class file.
SELECT mev.prompt "Menu Prompt" ,ffv.function_name "Function" ,ffv.user_function_name "User Function" ,ffv.form_id ,ffv.web_host_name "MWA Host" ,ffv.web_html_call "Java Class" FROM fnd_form_functions_vl ffv, fnd_menu_entries_vl mev WHERE mev.function_id = ffv.function_id AND UPPER (ffv.function_name) LIKE '%' || UPPER (NVL (:functionname, ffv.function_name)) || '%' AND UPPER (ffv.user_function_name) LIKE '%' || UPPER (NVL (:userfunctionname, ffv.user_function_name)) || '%' AND UPPER (ffv.web_html_call) LIKE '%' || UPPER (NVL (:javaclassname, ffv.web_html_call)) || '%' AND UPPER (mev.prompt) LIKE '%' || UPPER (NVL (:menuprompt, mev.prompt)) || '%' ORDER BY user_function_name; Note: The above code was written using TOAD as a development tool. The query may require modification to run with other PL/SQL development tools.

Display MSCA Character Mode Form Information

The above topic identified how to get information about menu items in MSCA. It will typically be necessary to get information about a data entry/view form. MSCA has functionality similar to Help About Form in the standard EBS applications. To access About information in any MSCA screen, enter ctrl-x. Figure 14 below illustrates the results. To return to the form, press the back key (F3).

Figure 16 Get MSCA Form Information

Display MSCA Function and Hot Keys

There are quite a few MSCA Function and Hot Keys. To get a list of all of these keys, press F1 at any point in the application and the Function Key List form will appear (see Figure 15).

Figure 17 Displaying Function/Hot Keys

Page 22 of 35

About MSCA Fields and Buttons

When viewing an MSCA Character Mode form, it is not necessarily intuitive what the presentation of the various fields represents. To understand changes you have made, it is necessary to understand the various field types and how they are displayed. Figure 16 provides a breakout of the various field layout meanings.
Field Image Field Type Enterable List of Values Characteristics A field that is enterable and is associated with a list of values (LOV) is displayed with a > to the right of the field. The list can be displayed by pressing ctrl-l. An MSCA Button looks like any other field with two exceptions. The field name (or button label) is enclosed in <>.

MSCA Button

MSCA/MWA Class Types and Locations

The MSCA class files all reside under the $JAVA_TOP directory. The class files reside in sub-directories corresponding to their purpose. It is helpful to know the directory associated with the various types of class files. The table below relates the key class types to their corresponding directories.
$JAVA_TOP Directory Location oracle/apps/mwa/beans oracle/apps/mwa/container oracle/apps/mwa/device oracle/apps/mwa/eventmodel oracle/apps/inv/lov/server oracle/apps/inv/invtxn/server oracle/apps/inv/transaction/server oracle/apps/inv/utilities/server oracle/apps/inv/mo/server oracle/apps/inv/invinq/server oracle/apps/inv/structures Note: Java Class File Types All of the base Java beans (e.g., field, LOV, button, page, etc.) Base miscellaneous handlers, listeners, state, key movements, and special page classes. Base handheld device driver and handler classes. Base event handler classes including the standard abort class. Base inventory LOVs. Base classes for performing various types of inventory transactions. Base classes for transaction managers. Base classes for inventory attributes, lookups, etc. Base classes for inventory pick and move operations and pages. Base classes for various inventory inquiries such as on-hand quantity. Base classes for inventory value sets, conversions, UOMs, etc.

Custom class files should be put in the directories that correspond to the class purpose as identified above.

MSCA Customizations Case Studies

It is important to understand the architecture details and MSCA framework in order to customize the application. However, walking through real world examples really adds meaning and understanding to the theory. The remainder of this document contains real world case studies of customizing MSCA and walks through the process and code step-by-step. The general approach to customizing MSCA includes the following: 1. Understand the functional requirement. If it is not clearly defined, work with the functional leads and/or end users to ensure you have a well formed and unambiguous functional requirement definition. 2. Create test data sets and test cases necessary to validate the customized functionality. 3. Identify the Current State from a screen flow and Java class hierarchy perspective. 4. Identify the To Be state from a screen flow and Java class hierarch perspective. 5. Document the changes that will be made. Page 23 of 35

6. Make the changes. 7. Test 8. If necessary, revise any documentation to reflect the As Built condition.

Case 1: XXXXX CR to Add Part Serialization to XXXXX Quick Pick

This is a real case study where a change request (CR) was submitted and approved to add parts serialization to a previous MSCA customization. Understand the Functional Requirement The stated functional requirement is: Need to modify MSCA XXXXX Quick Pick to confirm serial numbers from list of values associated with parts. This is the same functionality that exists with the standard "Pick Confirm" menu option. Still will save 3.5 hours daily when new serialization process is implemented, as compared to using standard MSCA Pick confirm menu option. A previous customization created the new function XXXXX Quick Pick which was built as an extension to the standard Pick Confirm functionality. This customization further modifies the previous customization and reverses one of the customizations. Specifically, the functional requirement translates to the following technical tasks (Ref Figure 18 below): 1. 2. 3. 4. Remove the Query Button Re-enable the Serial Triggered Button Change the Serial Triggered button label button to Process Line Move the Cancel Button below the Process Line button

Figure 18 Current XXXXX Quick Pick Form

This is a relatively simple customization (thus the first case study). The following provides the details on the analysis and coding that occurred to complete the CR work. Create Test Data Sets To be able to understand current state and validate the To Be state, sales orders with various line configurations were created and released to the shop floor. The sales orders and configurations included:

Page 24 of 35

2095175 thru 2095177 several lines each with nothing being serialized 2095178 thru 2095180 several lines each with one line for item 970043293 serialized being one of them 2095181 thru 2095183 single line orders for 970043293

Identify the XXXXX Quick Pick Current State The key element of this change is the removal of the Query button. The function of the Query button is similar to the Serial Triggered button except the Query button is intended to process order lines where the items are not serialized and the Serial Triggered button performs the same functionality for order lines where the items are serialized. So, the very first thing that had to be done was to determine if the Serial Trigger would process serialized and unserialized line items. As it turns out, the Serial Triggered listener, which is actually accomplished in the page listener class, will process serialized and unserialized items. If this had not been the case, the customization would have been considerably more complex. To analyze the current state, it was necessary to traverse the menus and forms and document the process flow from MSCA Form and Java Classes perspective as follows: 1. Start the MWA Telnet Server in the XXXD environment. $ su - applXXXd Password: $ cd $MWA_TOP/bin $ startMWA starting MWA Telnet Port $ MWA Telnet Server Release: 1.0.8.4 [December 12th 2002] Created server socket : listening on port 10302 Server startup is successful. $ 2. Telnet to and login to MSCA (use regular Oracle credentials). Telnet to: telnet cosuaor20 10302 Select handheld Device Select responsibility Navigate to XXXXX Quick Pick function

Login to MSCA

Page 25 of 35

3. Identify the Java class files associated with each of the functions /forms.
Function XXXXX Quick Pick XXXXX Quick Pick Form N/A N/A N/A N/A
Note:

Method to Determine Class Query (see User Guide) Ctrl-x (see Users Guide) Code Review Code Review Code Review Code Review

Result XXXXXPickWaveFunction.class XXXXXQueryPickWavePage.class MWAFieldListener.class QueryPickWavePage.class BaseQPage.class MWAPageListener.class

In this customization, only one class will be modified. However, it is necessary to review all related class files to ensure the change being made will not adversely affect and other application functionality.

4. Document the related class hierarchy (see Figure 19).

Figure 19 Class Hierarchy Diagram

Page 26 of 35

Identify the XXXXX Quick Pick To Be State

Figure 20 "To Be" State Screen Flow

Document and Build the Required Changes The code change associated with this customization was a simple modification to the previously built custom class XXXXXQueryPickWavePage and are shown below: //----- CR 15202 Approved Change Request //----- Remove all of the buttons from the page. Then recreate the Serial //----- Triggered button and the Cancel button with the cancel button below //----- Serial Triggered. Then change the prompt on the Serial Triggerd button //----- to Process Line. removeFieldBean(mQueryBtn); removeFieldBean(mCancelBtn); removeFieldBean(mSeriXXXriggeredBtn); addFieldBean(mSeriXXXriggeredBtn); addFieldBean(mCancelBtn); mSeriXXXriggeredBtn.setPrompt("Process Line"); //----------

Page 27 of 35

Case 2: Addition of extra fields on Quick Ship Page to collect FOB terms, freight terms, and document shipset
This is a case study published by Oracle on Customizing MSCA in 2002. The code modifications and additions are included as additional reference information. In this case study, Oracle followed the intent of the customization steps previously identified but not in complete detail. Understand the Functional Requirement A large computer manufacturer would like to add extra fields on the quick ship page and therefore allow their mobile shipping employees to scan this extra information at time of using the LPN Quick Ship page provided by Oracle. In order to do this, the custom code developer must extend the existing base class and add additional fields. For this case, it is best to examine the custom source code and analyze the changes made. From a high level, first the developer will create the three necessary fields that extend from INVFieldBean. Identify the Quick Ship Current State

Figure 21 Quick Ship Current State

Identify the Quick Ship To Be State

Figure 22 Quick Ship Field Additions

Page 28 of 35

Figure 23 Quick Ship Class Extensions

Code Changes and Additions The following code segments are associated with the Quick Ship customization. XXXhough the functional requirement specifies three additional LOVs will be created, it is not necessary to include the code for all three in this Developers Guide. Instead, one complete set of code for one additional LOV (DocumentShipSetLOV) is included. Create DocumentShipSetLOV Java Class Note that the package for the custom LOV will reside in the $JAVA_TOP directory structure identified in the package definition. This is where all standard and custom LOV classes reside.
package oracle.apps.inv.lov.server; import java.sql.SQLException; import java.util.Vector; import oracle.apps.fnd.common.VersionInfo; import oracle.apps.inv.utilities.InvResourceTable; import oracle.apps.inv.utilities.server.UtilFns; import oracle.apps.mwa.beans.*; import oracle.apps.mwa.container.MWALib; import oracle.apps.mwa.container.Session; import oracle.apps.mwa.eventmodel.*; // Referenced classes of package oracle.apps.inv.lov.server: // InvLOVFieldBean public class DocumentShipSetLOV extends InvLOVFieldBean implements MWAFieldListener { private String mDocumentShipSetCode; private String mDocumentShipSetMeaning; private String mDocumentShipSetDesc; private static String namePrompt = ""; private static String descPrompt = ""; public DocumentShipSetLOV() { super(); setName("INV.DocumentShipSet"); setlovStatement("XXCS_WMS_UTIL.GET_SHIP_DOCS"); String paramTypes[] = {"C", "S"};

Page 29 of 35

this.setInputParameterTypes(paramTypes); boolean[] displays = {true, true, false}; this.setSubfieldDisplays(displays); this.setRequired(false); this.setHidden(false); this.setValidateFromLOV(true); String[] subprompts = {"A", "A", "A"}; setSubfieldPrompts(subprompts); addListener(this); } public void fieldEntered(MWAEvent e) throws AbortHandlerException, InterruptedHandlerException, DefaultOnlyHandlerException { UtilFns.log("DocumentShipSet: fieldEntered"); setSubPrompts(e.getSession()); } public void fieldExited(MWAEvent e) throws AbortHandlerException, InterruptedHandlerException, DefaultOnlyHandlerException { Session ses = e.getSession(); UtilFns.log ("DocumentShipSetLOV: fieldExited" + this.getValue() + "."); if (e.getAction().equals("MWA_SUBMIT")) { try { this.setReturnValues(); } catch (Exception exception) { UtilFns.log("Exception in DocumentShipSetLOV - fieldExited" + exception); throw new AbortHandlerException("Exception in DocumentShipSetLOV - fieldExited" + exception); } } } private void setReturnValues() { Vector vector = this.getSelectedValues(); if (vector != null) { this.mDocumentShipSetCode = (String) vector.elementAt(2); this.mDocumentShipSetMeaning = (String) vector.elementAt(0); this.mDocumentShipSetDesc = (String) vector.elementAt(1); } } public void clear() { this.setValue(""); this.mDocumentShipSetCode = ""; this.mDocumentShipSetMeaning = ""; this.mDocumentShipSetDesc = ""; } public String getDocumentShipSetCode() { return this.mDocumentShipSetCode; } public String getDocumentShipSetMeaning() { return this.mDocumentShipSetMeaning; } public String getDocumentShipSetDesc() { return this.mDocumentShipSetDesc; } public void setSubPrompts(Session session) { if (namePrompt.equals("")) {

Page 30 of 35

try { namePrompt = "DocumentShipSetPrompt"; descPrompt = "DocumentShipSetDescription"; } catch (Exception sqlexception) { UtilFns.error("Error initialising the lov propmts for DocumentShipSet Lov", sqlexception); } } String[] subprompts = {namePrompt, descPrompt, "A"}; setSubfieldPrompts(subprompts); } }

Create CustomEZShipFunction Java Class As was described in the theory a custom function is class is needed which the Function Definition in EBS will point to. The following code segment creates that class. package oracle.apps.inv.wshtxn.server; import oracle.apps.mwa.beans.*; import oracle.apps.mwa.container.*; import oracle.apps.mwa.eventmodel.*; import oracle.apps.fnd.common.VersionInfo; import oracle.apps.inv.utilities.server.*; public class CustomEZShpFunction extends EZShpFunction implements MWAAppListener { public CustomEZShpFunction() { super(); setFirstPageName("oracle.apps.inv.wshtxn.server.CustomEasyShipPage"); } } Create CustomEZShipPage Java Class This class extends the base EZShipPage class to add the additional LOV. Again, note the package definition which corresponds to the $JAVA_TOP directory structure where the custom class needs to reside.
package oracle.apps.inv.wshtxn.server; import oracle.apps.mwa.beans.*; import oracle.apps.mwa.container.*; import oracle.apps.mwa.eventmodel.*; import oracle.apps.fnd.common.VersionInfo; import oracle.apps.inv.lov.server.CarrierLOV; import oracle.apps.inv.lov.server.ShipMethodLOV; import oracle.apps.inv.lov.server.DeliveryLOV; import oracle.apps.inv.lov.server.UomLOV; import oracle.apps.inv.utilities.*; import oracle.apps.inv.utilities.server.*; import oracle.apps.mwa.presentation.telnet.*; import oracle.apps.inv.lov.server.*; import java.sql.*; import java.lang.*; import java.util.Vector;

Page 31 of 35

/** * EasyShipPage.java */ public class CustomEasyShipPage extends EasyShipPage implements MWAPageListener { FreightTermsLOV mFreightTermsLOV; FOBCodeLOV mFOBCodeLOV; DocumentShipSetLOV mDocumentShipSetLOV; TextFieldBean NumberOfLPNField, additionalInfoField; public CustomEasyShipPage(Session s) { super(s); } public void pageExited(MWAEvent e) throws AbortHandlerException, InterruptedHandlerException, DefaultOnlyHandlerException { } public void pageEntered(MWAEvent e) throws AbortHandlerException, InterruptedHandlerException, DefaultOnlyHandlerException { super.pageEntered(e); //Be sure to set inputparameters, otherwise LOV will popup everytime field exited. String[] deliveryInputs = {" ", "oracle.apps.inv.wshtxn.server.CustomEasyShipPage.EasyShip.Delivery", "ORGID"}; mDeliveryLOV.setInputParameters(deliveryInputs); String[] ShipMethodInputs = {" ", "ORGID", "oracle.apps.inv.wshtxn.server.CustomEasyShipPage.EasyShip.ShipMethod"}; mShipMethodLOV.setInputParameters(ShipMethodInputs); //Add new Field NumberOfLPNField = new TextFieldBean(); NumberOfLPNField.setName("NumberOfLPN"); NumberOfLPNField.setPrompt("# LPN's"); addFieldBean(5, NumberOfLPNField); //Add LOV Field mFreightTermsLOV = new FreightTermsLOV(); mFreightTermsLOV.setName("FreightTerms"); mFreightTermsLOV.setPrompt("Freight Terms"); String[] FreightTermsInputs = {" ", "ORGID", "oracle.apps.inv.wshtxn.server.CustomEasyShipPage.FreightTerms"}; mFreightTermsLOV.setInputParameters(FreightTermsInputs); mFreightTermsLOV.setRequired(false); mFreightTermsLOV.addListener(this); addFieldBean(6, mFreightTermsLOV); //Add new Field additionalInfoField = new TextFieldBean(); additionalInfoField.setName("AdditionalInformation"); additionalInfoField.setPrompt("Add Info"); addFieldBean(7, additionalInfoField); //Add LOV Field mFOBCodeLOV = new FOBCodeLOV(); mFOBCodeLOV.setName("FOB"); mFOBCodeLOV.setPrompt("FOB"); String[] FOBCodeInputs = {" ", "ORGID", "oracle.apps.inv.wshtxn.server.CustomEasyShipPage.FOB"}; mFOBCodeLOV.setInputParameters(FOBCodeInputs); mFOBCodeLOV.setRequired(false); mFOBCodeLOV.addListener(this); addFieldBean(8, mFOBCodeLOV); //Add LOV Field mDocumentShipSetLOV = new DocumentShipSetLOV(); mDocumentShipSetLOV.setName("DocumentShipSet"); mDocumentShipSetLOV.setPrompt("Doc Set"); String[] DocumentShipSetInputs = {" ", "oracle.apps.inv.wshtxn.server.CustomEasyShipPage.DocumentShipSet"}; mDocumentShipSetLOV.setInputParameters(DocumentShipSetInputs);

Page 32 of 35

mDocumentShipSetLOV.setRequired(false); mDocumentShipSetLOV.addListener(this); addFieldBean(9, mDocumentShipSetLOV); //get the handle of the Done button field bean Vector v = getFieldBeanList(); FieldBean doneButton = (FieldBean) v.elementAt(10); FieldBean deliveryID = (FieldBean) v.elementAt(0); //create custom listener and add it to Deliveryid CustomDeliveryListener cdl = new CustomDeliveryListener(); deliveryID.addListener(cdl); //create custom listener and add it to Done button CustomRcvDoneListener crdl = new CustomRcvDoneListener(); doneButton.addListener(crdl); } }

Page 33 of 35

Index
$
$JAVA_TOP, 19, 23, 29, 31 F3

F
Back Key, 22 Field Bean, 11 Field Bean Sub-class Diagram, 11 FieldBean, 7 FieldEntered, 8 FieldExited, 8 FlexFieldBean, 10 form functions In MSCA, 14 framework. See Application Framework

A
Add Jar/Folder, 20 addFieldBean, 10 addListener, 9 addSegmentBean, 10 AK Repository, 15 AppEntered, 8 AppExited, 8 Application Framework, 7 Applications Flow, 7 attribute In AK Repository, 18

G
general approach to Customizing MSCA, 23 getAlignment, 14 getBarcodeDelimiter, 12 getDFIs, 12 getFirstPageName, 9 getFlexfield, 10 getInputParameters, 13 getInputParameterTypes, 13 getlovStatement, 12 getMenuConfirmMessage, 9 getName, 10, 11 getNextPageName ButtonFieldBean, 14 getPrompt, 10, 11 getSelectedValues, 13 getSession, 10 getSubfieldDisplays, 13 getSubfieldNames, 13 getSubfieldPrompts, 13 getValue, 12 ListFieldBean, 14 GUI, 6

B
back key F3, 22 best practices w.r.t Customizing MSCA, 18 ButtonFieldBean, 14

C
Character Mode, 6 Class Types and Locations, 23 Controller In AK Repository, 16 Create Labels In AK Repository, 15 CTRL-G, 8 ctrl-x, 22

D
Define a AK Region, 16 Defining Labels In AK Repository, 15 Development Environment setting up, 18

H
HeadingFieldBean, 13 Hot Keys, 22

E
Event-Listener Model, 8 IDE, 19

Page 34 of 35

J
JDeveloper, 18 JDK, 19

L
Link AK Regions, 17 ListfieldBean, 14 LOVFieldBean, 12

M
MenuItemBean, 7 Mobile Supply Chain Applications, 5

N
NetBeans, 18

P
PageBean, 7 PageEntered, 8 PageExited, 8

setDFIs, 12 setEditable, 11 setFirstPageName, 9 setHeadingType, 14 setHidden, 11 setInputParameters, 13 setInputParameterTypes, 13 setIsPassword, 13 setlovStatement, 13 setMenuConfirmMessage, 10 setName, 11 setNextPageName ButtonFieldBean, 14 setPrompt, 10, 11 setRequired, 12 setSelectedValues, 13 setSession, 10 setSubfieldDisplays, 13 setSubfieldNames, 13 setSubfieldPrompts, 13 setValidateFromLOV, 13 setValue, 12, 13 SpecialKeyPressed, 8 startMWA, 21 stopMWA, 21

R
REF CURSOR, 12 removeFieldBean, 10 removeListener, 9 removeSegmentBean, 10 RF, 5 TCP/IP, 5 Telnet, 5 TextFieldBean, 13

U S
UI, 6 User Interface, 6

SCP, 19 setAlignment, 14 setXXXer, 12 setBarcodeDelimiter, 12 setDFIRequired, 12

W
WebHTML, 15

Page 35 of 35