Professional Documents
Culture Documents
Oracle MSCA Developers Guide
Oracle MSCA Developers Guide
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
Case 2: Addition of extra fields on Quick Ship Page to collect FOB terms, freight terms, and
document shipset _________________________________________________________________ 28
Understand the Functional Requirement ______________________________________________________
Identify the Quick Ship Current State _________________________________________________________
Identify the Quick Ship To Be State _________________________________________________________
Code Changes and Additions ________________________________________________________________
Create DocumentShipSetLOV Java Class _____________________________________________________
Create CustomEZShipFunction Java Class ____________________________________________________
Create CustomEZShipPage Java Class _______________________________________________________
28
28
28
29
29
31
31
Index ______________________________________________________________________ 34
Table of Figures
FIGURE 1 ORACLE MSCA INFORMATION FLOW........................................................................................................................5
Page 3 of 35
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.
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
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
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.
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.
Page 8 of 35
Field Bean
FlexField Bean
Menu Item Bean
Page Bean
Note: Throughout this document MWA (Mobile Web Applications) and MSCA are used
interchangeably.
Bean APIs
public void addListener(MWAListener)
public void removeListener(MWAListener)
Page 9 of 35
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()
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
Page 10 of 35
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)
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()
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)
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
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()
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)
*For those who are familiar with OAF, setNextPageName is something like SetForwardURL ()
Page 14 of 35
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.
Defining Labels
Defining DFIs
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
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
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.
6. Within the Project Navigator, select the project you created, right mouse click on it, and select
properties (see below).
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
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.
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.
Page 22 of 35
Field Type
Enterable List
of Values
MSCA Button
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
<>.
Custom class files should be put in the directories that correspond to the class purpose as identified above.
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
Login to MSCA
Select responsibility
Navigate to XXXXX Quick Pick
function
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:
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.
Page 26 of 35
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
Page 28 of 35
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);
}
}
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
F
F3
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
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
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
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
H
HeadingFieldBean, 13
Hot Keys, 22
E
Event-Listener Model, 8
I
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
SCP, 19
setAlignment, 14
setXXXer, 12
setBarcodeDelimiter, 12
setDFIRequired, 12
UI, 6
User Interface, 6
W
WebHTML, 15
Page 35 of 35