MSCA Developers Guide

Oracle Mobile Supply Chain Applications

Developers GuideVersion 1.0January 8, 2012

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_____________________________________________________________________9Bean APIs_________________________________________________________________________________9Sub classes associated with the MWA Bean______________________________________________________9

Menu Item Bean_________________________________________________________________________9Commonly Used Menu Item Bean APIs_______________________________________________________9Page Bean_____________________________________________________________________________10Commonly Used Page Bean APIs___________________________________________________________10Flexfield Bean__________________________________________________________________________10Commonly Used Flexfield APIs_____________________________________________________________10Field Bean_____________________________________________________________________________10Commonly used Field Bean APIs___________________________________________________________11

Field Bean Types and Commonly Used APIs______________________________________________11Field Bean Sub-class Diagram________________________________________________________________11

InputableFieldBean______________________________________________________________________11The Commonly used APIs_________________________________________________________________11LOVFieldBean__________________________________________________________________________12Commonly Used APIs____________________________________________________________________12TextFieldBean__________________________________________________________________________13Commonly Used APIs____________________________________________________________________13HeadingFieldBean_______________________________________________________________________13Commonly used APIs____________________________________________________________________14ListFieldBean___________________________________________________________________________14Commonly used APIs____________________________________________________________________14ButtonFieldBean________________________________________________________________________14Commonly used APIs____________________________________________________________________14

Form Functions in MSCA________________________________________________________14

MSCA and the AK Repository_____________________________________________________15

Defining Labels in the AK Repository___________________________________________________15

of 35

AK Repository Data Field Identifier (DFI)________________________________________________15

Steps to Create Labels in AK Repository_________________________________________________15

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___________________________________________________________19NetBeans Installations Special Instructions_____________________________________________________19NetBeans 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_____________________________24Understand the Functional Requirement_______________________________________________________24Create Test Data Sets______________________________________________________________________24Identify the XXXXX Quick Pick Current State____________________________________________________25Identify the XXXXX Quick Pick “To Be” State____________________________________________________27Document 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_______________________________________________________28Identify the Quick Ship Current State__________________________________________________________28Identify the Quick Ship “To Be” State__________________________________________________________28Code Changes and Additions________________________________________________________________29

Create DocumentShipSetLOV Java Class_____________________________________________________29Create CustomEZShipFunction Java Class____________________________________________________31Create CustomEZShipPage Java Class________________________________________________________31

Index________________________________________________________________________34

of 35

Table of Figures

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

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 XXXXX’s 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 XXXXX’s 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, PDA’s, 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, MSCA’s layered architecture includes (see below):

1. presentation layer consisting handheld devices such as RF Barcode Scanners, laptops, etc,2. application access via Telnet,3. application logic comprised of managers and services, and4. data access through PL/SQL packages, SQL scripts, and EJBs.

of 35

Figure 2 MSCA Application Components

MSCA User InterfaceThe 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.

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

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.

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) Add a listener to event listener listpublic void removeListener(MWAListener) 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 BeanMenuItemBean is the base class for all user developed menu item level beans

Commonly Used Menu Item Bean APIs

public java.lang.String getFirstPageName() Get name of the first page within the menu item.public void setFirstPageName(java.lang.String) Set name of the first page within the menu item.public java.lang.String getMenuConfirmMessage() get the menu confirmation message

public void setMenuConfirmMessage(java.lang.String) set the menu confirmation message

of 35

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) Add the bean at end of pagepublic void addFieldBean(int index,FieldBean) Add the bean at specified indexpublic void removeFieldBean(FieldBean) Removes the field bean from the pagepublic String getName() Get fully qualified class path of the pagepublic Session getSession() 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

public void setSession(Session) Sets the session for the page.

public String getPrompt() Get the Page Title

public void setPrompt(java.lang.String) Set the Page Title

Flexfield BeanThe 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 Seg)

add a segment to Flex field

protected void removeSegmentBean(oracle.apps.fnd.flexj.Segment Seg)

removes a segment

Field BeanThe FieldBean is the base class for all user developed field level beans. Examples of FieldBeans are TextFieldBean, ButtonFieldBean, LOVFieldBean, MultiListFieldBean, ListFieldBean, HeadingFieldBean, and SeparatorFieldBean.

Commonly used Field Bean APIs

public String getName() Get Unique Id for the field

of 35

public void setName(java.lang.String) Set Unique Id for the field

public String getPrompt() Get Label for the field.

public void setPrompt(java.lang.String) Set Label for the field.

public void setHidden(boolean) Make the field visible or not.

Field Bean Types and Commonly Used APIsThe 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.

public void setRequired(boolean Required)

Mandatory or not.

public void This is used to XXXer the case of the values entered by the user. For

of 35

setXXXer(java.lang.String) example, setXXXer ("U") makes the user input to Upper Case after the user types in the value.

public java.lang.String getValue()

Get the value entered by the user

public void setValue(java.lang.String)

Set the value in the field

public void setBarcodeDelimiter(char)

Set data stream delimiter

public int getBarcodeDelimiter()

Get data stream delimiter

public void setDFIs(java.lang.String[] )

Set The DFI - Data Field Indicator

public java.lang.String[] getDFIs()

Get the DFI

public void setDFIRequired(boolean)

Set the DFI required flag

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.

public void setlovStatement(java.lang.String) Set SQL query or PL/SQL procedure with a reference cursor output parameter.

of 35

public java.lang.String[] getSubfieldNames() get unique names of subfields of each value

public void setSubfieldNames(java.lang.String[]) Set Key names of subfields.

public java.lang.String[] getSubfieldPrompts() Get prompts of subfields.

public void setSubfieldPrompts(java.lang.String[]) Set prompts of subfields.

public boolean[] getSubfieldDisplays() Get display properties of subfields.

public void setSubfieldDisplays(boolean[])

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 java.lang.String[] getInputParameterTypes() Get parameter data type list.

Public void setInputParameterTypes(java.lang.String[])

Set parameter data type list.

public java.lang.String[] getInputParameters() Get input parameter list.

public void setInputParameters(java.lang.String[]) Set input parameter list.

public void setSelectedValues(java.util.Vector) Sets the return vector.

public java.util.Vector getSelectedValues() obtain a vector of String values for the chosen LOV

public void setValue(java.lang.String) When we setValue we also have to clear the subfield values for this bean.

public void setValidateFromLOV(boolean) 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.

Commonly used APIs

public void setHeadingType(short) Set the type of headings.

of 35

Value of this property is either FieldBean.HEADING1 or FieldBean.HEADING2.

public short getAlignment() return the heading alignment

public void setAlignment(short)set the heading alignment value of this property is either HeadingFieldBean.LEFT or HeadingFieldBean.CENTER

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() Get list of options with each option separated by comma.

public void setListSource(java.lang.String) Set list of options with each option separated by comma.

public void setListSource(java.util.Vector) Set list of options via a 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() Get block name of the block to be navigated after button is pressed.

public void setNextPageName(java.lang.String)

Set block name of the block to be navigated after button is pressed.

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

Form Functions in MSCAWhen 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.

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 Repository1. Define Attribute (see Figure 9)

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.

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).

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 PracticesBefore 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 Paper’s 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. Don’t 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 EnvironmentChoice of development method for customized Java and PL/SQL code is left to the application developer’s 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.

of 35

Download and Install the Required JDKSince MSCA application installed with Oracle’s 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-javase5-419410.html

Select and Install a Java IDEAs 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 Oracle’s 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 Java’s 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.

of 35

http://netbeans.org/downloads/6.5.1/index.html



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.

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 ServerTo 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 - applXXXdPassword: [enter applXXXd password]$ cd $MWA_TOP/bin$ startMWA

Stop MWA Telnet Server$ su - applXXXdPassword: [enter applXXXd password]$ cd $MWA_TOP/bin$ stopMWA

Miscellaneous Topics on Customizing MSCAThere are a few “loose thread” topics that don’t 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 ItemThe 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

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 InformationThe 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

of 35

Ctrl-x

F1

About MSCA Fields and ButtonsWhen 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 Characteristics

Enterable List of Values

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.

MSCA Button

An MSCA Button looks like any other field with two exceptions. The field name (or button label) is enclosed in ‘<>’.

MSCA/MWA Class Types and LocationsThe 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 Java Class File Typesoracle/apps/mwa/beans All of the base Java beans (e.g., field, LOV, button, page, etc.)oracle/apps/mwa/container Base miscellaneous handlers, listeners, state, key movements,

and special page classes.oracle/apps/mwa/device Base handheld device driver and handler classes.oracle/apps/mwa/eventmodel Base event handler classes including the standard abort class.oracle/apps/inv/lov/server Base inventory LOVs.oracle/apps/inv/invtxn/server Base classes for performing various types of inventory

transactions.oracle/apps/inv/transaction/server Base classes for transaction managers.oracle/apps/inv/utilities/server Base classes for inventory attributes, lookups, etc.oracle/apps/inv/mo/server Base classes for inventory pick and move operations and

pages.oracle/apps/inv/invinq/server Base classes for various inventory inquiries such as on-hand

quantity.oracle/apps/inv/structures Base classes for inventory value sets, conversions, UOMs, etc.

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

MSCA Customizations Case StudiesIt 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.

of 35

6. Make the changes.7. Test8. If necessary, revise any documentation to reflect the “As Built” condition.

Case 1: XXXXX CR to Add Part Serialization to XXXXX Quick PickThis 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 RequirementThe 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. Remove the Query Button2. Re-enable the Serial Triggered Button3. Change the Serial Triggered button label button to Process Line4. 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 SetsTo 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:

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 StateThe 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 - applXXXdPassword:$ cd $MWA_TOP/bin$ startMWAstarting MWA Telnet Port$ MWA Telnet Server Release: 1.0.8.4 [December 12th 2002]Created server socket : listening on port 10302Server startup is successful.

$

2. Telnet to and login to MSCA (use regular Oracle credentials).

- Telnet to: telnet cosuaor20 10302- Select “handheld Device”

- Login to MSCA

- Select responsibility- Navigate to XXXXX Quick Pick

function

of 35

3. Identify the Java class files associated with each of the functions /forms.Function Method to Determine Class ResultXXXXX Quick Pick Query (see User Guide) XXXXXPickWaveFunction.classXXXXX Quick Pick Form Ctrl-x (see Users Guide) XXXXXQueryPickWavePage.classN/A Code Review MWAFieldListener.classN/A Code Review QueryPickWavePage.classN/A Code Review BaseQPage.classN/A Code Review MWAPageListener.class

Note: 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

of 35

AltecQueryPickWavePage

QueryPickWavePage

Extends

MWAFieldListenerImplements

BaseQPage

Extends

MWAPageListenerImplements

Identify the XXXXX Quick Pick “To Be” State

Figure 20 "To Be" State Screen Flow

Document and Build the Required ChangesThe 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"); //----------

of 35

AltecQueryPickWavePage.class

= Remove

1

1 = Change Prompt to “Process Line” and Move Above Cancel

SerialDetailPage.class

AltecDetailPage.class

SerialControlled

NotSerial

Controlled

Case 2: Addition of extra fields on Quick Ship Page to collect FOB terms, freight terms, and document shipsetThis 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

of 35

EZShipFunction.class

EZShipPage.classMenu

Figure 23 Quick Ship Class Extensions

Code Changes and AdditionsThe 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 ClassNote 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:// InvLOVFieldBeanpublic 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"};

of 35

EZShipFunctionImplements

MWAAppListener

EZShipPageImplements

MWAPageListenerMenu

CustomEZShipFunction

ImplementsMWAAppListener

CustomEZShipPage

ImplementsMWAPageListenerCustomRcvDoneLi

stenerImplements

MWAFieldListener

Extends Extends

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("")) {

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 ClassAs 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 ClassThis 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;

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);

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); }}

of 35

Index

$

$JAVA_TOP, 19, 23, 29, 31

A

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

In AK Repository, 18

B

back keyF3, 22

best practicesw.r.t Customizing MSCA, 18

ButtonFieldBean, 14

C

Character Mode, 6Class Types and Locations, 23Controller

In AK Repository, 16Create Labels

In AK Repository, 15CTRL-G, 8ctrl-x, 22

D

Define a AK Region, 16Defining Labels

In AK Repository, 15Development Environment

setting up, 18

E

Event-Listener Model, 8

F

F3Back Key, 22

Field Bean, 11Field Bean Sub-class Diagram, 11FieldBean, 7FieldEntered, 8FieldExited, 8FlexFieldBean, 10form functions

In MSCA, 14framework. See Application Framework

G

general approachto Customizing MSCA, 23

getAlignment, 14getBarcodeDelimiter, 12getDFIs, 12getFirstPageName, 9getFlexfield, 10getInputParameters, 13getInputParameterTypes, 13getlovStatement, 12getMenuConfirmMessage, 9getName, 10, 11getNextPageName

ButtonFieldBean, 14getPrompt, 10, 11getSelectedValues, 13getSession, 10getSubfieldDisplays, 13getSubfieldNames, 13getSubfieldPrompts, 13getValue, 12

ListFieldBean, 14GUI, 6

H

HeadingFieldBean, 13Hot Keys, 22

I

IDE, 19

of 35

J

JDeveloper, 18JDK, 19

L

Link AK Regions, 17ListfieldBean, 14LOVFieldBean, 12

M

MenuItemBean, 7Mobile Supply Chain Applications, 5

N

NetBeans, 18

P

PageBean, 7PageEntered, 8PageExited, 8

R

REF CURSOR, 12removeFieldBean, 10removeListener, 9removeSegmentBean, 10RF, 5

S

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

setDFIs, 12setEditable, 11setFirstPageName, 9setHeadingType, 14setHidden, 11setInputParameters, 13setInputParameterTypes, 13setIsPassword, 13setlovStatement, 13setMenuConfirmMessage, 10setName, 11setNextPageName

ButtonFieldBean, 14setPrompt, 10, 11setRequired, 12setSelectedValues, 13setSession, 10setSubfieldDisplays, 13setSubfieldNames, 13setSubfieldPrompts, 13setValidateFromLOV, 13setValue, 12, 13SpecialKeyPressed, 8startMWA, 21stopMWA, 21

T

TCP/IP, 5Telnet, 5TextFieldBean, 13

U

UI, 6User Interface, 6

W

WebHTML, 15

of 35

MSCA Developers Guide

Documents

Transcript of MSCA Developers Guide