Вы находитесь на странице: 1из 186

SMART

 MOBILE SUITE
 
FOR SAP SYSTEMS

Configuration Level 1 Tutorial
4th Edition
1721 Moon Lake Boulevard | Suite 300
Hoffman Estates, IL 60169
800.567.9256 toll free - North America
info@syclo.com | www.syclo.com

Syclo International Limited | Europe, Middle East & Africa


Fetcham Park House, Lower Road, Fetcham,
Leatherhead, Surrey, KT22 9HD, United Kingdom
+44 (0) 1372 371031 phone | +44 (0) 1372 371032 fax
This document is presented as is and as such no warranty, express or implied, is made by Syclo as to the accuracy and completeness of this docu-
ment or related material, nor shall the fact of distribution of this document and the related material constitute any such warranty, and no such
responsibility is assumed by Syclo in connection therewith. Information contained within is subject to change without notice.
This work is protected by the copyright laws of the United States of America and is proprietary to Syclo, LLC. Disclosure, copying or reproduc-
tion, merger, translation, modification, enhancement or use by anyone other than authorized employees or licensees of Syclo, without prior express
consent of Syclo, is strictly prohibited.
Copyright © 2010 Syclo, LLC. All Rights Reserved.
™ ™
Syclo and Agentry are trademarks of Syclo, LLC.

SAP®, SAP® CRM® and SAP® ERP® are registered trademarks of SAP AG in Germany and several other countries.

All other products and logos are the trademarks or registered trademarks of their respective holders.
Contents
Introduction to the SMART Mobile Suite for SAP® Systems 7

SMART Mobile Suite Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8


Agentry Components for SMART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
SMART Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Lesson 1: The SMART Server in a Production Environment. . . . . . . . . . . . . . . . . . 11
Lesson 2: The SMART Server in a Development Environment. . . . . . . . . . . . . . . . 12
The Agentry Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Lesson 3: Eclipse Plug-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Lesson 4: Agentry Application Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Lesson 5: Application Project Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
The SMART Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
The Agentry Test Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
SMART Mobile Suite System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Java Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
About this Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Installation and Initial Configuration 25

Installation and Configuration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26


Lesson 6: Installing and Configuring the SMART Server. . . . . . . . . . . . . . . . . . . . . 28
Exercise A: Installing the SMART Server For Windows . . . . . . . . . . . . . . . . . . . 30
Lesson 7: Installing the Agentry Test Environment . . . . . . . . . . . . . . . . . . . . . . . . . 38
Exercise A: Installing the Agentry Test Environment . . . . . . . . . . . . . . . . . . . . . 39
Lesson 8: Installing and Configuring the Agentry Editor . . . . . . . . . . . . . . . . . . . . . 43
Exercise A: Installing the Agentry Editor Plug-In and Eclipse Platform . . . . . . . 45
Exercise B: Round Trip between SAP and the SMART Client . . . . . . . . . . . . . . 51

Mobile Integration Components 55

Integration Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56


Exercise A: Change How Data is Displayed Using Filter Options . . . . . . . . . . . 58
Configuration Set for Integration Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Creating Integration Components for Complex Table Synchronization . . . . . . . . . . 61
Creating Integration Components for Data Table Synchronization . . . . . . . . . . . . . 63
Creating Integration Components for Transaction Synchronization . . . . . . . . . . . . 65

4
Contents
Working With The Mobile Integration Settings 67

Business Logic Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68


Lesson 9: Business Logic Layer - Complex Tables. . . . . . . . . . . . . . . . . . . . . . . . . 69
Exercise A: Complex Table Entry Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Exercise B: Create a Mobile Data Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Exercise C: Create a BAPI Wrapper Assignment . . . . . . . . . . . . . . . . . . . . . . . 82
Exercise D: Create a Complex Table and Java Logic in Agentry . . . . . . . . . . . 86
Exercise E: Create Entry List Table Fields and Indexes . . . . . . . . . . . . . . . . . . 89
Exercise F: Assign a BAPI Wrapper to a Complex Table in Agentry . . . . . . . . . 92
Exercise G: Assign a POJO to a Complex Table. . . . . . . . . . . . . . . . . . . . . . . . 94

Administration Component: Change Detection Layer 95

Change Detection Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96


Lesson 10: Exchange Object Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . 97
Exercise A: Navigating the Exchange Object Settings. . . . . . . . . . . . . . . . . . . . 99
Lesson 11: EFI Assignment Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . 105
Exercise A: Navigating the EFI Assignment Settings. . . . . . . . . . . . . . . . . . . . 106

Working With the Change Detection Layer 111

Change Detection and the Exchange Data Model . . . . . . . . . . . . . . . . . . . . . . . . 112


Lesson 12: Round Trip Using the Exchange Process . . . . . . . . . . . . . . . . . . . . . . 114
Lesson 13: Detecting Additional Object Changes: Exchange Object Fields . . . . . 115
Exercise A: Create an Exchange Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Exercise B: Create a Trigger Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Exercise C: Assign the Exchange Object to the Mobile Data Object . . . . . . . . 124

Business Logic Layer - Fetches 127

Business Logic Layer - Fetches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128


Exercise A: Create the Reservation Class and BAPI in SAP. . . . . . . . . . . . . . 129
Exercise B: Configure the MDOs and BAPI Wrappers . . . . . . . . . . . . . . . . . . 131
Exercise C: Create the Reservation Java Logic in Eclipse . . . . . . . . . . . . . . . 133
Exercise D: Create the Reservation Object in Agentry . . . . . . . . . . . . . . . . . . 138

Business Logic Layer - Transactions 147

Business Logic Layer - Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148


Exercise A: Configure the MDOs and BAPI Wrappers . . . . . . . . . . . . . . . . . . 149
Exercise B: Create the Goods Java Logic in Eclipse . . . . . . . . . . . . . . . . . . . . 150
Exercise C: Create the Goods Issue Object in Agentry . . . . . . . . . . . . . . . . . . 151

5
Exercise D: Create Screensets and Screens for Reservations . . . . . . . . . . . . 157
Exercise E: Create Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Testing, Debugging, and Troubleshooting Techniques 169

Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Project Standards and General Staging Techniques 173

Project Staging and Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Importing and Exporting Java Source Code 177

Importing the Java Source Files for the Application to the Eclipse Platform . . . . . 178
Exercise A: Importing the Java Source Files for the Application to the Eclipse Platform
179

6
1 Introduction to the SMART Mobile Suite for SAP® Systems
8 Introduction to the SMART Mobile Suite for SAP® Systems

SMART Mobile Suite Overview


SMART Mobile Suite is a set of pre-built mobile applications that are used for:
 Increasing productivity by eliminating paperwork and reducing foot traffic
 Improving decision-making by giving mobile workers easy data access at the point of
performance
 Gaining the maximum value from enterprise applications, such as SAP, with timely
and accurate data collection
 Lowering operating costs by reducing overhead and getting more from existing
resources
With mobile solutions from Syclo, organizations can create a seamless flow of information
between business units that improve efficiency and move operations closer to real-time.
By deploying multiple products, organizations ensure that real-time data updates to one
application can drive another action or transaction in a parallel business unit. Using SMART
Mobile Suite, organizations eliminate delays traditionally caused by paperwork backlogs and
communication flaws, thereby streamlining workflow and delivering benefits to multiple
business units.
The Agentry Mobile Platform makes it simple and cost-effective to deploy and manage
multiple SMART Mobile Suite products. Built on Syclo's Agentry platform, all SMART Mobile
Suite products are 100% configurable and centrally administered through application updates
that automatically flow to users' devices while deployed in the field. Agentry provides the
flexibility, scalability and features that ensure SMART Mobile Suite mobile applications are
future-proof and remain on the cutting-edge of mobile technology.
In addition to the ability to deploy on a wide range of mobile devices and utilize an array of
communications methods, Agentry provides out-of-the-box integration with more than 25
popular mobile peripherals, including bar codes, RFID, GPS, and GIS, as well as support for
11 international languages.
Businesses can lower the total cost of ownership for their collective mobile projects by
deploying on a single mobile platform. The addition of new SMART Mobile Suite products
does not add an additional burden to your IT team because they are pre-packaged proven
applications built on the same underlying technology. Solutions can be integrated to feed
multiple back end systems, improving communications across the enterprise.
Introduction to the SMART Mobile Suite for SAP® Systems 9

Agentry Components for SMART


SMART is developed and deployed on Syclo's Agentry Mobile Platform. The Agentry Mobile
Platform has three main software components:
 The Agentry Server
 The Agentry Editor
 The Agentry Client
The SMART Server and SMART Client are software components built on the Agentry Server
and Agentry Client.
The Agentry Mobile Platform consists of the Agentry Development Environment and Agentry
Production Environment. The Agentry Editor is the primary development tool used to create
and customize the SMART application.
The diagram below displays how the components of SMART interact with each other and the
SAP® System.
10 Introduction to the SMART Mobile Suite for SAP® Systems

SMART Server
The SMART Server is a communication hub within the SMART application. The Server
provides two-way communication between the SMART application and the SAP® database
during synchronization. The information exchanged between these two systems is referred
to as the “production data” of the SMART application. The SMART Server does not store any
information internally, but rather manages all communications, synchronization, error
handling, personalization and transactional controls needed for the mobile application to
function.
The SMART Server also serves “application data,” or the data that provides the business
logic and behavior to the SMART Clients. When changes are made to the application in the
Agentry Editor, they are published to the SMART Server. The Server transmits the changes
to the SMART Clients during their next synchronization. No special actions are required on
the part of the users when new application data is received. For instance, the users do not
need to restart the Client.
In the SMART Production Environment, multiple versions of the application are stored and
supported by the SMART Production Server at one time. This allows for older versions of the
application running on the Clients to still communicate with the server and receive the
updates.
The SMART Server can be configured as a Development or Production Server. The
functionality and behavior of each is similar in either configuration. However, the
Development Server is intended for development work and the Production Server is intended
for real-world production environments.
Introduction to the SMART Mobile Suite for SAP® Systems 11

Lesson 1: The SMART Server in a Production Environment


The SMART Server in a production environment, called the SMART Production Server,
exhibits the behaviors beneficial to large numbers of concurrent users synchronizing
production data. It also is capable of maintaining multiple versions of the application to allow
for incremental updates of application modifications to the Clients.
To improve performance and minimize storage requirements, an SMART Production Server
does not generate most of the available log files by default. The run-time information it does
log covers startup and shut down events, Client-Server messaging, and certain Server
events. All other log files are disabled by default. Enable these log files when needed, but do
not allow them to remain enabled longer than is necessary.
The application data stored on the Server is managed to allow for an incremental upgrade of
the application to the Clients when modifications are published from the Agentry Editor.
Depending on information provided during the publish, the Server may process data changes
received from a Client using the previous version of the application before sending the new
version to that Client. It is also possible in a production publish to specify that changes
published to the Server are not updated to the Clients until after a specified date and time.
Never use an instance of the SMART Production Server for development work. This is
primarily due to the number of times a publish is performed in a typical development life cycle.
A Production Server keeps all versions of the application published to it and reads in all
versions during startup. During development work, the number of versions could quickly
number in the dozens, which would in turn result in a long delay in starting a Production
Server and significantly impact overall performance.
12 Introduction to the SMART Mobile Suite for SAP® Systems

Lesson 2: The SMART Server in a Development Environment


The SMART Server in a development environment, called the SMART Development Server,
is intended for use during the development, configuration, and/or customization process.
Frequent changes are made to the application and published to the Server for testing. The
SMART Development Server is not intended for a large number of users. The behaviors
exhibited by the Server in a development environment benefit developers or implementors
only.
The SMART Development Server stores only one version of the application, with each new
published version overwriting the previous version. This is for the sake of performance, as the
Server reads in all versions of the application at startup. Since in a development environment
dozens of changes may be made and published within a short time period, if different
versions were kept, the total number stored on the Server could quickly become large and
result in much longer startup times for the Server.
These definitions are maintained as separate files. This structure allows for direct
modification of any script or source file containing SQL, Java, or batch file commands. The
previously published version of the application is not kept, but instead is overwritten by the
new version. The resulting effect of this behavior is that Client-Server communications always
behave according to the latest version of the application. There is no version information
stored with a development publish.
Never use an instance of the SMART Development Server in a live production
implementation. The configuration of a Development Server is such that performance is
sacrificed for development-level information and behaviors. For this reason, the SMART
Development Server is only implemented in a development environment for development or
test users and back end systems.
Introduction to the SMART Mobile Suite for SAP® Systems 13

The Agentry Editor


The Agentry Editor is the primary development tool used to create, test, and deploy a mobile
application. It is also the tool used to configure or extend an application for a specific
deployment. The Editor is a 4th-generation language tool (4GL), providing point-and-click
development. Much of the lower-level code writing is removed from the development process
through the use of the Agentry Editor.
The Agentry Editor is a component of the development environment. During development,
the application is published from the Editor to an instance of the SMART Development Server
for development and unit testing. Once an application is finalized and ready for deployment,
it is published from the Editor to the SMART Production Server. From here, it is deployed to
the Clients during synchronization.

Eclipse Plug-In
The Agentry Editor is provided as a plug-in tool to the Eclipse platform. This architecture is
beneficial to the developer or implementor in that it provides an industry standard interface,
and allows the Editor to leverage many of the powerful tools available within Eclipse. During
installation, the Eclipse platform can be installed with the Editor, or the Editor plug-in can be
installed to an existing Eclipse implementation.
Eclipse provides built-in testing, debugging, and emulation capabilities. It also includes
search functionality, import/export features, and the ability to visually modify screens.

Agentry Application Projects


The pieces of an Agentry application are called definitions. A developer creates or modifies
these definitions to affect the behavior of the application. The definitions for applications are
organized into projects, which are created and maintained within the Agentry Editor.
The Editor itself presents the definitions according to the application hierarchy within Agentry.
The hierarchy is the logical structure of an application and dictates how the different
definitions relate to one another.
An Agentry application project is stored and managed within the Eclipse workspace. You can
import an existing application project from one workspace to another, creating a new Agentry
application project within that workspace. Other components of the overall application
solution, such as Java projects and related source code, are also stored in this same
workspace within Eclipse. This supports a more seamless overall structure to the mobile
application and its related components.

Application Project Management


In addition to development work, the Agentry Editor provides tools to support management of
the application project. These include the ability to export portions of an application from one
project and to import those same pieces into another project. This can be useful when
modularizing functionality for reuse in separate applications, and also when multiple
developers are working on the same application. Part of this import and export functionality
14 Introduction to the SMART Mobile Suite for SAP® Systems

is the ability to visually compare two projects and to export the differences between two
different versions of the same application.
Another significant functionality set for application and project management is Team
Configuration. This functionality set was added to the system with the 5.2 release of Agentry.
This new feature provides support for a shared repository of development work accessible to
all developers on a team for the same application. The repository supports multiple revisions,
and checkouts, commits, and updates to and from this common source. For full details on this
functionality, see the Agentry Development Guide for Agentry 5.2.
Introduction to the SMART Mobile Suite for SAP® Systems 15

Lesson 3: Eclipse Plug-In


The Agentry Editor is provided as a plug-in tool to the Eclipse platform. This architecture is
beneficial to the developer or implementor in that it provides an industry standard interface,
and also allows the Editor to leverage many of the powerful tools available within Eclipse.
During installation, the Eclipse platform can be installed with the Editor, or the Editor plug-in
can be installed to an existing Eclipse implementation.
Eclipse provides built-in testing, debugging, and emulation capabilities. It also includes
search functionality, import/export features, and the ability to visually modify screens.
16 Introduction to the SMART Mobile Suite for SAP® Systems

Lesson 4: Agentry Application Projects


The pieces of an Agentry application are called definitions. A developer creates or modifies
these definitions to affect the behavior of the application. The definitions for applications are
organized into projects, which are created and maintained within the Agentry Editor.
The Editor itself presents these definitions according the application hierarchy within Agentry.
This hierarchy is the logical structure of an application and dictates how the different
definitions relate to one another.
An Agentry application project is stored and managed within the Eclipse workspace. An
existing application project can be imported from one workspace to another, creating a new
Agentry application project within that workspace. Other components of the overall
application solution, such as Java projects and related source code are also stored in this
same workspace within Eclipse. This then supports a more seamless overall structure to the
mobile application and its related components.
Introduction to the SMART Mobile Suite for SAP® Systems 17

Lesson 5: Application Project Management


In addition to development work, the Agentry Editor provides tools to support management of
the application project, including the ability to export portions of an application from one
project and to import those same pieces into another project. This can be useful when
modularizing functionality for reuse in separate applications, and also when multiple
developers are working on the same application. Part of the import and export functionality is
the ability to visually compare two projects and to export the differences between two different
versions of the same application.
18 Introduction to the SMART Mobile Suite for SAP® Systems

The SMART Clients


The SMART Client is the SMART component installed to the client devices provided to the
end users. This component of SMART is the one that presents the interface of the application.
There are numerous builds of the Client, each intended for a different type of client device.
These include different versions of the mobile Windows operating systems, in combination
with different device processors, and also in combination with certain device manufacturers.
The SMART Client provides certain built-in functionality that is exhibited regardless of the
application it is running, including screens to provide a common user interface. For devices
with added hardware capabilities, such as barcode scanners or GPS units, additional
resources are installed with the SMART Client executable to support their functional
requirements.
An additional set of Client builds are those that provide client-side data encryption. This
functionality encrypts all data, both production and application, stored on the client device by
the SMART Client. This is an optional build of the Client that may or may not be installed.
The SMART Client is capable of providing the user with the full functionality set available
within the application whether it is connected to the SMART Server or not. This ability to run
and function in an off-line state means users will experience little or no work interruptions due
to unavailable or spotty network access. The Client is capable of storing large amounts of
production data, within the limitations of the client device’s storage capacity, for use within the
application.
Introduction to the SMART Mobile Suite for SAP® Systems 19

The Agentry Test Environment


The Agentry Test Environment, or ATE, is a software component provided for developers and
testers. It is used in both the development and production environments of SMART. The ATE
is used for development and unit testing and includes the standard SMART Client wrapped
within the ATE itself.

Mimicking Multiple Platforms


The ATE provides the developer or tester with the ability to mimic different supported client
device platforms. This includes the display of the screens defined for a specific platform within
the application project. The current platform is changed within the ATE and can be done at
any time. The Client will be reset and a transmit is performed to retrieve the application as it
appears on the new target platform.

Debugging Tools
The ATE provides debugging and data inspection tools. These tools can be very useful to a
developer, as they expose the data stored on the Client as well as the complex business logic
contained in the definitions at run time.
During transmit, the transmit dialog within the ATE’s Client displays additional information in
relation to any errors or issues that are not normally displayed on a standard Client. This
information includes error messaging returned by SAP® system. This can include error
messages related to processing SQL statements, messages generated by the Java Runtime
Environment, and other similar messaging.
For client-side functionality, the ATE includes a robust set of debugging tools. These tools
allow for the setting of break points within transaction processing, rule debugging and
logging, data inspectors for objects, data tables, complex tables, and transactions. For testing
of scanner platforms, the ATE includes the ability to pass values to the client through the
scanner API, mimicking scanner functionality and allowing for the evaluation and testing of
scanner behaviors and features. Similar behavior exists for GPS unit functionality. Location
values can be passed to the client through the ATE, as if provided by a client device’s GPS
unit.
Other functionality related to testing includes the ability to fail network communications for a
given transmit configuration. This is used to test defined transmit configuration failover
behavior.
The ATE also has uses in the Production Environment. Specifically, it can be used to
diagnose an issue encountered in a deployed application. In addition to the inspection and
debugging tools, the ATE can force the SMART Production Server to produce the logging
information that is otherwise disabled. This information is only generated for a single
transmission from the ATE, meaning the log files are not enabled for all users. This prevents
unneeded log file messages from being generated and significantly reduces any impact on
the Server’s performance.
20 Introduction to the SMART Mobile Suite for SAP® Systems

Test Script Recording and Playback


Another powerful feature of the ATE is the ability to record and play back test scripts. Using
the test script functionality, the operations performed by a test user can be recorded in the
ATE to an XML file that is an Agentry Test Script. You can then replay this script back
repeatedly to perform the exact same test operations multiple times. The test script language
includes methodology for querying database values, as well as providing test data to be
passed into the test client.
Recorded in the script are all button clicks, list selections, entered values, and any other
actions performed by a user with the Client. The ATE can then play back any Agentry Test
Script that has been created.
Introduction to the SMART Mobile Suite for SAP® Systems 21

SMART Mobile Suite System Components


The Administration component is an integration framework that provides an efficient way to
build mobile solutions for SAP using Syclo's Agentry mobile platform. The framework consists
of several components shown in the diagram below.
Figure 1: SMART Mobile Suite System Components
6$3(53

6$32/73'DWDEDVH

6$36WDQGDUG%$3,V&ODVVHV 6$3(QKDQFHPHQW)UDPHZRUN

&KDQJH'HWHFWLRQ/D\HU

6\FOR0RELOH([FKDQJH 6\FOR'HOWD'HWHFWLRQ &KDQJH'HWHFWLRQ


3HUVLVWHQW/D\HU 5RXWLQHV &RQILJXUDWLRQ6HW
6\FOR,QWHJUDWLRQ)UDPHZRUN

&RQILJXUDWLRQ0RGXOH

%XVLQHVV/RJLF/D\HU

6\VWHP0RQLWRU
$SSOLFDWLRQ'DWD)LOWHU6HUYLFHV

6\FOR'DWD2EMHFW&ODVV 0RELOH,QWHJUDWLRQ
+DQGOHU5HSRVLWRU\ &RQILJXUDWLRQ6HW

$SSOLFDWLRQ$XWKRUL]DWLRQ6HUYLFHV

,QWHJUDWLRQ/D\HU
6\FOR%$3,:UDSSHU

-DYD&RQQHFWRU
0LGGOHZDUH

6\FOR
$JHQWU\6HUYHU

)LUHZDOO

&RPPXQLFDWLRQV:/$1::$1*356*601HWZRUN'RFNLQJ&UDGOH,5'$

0RELOH$SSOLFDWLRQV
22 Introduction to the SMART Mobile Suite for SAP® Systems

Java Architecture
The Java backend uses classes of type SAPObject to represent data objects sent to and from
the Client. Most of these classes are POJOs (Plain Old Java Objects), meaning they store
data in fields, provide accessory/mutator methods, and know how to construct themselves
when told to by the code. The following are the types of Java classes we will work with:
 SAPObjects: SAPObjects can be composed of other SAPObjects stored as arrays of
SAPObjects (i.e., Notifications have NotificationItems). All metadata is encapsulated
in the SAPObject class rather than in an external file.
 StepHandler: StepHandler classes provide the calling interface to classes
subclassing the Agentry API (steplets, data tables, and complex tables). Methods in
StepHandler classes should be static. StepHandler methods also provide an interface
for JUnit test suites.
 BAPI: The BAPI class encapsulates all of the BAPI processing needed by the Java
backend. It is abstract, as there are two specific types of BAPIs; FetchBAPIs and
TransactionBAPIs.
 FetchBAPIs: Types of BAPIs that create SAPObjects from the exchange
process. The SAPObjects are then parsed by Agentry for use on the Client.
 TransactionBAPIs: Take an Agentry transaction on the Client and turn it into
one or more jCo tables, then run the BAPI passing the tables in order to update
SAP.
The BAPI objects that the code uses are subclasses of FetchBAPI, TransactionBAPI,
DataTableBAPI, or ComplexTableBAPI. Developers write these BAPI classes to call the
BAPIs to do the things that the mobile application needs to do. A developer-written BAPI is a
specific ABAP function call for a particular application. For example, fetching all work orders
for a user, or sending up a locally added notification.
Note that there is not necessarily a one-to-one correspondence between BAPI classes and
ABAP function names.
BAPI classes accomplish the following:
 Create themselves out of the JCO.Repository when necessary. This is done just
before they are called, but a developer might make these poolable or cacheable.
 Set input values in JCO.Table parameters, such as search ranges in the case of
FetchBAPIs or transaction data in the case of TransactionBAPIs.
 Are executed when called (get the results or post the data to SAP).
 Report exceptions and errors back to calling code. This includes reading return tables
and parsing for error messages when necessary.
Introduction to the SMART Mobile Suite for SAP® Systems 23

About this Tutorial


This tutorial is the main material for the SMART Mobile Suite for SAP® Systems Configuration
training class. It includes lessons and exercises that present and reinforce the concepts and
procedures related to the products within this suite. It is primarily intended for use within this
class, and can also serve as a useful reference later on.
Most exercises within this tutorial are made as practical as possible, with real-world
applicability. However, certain exercises may implement functionality or modify behavior in a
way not likely to be found in real-world implementations. Their purpose is to present topics
and concepts related to real-world work. This may be necessary to present these items in a
manner best suited for the training environment.
The information presented in this tutorial is organized in lessons. Each lesson contains one
or more exercises to be completed by the training attendee to reinforce the concepts
presented in the lesson. Materials provided in the lessons, while as complete as is practical,
should not be considered comprehensive. Rather, the material in each lesson is intended for
reference purposes with the support of presentation made by the course instructor. Full
documentation is provided in the document set for each product within the SMART Mobile
Suite.
It is not necessary to read the lesson information prior to performing exercises within class.
Rather, this material is intended to be most beneficial for review after the instructors
presentation and completion of the exercises, or for later reference when class is complete.
However, the attendee should feel free to use any information within this guide at any time it
is found to be beneficial.
This course is intended for those who have completed the Agentry Essentials training class,
the Agentry Essentials Self-Study materials, or those with equivalent experience. A certain
level of understanding and knowledge is assumed on the part of the attendee as that
understanding relates to the Agentry Mobile Platform, its development environment, and its
tools. This course does not provide the basic Agentry information presented in the Agentry
Essentials materials. It does, however, build upon these concepts.
Likewise, this course and guide specifically does not provide information pertaining to general
SAP Systems topics. The attendee of the class and/or person working through the materials
presented is assumed to be adept in working with SAP’s technology and environments.
The main vehicle for this course is the SMART Work manager for SAP® ERP® application
within the SMART Mobile Suite. However, the concepts and methods presented within this
class are generally applicable to all products within this suite.
24 Introduction to the SMART Mobile Suite for SAP® Systems
2 Installation and Initial Configuration
26 Installation and Initial Configuration

Installation and Configuration Overview


The first processes in any mobile application deployment pertain to the installation and
configuration of the software components for that application. For those products within the
SMART Mobile Suite, the following general tasks are necessary and should be performed in
the following order to create a development or configuration environment:
1) Install the SMART Mobile Suite Administration Component, which includes:
 Verifying all system requirements have been met
 Installation preparation, including downloading the software and support
packages
 Installation of the SMART Mobile Suite Administration Component
 Activation of the Administration Component in the target client
 Definition and scheduling of background jobs related to maintenance of
synchronization components
2) Install the SMART Server for the application, which includes:
 Verifying all system requirements have been met
 Installation of the Java SDK and JRE Software
 Installation of the SMART Mobile Server to the host system
 Configuration of the Server to communicate with the SAP system
 Configuration of the Server to allow communications with the mobile client
applications
3) Install the Agentry Editor, which includes:
 Verifying all system requirements have been met
 Installation of the Java SDK and JRE for both development work and to support
the Eclipse environment
 Installation of the Eclipse Platform with the Agentry Editor Plug-in
 Import of the mobile application from the SMART Server to create an Agentry
application project within the Eclipse workspace
 Creation of the Java development project within the Eclipse workspace. This
project contains the business logic for synchronization between the SMART
Server and the SAP application through the Administration Component.
4) Install the Agentry Test Environment to use during testing of modifications to the
mobile application.
5) Install the SMART Client for the mobile application to sample devices that represent
the device type(s) for the implementation.
Installation and Initial Configuration 27
In each of the following lessons in this chapter the above tasks 2 - 4 will be accomplished.
Given that the first task covers installation oft he SMART Mobile Suite Administration
Component, which is typically performed by those outside the target audience for this class,
this component is already installed in the training environment. The 5th task is listed here for
reference purposes is not covered in this chapter. Full instructions on installing both the
Administration Component and the mobile client are provided in the Implementation and
Administration guides for each product.
28 Installation and Initial Configuration

Lesson 6: Installing and Configuring the SMART Server


The SMART Server for a given mobile application within the SMART Mobile Suite is the hub
of the application deployment. The Server communicates with the SAP application, through
the integration framework within the Administration Component. The Server contains and
executes all synchronization logic within the mobile application. It also serves up any
Client-side definitions when they have been modified and published to the Server.
The Server can be configured for development or production environments. In a development
environment, the Server is intended to serve small numbers of users, and is likely to receive
published updates from the Agentry Editor several times a day during the configuration phase
of an implementation or deployment. It maintains only a single version of the mobile
application.
A SMART Server instance configured for production is intended for real-world users in a
production environment. It serves hundreds of users at a time and maintains multiple versions
of the mobile application. Each publish to a production server results in a new version stored
on that server. Users always receive the latest version. Multiple versions are maintained by
the server to support resolution of conflicts when a Client contains data captured via
transactions in a previous publish version, allowing for that data to be processed using the
previous version’s logic before updating the Client with the latest publish version.
Multiple versions are also maintained on production Servers as a part of clustering behavior.
Multiple production Server instances for the same mobile application deployment can be
clustered together. When part of a cluster, each Server instance is updated simultaneously
with configuration changes made through the Agentry Administration Client. Additionally,
when a new version of the mobile application is published, Server instances within the cluster
will not provide that new version to Clients until all Server instances have received that new
publish version.

SMART Server Installation and Configuration Overview


Installation of the SMART Server should always occur after the Agentry Administration Client
has been installed and configured, as the Server can then be tested for connectivity to the
SAP system. When installing the SMART Server, it is necessary to select whether to install
a Development or Production Server. A Development Server instance is installed to support
configuration, development, and customization work performed for a given implementation.
A production instance is installed to deploy the application to users.
Once the Server software component installation is complete, the next step is configuration.
This includes configuration for connectivity to the SAP system, Client-Server
communications, security settings, clustering of Production Servers, log file settings, the
location of Java resources, and other tasks.
Installation and Initial Configuration 29
In general, the following items must be accomplished to successfully install and configure the
SMART Server:
1) Install the Java Development Kit (JDK) and Java Runtime Environment (JRE) to the
system that will host the SMART Server.
2) Install the SMART Server software component for the mobile application.
3) Configure the SMART Server to communicate with the SAP system.
4) Configure the SMART Server to match the SAP system’s time zone.
5) Optionally, enable and configure push behavior (this functionality also requires
configuration changes in the Agentry Administration Client).
6) Test connectivity with the SAP system.
7) Make additional changes to the JavaBE.ini configuration file.
8) Configure the Client-Server communications.
9) Test Client-Server communications by performing a transmit using each of the defined
transmit configurations and network environments supported in the implementation.
This test is performed after Clients are installed, and possibly re-tested after changes
to the default transmit configurations provided with the mobile application.
In the exercises of this lesson, the above tasks are accomplished in the training environment.
A Development Server environment for Work Manager is installed and configured to connect
to the training SAP system.

Installing the Server in the Training Environment


Information has or will be provided to you concerning items such as log ins and passwords,
server names, etc. Also, the Administration component, as well as the necessary Java
components, including the JDK and JRE are already installed and configured.
The procedure provided here for the installation of the Work Manager Server is the standard
Server installation process, also provided in the Implementation and Administration manual
for all products within the . When the installer prompts for values and settings, refer to the
information provided about the training environment.
If you have questions during this or any set of exercises, ask the course instructor for
assistance.
30 Installation and Initial Configuration

Exercise A: Installing the SMART Server For Windows


PREREQUISITE

Address the following items prior to installing the SMART Server:


 The host system must meet the system requirements as provided with the application.
 The Java SDK and JRE must be installed to the host system.
 The SMART Mobile Suite Agentry Administration Client must be installed to the SAP
system.
 You must have the name, client number, and system number of the SAP Application
Server to which the SMART Server will connect.

This procedure describes the steps to install the SMART Server software to a Windows
system. This procedure is the same for Windows Server and Windows XP Professional
systems. Note that the 64-bit build of the SMART Server can only be installed to 64-bit
operating systems. The 32-bit build of the SMART Server can be installed to either 32- or
64-bit Windows systems, but will not take advantage of the 64-bit memory addressing. The
SMART Server should never be installed to a Windows XP Professional host system for
production purposes. This operating system is supported by the installer solely for
development purposes. Production Servers should always be installed to server class host
systems.
When this procedure is complete, it will be necessary to perform initial configuration of the
SMART Server. Specifically, configuration options related to communications between the
SMART Clients and the SMART Server, and related to communications between the SMART
Server and the SAP system must be set according to the specifics of the implementation
environment.
For production environments in which multiple SMART Server instances will be installed for
load balancing and fail-over, perform this procedure for each SMART Server instance.
Installation and Initial Configuration 31
Additionally, review information provided on establishing SMART Server clusters using the
Agentry Administration Client.

Step 1 - Launch the installer executable for the SMART Server.


The Welcome screen is displayed.

Step 2 - Click the [Next] button to continue the installation.


The License Agreement screen displays.
32 Installation and Initial Configuration

Step 3 - Click the [Yes] button to agree to the license agreement and to begin installing
the SMART Server.
The Customer Information screen displays.

Step 4 - Enter the name of the administrator for the SMART Server and the company
name. In the Serial Number field, enter the number provided with the SMART Server
Installer. Click [Next] to continue.
The Enter Product Keys screen displays.
Installation and Initial Configuration 33
Step 5 - Enter the user key, device key, and expiration keys provided by Syclo.
Information entered on this screen is written out to the agentry.ini file. Click [Next]
to continue.
The Choose Server Type screen displays.

Step 6 - Select the type of SMART Server you want to install. Select Production for live,
production environments. Select Development for development or test environments.
If both are selected, two separate SMART Servers will be installed in separate
locations. Click [Next] to continue.
The SAP Connectivity Information screen displays.

Step 7 - Enter the name of the SAP Server and its port number in the Server field, using
the format: servername:portnumber. If both a Production and Development Server
are being installed, this previous screen will be displayed twice, once for each Server
instance. Enter the appropriate information for both SMART Server instances.
NOTE: All information entered in Steps 7-10 is written out to the JavaBE.ini file.
34 Installation and Initial Configuration

Step 8 - Enter the Client Number and System Number the SMART Server will use to
communicate with the SAP Application server. Click [Next] to Continue.
The User Information screen displays.

Step 9 - Enter the Service User Name and Service User Password. This is an
administrative user established as a proxy for all users. If both a Production and
Development Server are being installed, this previous screen will be displayed twice,
once for each Server instance. Enter the appropriate information for both SMART
Server instances.

Step 10 - If you are using Push Notifications, you must check the Enable Push
checkbox and then enter the Push User Name and Push User Password. Again, this is
an administrative user established as a proxy for all users. In most cases, this can be
the same user name and password as the Service User. Click [Next] to Continue.
The Java Backend Information screen displays.
Installation and Initial Configuration 35
Step 11 - Change the default values for the Java backend class paths should only if
you want to point the server to a different SAPjco.jar file or a different runtime
environment.

Step 12 - Click [Next] to continue.


The Choose Install Location screen displays.

Step 13 - Specify the folder in which to install the SMART Server. To change the default
folder, click [Browse] and navigate to the desired folder.
NOTE: If both Production and Development Server installations were selected in the Choose Server
Type screen, these screens will display once for the Production Server and once for the
Development Server.

Step 14 - Click [Next] to continue.


The Shortcuts for Production Server screen displays.
36 Installation and Initial Configuration

Step 15 - In addition to the shortcuts for the Server instance, the option to install the
Server as a Windows Service is also provided. Check this box to install the Server as
a Service if this is the desired configuration. Note that this is commonly set for
Production Servers but rarely for Development Servers. Also, select what shortcuts
and where they should be located from the Shortcuts window.
NOTE: If both Production and Development Server installations were selected in the Choose Server
Type screen, these screens will display once for the Production Server and once for the
Development Server.

Step 16 - Click [Next] To Continue.


The Installing screen displays and indicates the status of the installation.

Step 17 - When the installation is complete, you may be prompted to reboot the host
system. Select the desired option and click the [Finish] button to complete the wizard.

RESULT
Installation and Initial Configuration 37
The SMART Server software has been installed to the Windows host system. This includes
the server executable, as well as the SMART application, as provided by Syclo.

AFTER COMPLETING THIS TASK

The SMART Server instance now requires initial configuration based on the implementation
environment. This configuration includes:
 Client-server communications settings
 Server-SAP system communications settings
 Security and authentication settings
 For multiple Server instances, clustering settings and behaviors
The specifics of the Server-SAP system communications settings depends in large part on
the configuration of the SAP system. Specifically, whether the SAP system is configured in a
distributed environment, or if it is in a load balanced environment. Follow the procedures
provided for the implementation-specific needs.
38 Installation and Initial Configuration

Lesson 7: Installing the Agentry Test Environment


The Agentry Test Environment is a tool provided for integrators, developers, and
administrators, as well as quality assurance testers, to provide a means of testing and
debugging the Client-side functionality of a mobile application. In this tutorial, the Agentry
Test Environment, or ATE, is installed and used for most of the Client-side testing performed
in each lesson’s Publish and Test sections.
This lesson includes the basic instructions for installing the ATE. When specifying the
installation location, refer to the informational sheet for your training environment to
determine the proper location.
The installation software is available in the same location as the other installation
components of the mobile application. Refer to the information provided for your training
environment for this location.
Installation and Initial Configuration 39

Exercise A: Installing the Agentry Test Environment


PREREQUISITE

Address the following items prior to performing this procedure:


 Obtain the Agentry Test Environment installer. The installer is found on Syclo’s
fulfillment center at http://software.syclo.com (authorization required). If you
have access to multiple versions of the Agentry Mobile Platform, verify that the proper
installer version is obtained.
 Determine the installation location of the Agentry Test Environment on the intended
host system. By default this location is C:\Agentry\Test Environment. You can
specify a different location during the installation if desired.
 Log into the host system as an administrator, with privileges to install software to the
desired location.

This procedure describes the steps necessary to install the Agentry Test Environment
software component of the Agentry Mobile Platform. This component is used as a Client test
tool during development, configuration, and other modification work. It is not intended for end
users.
Perform this procedure to:
 Test modifications of the mobile application, when those modifications affect
Client-side behavior or Client-Server communications or synchronization.
 Test or debug run time issues in a Production environment. The Agentry Test
Environment can be connected to the SMART Production Server just as a normal
Client can.
40 Installation and Initial Configuration

When this procedure is complete, the Agentry Test Environment is available for use to test
the Client-side behaviors of any modifications made to the mobile application.

Step 1 - Start the Agentry Test Environment installer on the host system where you are
installing this component.
The welcome screen of the installer is displayed:

Step 2 - Click the [Next] button to advance the wizard.


The License Agreement screen is displayed:
Installation and Initial Configuration 41
Step 3 - Click the [Yes] button to accept this agreement and advance the wizard.
The Install Location screen is displayed:

Step 4 - Enter the desired directory path in the Destination Folder field. This can be a
new path, an existing location selected by clicking the [Browse] button, or the default
location. Click the [Next] button to install the Agentry Test Environment to the
specified directory.
The Agentry Test Environment is installed to the specified location. The Shortcut Selection
screen is displayed.
42 Installation and Initial Configuration

Step 5 - Select the desired shortcut locations by checking or unchecking the listed
shortcut options. Once the shortcuts are configured, click the [Install] button to begin
the installation of the Agentry Test Environment software component.
The selected shortcuts are created by the installer. The Installation Status screen is
displayed next indicating the installation progress. When the installation is complete, the
Finished screen is displayed.

Step 6 - To start the Agentry Test Environment now, leave the box checked on this
screen. Otherwise, uncheck this box. Click the [Finish] button to close the wizard.

RESULT

With the completion of this procedure, the Agentry Test Environment is installed to the
selected location and is available for use in testing mobile applications in development,
configuration, implementation, or production issue resolution scenarios.

AFTER COMPLETING THIS TASK

Just as with a standard Client installation, the Agentry Test Environment needs to connect to
an Agentry Server to perform an initial transmit. Prior to performing this transmit, the proper
Client platform to be mimicked, enabling or disabling scan and GPS simulations, and other
similar selections should be made.
Installation and Initial Configuration 43

Lesson 8: Installing and Configuring the Agentry Editor


The Agentry Editor is a plug-in to the Eclipse development platform. Together these items are
the primary development tools for the mobile applications within the SMART Mobile Suite.
The Editor provides a 4th generation language (4GL) interface to the mobile application’s
logic and data structures. Data synchronization is encapsulated in the Java logic, referenced
by the synchronization definition types and stored in Java source files.
Each project within the SMART Mobile Suite is stored in an Agentry application project. This
project is displayed in and edited or configured using the Agentry Editor plug-in. The project
contains the definitions for the mobile application. Some of these definitions provide
synchronization behaviors and logic, which at run time are processed and executed by the
SMART Server. The logic for these definition types is written in Java code, which includes
calls into the Java Connector, or JCo.
This Java logic is referenced by the synchronization definition types by referencing the Java
source files in which the logic is contained. Within Eclipse is the Java perspective, which
provides numerous tools for Java development work. The Java source files for a given mobile
application are managed and stored in a Java project edited in the Eclipse Java Perspective.
The Java projects and the Agentry application project for a given mobile application are
stored in a workspace within Eclipse. The Eclipse workspace consists primarily of the
workspace folder under which most resources for the workspace’s projects are stored, as well
as the configuration settings and preferences of Eclipse. This allows you to configure the
workspace in a manner best suited for your projects. You can then set up these preferences
different ways for different workspaces that contain different projects and project types.

Agentry Editor Installation and Configuration Overview


The Agentry Editor is installed from the Editor Installer provided by Syclo. Included in this
installer is the Eclipse development platform and the Agentry Editor plug-in for Eclipse. Also
included in this installer is the JRE version required by Eclipse. Note that while the version of
the JRE for Eclipse and the version required to develop the Java logic for the mobile
applications are currently the same, this may not always be the case. As of this writing, the
JRE for Java 6 (version 1.6) are required by both components. However, it is possible that a
future release of either Eclipse or SAP systems may include a later release of Java (Note that
1.6 is the most recent release as of this writing). Should this be the case, two instances of the
JRE will be needed for the host system of the Agentry Editor, one to match each of the two
requirements.
As stated, currently both Eclipse and the mobile application support the same version of Java
and therefore the installation of the Java components need only occur once. The installer for
the Editor, however, does not include the JDK. While the JRE is used by Eclipse in for it to
execute, the JDK is needed for Java development work. For this reason, it may be more
efficient to install the JDK before installing the Agentry Editor and Eclipse, as the JDK installer
provided by Sun® includes the JRE as well. The installer for the Editor checks the host system
for the required Java components and, if found, will not reinstall them.
44 Installation and Initial Configuration

Once installation is complete, the Eclipse environment will likely require initial configuration,
including the creation of a workspace, and setting the preferences for that workspace.
Finally, before beginning work on a mobile application within the SMART Mobile Suite it is
necessary to first import the definitions from the SMART Server for that product, creating an
Agentry application project within the Eclipse workspace. The SMART Server contains all the
business logic within the application project developed by Syclo. This project itself, however,
is not distributed with the application as an Agentry application project, rather existing only as
a published application with the SMART Server installation. The Agentry Editor includes
import functionality that allows for the creation of an Agentry application project from multiple
source types, including the SMART Server for a mobile application within the SMART Mobile
Suite.
Following are the general tasks to install and configure the Agentry Editor:
1) Install the Java Development Kit, which includes the Java Runtime Environment, to the
intended host system for the Agentry Editor.
2) Install the Eclipse development platform and Agentry Editor plug-in using the
Syclo-provided software installer.
3) Configure the Eclipse environment, including creating a workspace and setting
preferences suited to the projects the workspace will contain.
4) Using the Agentry Editor plug-in, import the definitions from the previously installed
SMART Server for the application, creating a new Agentry application project for this
application.
5) Within the Eclipse workspace, open the Java perspective and create the Java project
containing the Java source for the application.
In the exercises of this lesson, the Work Manager Server installed previously is used as the
import source for the new Agentry application project created after we install the Agentry
Editor. Likewise, the Java project created is for the Work Manager application.
Installation and Initial Configuration 45

Exercise A: Installing the Agentry Editor Plug-In and Eclipse Platform


PREREQUISITE

Before installing the Agentry Editor:


 If any other SMART components (Server, Clients) are installed to the same host
system, those components must not be running during installation. Verify they are shut
down, including any SMART Server instances running as Windows Services.

Beginning with the release of the Agentry Mobile Platform version 5.0, the Agentry Editor is
provided as a plug-in component to the Eclipse Platform. The installer provided by Syclo
includes:
 Eclipse Platform v3.7
 The Agentry Editor plug-in for Eclipse
 The Java Runtime Environment (JRE) version 1.6 (Java 6)
 The Microsoft Visual Studio C++ runtime libraries
Of these components, the Eclipse Platform and the Agentry Editor plug-in are always listed
in the installer as options to install. The JRE is listed if it is not currently present. If already
installed, the installer does not attempt to reinstall it. The C++ runtime libraries are installed
in the background if not already present.
Note with the release of the Agentry Mobile Platform v.6.0 the Agentry Editor plug-in can no
longer be installed to an existing Eclipse implementation. The installer will not allow the
existing Eclipse folder to be selected as a valid installation location. This is true for Eclipse
implementations whether or not they contain a previous version of the Agentry Editor plug-in.
The plug-in can also not be installed to an Eclipse implementation even if the version is the
same as the one installed by the Editor installer software.

Step 1 - Launch the Agentry Editor installer executable.


The Welcome screen displays.
46 Installation and Initial Configuration

Step 2 - Click the [Next] button to advance the wizard.


The License Agreement displays.

Step 3 - Click the [Yes] button to accept the license agreement and advance the wizard.
The Choose Components screen displays.
Installation and Initial Configuration 47
Step 4 - Select the proper components to install for the Agentry Editor plug-in. If you
are adding the Agentry Editor plug-in to an existing Eclipse environment, uncheck this
option. For a new installation, select all components. Note that the Agentry Editor
plug-in is always selected. Also note that if the Java Runtime Environment version 1.6
is not found, an option is listed on this screen to install it. In this case, the JRE will be
installed to the default location. Click the [Next] button to continue.
The Choose Install Location screen displays.
48 Installation and Initial Configuration

Step 5 - Select where to install the Eclipse environment and the Agentry Editor plug-in,
depending on the components selected for installation in the previous step. If Eclipse
v3.7 was installed or upgraded prior to running the Editor installer, the destination
folder is the installation folder of that Eclipse installation. If the complete Eclipse
environment is also installed, use the default location, or choose any other valid path.
Click the [Next] button to continue.
The Shortcuts for Agentry Editor screen displays.

Step 6 - Check the boxes that apply to the desired shortcuts for the installer to create.
These shortcuts are started when the Agentry Editor plug-in is loaded. Click the
[Install] button to begin the installation.
The installation will proceed and the status will be displayed. Click the [Show Details] button
to view the detailed progress of this process, if desired.
Installation and Initial Configuration 49
Step 7 - Once the installer has completed its processing, the following screen is
displayed.

From here, you can choose to start the Eclipse environment with the Agentry Editor plug-in.
If this is the first time Eclipse is installed and the Java Runtime Environment is not a part of
your system’s Path variable, do not start Eclipse. Uncheck the box and click the [Finish]
button. Continue to the next step.

Step 8 - If JRE was added to the host system as a part of the Eclipse and Agentry Editor
installation, there are two folder locations that you need to add to the system’s Path
environment variable. To add these, right-click on the My Computer icon on the
desktop and select the Properties item in the menu displayed. In the System Properties
screen, select the Advanced tab. Click the button Environment Variables. In the lower
half of the screen is a list of the currently defined System Variables. Select the Path
item in this list.

Click the [Edit] button and on the screen displayed, check for or add the following two paths
to the existing values. If they are already present, do not add them again. If they are not
found, add them as listed below. NOTE: Take caution not to modify any existing values in
this list. When adding path values, separate each path with a semi-colon (;).
C:\Program Files\Java\jre1.6.0_07\bin
C:\Program Files\Java\jre1.6.0_07\lib
50 Installation and Initial Configuration

Step 9 - Click the [OK] button after adding the values and click [OK] to close out of the
system properties screen.

Step 10 - Launch the Eclipse environment with the Agentry Editor plug-in.

RESULT
The Eclipse environment, Agentry Editor plug-in, and any other components selected are
installed on your system.

AFTER COMPLETING THIS TASK

Additional configuration of Eclipse is needed as it relates to the Agentry Editor plug-in. This
configuration is performed within the Eclipse Platform and includes the following general
items:
 Agentry projects work with several file types. You must create file associations within
Eclipse for these types to allow the platform to properly handle, display, and edit them.
 Script files, including SQL and shell or batch scripts created in Agentry Editor are
saved with a Unicode encoding. The default file encoding for an Eclipse workspace is
different. You must modify file encoding options within the Eclipse preferences.
 When working with a database back end system, you must configure the Data Source
Tools installed with Eclipse in order for the Agentry Editor connector studio to work
with a database back end.
It may also be necessary to complete the configuration of one or more SMART Servers. With
the release of version 5.0 of the Agentry Mobile Platform, a publish from the Editor is a part
of the Server configuration process as it relates to the Agentry application project’s system
connections. If connectivity was already configured between the SMART Server and SAP®
Systems, the publish is not necessary for connection configuration.
Installation and Initial Configuration 51

Exercise B: Round Trip between SAP and the SMART Client

In this exercise, you will create a notification document for a work order, create a work order,
and assign it to yourself in SAP. Then you will download the work order using the SMART
Client in the ATE, complete the work order, and upload it back into SAP. This will demonstrate
the basic flow of data between SAP and the SMART application.

Step 1 - Create a Notification Document using the SMART Application


In the ATE, select the Notification tab. From the Notification screen, select the [Action]
button, then click Add.
Enter the following information fields on the Edit Notification screen:
 Desc: Broken water pipe
 FLOC: [Use the one provided]
 Equip: Select one from the drop-down menu
 Brk Dwn: Check the box
 Priority: 1 - High
Click the right arrow to continue. Add any relevant information in the Notes screen that
you desire. Click the green check mark to finish the notification.
Tap the transmit icon to upload the new notification to SAP. Notice that during the transmit
how your information is entered into SAP. After the transmit, your notification receives an
official SAP ID and appears on the Notification main screen of the Client. Note down that
number.

Step 2 - Create a Work Order from the New Notification Using SAP
Log into SAP using the log on information provided in class. Type in IW22 in the command
field and press Enter.
In the Notification field, type in the notification number you created in the ATE and
transmitted up to SAP in the previous step and press Enter. The Change PM Notification
screen displays.
Click the Create Order button to convert the notification to a work order. Accept the
defaults provided to create the work order. Your assigned user ID will automatically be
filled in as the Person Responsible. Take note of your ID number.
Click the green check mark to create the work order. The Create Maintenance Order
screen displays. Click the green check mark to create the work order.
Click the Release button to release the work order.
Click the Save icon to issue the work order. Note the work order number in the status bar
at the bottom of the screen.
52 Installation and Initial Configuration

Step 3 - Download the New Work Order to the SMART Client


To use the SMART Client application, you must first download or retrieve the work order
from the SMART Server. Then you can change the status of the work order to Completed,
indicating that you have completed the work the work order represents, and upload it
(transmit) it back to SAP.
Using the ATE, running Work Manager, perform a transmit. Watching the transmit
messages, notice that this retrieves the new notification.
When the Client application screen displays, click on the Work Orders tab. Notice the
new work order is displayed on the main screen.
Highlight the work order, click the [Action] button, and click Start. The work order will
change to a STARTED status. Keep in mind that you can only have one work order in a
Started status at any one time.

Step 4 - Completing a Work Order (TECO) Using the SMART Application


From the Work Order main screen, highlight the work order in the Started state and tap
the [Action] button.
Select TECO from the menu. The Notes screen displays. You can add any notes you wish
at this time. Tap the right arrow to proceed.
The Add Timesheet screen displays. Enter the following information:
 Hours: 1
 Abs/Att: [none]
 Act Type: 1410 - Repair Hours
 Operation: 0010
 Sub Op: None
 Work Ctr: None
Click the green check mark to finish. The status changes to TECO, or Work Order
Complete. The icon in the tile screen also changes to a check mark, indicating to the user
that the work order is in a completed state.
Perform a transmit by clicking the transmit icon. This updates the work order in SAP and
sets its status as Completed.
Installation and Initial Configuration 53
Step 5 - Verify that the Work Order was Completed in SAP
Now that the work order is complete and the status was changed in SAP, you can verify
that the work order was completed by viewing the Work Order Document.
Type in IW33 in the command field in SAP and press Enter. The Display Order Document
screen displays.
Enter the ID number of the work order you created into the Order field and press Enter.
Verify that the status of the work order shows as TECO, which means ‘complete’.
Click the Display Text icon to view the notes you entered in the Notes field on the ATE,
if you made any.
54 Installation and Initial Configuration
3 Mobile Integration Components
56 Mobile Integration Components

Integration Layer Overview


BAPIs (Business Application Programming Interface) provide the interface to the processes
and data in SAP, and are located in SAP. BAPIs are called from external application systems,
like a SMART Mobile Suite application. BAPIs interface to outside applications through
defined methods. An application only needs to know how to call the methods without having
to know anything about the underlying business data details.
The set of methods associated with a BAPI represent the object’s behavior. When a method
is executed on a BAPI, the method can change the internal state, and therefore the object’s
data. To use a BAPI method to access data in SAP business objects, the application needs
to know the name of the BAPI and the import/export parameters to import and export data
from the application to SAP.
BAPI wrappers are used to expose the SAP data and business logic to the mobile application.
By design, BAPI wrappers do not contain any business logic themselves.

BAPI Wrappers and Mobile Data Object Integration


The Mobile Integration Settings section in the Configuration Portal main page is used to link
BAPI wrappers with mobile data objects and to encapsulate the business logic related to the
mobile application. By working with BAPI wrappers and MDOs, you can create integration
rules and filters for every class handler, for every mobile application on your system.
The following system diagram shows how BAPI wrappers work with MDOs and the system
as a whole.

Outbound Triggers
An outbound trigger allows a mobile application to interface with external systems such as an
Agentry middleware Server from SAP. Outbound triggers can be integrated into standard
mobile application processes, such as push processing. You can define different types of
outbound triggers, including HTTP triggers, file triggers, and Web service triggers.
Mobile Integration Components 57
Outbound triggers are configured for each mobile application. Therefore, your mobile
applications must be defined first. Outbound trigger handlers must be developed before it can
be assigned to a trigger. Once you define the outbound triggers, you must use the
Configuration portal to assign the triggers to push scenarios.

Java Classes in Agentry


If complex tables or data tables are created in Agentry, you must associate the new Java
class with the correct BAPI name in SAP. If this is not set, transactions and fetches will not
work, even though the BAPI wrappers are associated with the appropriate MDOs in the
Configuration portal.
58 Mobile Integration Components

Exercise A: Change How Data is Displayed Using Filter Options


In SAP, your instructor will deactivate the filter rule for data filter WORK_CNTR of the mobile
data object SWM5_WORKCENTER using the Configuration portal.

Step 1 - Perform a Transmit in the Client ATE


Verify that additional work center records were fetched into the complex table
ctWorkCenter by viewing the logs as they scroll during the transmit.
Mobile Integration Components 59

Configuration Set for Integration Layer Overview


Mobile integration settings are used to link BAPI wrappers with mobile data objects (MDOs).
Linking BAPI wrappers to MDOs encapsulates the business logic related to the mobile
application. The two areas used in the Configuration portal are:
 Mobile Data Objects Configuration
 BAPI Wrapper Configuration
You will be connecting BAPI wrappers to MDOs in future lessons. This lesson will walk you
through the fields and settings used in the Configuration portal, so you become familiar with
working with them.
The integration layer provides an interface and business logic for both upstream and
downstream synchronization. In upstream synchronization, information captured on the
Client is transmitted to the Server. The integration layer includes business logic and
processing to update the appropriate data in SAP. In downstream synchronization, SAP uses
information in the exchange tables from the change detection layer to determine what data a
given mobile client needs by comparing the information in the exchange table records with
the information existing on the mobile client. The nature of the Client information varies
depending on the Agentry definition type that is synchronized.

Mobile Data Object Configuration


A mobile data object (MDO) represents a mobile semantic view of data and activity
combination for an SAP object. MDOs are data repositories in the namespace that can get,
create, update, and delete information in SAP. They encapsulate the business logic of mobile
applications by defining transactions, data structures, and business rules.
There are three types of mobile data objects:
 Data Table (DT): A simple representation of SAP business objects KEY and VALUE
 Complex Table (CT): A two-dimensional representation of a business object with a
single table of multiple columns
 Standard Data Object (DO): A multi-dimensional representation of a business object
with multiple tables representing different subsets of the business object
The Configuration portal is used to modify MDO properties such as object type, class
handlers, data filters, and other settings. For example, instead of modifying BAPIs to change
what information is retrieved from SAP and pushed out to mobile devices, you can use the
Configuration portal to modify MDOs and set up their data filter rules.

BAPI Wrapper Configuration


A BAPI wrapper exposes SAP data and business logic to the mobile application. By design,
the BAPI wrapper does not contain any business logic. Each BAPI wrapper must be assigned
to a specific method type (GET, CREATE, UPDATE, or DELETE) of an MDO to perform the
required business logic. By decoupling the business logic from the BAPI wrapper, it is
possible to switch MDOs without affecting the underlying mobile application definition.
60 Mobile Integration Components

BAPI Wrappers and Data Filtering


BAPI wrappers contain data filtering abilities, which control the data that can be viewed by a
specific mobile application, based on business needs. In SAP, each user is assigned a
role-based profile with authorization permissions on viewable data and available activities.
For example, a user working in one plant should not be able to view data for a different plant.
When business activities performed by a user are mobilized through the Client application,
the ability to extend the same restrictions to the application is necessary. Data filter rules, set
through the Configuration portal, provide the function to restrict data access for mobile
application.
Data filters can be user-dependant or applied to the entire mobile application.
Mobile Integration Components 61

Creating Integration Components for Complex Table Synchronization


The complex table definition defines a table of records containing multiple fields stored on the
Client in a structured and searchable format. A complex table can contain large amounts of
data with records numbering in the thousands. Included in the complex table are the fields for
its records and indexes on fields to provide search functionality and structure to the overall
data in the table. The complex table definition also defines how its data is synchronized.

Complex Table Data Flow


The following diagram and steps depict what happens when the Client loads or reloads a
complex table. In the exercise in this section, you will use the Configuration portal to
associate a BAPI wrapper with an MDO for a complex table, as well as modify the Java in
Agentry to work with the necessary fields in the BAPI in SAP.
NOTE: In both the diagram and the steps, ‘xxx’ stands for the Client application name. For
instance, xxx is replaced with WorkManager for the Work Manager application.

1) The complex table’s initialize() method is called.


2) The initialize() method calls a ComplexTableStepHandler build() static method,
passing the user object.
3) The ComplexTableStepHandler build() method constructs the necessary CTBAPI
class, passing the user object and clientLastUpdate parameter to it.
4) The CTBAPI constructor retrieves the JCO function object from the repository, using
the connection on the user object.
62 Mobile Integration Components

5) CTBAPI sets the BAPI import parameter IS_BAPI_INPUT.


6) CTBAPI adds IT_xxx record(s) to ComplexTableObject import tables for search
criteria or other input parameters.
7) The ComplexTableStepHandler build() method calls getNumRows() method in
CTBAPI.
8) CTBAPI getNumRows() method calls the execute() function and checks for
exceptions.
9) CTBAPI getNumRows() method reads the ET_RETURN table in the BAPI class for
error messages.
10)CTBAPI getNumRows() method iterates over ET_COMPLEX_TABLE and reads
records from the table.
11)For each record, CTBAPI getNumRows() method calls the appropriate constructor in
the appropriate SAPObject subtype.
12)The SAPObject subtype constructor maps the JCO record column names to field
names.
13)The CTBAPI getNumRows() method collects the SAPObjects in ComplexTableIterator
and passes them back to ComplexTableStepHandler.
14)ET_EXCHANGE_ACTION_DELETED is read and follows the same steps as 10 - 13.
These SAPObjects populate another ComplexTableIterator.
15)ComplexTableStepHandler passes the iterators back to dataIterator() and
deleteIterator().
16)The complex table initialize() method stores the interators in ComplexTableIterator
and returns them to Agentry in dataIterator and deleteIterator.
17)The Server parses these iterators and sends table rows up to the Client.
Mobile Integration Components 63

Creating Integration Components for Data Table Synchronization


The data table selection property type is used to store a selection made by the user from a
data table. The value stored in the data table selection property is the key field of the selected
record number within the data table. The data type of this value is a string, integral number,
or decimal number, based on the data type of the key field.

Data Table Data Flow


The following diagram and steps depict what happens when the Client loads or reloads a data
table. In the exercise in this section, you will use the Configuration portal to associate a BAPI
wrapper with an MDO for a data table, as well as modify the Java in Agentry to work with the
necessary fields in the BAPI in SAP.
NOTE: In both the diagram and the steps, ‘xxx’ stands for the Client application name. For
instance, xxx is replaced with WorkManager for the Work Manager application.

1) The data table’s initialize() method is called.


2) The initialize() method calls a DataTableStepHandler build() static method, which
passes the user object.
3) The DataTableStepHandler build() method constructs the necessary DTBAPI class,
passing the user object, clientLastUpdate parameter, and table name to it.
4) The DTBAPI constructor retrieves the JCO function object for
/SYCLO/CORE_DT_GET from the repository, using the connection on the user object.
64 Mobile Integration Components

5) DTBAPI sets the table name in the table IT_DOID, in the field DO_ID in the BAPI
import parameters.
6) DTBAPI adds IT_xxx record(s) to the DTObject import tables for search criteria or
other parameters.
7) The DataTableStepHandler build() method calls the getNumRows() method in
DTBAPI.
8) DTBAPI getNumRows() calls the execute() function and checks for exceptions.
9) DTBAPI getNumRows() reads the ET_RETURN table in the BAPI class for error
messages.
10)CTBAPI getNumRows() method iterates over ET_DATA_TABLE and reads records
from the table.
11)For each record, DTBAPI getRows() method calls the appropriate constructor in the
appropriate SAPObject subtype.
12)The SAPObject subtype constructor maps the JCO record column names to field
names.
13)DTBAPI getNumRows() method collects the SAPObjects in the data table and passes
them back to DataTableStepHandler.
14)The DataTableStepHandler build() method passes the DataTableObject back to the
initialize() method and is then stored in the appropriate field.
15)The Agentry Server parses these iterators and sends the table rows to the Client.
Mobile Integration Components 65

Creating Integration Components for Transaction Synchronization


The transaction definition defines data flow captured on the Client. As part of its definition, a
transaction includes a target object type, data values to capture, Client-side data validation,
and processing of the data to the back end system by the SMART Server during
synchronization. Transactions can add new object instances, edit an existing object, delete
an object, or modify a complex table or data table record. Each of these behaviors is exhibited
by a different transaction type, selected during the creation of the transaction.

Transaction Data Flow


The following diagram and steps depict what happens when the Client loads or reloads a
transaction. In the exercise in this section, you will use the Configuration portal to associate
a BAPI wrapper with an MDO for a transaction, as well as modify the Java in Agentry to work
with the necessary fields in the BAPI in SAP.
NOTE: In both the diagram and the steps, ‘xxx’ stands for the Client application name. For
instance, xxx is replaced with WorkManager for the Work Manager application.

1) A Server exchange steplet defined in a transaction calls Steplet doSteplet() method to


begin the transaction.
2) Steplet’s doSteplet() calls the appropriate method in the xxxStepHandler class to
create, update, or delete objects in SAP.
3) The xxxStepHandler method constructs the necessary SAPObject subtype by passing
User to the SAPObject’s constructor.
66 Mobile Integration Components

4) The xxxStepHandler method instantiates the necessary xxxCreateBAPI or


xxxUpdateBAPI object, passing the SAPObject to the constructor.
5) The xxxCreateBAPI or xxxUpdateBAPI constructor maps the SAPObject’s fields to the
necessary JCO record columns.
6) The xxxCreateBAPI or xxxUpdateBAPI constructor receives the JCO function object
from the repository, using the connection on User.
7) The xxxCreateBAPI or xxxUpdateBAPI constructor sets the BAPI import parameters
IV_xxx and/or IS_xxx.
8) The xxxCreateBAPI or xxxUpdateBAPI constructor adds IT_xxx records to the BAPI
import tables.
9) The xxxStepHandler method calls add(), update(), or delete() method of
xxxCreateBAPI or xxxUpdateBAPI.
10)The xxxCreateBAPI or xxxUpdateBAPI constructor calls the execute() method on the
BAPI and checks for exceptions.
11)The xxxCreateBAPI or xxxUpdateBAPI constructor reads the ET_RETURN table for
error messages.
12)If successful, control passes back to xxxStepHandler, Steplet, and Agentry.
4 Working With The Mobile Integration Settings
68 Working With The Mobile Integration Settings

Business Logic Layer Overview


The business logic layer contains the logical components to work with the exchange data
objects in the change detection layer for downstream synchronization. In addition, it contains
the logical components to update data from transactions in the mobile application to the
SAP® system.

Application Data Filter Services


The application data filter services specify the filtering of data to be retrieved from the SAP®
system for transmission down to the mobile application. Not all fields from a given table will
necessarily be sent to the mobile application. The application data filter services allow you to
specify which fields from a table to are be sent to the mobile application.

Data Object Class Handler Repository


The data object class handler repository contains the logic used by the mobile data objects
to synchronize data. A class handler is created to retrieve data from or update data to the SAP
system, making calls to the standard SAP® BAPIs.

Application Authorization Services


The application authorization services contain the security settings specific to the mobile user
group. Settings for authorization services can be applicable to users of all mobile applications
synchronizing data through the administration component, for a specific application, or for a
specific class handler within the business logic layer.

Additional Components
Data Staging and Proxy Settings are two additional tabs on the Mobile Data Object
Configuration page, but will not be discussed as part of the Mobile Integration Settings. These
two topics will be discussed elsewhere in this manual.
Working With The Mobile Integration Settings 69

Lesson 9: Business Logic Layer - Complex Tables


The complex table definition defines a table of records containing multiple fields stored on the
SMART Client in a structured and searchable format. A complex table can contain large
amounts of data with records numbering in the thousands. Included in the complex table are
the fields for its records and indexes on fields to provide search functionality and structure to
the overall data in the table. The complex table definition also defines how its data is
synchronized.

Complex Table Sync Processing


The synchronization of the complex table can include processing to only replace records
whose data has changed in the SAP database, add new records, and return information
about records to be removed. This processing is implemented using the exchange data
model of synchronization. This method is recommended for all downstream synchronization
as it is more efficient in most use cases, and is the standard method for synchronization.
The following diagram and subsequent description provide the general processing and data
flow that occurs during synchronization of a complex table in a typical implementation. This
processing assumes the use of the exchange data model of synchronization, which allows for
incremental updates of data on the client. For larger data sets, it may be necessary to
configure streaming within the SMART Mobile Suite Administration Component. Streaming
will alter the processing logic from the method described here and is discussed in the next
section.
70 Working With The Mobile Integration Settings

1) The SMART Client initiates a transmit and makes a request to the SMART Server to
synchronize a given complex table. Included in the request is the name of the complex
table definition to synchronize and the date and time the data for the complex table
was last updated.
2) The SMART Server processes the request, beginning by calling the constructor
method for the complex table Java class that corresponds to the specific complex table
definition. If the exchange data model is being used, the last update value from the
client for the complex table is then updated to the client information table in the SAP
database.
3) The SMART Server next calls the build() method within the complex table Java
class. This method call ultimately results in the call to the GET method specified in the
mobile data object for the complex table.
4) The GET method compares the last update timestamp in the client information table
to the records in the exchange table as well as the SAP database for the complex
table. Any records in the exchange table not marked for deletion and with a timestamp
value newer than the last update table result in the corresponding record in the source
table in the SAP database are retrieved.
5) The GET method next compares the last update timestamp in the client information
table to the records in the exchange table that are marked for deletion. The key value
is retrieved for any records marked for deletion and where the timestamp is newer than
the last update value in the client information table.
6) The GET method returns both the list of new and updated records, and the list of key
fields for records marked for deletion to the SMART Server. These values are cached
in the Java Virtual Machine running for the SMART Server.
Working With The Mobile Integration Settings 71
7) The deleteIterator() method is called by the SMART Server. This method
retrieves the cached items from the list of key values for records to be deleted,
returning these values to the SMART Server.
8) The SMART Server sends the list of key values to the SMART Client, instructing the
client to delete the records with matching key field values from the complex table.
9) The dataIterator() method in the complex table Java class is called next by the
SMART Server. This method returns the records from the cached new and updated
records in the Java Virtual Machine memory. These records are returned to the
SMART Server which uses the data to create records for the complex table being
synchronized. The SMART Server sends the records to the SMART Client in chunks
of 200 records at a time.
10)When the SMART Client receives a chunk of records, it matches them to the existing
records within the complex table based on the key field. Any matching records on the
SMART Client are replaced with the new ones. Any records in the new set that do not
match existing records on the SMART Client are added to the complex table. The
complex table’s indexes are then updated to match the new data.
11)The SMART Client responds to the SMART Server that the records have been
received and processed. The next chunk of records, if any, are sent to the SMART
Client. This portion of the process repeats until all records for the complex table have
been processed.
12)Once all new and updated records for the complex table have been downloaded, the
next complex table is synchronized, repeating this entire process. Note that the order
in which the complex tables for an application are synchronized is not guaranteed.

Complex Table Rebuild and Synchronization Without Exchange Data


In the previous process, the synchronization steps for complex tables were discussed. In that
process, it was assumed that the exchange data model is used, allowing for incremental
updates to the records within the complex table as stored on the SMART Client. Some
complex tables within the application do not use this method of synchronization. For those
complex tables, the synchronization process is a slightly different.
Also, there are situations when the complex table will be in a rebuild state, meaning that the
complex table is to be completely replaced and rebuilt on the SMART Client. When in a
rebuild state, the synchronization for the complex table does not use exchange data. Note
that a complex table can be in a rebuilt state if the definition for it has been modified on the
SMART Server, and also under other situations that can be controlled by the system
administrator. The SMART Server checks the rebuild state of the complex table during each
synchronization by calling the method reload(). This method returns true if the complex
table is in a rebuild state.
When not using the exchange data model for synchronization, all records to be stored in the
complex table on the SMART Client must be retrieved, rather than only retrieving those that
have been modified or added in the back end system. In this case, the synchronization
process is similar to the one previously described, but with the following differences:
 The GET method within the mobile data object does not use the client information
records or the exchange table. Both of these items are specific to the exchange data
process and therefore are not a part of the logic when this method is not in use.
72 Working With The Mobile Integration Settings

 The GET method, when called, returns all records that should be stored in the complex
table in the SMART Client. As previously described, these records are cached within
the Java Virtual Machine for the SMART Server.
 The data in this cache is still returned by the dataIterator() and processed in the
same manner for download to the SMART Client. However, the
deletedIterator()will not return records, as all records in the complex table are
replaced with those returned during the latest synchronization. Since all data in the
complex table is being replaced, it is not necessary to delete any records.
Working With The Mobile Integration Settings 73

Exercise A: Complex Table Entry Lists


An entry list is a set of measuring points. For example, if a boiler has several gauges that a
maintenance worker needs to record measurements from, these measurements would be
grouped in an entry list. Your first task in adding Rounds functionality to SMART is adding a
complex table to the application that pulls down an entry list from SAP and displays it on the
Client.
74 Working With The Mobile Integration Settings

This exercise extends the application by adding a new complex table for an entry list, with
help from your instructor. The key point to learn in this exercise are how a complex table class
handler in SAP is created.

Step 1 - Create a New Class for the Entry List


Launch the SAP GUI and log into SAP using the information provide with your classroom
packet. To create a new class in SAP, you use the Class Builder. Enter SE24 in the
command field and click the Enter icon:

This launches the Class Builder: Initial Screen.

Normally, you would now create a new class for your complex table, but for this exercise,
we will copy a pre-created class. To do this, enter ZCL_Group00_PM_EntryList_DO in
the Object type field, and click the Copy icon to the left of the field.
In the Copy To field, type in ZCL_GroupXX_PM_EntryList_DO, where XX is your
training login number. For example, Training02 would use
ZCL_Group02_PM_EntryList_DO. Click the green check mark to continue.

When the Create Local Object Directory window appears, click the [Local Object]
Working With The Mobile Integration Settings 75
button to finish, without filling in any of the fields. You are returned to the Class Builder:
Initial Screen, with the Object type field filled in with your newly-created class.

Step 2 - Review and Compile the Class


In this step, the instructor will walk you through some of the details of the
GET_COMPLEX_TABLE class method and its code. Once you are familiar with the basic
explanation, you will activate the class in SAP, which compiles it. Press the [Change]
button to view the details of the newly-created class.
The GET_COMPLEX_TABLE method retrieves data for the complex table that is then
stored on the Client. Find the GET_COMPLEX_TABLE line item in the table and
76 Working With The Mobile Integration Settings

double-click it in order to view its code. An example of what you should see is shown
below. Note that you may not see the exact code as shown in the example.

This method accepts parameters from both the BAPI and the SMART Mobile Suite
Administration component, or Configuration portal. The parameters control the behavior
of the method. The method runs a SQL query against the SAP database in order to obtain
the entry list data. The data is organized in a return table and returned to the BAPI. In this
Working With The Mobile Integration Settings 77
tutorial, our method does not have to accept any parameters from the BAPI or the
Configuration portal.
Once you are done scrolling through the method code, close the code display window and
return to the Class Builder: Initial Screen.
Click the [Activate] icon button in order to compile the new class:

The Inactive Objects window displays. Click the green check mark, or [Enter], button to
complete the compilation process.

Step 3 - Create a New BAPI for the New Class Handler


In order to create a new BAPI in SAP, you will use the Function Builder. Enter SE37 in the
command field, or use the shortcut available in the Favorites menu, if available. Normally,
78 Working With The Mobile Integration Settings

you would create a new BAPI for your new complex table, but for this training class, you
will copy a pre-created class.

Enter Z_GROUP00_PM_CTENTRYLIST_GET into the Function Module field and press


the Copy icon.

Enter Z_GROUPXX_PM_CTENTRYLIST_GET into the To field where XX is your log in


number and press the [Copy] button.
If required, create the local object when prompted.
Working With The Mobile Integration Settings 79
Step 4 - Modify the BAPI Code
Now you have to modify the BAPI code, in order to reflect the name of the new BAPI. In
this step, you are going to replace the ‘XX’ found in the code with your log in number found
in your training packet.
From the main Function Builder screen, click the [Change] button. Scroll down to the
Constants section and replace the XX in the line with your log in number, as
demonstrated in the following example:
CONSTANTS: lc_bapi_name TYPE funcname VALUE
'Z_GROUP02_PM_CTENTRYLIST_GET'.
NOTE: Double-click the line in the Template Section and click through the warnings that
appear to view the BAPI template that is called by this BAPI class. All BAPIs in all SMART
Mobile Suite applications use the template, so no additional code is required.
Click the Activate icon activate the changes. The Inactive Objects window displays.

Click the green check mark to compile the class and activate the object.
80 Working With The Mobile Integration Settings

Exercise B: Create a Mobile Data Object

Now that a new complex table, new class, and new BAPI are created, you need to set up the
configuration so that you can link them together. This involves creating an MDO configuration
and a BAPI wrapper assignment. Both of these are created through the Configuration portal
of the Administration Component.
To extend the existing framework of a SMART product, Syclo advises you to create a copy
of the MDO you are modifying by using the Z namespace in SAP. These copies are then
referred to as Z-MDOs. This ensures that you can undo any changes made to the application
without having to reinstall it in the future.

Step 1 - Create a New Mobile Data Object


Click on the Configuration portal menu item in the Favorite menu list in SAP to open the
Configuration portal, if it is not already open from a previous lesson. From the
Configuration portal home page, click on the Mobile Data Object Configuration link.

Click the [Create] button and fill out the fields as follows:
Working With The Mobile Integration Settings 81
NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Mobile Data Object ID: Z_GROUPXX_ENTRY_LIST
 Description: GROUPXX_ENTRYLIST
 Data Object Type: Complex Table
 Mobile Application: Syclo SMART Mobile Suite - Work Manager 5.1
 Data Object Handler: ZCL_GROUPXX_ENTRYLIST_DO
 Get Method: GET
 Data Object Active: True (checked)
Click the [Save] button to save the MDO to the list. You can expand the list to see your
MDO in the CT - Complex Table list, along with the MDOs created by other members in
your class.
82 Working With The Mobile Integration Settings

Exercise C: Create a BAPI Wrapper Assignment

The BAPI wrapper is the interface through which the SMART Server calls into the SAP
components. By default, whenever you create a new BAPI wrapper, a default MDO is
Working With The Mobile Integration Settings 83
assigned. You can assign multiple MDOs to the BAPI, though we will not do that for this
exercise.

Step 1 - Copy the BAPI Wrapper


Return to the main Configuration portal page by selecting the ConfigPanel Home link
from any sub-page, if you are not already at the main page. Once at the main page, click
the BAPI Wrapper Configuration link.

Click the [Create] button. Click the box to the right of the BAPI Wrapper Name field.
84 Working With The Mobile Integration Settings

In the Function Module field, type in Z_GROUPXX*, where XX is your log in number. Note
that the asterisk must also be included in the text string. Click the [Start Search] button.
From the list of returned BAPI wrappers, highlight the row that matches your BAPI and
click the [Copy] button. Notice that all the read-only fields in the General tab in the BAPI
Wrapper Detail pane are automatically filled in.

Step 2 - Create the BAPI Wrapper Assignment


Click the Assignment tab. Notice that here, too, the read-only fields are automatically
filled in with the copied BAPI wrapper’s information. You are now going to assign the MDO
you created in the previous exercise to this BAPI wrapper.

Fill in the fields as follows:


Working With The Mobile Integration Settings 85
NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Mobile Application: Syclo SMART Mobile Suite - Work Manager 5.1
 Mobile Data Object ID: CT-GroupXX_ENTRYLIST
 Description: GROUPXX_ENTRYLIST
 Method Type: Get Method
 Active Flag: True (checked)
Click [Save] to save the new BAPI wrapper assignment.
86 Working With The Mobile Integration Settings

Exercise D: Create a Complex Table and Java Logic in Agentry

Once the synchronization components are created for SAP, it is time to create the definition
for the mobile application. Definition creation includes creating a complex table definition,
Java synchronization classes, and logic, in order to work with SAP components. Your first
step is to create the table definition and the SAP connection.
Syclo recommends naming all newly-created complex tables with a ‘Z’ in front of the name.
In this way, it is obvious which tables were created after the application was provided to the
customer. We will be using this Z-naming method throughout this tutorial, starting with this
lesson.
Working With The Mobile Integration Settings 87
Here, you will create your first Java class associated with the complex table.

Step 1 - Create the Z_EntryList Class


In the Java perspective in Eclipse, navigate to the appropriate package (your instructor
will guide you, as this could change). Right-click and select New | Class. Fill out the fields
as shown below.

Click [Finish].
In the new tab for the newly-created class, delete any code. Copy or type the code from
the EntryList.java file found in your Exercise Code folder on your PC into this new
88 Working With The Mobile Integration Settings

class file. Save the file in Eclipse.

Step 2 - Create the Complex Table


In the Agentry perspective, click in the Complex Tables tab of the project and start the
wizard to add a new complex table with the following properties.
 Connection: SAP JavaConnection via Java Virtual Machine
 Name: Z_CTEntryList_XX (where ‘XX’ is your log in number)
 Display Name: Entry List
 Description: This is a new Java Complex Table
Working With The Mobile Integration Settings 89

Exercise E: Create Entry List Table Fields and Indexes

Now that the complex table and the Java classes are created, we can return to the complex
table definition in order to create the complex table fields and indexes. These fields define the
data for the records of the table, as well as the structure of that data for search and sorting
behaviors at run time.

Step 1 - Add a Field to the Z_CTEntryList Complex Table


Make sure you are in the Agentry perspective. Navigate to S4SAPWM | Complex Tables
| Z_CTEntryList and select the Fields tab. Click the Add icon to add a new field. Fill out
the fields as shown in the example below.

Click the [Finish] button to close the wizard and save the field settings. Create the
following fields using the same method.
 Name: EntryListID
 Display Name: ID
 Type: ASCII String (case-insensitive)
 No. of Characters: 24
 Name: EntryListName
 Display Name: Name
 Type: ASCII String (case-insensitive)
 No. of Characters: 20
 Name: EntryListNum
 Display Name: Entry Number
 Type: ASCII String (case-insensitive)
 No. of Characters: 12
 Name: PointID
 Display Name: Point ID
 Type: ASCII String (case-insensitive)
90 Working With The Mobile Integration Settings

 No. of Characters: 12

Step 2 - Define the Complex Table Indexes


In the Z_CTEntryList complex table, click on the Indexes tab, and click on the Add
button to add a new index. Fill out the index fields as shown below.

Click the [Finish] button to close the wizard and save the index settings. Create the
following indexes using the same method.
 Name: EntryListIDIdx
 Display Name: ID
 Field: EntryListID
 Name: EntryListNameIdx
 Display Name: Name
 Field: EntryListName
 Name: EntryListNumIdx
 Display Name: Entry Number
 Field: EntryListNum
 Name: PointByEntryListNameIdx
 Display Name: Point By Name
 Field: PointID
 Parent Index: EntryListName
 Name: PointByEntryListNumIdx
 Display Name: Point By Entry No.
 Field: PointID
Working With The Mobile Integration Settings 91
 Parent Index: EntryListNumIdx
 Name: PointIDIdx
 Display Name: Point ID
 Field: Point ID
92 Working With The Mobile Integration Settings

Exercise F: Assign a BAPI Wrapper to a Complex Table in Agentry

Depending on the configuration in JavaBE.ini, a BAPI wrapper can be assigned to a complex


table either through the Configuration portal or through the JavaBE.ini file. This exercise
shows you how to do it either way.

Step 1 - Assigning a BAPI Wrapper through the INI File


If the source parameter of the [CONFIG] section is configured to use the INI file, then the
following section of the JavaBE.ini file must be maintained:
[CT_BAPI_WRAPPER]
Z_CT_ENTRYLIST_00=Z_GROUP00_PM_CTENTRYLIST_GET
Where Z_CT_ENTRYLIST_00 is the complex table created in Agentry and
Z_GROUP00_PM_CTENTRYLIST_GET is the SAP BAPI wrapper that fetches the entry list
data.

Step 2 - Assigning a BAPI Wrapper through the Configuration Portal


If the source parameter of the [CONFIG] section is configured to use SAP, then the BAPI
wrapper must be assigned using the Configuration portal. Launch the Configuration portal
and click on the Mobile Application Configuration link. Then, click on the Parameters tab.
Working With The Mobile Integration Settings 93
Make sure that SMART_WORK_MANAGER_50 is selected in the Defined Mobile
Applications panel to the left. Click on the [Change] button.

Maintain the following parameters:


 Parameter Group: CT_BAPI_WRAPPER
 Parameter Scope: Application
 Parameter Name: Z_CT_EntryListXX (This is the name of the complex table that
you gave it in Agentry)
 Parameter Value: Z_GROUP00_PM_CTENTRYLISTGET (SAP BAPI wrapper
name)
 Comment: BAPI_WRAPPER defines the BAPI name used by Java class
 Active Flag: checked
 No Runtime Change: checked
94 Working With The Mobile Integration Settings

Exercise G: Assign a POJO to a Complex Table

Depending on the configuration in JavaBE.ini, a BAPI wrapper can be assigned to a complex


table either through the Configuration portal or using the JavaBE.ini file. This exercise shows
you how to do it either way.

Step 1 - Assigning a POJO through the INI File


If the source parameter of the [CONFIG] section is configured to use the INI file, then the
following section of the JavaBE.ini must be maintained:
[CT_SAPOBJECT]
Z_CT_ENTRYLIST=com.syclo.sap.workmanager.customer.object.Z_EntryL
ist
Where Z_CT_ENTRYLIST_00 is the complex table and
com.syclo.sap.workmanager.customer.object.Z_EntryList is the
corresponding POJO that maps the SAP fields to the complex table properties.

Step 2 - Assigning a POJO through the Configuration Portal


If the source parameter of the [CONFIG] section is configured to use SAP, then the POJO
must be assigned to the complex table in the Configuration portal. Launch the
Configuration portal and click on the Mobile Application Configuration link. Then, click on
the Parameters tab. Make sure that SMART_WORK_MANAGER_50 is selected in the
Defined Mobile Applications panel to the left. Click on the [Change] button.
Maintain the following parameters:
 Parameter Group: CT_SAPOBJECT
 Parameter Scope: Application
 Parameter Name: Z_CT_EntryList (Name of the complex table as you configured
it in Agentry)
 Parameter Value: com.syclo.sap.workmanager.customer.object.Z_EntryList
(This is the POJO)
 Comment: Write an optional description of the purpose of the complex table here
 Active Flag: Checked
 No Runtime Change: Checked
5 Administration Component: Change Detection Layer
96 Administration Component: Change Detection Layer

Change Detection Layer Overview


Within the Administration Component there are two layers, the business logic layer and the
change detection layer. The change detection layer includes the following elements:
 Change Detection Configuration Set: The change detection configuration set
includes the tools and utilities to configure the elements and objects within the change
detection layer.
 Syclo Delta Detection Routines: The Syclo delta detection routines are the triggers
and logic put in place to detect modifications made to the business objects of concern
to the mobile application. Notification of a change is provided by the enhancement
framework implementation, which monitors the business data in the SAP application.
The logic in the delta detection routines then determines if the change is one of
concern to the mobile application. If it is, these routines update the exchange table or
tables related to that business object indicating it has been modified.
 Syclo Mobile Exchange Persistent Layer: The Syclo mobile exchange persistent
layer contains the tables that store changes to the business objects of concern to the
mobile application. Information includes the unique identifier of the business object
and the date and time of its last modification. These records are updated and
maintained by the Syclo delta detection routines. The information stored in the
exchange persistent layer is used during synchronization by the exchange logic within
the mobile data objects found within the business logic layer.
The overall purpose of the change detection layer is to detect and track changes made to the
business objects of concern to the mobile application. This can include items such as work
orders, service orders, material items, etc. Changes can include new instances of the objects,
modifications to an object’s data, or removal of the object instance. When a change occurs,
the unique identifier of the modified business object and the system date and time are noted.
This information is then used during synchronization as a part of the overall exchange data
method to determine what data updates are needed for a given mobile client.
Administration Component: Change Detection Layer 97

Lesson 10: Exchange Object Configuration Settings


In this lesson, the exercises provide step-by-step instructions on navigating through the user
interface of the SMART Mobile Suite Administration Component, specifically those screens
related to the change detection layer. This includes the exchange object configuration and
the Enhancement Framework trigger implementation assignments.
In the main Configuration portal, there are a series of links grouped together in different
areas. These include:
 Framework Settings
 Mobile Application Settings
 Security Settings
In this lesson, we will focus on the sub-group Backend Change Detection Settings within
the Mobile Application Settings group. There are two links within the Backend Change
Detection Settings:
 Exchange Object Configuration
 EFI Assignment

Exchange Object Configuration


The Exchange Object Configuration link navigates to the main configuration page for the
exchange objects within the Administration Component. Here, existing exchange objects are
viewed and modified. You can also create new exchange objects.
There are five main sets of attributes to a configuration object, some of which may or may not
apply to a given exchange object. Which attributes are necessary depends on the type of data
being synchronized for the mobile application. These five sets of attributes include:
 Technical Settings: These attributes specify the general nature of the exchange
object, including to which mobile application the exchange object applies, the
functionality application area within the SAP application, the exchange table,
exchange object handler, and the exchange lock object.
 Change Detection Field Selection: This set of attributes lists the table(s) and the
field(s) within them to be monitored by the exchange object. Changes made to the
business object within the SAP application to fields listed here are then processed by
the exchange object. If changes are made to the table specified, but not to one of the
fields listed, the change is ignored by the exchange object, as it is not one of concern
to the mobile application.
 Change Detection Condition Filter: This set of attributes lists one or more filters,
when needed, to interrogate the type of change made to the table monitored by the
exchange object. Defined conditions can filter out certain types of changes when
necessary. For example, a filter may exist to look at the value of a field when changed.
If this value is not within a specified range, the change is filtered out, meaning the
exchange object ignores the modification.
 Linkage Settings: This set of attributes lists links between the current exchange
object and other exchange objects. Linkage settings are used for more sophisticated
98 Administration Component: Change Detection Layer

change detection, when a change to the table for the current exchange object requires
processing specific to it, as well as to other change detection processes. As an
example, if an equipment record is modified, it may be necessary to also modify any
work orders for that piece of equipment. A link can then exist between the exchange
object for equipment and for work orders.
 Push Settings: The only attribute here is Push Relevant, which can be checked or
not. When checked, this exchange object is used in push processing, part of the
real-time communications functionality available within the Agentry Mobile Platform.
Push synchronization processing is handled differently than processing items such as
fetches or complex tables.
In general, an exchange object is created for an object collection, complex table, or data table
within the mobile application. However, it is possible to have a single exchange object for
multiple definition instances if an existing exchange object serves the needs of those
definitions.

EFI Assignment
The Enhancement Framework Implementation (EFI) provided by SAP allows you to make
code enhancements to an SAP application. The SMART Mobile Suite Administration
Component uses this framework in the change detection layer to create triggers on tables
within the SAP application.
A trigger monitors a table in the SAP application for changes. When a change is made, the
trigger can then notify one or more exchange objects about the change and provide the data
changes made to that exchange object. For new records, this includes the new record. For
updates to existing records, this includes the record’s field values both before and after the
change, and an indication of which specific fields were modified.
The link for the EFI Assignment displays a screen where all EFI triggers are listed. Select a
given trigger to display its current exchange object assignments. Each exchange object to
which the trigger is assigned is notified by that trigger of the modification. It is then up to the
exchange object to decide if and how to process the modification.
Administration Component: Change Detection Layer 99

Exercise A: Navigating the Exchange Object Settings


In this exercise we will not make any changes to the elements within the Administration
Component. Rather, we will walk through the navigation of those elements within the Change
Detection Layer to familiarize you with the overall layout of this portion of the Administration
Component’s user interface.

Step 1 - Log in and View the Configuration Portal.


Begin by opening a web browser and navigating to the URL provided to you by the
instructor. Log into the SAP system using the credentials also provided. Once connected,
the main Configuration portal home page is displayed:

As shown in this example, there are three main sets of links. Of these, the Mobile
Application Settings group is where the bulk of our time will be spent. For this exercise we
will focus on the Backend Change Detection Settings section of links, which includes
the Exchange Object Configuration and EFI Assignment links.
Note the drop-down list in the upper-right corner labeled Mobile Application Filter. When
multiple mobile applications from the SMART Mobile Suite are installed, by default all
elements for all applications are displayed in the configuration pages. If working with a
single mobile application, you may want to filter those items displayed that application.
Select any of the installed applications in this drop-down list. You can change your
selection or list all elements for all installed applications at any time on the main
Configuration portal page.
100 Administration Component: Change Detection Layer

Step 2 - Exchange Object Configuration: Technical Settings


Click the Exchange Object Configuration link to display the Exchange Object settings
page:

When initially displayed, the fields on this page are empty. It is possible to create a new
exchange object at this point by clicking the [Create] button at the top of the screen. To
view the details of an existing exchange object, select it in the list on the left of the screen
by first expanding the application area to which the exchange object applies, and then
selecting the specific exchange object.
When an exchange object is displayed, additional buttons are enabled at the top of the
screen. [Copy] allows for the creation of a new exchange object that is initially an exact
copy of the one currently highlighted.
The [Delete] button removes the current exchange object. Use the [Change] button to
make changes to the exchange object settings. The default display of the page is
read-only, and you must click the [Change] button to edit the settings shown here.
Note the series of tabs below these buttons. Each displays a group of attributes or related
items for the exchange object. The first is Technical Settings, shown in the previous
example. These settings primarily specify the basic information for the exchange object
as well as the other elements within the Administration Component with which it works or
affects.
You can change any value for an existing exchange object with the exception of the
object’s name. Note that when creating a new exchange object, the other referenced
items must already exist, including the exchange table, the lock object, and the exchange
object handler, before they can be referenced in the new exchange object.
Administration Component: Change Detection Layer 101
Step 3 - Exchange Object Configuration: Change Detection Field Selection
Select the tab Change Detection Field Selection. Displayed here are the fields, grouped
by table, that the exchange object looks to for changes:

Within the main list of this page are each of the tables, and under those each of the fields
within those tables that concern the exchange object. You can select or deselect each
field within a table through the Active Flag checkbox. When selected, the exchange
object looks for changes to that field based on information sent to it by the EFI trigger.
If the change made to the table does not include changes to one of the fields selected in
this list, the change is ignored. Fields not selected for change detection are those that are
not a part of the data for the mobile application, or in some cases, are not deemed
important enough to warrant updating the data on the mobile clients.
Selecting the proper fields in this list is a key task in the proper configuration of the
exchange object.
102 Administration Component: Change Detection Layer

Step 4 - Exchange Object Configuration: Change Detection Condition Filter


In addition to determining which fields were modified and deciding whether any action
should be taken, the exchange object can also filter out modifications unimportant to the
mobile application based on how the data has been changed within a given field.
Select the Change Detection Condition Filter tab:

The condition filters for an exchange object are created for fields within a table for the
exchange object. As shown in the previous example, the filters defined for the exchange
Administration Component: Change Detection Layer 103
object are listed and can be selected. When a filter is selected, its details are displayed
on this same page:

Filters are made up of one or more rules. In this example, there are no rules defined for
the filter, which is typical of many of the filters for the standard exchange objects as
provided by the installer. These filters are place holders and, with no rules, have no effect
on the behavior of the exchange object.
When a filter does contain rules, those rules can determine the nature of the change to a
field. As an example, if the new value is within a certain range, it is treated as a change of
significance. If outside this range, it is ignored. Or, if is equal to a set value, it may be
important, such as the type of work order created. An emergency work order may be one
of importance to push processing, while other work order types are not. Therefore, a filter
may exist on the exchange object for work order push scenarios that filters out new work
orders unless the work order type is emergency maintenance.
Within this screen, a rule is added to the filter by first selecting the field and the Sign, or
comparison type. The pertinent values are then entered for comparison to the value of the
selected field. Once complete, the rule is added to the filter. You can add other rules to
the same filter, which results in an AND relationship, meaning all rules must be true in
order for the change to process.
In the list of filters on this page, those with active rules are denoted with an asterisk (*)
after their names.
104 Administration Component: Change Detection Layer

Step 5 - Exchange Object Configuration: Linkage Settings


It is possible to link one exchange object to another. A linkage causes the first exchange
object to notify the second when it has processed a change. The second exchange object
may then also process this change in relation to the business object of concern to it.
To view the linkage settings for an exchange object, which includes a list of the exchange
objects to which the current one is linked, select the Linkage Settings tab:

Many exchange objects will not have a list of items here, as most do not require any link
to other exchange objects. When a link does exist, it is listed on this screen in the Linked
Exchange Object List.
In the above example, the link is between the exchange object for equipment and the one
for work orders. When a change is made to an equipment record in the SAP database, it
is processed by the equipment exchange object. The work order exchange object is then
notified of the change, so that it can update any work order exchange records for work
orders that were created for that piece of equipment.

Step 6 - Exchange Object Configuration: Push Settings


The Push Settings tab displays the single setting Push Relevant. When this item is
checked, the exchange object’s processing is relevant to at least one push scenario within
the system. You can select this tab now to view this page.
Administration Component: Change Detection Layer 105

Lesson 11: EFI Assignment Configuration Settings


The Enhancement Framework Implementation (EFI) configuration settings are used primarily
to assign the exchange objects to the EFI. You can assign a given EFI to one or more
exchange objects. The assignment of the EFI indicates that when a change occurs in the SAP
database, the assigned exchange object(s) are notified of the modification, including
information about the type of change made, possible insertion of a new record, updating an
existing record, or deleting a record.
The EFI does not perform any filtering or other processing of the data changes related to the
mobile application. It is limited to notifying the exchange object of the change and providing
the information about the modification.
This information can include the following, based on the type of change made:
 Inserting a Record
The record that was created is passed to the exchange object, including all
values inserted with the record
 The system date and time of the record creation
 Updating a Record
 The old and new revisions of the record
 The record’s key values
 The system date and time of the change
 Deleting a Record
 The key values of the deleted record
 The system date and time of the record deletion
106 Administration Component: Change Detection Layer

Exercise A: Navigating the EFI Assignment Settings


In this exercise, we will navigate through the EFI assignment settings, though we will not
make any changes. Rather, the general navigation of this area of the Administration
Component, as well as the basics of making changes are discussed.

Step 1 - Navigate to the EFI Assignment Configuration Settings


Begin by opening a web browser and navigating to the URL provided to you by the
instructor. Log into the SAP system using the credentials also provided. Or, if already
logged into this interface, click the link ConfigPanel Home located in the upper left corner
of the current page. The main Configuration Panel home page is displayed:

Within the section Backend Change Detection Settings, select the link EFI Assignment.
Administration Component: Change Detection Layer 107
Step 2 - EFI Assignment Detail: General Settings
When the EFI Assignment Detail screen is displayed, it is initially empty. Selecting an
Enhancement Implementation Include from the tree control on the left will display it
settings in this screen:

The settings listed in the General tab contain the EFI include name, a description, and the
package to which the EFI assignment belongs. Typically these items are set when the EFI
assignment is created and are not modified again.
108 Administration Component: Change Detection Layer

Step 3 - EFI Assignment Detail: Assignment Settings


Next select the Assignment tab. This displays the EFI Assignment settings for the
selected Enhancement Implementation Include:

Displayed on this screen is the EFI Assignment List of the exchange objects to which
the EFI is assigned. As shown in this example, a single EFI can be assigned to one or
more exchange objects. When a change occurs to the table monitored by the EFI, each
of the assigned exchange objects are notified provided that the assignment is active. This
is denoted in this list in the Active Flag column, with a check mark indicating the
exchange object assignment is active.
Below this list are the settings related to the exchange object assignment currently
selected in the EFI Assignment List. These Assignment Details include:
 Mobile Application: The mobile application in which the exchange object resides.
 Exchange Object and Description: The exchange object and its description to
which the EFI is assigned.
 Active Flag: Indicates whether or not the assignment is active. Exchange object
assignments will result in the EFI not notifying the exchange object of any changes.
To add a new assignment, first click the [Change] button. Then, in the assignment list,
click the [Add] button. The Assignment Detail fields are then enabled, and the you can
Administration Component: Change Detection Layer 109
select the settings. Once your changes are saved, the EFI will notify the exchange object
of any changes made to the table it monitors.
An existing EFI Assignment can be edited by clicking the [Change] button and then
selecting the assignment to edit in the Assignment List. The Assignment Detail fields are
then enabled and the values can be changed as desired. Typically this is done to set or
un-set the Active Flag value.
110 Administration Component: Change Detection Layer
6 Working With the Change Detection Layer
112 Working With the Change Detection Layer

Change Detection and the Exchange Data Model


When working with the synchronization logic and components of an application within the
SMART Mobile Suite for SAP® Systems, it is necessary to consider how any modifications
will affect the synchronization logic. Within these applications, much of this data is
synchronized using the Exchange Data Model of synchronization.
The exchange data model is used to support incremental updates to the data stored by a
given Client application. Use of the exchange data model results in the retrieval of only
changed data from the SAP system, rather than retrieving all data for a Client during each
transmit. This model of synchronization is supported by the platform, Agentry, upon which the
applications within the SMART Mobile Suite are built and deployed.
The key steps in the exchange data model include the following:
1) The SMART Client must provide information about the data it currently contains. This
information includes the key identifier for each data item (object key property, complex
table record key field, etc.) and the date and time when that item was downloaded.
2) The SMART Server compares the information about the SMART Client’s current data
with information about the data stored in the SAP system. Differences in either the
items the Client contains and those found in the SAP database, or data contained in
both the Client and database, but was modified since the time when that data was
previously downloaded to the Client, are tracked by the processing executed by the
SMART Server.
3) The SMART Server processing determines and records any data found on the SMART
Client, but that is in a state in the database that dictates it should no longer exist on
the Client.
4) The data items determined to be needed by the SMART Client due either to their
creation since the last transmit by the SMART Client, or due to changes made to that
data since its last retrieval for that Client must be retrieved from the database by the
SMART Server processing. This data is then used to instantiate objects or table
records by the Server to send to the Client.
5) The key identifiers for those data items in need of removal from the SMART Client are
retrieved by the processing of the SMART Server, which sends them to the Client with
instructions to delete those data items (object instances or table records).

Exchange Data Model in the SMART Mobile Suite for SAP® Systems
Within the SMART applications, the use of the exchange data model involves the above
processing, implemented using the components and elements specific to this suite. The key
pieces to this processing include:
 The exchange object within the SMART Mobile Suite Administration Component that
evaluates and processes changes to the database.
 The EFI trigger that notifies the exchange object of changes to the database.
 The mobile data object within the SMART Mobile Suite Administration Component that
retrieves data from the database, using information generated by the exchange object
concerning which data to retrieve.
Working With the Change Detection Layer 113
 The definitions within the Agentry application project responsible for retrieving data
from the SAP database through the mobile data object.
 The last update information and key identifier values of the data instances contained
on the device prior to the beginning of a transmit.
The EFI trigger and the exchange object for a given data component of the mobile application
work to track changes made to the database. This information is then used by the mobile data
object’s GET method to determine the data to retrieve, comparing it to the information
provided by the mobile application about the data currently stored on the Client.
The EFI trigger and exchange object elements of the SMART Mobile Suite Administration
Component are a part of what is termed the Change Detection Layer. These two components
are constantly monitoring and processing changes to the database, with the exchange object
tracking changes by recording them in an exchange table. The records of this table are then
referenced later by the mobile data object’s GET method to retrieve data.
In the lessons of this chapter, we will focus on working specifically with the exchange object,
modifying it to track changes beyond those processed by the default configuration of the
Work Manager application.
114 Working With the Change Detection Layer

Lesson 12: Round Trip Using the Exchange Process


In the following exercise, you will make a change to a material listed in your warehouse in
order to demonstrate how the exchange table works in the SMART application. A change in
the material’s description is logged in the exchange table, and when the Client performs a
transmit with the Server, the Server uses the table to push down only the changed material
entry back to the Client.
Working With the Change Detection Layer 115

Lesson 13: Detecting Additional Object Changes: Exchange Object Fields


The applications within the SMART Mobile Suite are configured with the most common
change detection settings, typically applicable to most or all customers. However, there are
several situations in which adjustments to these settings are necessary. One of the most
basic is the need to track changes made to a field within the database beyond those fields
tracked by default.
To process an additional type of change to the database, you modify the exchange object
responsible for tracking changes to the business entity’s data. Specifically, you activate the
field in the field catalog list for the exchange object. These fields are the change detection
fields for the exchange object.
Changes passed to the exchange object by the EFI trigger are only processed if the change
is to the values of one or more of the fields currently selected (considered active) within that
exchange object. If the change involves only field values that are not currently active, the
change is ignored by the exchange object. This is desired behavior, as it supports the data
filtering that is a part of any mobile application deployment.
When the data stored by the SMART Client needs an update to reflect a change made to the
database, the fields that are modified as a result of that change must then be active within the
exchange object. As stated, many of the common fields are already active in the default
configuration of the applications. However, you can activate an additional field or fields when
needed.
When activating a new field for an exchange object, it is also important to consider the type
of changes to make. In some cases, the value of the field may also be one that should be
interrogated prior to tracking and recording the modification. An existing example of such a
behavior is the category of a work order and its effect on the synchronization of the Work
Manager application.
The default configuration of Work Manager includes a filter within the
SWM50_WORK_ORDER exchange object. This object currently filters out changes made to
work orders of any type other than Maintenance Order. When a change is processed by the
exchange object, if the affected work order is not a maintenance order, the exchange object
ignores the modification and no information is written to the exchange table.
In this lesson, the SWM50_WORK_ORDER exchange object is modified to include the
processing of changes made to a field within the database that is ignored by the default
implementation of the application. This also includes the creation and configuration of a rule
and rule filter associated with that field.
116 Working With the Change Detection Layer

Exercise A: Create an Exchange Object


When you created a complex table in the previous set of exercises, you created a fetch for
data to fill a complex table for an entry list. In this set of exercises, you will create an exchange
object for the table to monitor the data and fetch only the changed data.
During synchronization of the mobile application with SAP, the mobile data object uses the
exchange table maintained by the exchange object to determine the changes considered
important. The data retrieved and sent to the Client reflects all changes and additions since
the mobile Client’s last transmit. Unchanged data is not retrieved again, as it already exists
on the Client and does not need to be replaced or updated.
Without an exchange object, if data in an entry list changes, there is no way to determine what
changed. Therefore, to ensure data integrity on the Client, a fetch would bring down all data
on the entry list on every transmit, which is inefficient and unnecessary. The exchange object
ties together all the components involved in the exchange process.
During the exchange process, information is added to the exchange table while SAP is saving
to its data table. The exchange table becomes the record for what has changed since the last
transmit on the Client. SMART Mobile Suite provides a standard structure for these exchange
tables that are sufficient for most uses. However, you can configure these tables to suit your
business needs.
There are four separate components involved in adding an exchange object:
 EFI (Enhancement Framework Implementation) trigger, used to update the exchange
table with SAP data tables
 Class handler, called ex.classhandler
 Exchange table, one dedicated table for each SAP object
 Exchange object, referenced by one or more MDOs
The EFI injects into SAP and calls ex.classhandler to update the exchange handler. The class
object creates a link between the EFI and the data table so that the EFI knows which class
handler to call. In order for this to happen, creating an exchange object requires these four
steps:
1) Create an exchange table
2) Create an exchange class handler
3) Create an EFI
Working With the Change Detection Layer 117
4) Create a configuration object

Step 1 - Review the Exchange Table in SAP


Normally, you would create a new exchange table. However, for the purpose of this
course, an exchange table already exists. To view the table, enter the transaction code
SE11 in the command field in SAP to launch the ABAP Dictionary Initial screen.

In the Database table field, enter Zsyc_XX_melnr_EX, and click the [Display] button.
Be sure to enter your log in number in place of the XX in the field name. The Dictionary:
Display Table screen appears.
118 Working With the Change Detection Layer

Notice the Field column, the indicator columns, and the CHANGED_TS, or changed
timestamp row. These are all indicators to point to what object changed, how it changed,
and when it changed. Your instructor will go over more of this table, verbally, with you in
class.

Step 2 - Create the Exchange Object Class Handler


Return to the main screen in SAP and enter SE24 in the command field at the top of the
screen to access the Class Builder screen. In a real-world environment, you would
normally create a new class, but for this course, you will copy a pre-existing class.
In the Object type field, enter ZCL_GRP00_PM_MELNR_EX_HNDLR and press the Copy
icon.
In the Copy to field that displays in the pop up window, enter
ZCL_GRPXX_PM_MELNR_EX_HNDLR, where XX is your log in number. Click the green
check mark to continue.
Click the [Change] button to view the details of the class you created. Then click the
Activate icon to activate and compile the class.
Working With the Change Detection Layer 119
Step 3 - Review the Code for the New Class
Click the [Display] button display the code for the newly-created class.

What you are viewing is a copy of the standard exchange class handler that is delivered
with the SMART application. It is capable of handling the exchange table system.
The methods in blue text indicate that the method is using predefined methods in the class
that are passed down from the parent class. Methods in black text indicate that they have
been overridden and are different than the parent.
There are two override methods in this class. Double-clicking on either method (or any
row) displays its code. Since the standard class is generic, you need to specify what you
need to monitor for your exchange process. The SMART Mobile Suite architecture allows
you to define field-level change detection. Since only a subset of SAP’s data is sent to the
SMART application, it only needs to monitor that subset for changes, and the exchange
120 Working With the Change Detection Layer

process only needs to monitor fields relevant to the application. This allows the exchange
table to tell not only if data has changed but also if it is relevant to the Client application.
Fields are specific for each data object, so the first override method contains only the list
of fields that are relevant for this data object. The second override method supports
additional criteria for filtering. Using filters, you can filter changes that only apply to certain
filter settings. For instance, you can filter data to bring down only changes that are
relevant to a specific mobile application, such as only certain types of work orders,
inventory in a certain location, etc.

Step 4 - Create the EFI Include


Now you will embed an EFI include into SAP’s program code. This EFI include will update
the exchange table, along with SAP’s data table whenever any relevant data is changed.
Working With the Change Detection Layer 121
Normally, you would create a new EFI include, but for this course, you will use a
pre-created program.
Return to the main SAP screen and enter SE38 into the command field. This launches the
ABAP Editor: Initial Screen.

Type in Z_GROUPXX_PM_EFI_MELNR_EX_INCL, where XX is your log in number, in the


Program field, and click the [Change] button. The ABAP Editor displays.
Uncomment all code in the file and save your changes.
Scroll to the ***Constants section of the file. Replace the value
Z_GROUPXX_PM_EFI_MELNR_EX_INCL with your log in number in place of the XX. Save
the file.
This code is not the EFI itself, but rather a part of the EFI. To make the entire EFI work,
the EFI must be injected into the SAP program. We are not going to alter the specific SAP
program in class, as that is beyond the scope of the class, and the code was already
altered to call the EFI. When you un-commented the code, the EFI became active in the
SAP code.
122 Working With the Change Detection Layer

Step 5 - Create the Exchange Object in the Configuration Portal


From the Configuration portal main page, click on the Exchange Object Configuration
link and click the [Create] button.

Fill in the fields on the General tab as follows:


NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Exchange Object: Z_GROUPXX_EXCHANGEOBJECT
 Exchange Object Description: GROUPXX_ENTRYLIST
 Application Area: Plant Maintenance
 Exchange Object Handler: Select the class exchange handler with your log in
number
 Active: True (checked)
Click the [Save] button.
Working With the Change Detection Layer 123

Exercise B: Create a Trigger Assignment

Once the exchange object is created in the Configuration portal, we need to link it with the
EFI trigger we created in SAP. This is also done through the Configuration portal.

Step 1 - Link the Exchange Object to the EFI Trigger in the Configuration Portal
Return to the Configuration portal main page and click on the EFI Assignment link. Click
on the [Create] button.

Fill in the fields on the General tab as follows:


NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 EFI Include Name: Click the box to the right of the field. In the Program Name
field, type in Z_Group* (including the asterisk), and click [Start Search]. Select
your EFI with your log in number.
Fill in the fields on the Assignment tab as follows:
NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Mobile Application: Syclo SMART Mobile Suite - Work Manager 5.1
 Exchange Object: Z_GROUPXX_EXCHANGEOBJECT
Click the [Save] button.
124 Working With the Change Detection Layer

Exercise C: Assign the Exchange Object to the Mobile Data Object

In a real world environment, you would have the class handler retrieve data for you and then
determine what to do with the data. This has been provided for you for the purposes of this
course. Now that your exchange object and trigger assignments are created, you must assign
your exchange object to one or more MDOs. In this way, it will be part of the synchronization
process.
Working With the Change Detection Layer 125
We will use the Configuration portal to assign the exchange object to the appropriate MDO
for this exercise. In this exercise, you are modifying the MDO for EntryList, so it can use the
new exchange object you created in the previous lesson.

Step 1 - Select the Appropriate Mobile Data Object


Return to the main page of the Configuration portal and click on the Mobile Data Object
Configuration link.

In the left pane, expand the Data Object Navigation Tree under the CT - Complex Table
main heading. Find your Z_GROUPXX_ENTRY_LIST, which uses your log in number
and select it.
Click the [Change] button. Locate the Exchange Object Settings section. Using the
drop-down arrow, select your newly-created exchange object from the list.
Click the [Save] button.
126 Working With the Change Detection Layer
7 Business Logic Layer - Fetches
128 Business Logic Layer - Fetches

Business Logic Layer - Fetches


A fetch defines how the SMART Server synchronizes data for a target object collection. This
object collection must be a top-level collection within the module. A fetch is made up of steps
that retrieve the data for the collection from the back end system. These steps are grouped
into three categories within the fetch definition: Client Exchange Steps, Server Exchange
Steps, and Removal steps. A fetch can also include properties to store data captured from
the user and validation rules for those property values.

Application Data Filter Services


When a data filter function is enabled for a class handler, the option exists to define various
types of filter rules to control what data can be viewed y the mobile application based on a
customer’s business process. In an SAP® environment, each user is assigned a role-based
profile with authorization restrictions for what data is viewed and which activities are to be
performed.
For example, a user who works for a specific plant should not be able to view data for any
other plant. Data filter rules allow you to restrict data access for mobile applications. Data
filters can e user-dependent or applied to the entire mobile application.

Data Object Class Handler Repository


The name of the ABAP OO class handler from Syclo’s class repository is the Data Object
Handler. The ABAP OO Class handler is developed y the application developer with
predefined business logic and scope to perform fetch, create, delete, or update activities for
an SAP business object.
The Data Object Handler Settings section of the Mobile Data Object’s General Settings tab
is used to configure the methods of the mobile data object.
Business Logic Layer - Fetches 129

Exercise A: Create the Reservation Class and BAPI in SAP


For this exercise, you will extend the Work Manager application to fetch reservations for a
specific work order. SAP creates a reservation for the attached components (materials) when
the work order is released. The purpose of a reservation is to ensure that a material is
available when it is needed. It also serves to simplify and accelerate the goods issue process
and to prepare the tasks at the point of goods issue.
As you have seen, the Configuration portal allows you to access objects across all
applications across your systems. Therefore, you can configure, or add on, components, from
one system to another, through the Configuration portal.
NOTE: Keep in mind that because a reservation class is an on-demand function, no
exchange class is needed, unlike in the previous exercise you performed in this tutorial.

Step 1 - Create the Reservation Class


Enter SE24 in the command field in SAP and click the Enter icon to launch the Class
Builder: Initial Screen.
In the Object type field, enter ZCL_GROUP00_MM_RESERVATION_DO and click the Copy
icon. Ordinarily, you would be creating a new class, but for the purposes of this exercise,
you are copying a pre-created class.
In the Copy to field type in ZCL_GROUPXX_MMRESERVATION_DO, where XX is your log
in ID and click the green check mark. When the Create Object Directory Entry window
appears, click the [Local Object] button to finish creating the Reservation object.
Click the [Change] button to view the details of the newly-created Reservation class. After
your instructor explains any important details of the class, click the Activate icon, and
then the green check mark to activate and compile the class.

Step 2 - Create the Reservation BAPI


Return to the main SAP screen, enter SE37 in the command field and press Enter to
launch the Function Builder: Initial Screen. Normally, you would create a new BAPI for
your new class, but for this tutorial, you will use a pre-created BAPI.
In the Function Module field, type in Z_GROUP00_MM_DORESERVATION_GET and click
the Copy icon. When the Copy Function Module window appears, in the To Function
130 Business Logic Layer - Fetches

module field, type in Z_GROUPXX_MM_DORESERVATION_GET where XX is your log in ID


and click the [Copy] button.
Click the [Change] button. Click the Tables tab. Note there are two tables returned with
this BAPI. Your instructor will go into more detail on this. Click back over to the Source
code tab.
Scroll to the *Constants section of the BAPI code.
Replace the 00s in Z_GROUP00_MM_DORESERVATION_GET with your log in ID number.
Click the Activate icon to activate the changes. When the Inactive Objects window
appears, click the green check mark to approve and compile the changes.
Business Logic Layer - Fetches 131

Exercise B: Configure the MDOs and BAPI Wrappers

In a previous exercise, you configured a complex table’s MDO and BAPI wrapper through the
Configuration portal. In this case, a reservation object does not use a complex table, but
rather a data table. Therefore, while we will still be configuring the MDO and BAPI wrapper
using the Configuration portal, we will be using the DO - Standard Data Object section in the
Data Object Navigation Tree when working with the mobile data object configuration.

Step 1 - Create the Mobile Data Object


Log onto the Configuration portal. From the main page, click on the Mobile Data Object
Configuration link. Click the [Create] button and fill out the fields as follows:
NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Mobile Data Object ID: Z_GROUPXX_RESERVATION
 Description: SIM 3.0 - Reservations
 Data Object Type: Standard Data Object
 Get Method: GET
 Data Object Active: True (checked)
Click the [Save] button to save the MDO to the list. You can expand the list to see your
MDO in the DO - Standard Data Object list, along with the MDOs created by other
members in your class.

Step 2 - Create the BAPI Wrapper


Return to the main Configuration portal page and then click on the BAPI Wrapper
Configuration link. Click the [Create] button. Click the box to the right of the BAPI
Wrapper Name field.
In the Function Module field, type in Z_GROUPXX*, where XX is your log in number. Note
that the asterisk must also be included in the text string. Click the [Start Search] button.
Note that your previously-created BAPI from the last exercise was also found in this
search due to using the asterisk as a wildcard character.
Highlight the Z_GROUPXX_MM_DORESERVATION_GET function module row and
press [Copy].
Click the Assignment tab. Make sure the fields are filled out as follows:
132 Business Logic Layer - Fetches

NOTE: Replace ‘XX’ with your log in number in all places shown in the list below.
 Mobile Application: Syclo SMART Mobile Suite - Inventory Manager 3.0
 Mobile Data Object ID: Z_GROUPXX_RESERVATION::DO - SIM 3.0 -
Reservations
 Description: SIM 3.0 - Reservations
 Method Type: Get method
 Active Flag: True (checked)
Click the [Save] button to save the BAPI wrapper.
Business Logic Layer - Fetches 133

Exercise C: Create the Reservation Java Logic in Eclipse

In order to create the Reservation fetch in the Agentry application, you will first need to add
Java files to the source/SAPWM-5.0/src package in Eclipse. Switch to the Java
perspective in Eclipse for this portion of the tutorial.
134 Business Logic Layer - Fetches

Because we are adding on to the original functionality of the SMART application, any Java
classes we create are appended with a ‘Z’ in front of the descriptive name as a best practice.

Step 1 - Add the Java Steplet


Find the Java package com.syclo.sap.workmanager.customer.steplet in the package
list, right-click, and select New | Class to create a new Java class. Fill out the fields as
shown below and click [Finish].

In your Exercise Code folder, open the


Z_GetMaterialReservationSteplet.java file. Copy and paste the code from that
Business Logic Layer - Fetches 135
file into your newly-created class in Eclipse. Save the file.

Step 2 - Add the Java StepHandler


Find the Java package com.syclo.sap.workmanager.customer.stephandler in the
package list, right-click, and select New | Class to create a new Java class. Fill out the
fields as shown below and click [Finish].

In your Exercise Code folder, open the


Z_MaterialReservationStepHandler.java file. Copy and paste the code from
that file into your newly-created class in Eclipse. Save the file.
136 Business Logic Layer - Fetches

Step 3 - Add the Java POJO


Find the Java package com.syclo.sap.workmanager.customer.object in the package
list, right-click, and select New | Class to create a new Java class. Fill out the fields as
shown below and click [Finish].

In your Exercise Code folder, open the Z_MaterialReservation.java file. Copy


and paste the code from that file into your newly-created class in Eclipse. Save the file.
Create another class, named Z_MaterialReservationItem, using the same Package and
Superclass. Use the code from the Z_MaterialReservationItem.java file found in
your Exercise Code folder, and be sure to save the file.
Business Logic Layer - Fetches 137
Step 4 - Add the Java BAPI Class
Find the Java package com.syclo.sap.workmanager.customer.bapi in the package
list, right-click, and select New | Class to create a new Java class. Fill out the fields as
shown below and click [Finish].

In your Exercise Code folder, open the


Z_MaterialReservationFetchBAPI.java file. Copy and paste the code from that
file into your newly-created class in Eclipse. Save the file.
138 Business Logic Layer - Fetches

Exercise D: Create the Reservation Object in Agentry

Objects are synchronized with the back end SAP system through the module-level fetch
definitions. A fetch defines how the Server synchronizes data for a target object collection by
referencing the step definitions in order to perform this task. The fetch is processed during
synchronization between the Client and the Server, resulting in new object instances
retrieved for the target collection, replacement of existing objects within the collection, and
possible removal of objects from the collection. All of these determinations are based on the
definition of the fetch and the child step usage definitions.
In this exercise, we will create the Reservation object, fetch, step, screens, steps, and buttons
associated with the object. In a later exercise we will create two other collections to this
Reservation object, in order to make up the entire reservation fetch and have it work correctly
during the final publish and test phase.

Step 1 - Create the Reservation Object


Make sure you have the Agentry perspective open in Eclipse. Highlight the top-level
Objects, directly under “PM” Module and click the green plus icon to add a new object
with the following attributes:
 Name: Z_Reservation
 Display Name: Reservation
Click [Finish] when done. Note the ‘Z’ in front of the steplet name. When modifying an
application from the standard Syclo-provided application, it is considered good practice to
always preface your changes with a ‘Z’, to easily denote your changes and to roll back if
necessary.
Business Logic Layer - Fetches 139
Step 2 - Create the Reservations Collection
Highlight the “MainObject” Object, as shown in the figure below, and click the green Add
button to start the wizard. Even though we have added a Reservation object, we are now
going to add a Reservations Collection Property to the MainObject object.

Select Collection for the Property Type and click [Next]. Fill out the next wizard screen
as shown below. Notice that in this screen you are using the plural of reservation -
140 Business Logic Layer - Fetches

reservations. It is standard practice to always use the plural format when naming
collections in an Agentry application. Click [Finish] when done.

Normally, a MainObject includes some read steps and transactions. Those will be
included in later exercises.
Now, create an object called Z_ReservationItem under the main Objects section, like
you did in Step 1.
After creating the Z_ReservationItem object, make sure it is highlighted in Agentry, and
click the Properties tab. You are going to add a Properties collection to this object by
clicking the green plus sign icon.

Select Collection for the Property Type and click [Next] in the wizard. Then fill out the
fields as shown:
Business Logic Layer - Fetches 141

Click [Finish] to create the collection within the object.

Step 3 - Create the Server Exchange Step


Click in the Step portion of the SMART application and click the plus icon to add a new
Server Exchange Step as follows:
 Step: Reservation Steps | GetMaterialReservationsSteplet
 Run: Run One Time
 Read Into: None
 Description: [leave blank]
Click [Finish] to add the Server exchange step.

Step 4 - Create the Reservation Fetch


Click in the Fetch portion of the SMART application and click the plus icon to add a new
fetch. Fill out the wizard as shown:

Click [Finish] to create the fetch.


142 Business Logic Layer - Fetches

Step 5 - Define the Reservation Fetch Properties


Click on the Properties tab in the Get_Z_Reservations fetch. Add the following String
properties. If the field is not mentioned, leave the default set as-is:
 Name: Batch
 Display Name: Batch
 Trim: True (checked)
 Name: Material
 Display Name: Material
 Trim: True (checked)
 Name: movementType
 Display Name: Movement Type
 Trim: True (checked)
 Name: Plant
 Display Name: Plant
 Trim: True (checked)
 Name: reqDate
 Display Name: Required Date
 Trim: True (checked)
 Name: reservationNumber
 Display Name: Reservation Number
 Trim: True (checked)
 Name: storageLocation
 Display Name: Storage Location
 Trim: True (checked)

Step 6 - Create the Reservation Screen


Navigate to the Screen Sets portion of the Agentry application. Here, like with Java
classes, objects, and other added components to an application, it is considered best
Business Logic Layer - Fetches 143
practices to always preface a screen set name with a ‘Z’ before the descriptive part of the
name. Click the green plus icon to start the screen set wizard and select the following:
 Displays: Fetch - Get_Z_Reservations
 Name: SearchMaterialReservations
Click [Finish] to add the screen set.
Click the Platforms tab, and start the wizard to add a platform. Make the following
selections, clicking [Next] when necessary. If nothing is listed for a field, leave the default
set as-is or leave the field blank:
 Platform: Windows CE (Pocket PC) Portrait
 Caption: Select Criteria
 Button Placement: Bottom
Click [Finish] to create the screen set platform.
Click the Screens tab and start the wizard to add a detail screen. Make the following
selections. If nothing is listed for a field, leave the default set as-is or leave the field blank:
 Caption: Select Criteria
 Name: MaterialReservations_Detail_PPC
 Rows: 8
Click [Next]. On the Properties screen, add the following properties from the Available
column to the Selected column, so they are in this order:
 “reqDate” String Property
 “reservationNumber” String Property
 “Plant” String Property
 “Material” String Property
Click [Finish] to add the detail screen to the screen set.

Step 7 - Create the Reservation Tab List Screen


During this step, you will create a new tab that displays on the main screen. This tab, when
selected, brings up the detail screen that displays the reservation objects. To create a new
tab, click on the Screen Sets portion of the Agentry application.
If there are a large number of screen sets in an application, finding the main screen set
may be difficult. The easiest way to determine the main screen set is to find it in the
144 Business Logic Layer - Fetches

Properties pane of the application and scroll through the list until you see the Yes in the
Main? column. The main screen set is also usually called MainScreen as a best practice.

When you find MainScreen in the Screen Sets list, double-click it and start the wizard to
add a new list screen. Make the following selections. If nothing is listed for a field, leave
as-is or leave the default:
 Screen Type: List Screen (click [Finish] to bring up the next screen of the wizard)
 Caption: Reservations
 Name: Z_Get_Reservations
 Collection: Z_Reservations
Click [Next] to continue. Chose from the Available Properties and move them to the
Selected Properties in the following order:
 “WorkOrders” Property
 “Z_Reservations” Property
Click [Next] through the rest of the screens of the wizard, leaving the default settings
as-is. If you have questions about some of the settings, or would like to change some of
them as an experiment, talk to your instructor if time permits. Click [Finish] upon
completion to set the detail screen.
Note that because this screen was added last, it was added at the end. To move the
screen tab placement, highlight the row and use the arrow icons in the Agentry application
to move the placement up and down as desired.
Business Logic Layer - Fetches 145
Step 8 - Create the Reservation Transmit Action
Click in the Actions portion of the Agentry application and start the wizard to create a new
action. Here you are going to create a new action that ties the newly-created fetch to the
fetch screen set you created in Step 5. Type in the following selections:
 Name: MaterialReservationsFetch
 Display Name: Search Reservations
 Group: Fetch
Click [Finish] to create the transmit action. Double-click on the newly-created transmit
action to access the details of it. Click on the Action Steps tab and start the wizard to add
a new action step. If nothing is listed below, chose the default or leave as-is. Choose the
following:
 Step Type: Transmit
 Step Name: MaterialReservationsFetch
 Automatically start transmission: True (checked)
Click [Finish] to create the transmit action step.

Step 9 - Add a Transmit Button to the Reservations List Screen


Double-click on the Z_Get_Reservations list screen you created in Step 7. Click on the
Buttons tab and start the add wizard to add a new transmit button. When this button is
created, after a user presses it, it sends a transmit action to the back end to start the
search process for the requested part to reserve.
 Button Type: Action Button
 Action: Fetch Action | MaterialReservationsFetch
 Name: Materials
 Label: Search
 Target: “MainObject” Object (which contains the “Z_Reservations” Collection)
Click [Finish] to create the action button.
146 Business Logic Layer - Fetches
8 Business Logic Layer - Transactions
148 Business Logic Layer - Transactions

Business Logic Layer - Transactions


The transaction definition defines data to be captured on the SMART Client. As a part of its
definition, the transaction includes a target object type, data values to be captured, client-side
data validation, and updating its data to the back end system by the SMART Server during
synchronization. Transactions can add new object instances, edit an existing object, delete
an object, or modify a complex table or data table record. Each of these behaviors is exhibited
by a different transaction type, selected during the creation of the transaction.
Processing a transaction’s data during synchronization involves the transaction and all its
property values being sent from the SMART Client to the SMART Server. The SMART Server
then processes and executes that transaction’s server data state and server update steps,
which are child definitions to the transaction. Data state steps are provided to support
collision detection and collision handling and are rarely used in the SMART application.
Server update steps, or simply update steps, perform the actual processing of the
transaction’s data and updating or adding it to the SAP database. The server data state and
server update step definitions are both step usage definitions, meaning they use step
definitions within the same module as the transaction.
Within the SMART Mobile Suite Administration Component, the mobile data object (MDO) for
the business object is used to perform the processing. The step definitions processed as
update steps for the transaction contain classes that inherit from the Agentry Java API class
Steplet. The method doSteplet() is called by the SMART Server during the processing
of the Steplet class to perform the actual step processing.
Depending on the type of transaction being processed, the method within the MDO being
called will differ. Within the MDO, there are methods for Get (not typically used by
transactions), Create, Update, and Delete. The last three of these are typically used in
transaction processing according to the following:
 Add transaction - Create method
 Edit transaction - Update method
 Delete transaction - Update or Delete method
For Delete transactions, the object instance targeted by the transaction is removed from the
SMART Client. However, it is rare that the data is also removed from the SAP database.
Typically, the processing of the Delete transaction is handled by an update method in the
MDO. This processing may include actions such as changing the status of the item (i.e., from
Started to Complete), or updating an item as deprecated, or some other similar change.
Business Logic Layer - Transactions 149

Exercise A: Configure the MDOs and BAPI Wrappers


Building on the Reservation Material functionality you added in the previous set of exercises,
in this next set of exercises, you are going to add a new object and collection for the items
that are found and reserved when the user initiates the Reservation fetch.
Unlike the Reservation, the Goods Issue uses out of the box classes and BAPIs in SAP, so
you will not need to use the SAP interface for this exercise. However, you will need to use the
Configuration portal to configure the standard BAPIs and SAP classes to suit the application’s
needs, which is where we will start.
NOTE:In SAP, the class used in this exercise is
/SYCLO/CL_MM_GOODSMOVEMENTDO. The function module used is
/SYCLO/MM_DOGOODSMOVEMENT_CRT.
In this exercise, you have the option to use the out-of-the-box MDOs and BAPI wrappers as
they exist in the Configuration portal, without making any changes to them at all, or you can
make a copy of them and change them for future exercises. If you do decide to make a copy
and make changes, you can then make additional changes to them during the Agentry
exercises later on in this tutorial, and you will see the fruits of your labors during the Publish
and Test phase of the process. If you do decide to make a copy of the out-of-the-box MDO
and BAPI wrapper, always use your log in ID and append the name of the object with a ‘Z’ as
a best practice.

Step 1 - Copy and Change the Mobile Data Object


Log onto the Configuration portal. From the main page, click on the Mobile Data Object
Configuration link. Click on DO - Standard Data Object and scroll through until you find
SWM50_GOODSMVT_GENERIC. Your instructor will walk you through the functionality
of this data object and how it can work with both the Work Manager and Inventory
Manager applications. Notice that it uses the CREATE method instead of the GET
method. Your instructor will go over that as well.
If you would like to create a copy for your own use, click the [Copy] button. In the Mobile
Data Object ID field, change the name to add a ‘Z’ to the beginning of the name and
include your log in ID number. Notice that the Configuration portal automatically appends
a ‘_CPY’ to the end of the name. You can delete this if desired. Make a note of the name
of your MDO, as you will need it later in the tutorial. Click [Save] when done.

Step 2 - Copy and Change the BAPI Wrapper


Return to the main Configuration portal page and then click on the BAPI Wrapper
Configuration link. Click on /SYCLO/BAPI_MM and scroll through until you find
/SYCLO/MM_DOGOODSMOVEMENT_CRT.
As with the MDO, if you would like to create a copy for your own use, click the [Copy]
button, add a ‘Z’ to the beginning of the copy, add in your log in number to the name, and
[Save] the copy. Make a note of the name you used for the BAPI wrapper.
150 Business Logic Layer - Transactions

Exercise B: Create the Goods Java Logic in Eclipse

Be sure you are in the Java perspective in Eclipse. You have already created Java classes
in Eclipse for the Reservation, so this exercise will not include screenshots or detailed
information. Try to add the new Java classes in Eclipse without referring back to a previous
exercise first.
The Java classes are found in the Exercise Code folder, in the Goods Movement
subfolder. Remember that all Superclasses are named starting with com.syclo.sap in
Eclipse.

Step 1 - Add the Java Steplet


Add the IssueSteplet.class file and name it Z_GoodsMovementSteplet. Copy and
paste the code from the class file in the folder on your PC into the newly-created class file
in Eclipse and save the file.

Step 2 - Add the Java Stephandler


Add the GoodsMovementStepHandler.class file and name it
Z_GoodsMovementStephandler. Copy and paste the code from the class file in the
folder on your PC into the newly-created class file in Eclipse and save the file.

Step 3 - Add the Java POJO


Add the MaterialDocumentItem.class file and name it Z_MaterialDocumentItem.
Copy and paste the code from the class file in the folder on your PC into the newly-created
class file in Eclipse and save the file.

Step 4 - Add the Java BAPI Class


Add the MaterialDocumentCreateBAPI.class file and name it
Z_MaterialDocumentBAPI. Copy and paste the code from the class file in the folder on
your PC into the newly-created class file in Eclipse and save the file.
Business Logic Layer - Transactions 151

Exercise C: Create the Goods Issue Object in Agentry

In this exercise, we are creating two collections under the previously-created Reservation
object, in order to make up the entire reservation fetch and have it work correctly during the
final publish and test phase. These collections are the Issues and the Items collections.
When designing a new collection or a nested set of collections as an add-on for your standard
application, drawing a flowchart of the objects and collections beforehand may help you to
visualize the best way to design it before getting to work in Agentry.

Step 1 - Create the Material Document Items Object


Open the Agentry perspective in Eclipse. Use the wizard to create an object called
Z_MaterialDocumentsItems in the Objects section of the application. The Display
Name is Items. Click [Finish] to create the object.
Double-click on the object, then click on the Properties tab and start the wizard to add the
following String properties to the new object. If a field is not listed, leave blank or the
default as-is:
 Name: ID
 Display Name: ID
 Name: materialDocument
 Display Name: Material Document
 Trim: True (checked)
 Name: materialDocumentYear
 Display Name: Material Document Year
 Trim: True (checked)
 Name: materialDocumentItem
 Display Name: Material Document Item
152 Business Logic Layer - Transactions

 Trim: True (checked)


 Name: Plant
 Display Name: Plant
 Trim: True (checked)
 Name: storageLocation
 Display Name: Storage Location
 Trim: True (checked)
 Name: Material
 Display Name: Material
 Trim: True (checked)
 Name: movementType
 Display Name: Movement Type
 Trim: True (checked)
 Name: movementIndicator
 Display Name: Movement Indicator
 Trim: True (checked)
 Name: UOM
 Display Name: UOM
 Trim: True (checked)
 Name: Batch
 Display Name: Batch
 Trim: True (checked)
 Name: Bin
 Display Name: Bin
 Trim: True (checked)
 Name: specialStockIndicator
 Display Name: Special Stock Indicator
 Trim: True (checked)
 Name: stockType
 Display Name: Stock Type
 Trim: True (checked)
 Name: Reason
 Display Name: Reason
 Trim: True (checked)
 Name: Text
 Display Name: Text
Business Logic Layer - Transactions 153
 Trim: True (checked)
 Name: reservationNumber
 Display Name: Reservation Number
 Trim: True (checked)
 Name: reservationItem
 Display Name: Reservation Item
 Trim: True (checked)
 Name: finalIssue
 Display Name: Final Issue
 Trim: True (checked)
 Name: GMCode
 Display Name: GM Code
 Trim: True (checked)
Create a Decimal Number property:
 Name: Quantity
 Display Name: Quantity
Create a Date property:
 Name: postingDate
 Display Name: Posting Date
Create a Collection property:
 Name: SerialNumbers
 Display Name: Serial Numbers
 Property Type: Object
 Object: Z_SerialNumber
NOTE: The SerialNumbers Collection property is for a future/at-home assignment and is not
necessary for the exercise. In order to add the collection, the Z_SerialNumber object must
be created first, and the Z_SerialNumber object must have a key property.
Select the Object Definition tab. In the Key Properties pull-down list, select
reservationNumber.
154 Business Logic Layer - Transactions

Step 2 - Create the Issues Collection


Double-click on the “Z_Reservation” Object, click the Properties tab, and start the
wizard to add a new Collection property with the following attributes:
 Name: Z_MaterialDocumentsItems
 Display Name: Issues
 Property Type: Object
 Object: Z_MaterialDocumentsItems
Click [Finish] to create the new collection within the Reservation object.
Now add the following String properties to the new object. If a field is not listed, leave
blank or the default as-is:
 Name: ID
 Display Name: ID
 Trim: True (checked)
 Name: reservationNumber
 Display Name: Reservation Number
 Trim: True (checked)
 Name: reservationItem
 Display Name: Reservation Item
 Trim: True (checked)
 Name: recType
 Display Name: Record Type
 Trim: True (checked)
 Name: Material
 Display Name: Material
 Trim: True (checked)
 Name: Plant
 Display Name: Plant
 Trim: True (checked)
 Name: storageLocation
 Display Name: Storage Location
 Trim: True (checked)
 Name: Batch
 Display Name: Batch
 Trim: True (checked)
 Name: Quantity
 Display Name: Quantity
Business Logic Layer - Transactions 155
 Trim: True (checked)
 Name: Unit
 Display Name: Unit
 Trim: True (checked)
 Name: reqDate
 Display Name: Request Date
 Trim: True (checked)
 Name: GLAccount
 Display Name: GL Account
 Trim: True (checked)
 Name: shortText
 Display Name: Short Text
 Trim: True (checked)
 Name: unloadPoint
 Display Name: Unload Point
 Trim: True (checked)
 Name: Withdrawn
 Display Name: Withdrawn
 Trim: True (checked)

Step 3 - Add Properties to the Z_Reservation Object


The Z_Reservation object was added when you created the reservation fetch in a
previous exercise. Now add the following String properties through the wizard:
 Name: ID
 Display Name: ID
 Trim: True (checked)
 Name: reservationNumber
 Display Name: Reservation Number
 Trim: True (checked)
 Name: movementType
 Display Name: Movement Type
 Trim: True (checked)
 Name: shipParty
 Display Name: Ship Party
156 Business Logic Layer - Transactions

 Trim: True (checked)


Add a Date property:
 Name: baseDate
 Display Name: Base Date
 Blank: True (checked)
Add a Collection property:
 Name: reservationItems
 Display Name: Items
 Object: Z_MaterialDocumentsItems
Business Logic Layer - Transactions 157

Exercise D: Create Screensets and Screens for Reservations

You’ve already created a screenset and screens for a fetch in a previous exercise. Now, you
are going to create two screensets, each with separate screens. Sometimes when you are
designing a new function on top of an out-of-the-box application, it is easier to draw a flow, to
envision the design, before developing the screensets and screens. Here, you can see the
screenset and screen flow of the Reservations:
158 Business Logic Layer - Transactions

The shaded boxes in the image are not discussed in the steps, but are part of the optional
take-home advanced exercises. The Login box is the main Client log in screen of the
application and is also not discussed or built in the steps.

Step 1 - Create the Reservations Screen Set and Screens


Navigate to the Screen Sets section of the application and start the wizard to add a new
screen set. Fill in the properties as shown and click [Finish].
 Displays: Object | Z_ReservationItem
 Name: ShowReservations
 Description: Show the Reservation item object details
Click the Platform tab and add a platform. Make the following selections:
 Platform: Windows CE (Pocket PC) Portrait
 Caption: Reservation
 Button Placement: Bottom
 Navigation: True (checked)
Click [Next], then click [Finish] to add the platform to the screen set.
Click the Screens tab and add a screen. Make the following selections:
 Screen Type: List Screen
 Caption: Items
 Name: ShowReservationItemsList_PPC
 Rows: 7
Click [Next]. On the Properties screen, add the following properties from the Available
column to the Selected column, so they are in this order:
 “ID” Property
 “Material” Property
 “Plant” Property
 “storageLocation” Property
 “Unit” Property
 “Batch” Property
 “Quantity” Property
Click [Finish] to add the new list screen to the screen set.
Add a new Screen with the following properties:
 Screen Type: List Screen
 Caption: Issues
 Name: ShowReservationIssues_List_PPC
Click [Next]. On the Properties screen, add the following properties from the Available
Business Logic Layer - Transactions 159
column to the Selected column, so they are in this order:
 “Material” Property
 “reservationNumber” Property
 “Plant” Property
 “storageLocation” Property
 “Bin” Property
 “Batch” Property
 “UOM” Property
 “Quantity” Property
Click [Finish] to add the new list screen to the screen set.
160 Business Logic Layer - Transactions

Step 2 - Create the Add Document Items Screen Set and Screens
Add a new Screen Set with the following properties:
 Displays: Object | AddZ_MaterialDocumentsItems
 Name: AddDocumentsItems
 Description: Add Document Items
Click the Platform tab and add a platform. Make the following selections:
 Platform: Windows CE (Pocket PC) Portrait
 Caption: Reservation
 Button Placement: Bottom
 Navigation: True (checked)
Click [Next], then click [Finish] to add the platform to the screen set.
Click the Screens tab and add a screen with the following selections:
 Screen Type: Detail Screen
 Caption: Issue
 Name: AddDocumentsItems_Detail_PPC
 Rows: 8
Click [Next]. On the Properties screen, add the following properties from the Available
column to the Selected column, so they are in this order:
 “reservationNumber” Property
 “reservationItem” Property
 “Plant” Property
 “storageLocation” Property
 “movementType” Property
 “Quantity” Property
 “Text” Property
 “finalIssue” Property
Click [Finish] to add the new detail screen to the screen set.
Some of these properties now must be set to be read-only on the Client, so that the user
cannot modify content contained within the fields. Click on the Fields tab on the
Business Logic Layer - Transactions 161
newly-created screen. Now double-click on the reservationNumber property to display
its properties.
In the Field Definition tab, locate the Read-only checkbox and check the box (i.e., make
it true). Then click the Save icon to save your changes in Eclipse. Do this for the following
properties to make them read-only:
 reservationItem
 Plant
 storageLocation
 movementType
Click on the finalIssue property. This field will appear as a check box on the mobile
application, which you will change in the properties of the property. In the Edit Type
drop-down field, select Button and save your changes.
162 Business Logic Layer - Transactions

Step 3 - Create the Actions For the Transaction Functionality


Create an action for the add transaction with the following attribute settings:
 Name: AddDocumentItems
 Display Name: Issue
 For Object: Z_Reservation
Next, add the transaction step to this action:
 Step Name: AddDocItem
 Transaction: AddZ_MaterialDocumentItems
 Screen Set: AddDocumentItems
Finally, add a second step of type Apply to this action.
Return to the list of actions for the module and create another action with the following
attributes:
 Name: EditDocumentItem
 Display Name: Edit
 For Object: Z_MaterialDocumentItems
Add a transaction step to this action:
 Step Name: EditDocumentItem
 Transaction: EditZ_MaterialDocumentItems
 Screen Set: AddDocumentItems
Note in the above that the screen set for the add transaction can be reused here for the
edit, as the same values are being captured.
Finally, add an apply step to this action.
Return once again to the list of actions for the module. Create an action for the delete
transaction with the following attributes:
 Name: DeleteIssue
 Display Name: Clear
 For Object: Z_MaterialDocumentItems
Now add a transaction step to this action:
 Step Name: DeleteItem
 Transaction: DeleteZ_MaterialDocumentItems
 Screen Set: No Screen Set
Once this step is defined, add an Apply step to the transaction.
Business Logic Layer - Transactions 163
Step 4 - Define the Buttons to Execute the Actions
Navigate to the ShowReservations Screen Set | ShowReservationItems_List_PPC
screen and click on the Buttons tab. Create the following three buttons for this screen:
Transmit:
 Button Type: Action Button
 Action: Transmit | Transmit
 Name: Transmit
 Label: Xmit
 Target: Z_Reservation Object (which contains the “reservationItems” Collection)
AddDocumentItem:
 Button Type: Action Button
 Action: AddDocumentItems
 Name: AddDocumentItems
 Label: Issue
 Target: Z_Reservation Object (which contains the “reservationItems” Collection)
Close:
 Button Type: Action button
 Action: CloseThisScreenSet
 Name: CloseThisScreenSet
 Label: Close
 Target: Z_Reservation Object (which contains the “reservatioNItems” Collection)
Once these buttons have been defined, view the second screen in this same screen set,
ShowReservationIssues_List_PPC. Add the following buttons to this screen:
Transmit:
 Button Type: Action Button
 Action: Transmit | Transmit
 Name: Transmit
 Label: Xmit
 Target: Z_Reservation Object (which contains the “reservationItems” Collection)
EditDocumentItem:
 Button Type: Action Button
 Action: EditDocumentItem
 Name: EditDocumentItem
 Label: Edit
 Target: Selected Z_MaterialDocumentItems
DeleteIssue:
164 Business Logic Layer - Transactions

 Button Type: Action Button


 Action: DeleteIssue
 Name: DeleteIssue
 Label: Clear
 Target: Selected Z_MaterialDocumentItems Object
Close:
 Button Type: Action button
 Action: CloseThisScreenSet
 Name: CloseThisScreenSet
 Label: Close
 Target: Z_Reservation Object (which contains the “reservationItems” Collection)
Business Logic Layer - Transactions 165

Exercise E: Create Transactions

After the objects and properties within the objects are created, you need to create the
transactions for the objects.

Step 1 - Create the Add Transaction in Z_MaterialDocumentsItems


Click in the Z_MaterialDocumentsItems object, click on the Transactions tab, and start
the wizard.
 Type: Add
 Object: Z_MaterialDocumentsItems
 Collection: Browse Objects | “Z_Reservation” Object |
“Z_MaterialDocumentItems” Property
 Name: AddZ_MaterialDocumentsItems
 Display Name: Issue Item
Click [Next]. On the Properties screen, add the following properties from the Available
column to the Selected column, in this order:
 “reservationNumber” String Property
 “reservationItem” String Property
 “Plant” String Property
 “storageLocation” String Property
 “movementType” String Property
 “Quantity” Decimal Number Property
 “Text” String Property
 “finalIssue” String Property

Step 2 - Set the Add Transaction Properties Settings


Now you will link the properties of the Z_MaterialDocumentsItems object to the properties
of the properties of the Z_ReservationItem object, in essence, making the
Z_ReservationItem object a subset of the Z_MaterialDocumentsItems object in the screen
set flow on the Client for the user. However, you are only going to do this for the properties
that the two objects have in common.
Expand the Properties list in both objects in the Explorer panel and view them to note the
common properties. Since the list is in alphabetical order, you will see right away that the
Batch property is common to both objects. Click on the Z_MaterialDocumentsItems
166 Business Logic Layer - Transactions

object, Transactions tab. Then double-click on the AddZ_MaterialDocumentsItems


transaction to view its properties.
Highlight the Batch property and double-click it to view and edit its properties. Navigate
to the Transaction Property Settings section and click in the Initial Value field. Select
From a different object property.
Click the button to the right of the Other Property field and select Browse Objects. In the
Property Browser window, select and expand in the following order for the Batch property:
 Other Screen Sets
 “ShowReservations” Screen Set
 “ShowReservationsIssues_List_PPC” List Screen
 Selected (“Z_MaterialDocumentsItems”) Object
 “Batch” Property
Perform this step for the common properties between Z_MaterialDocumentsItems and
Z_ReservationItem until all common properties are linked.
Business Logic Layer - Transactions 167
Step 3 - Create the Edit Transaction in Z_MaterialDocumentsItems
Using the wizard, add another transaction in Z_MaterialDocumentsItems with the
following properties:
 Type: Edit
 Object: Z_MaterialDocumentsItems
 Name: EditZ_MaterialDocumentsItems
 Display Name: Edit Items
Click [Next]. On the Properties screen, add the following properties from the Available
column to the Selected column, in this order:
 “reservationNumber” String Property
 “reservationItem” String Property
 “Plant” String Property
 “storageLocation” String Property
 “movementType” String Property
 “Quantity” Decimal Number Property
 “Text” String Property
 “finalIssue” String Property

Step 4 - Create the Delete Transaction in Z_MaterialDocumentsItems


Using the wizard, add another transaction in Z_MaterialDocumentsItems with the
following properties:
 Type: Delete
 Object: Z_MaterialDocumentsItems
 Name: DeleteZ_MaterialDocumentsItems
 Display Name: Delete Items
Click [Next]. On the Properties screen, leave the “reservationNumber” String
Property in the Selected column and click [Finish].
168 Business Logic Layer - Transactions
9 Testing, Debugging, and Troubleshooting Techniques
170 Testing, Debugging, and Troubleshooting Techniques

Debugging Techniques
The SMART Server’s agentry.ini file contains the non-standard Java options in the
[Java-n] section. In general, this configuration option is used to pass the non-standard
options to the JVM during the load process.

Garbage Collection
Garbage collection algorithms are very specific to the application and the deployment
hardware. Therefore, the Server and the Server’s installer will never choose a garbage
collector. The correct garbage collector can only be chosen through diligent analysis of the
application and deployment. By default, the J2SE platform will choose a garbage collector if
one has not been specified. The selected garbage collector varies depending on the J2SE
platform version. J2SE platform version 1.4.2 creates the default single-threaded garbage
collector, while version 1.5 attempts to choose a collector based on hardware the application
has deployed. This is an important distinction since moving between J2SE platforms may
require garbage collection analysis.
In either version of the J2SE platform, to specify a non-default garbage collector and to
choose your own garbage collector, add it to the [Java-n] section of the agentry.ini file
as shown below:
nonStandardJavaOptions=-Xdebug
-Xrunjdwp:transport=dt_socket,address=7090,server=y,suspend=n
Visit the following sites for more information on how to choose the correct garbage collector:
 http://java.sun.com/docs/hotspot/gc1.4.2/
 http://www.oracle.com/technetwork/java/gc-tuning-5-138395.html

Heap Analysis Tools


There are several tools to help analyze the JVM heap:
JConsole. Provides out-of-the-box remote monitoring and management. JConsole output
can be specified in the Server’s agentry.ini file using the [Java-n] section. An example
is shown below:
nonStandardJavaOptions=-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=5001
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
Start JConsole and attach it to the connection specified by the Server’s PID. For more
information, see
http://download.oracle.com/javase/1.5.0/docs/guide/management/jconsole.html.
Jmap. This program prints shared object memory maps or heap memory details of a given
process or core file or a remote debug server. The following is an example of a J2SE platform
version 1.5 or 1.6:
Testing, Debugging, and Troubleshooting Techniques 171
jmap -histo <server's pid> - Prints a histogram of the heap.
The following is an example of J2SE platform version 1.6 only:
jmap -dump:format=b,file=heap.bin <server's pid> - Dumps heap in
binary format to heap.bin - use jhat to view.
For more information, see
http://download.oracle.com/javase/6/docs/technotes/tools/share/jmap.html.
Perl script. Syclo has developed a Perl script that helps to analyze your jmap output. It
requires pv.exe, which is the command line version of PRCView and Perl:
#find the process ID of the Agentry Server
$temp = ‘pv agentrygui.exe’;
$temp =~ tr/\ //s;
@flds = split(/\s/, $temp);
$pid = $flds[2];
print “\nAgentry PID: $pid\n”;
#call jmap with the Agentry Server PID and dump the output to a file
‘jmap -histo $pid > dump.txt’;
#open the file and grep out what you are interested in. In our case,
any Syclo classes. The output file will show the number of instances
of each class. If there are more than you think there should be, you
gotta problem.
open (F, “<dump.txt”);
while (<F>) {
$keep = 0;
$keep = 1 if /instances/i;
$keep = 1 if /syclo/i;
print if $keep == 1;
}
Jhat. This program parses a Java heap dump file and launches a webserver. An example is
shown below:
J2SE platform version 1.6 onlyjmap -dump:format=b,file=heap.bin
<server's pid> - Dumps heap in binary format to heap.bin - use jhat
to view.jhat heap.binThen use your browser to attach the http server
172 Testing, Debugging, and Troubleshooting Techniques

created by jhat (i.e http://localhost:<port>), it will tell you which


port.
For more information, see
http://download.oracle.com/javase/6/docs/technotes/tools/share/jhat.html.
10 Project Standards and General Staging Techniques
174 Project Standards and General Staging Techniques

Project Staging and Standards


There are many components to developing, building, and delivering customized Agentry
applications. This document describes setting up the environment, suggestions for using
version control during development and build steps, available build processes and scripts,
naming conventions, and other related issues.
Deliverables for a given Agentry application require support for most of the following
requirements:
1) The ability to produce a branded installer version of an Agentry WinCE Client, Win32
Client, Agentry Editor, and SMART Server.
2) The ability for the user to install the Server as either a Development or a Production
Server.
3) The support for connecting to a variety of back ends, including SAP, Maximo,
TRIRIGA, and ODBC databases.
4) The ability to add custom files and folder hierarchies to an installed application.
5) The ability to consistently reproduce a final installer, from either current tip revisions or
version controlled files from a historical point.

Development Environment
A version control hierarchy consists of the following directory structure:
ProjectRootDirectory
 Branding
 Editor
 Server
 Win32
 WinCE
 Build
 build.bat
 build.properties
 build.xml
 buildnum.exe
 temporary files not under version control
 Documents
 Syclo
 Customer
 Exports (generally only 1 AGX file in this directory)
 Project
 src (Java source)
Project Standards and General Staging Techniques 175
 classes (compiled Java that does not need to be maintained in version control)
 Releases
 A new subdirectory is created each time build.bat is run. Check in only those
releases that are distributed to the customer.
 Test (this directory and its children do not need to be under version control)
 Server-Dev
 Server-Prod
 Client
 Editor

Branding Folder
Contains the branding files required to produce the self-extracting archive installers. Branding
files are resources customized for the specific application. They can include things like:
 *.ini files
 Custom tables
 External *.jar files (SAP, jCO, etc.)

Build Folder
The build folder contains the control files, build scripts, and utilities used to create releases
based on Agentry branded installer files.

Documents Folder
The documents folder contains FSRS, project plans, design documents, and other materials
used to build the project before the release.

Exports Folder
The exports folder holds the Agentry export files from the Agentry Editor. This folder generally
should only hold a single application file.

Project Folder
The project folder is the main folder for anything maintained in Eclipse. This includes Java
files, SQL scripts, and XML files. Note that compiled classes under this folder do not need to
be versioned, only the source. The classes will be recompiled at build time and saved under
the final release Server installer.

Releases Folder
Final output from the build process is written to the releases folder. This folder contains a
subdirectory for each release which contains Server, Editor, and Client installers as well as
any release documentation, Java source code, or other material relevant to the release.
176 Project Standards and General Staging Techniques

Test Folder
The test folder contains an Editor, test environment Client, Development Server, and
optionally a Production Server.

Build Environment
The build environment is a set of *.ini files, branding files, and scripts that act as metadata to
turn a generic Agentry Client, Server, or Editor installer into a particular installer for a given
Agentry product.
The build environment consists of the following components:
 build.bat: Main batch file for initiating the build process
 build.properties: Java properties file that controls how and what is built
 buildnum.exe: Utility that generates the build number

Build Process
The basic steps of the build process are as follows:
1) Edit the build.properties file to make sure the file names and locations fit your project
and that you are using the desired test or release version of Agentry.
2) Run build.bat with a numeric parameter indicating which ‘build of the day’ you are
running. As an example, build.bat 1 would be the first build of the day.
3) The build process then:
 Pulls from version control the source files it needs.
 Creates Win32, WinCE, Editor, and Server installer files.
 Creates a Zip file of the Java source and copies these files into a directory under
the Releases folder.
 Manually checks the generated files into version control after testing.
11 Importing and Exporting Java Source Code
178 Importing and Exporting Java Source Code

Importing the Java Source Files for the Application to the Eclipse Platform
Once Eclipse is installed, you must then set up the development project that allows you to
modify, compile, and debug the Java portion of the application. The following items are a part
of the Java portion of the development project:
 Java source files for the application
 jCo.jar file
 Agentry-level *.class files, provided with the SMART application Server in the
subdirectory Java\Syclo\Agentry. All of the *.class files in this folder are a part of
the project.
 junit.jar file, provided with Eclipse

Java SDK
The SMART Production Server uses Java to perform data synchronization with the SAP
application server. The Java 2 Software Development Kit, or SDK, version 1.5 or higher, is
required for the SMART Production Server. Included in the SDK installation is the JRE, or
Java Runtime Environment. These components are already installed on your training
computer, but are mentioned here for reference.
NOTE: When installing the Agentry Editor on the same machine as the Agentry Server,
installation of Java SDK is not necessary, as the JDK is installed as part of the Editor
installation.
Importing and Exporting Java Source Code 179

ExercisePlatform
Eclipse A: Importing the Java Source Files for the Application to the
PREREQUISITE

In this procedure, you will first modify the Windows environment PATH variable, in order to
include the paths for the bin directory of the JDK and the bin directory for the JRE. After the
paths are set, the Java project is then imported into the Eclipse project set up in the previous
lesson.

Step 1 - Modify the PATH Environment Variable


Two new paths for the JDK need to be added to the PATH environment variable in
Windows. One is for the bin directory of the JDK and the other is the bin directory for the
JRE.
a Right-click My Computer and select Properties.
b Click the Advanced tab, then click Environment Variables.
c In the System Variables window, find and double-click Path.
d Add the following text to the beginning of the path, where xx is the version of the JDK
that was installed.
RESULT :C:\Java\jdk1.6.0_xx\bin;C:\Java\jdk1.6.0_xx\jre\bin\server
NOTE: When adding values to the Path variable, be sure to separate the paths with a
semicolon. Syclo recommends that the SMART Mobile Suite product paths are the
first two paths in the string for the path system variable.
e Click OK to return to the Properties screen. Click OK again to commit the new path.
180 Importing and Exporting Java Source Code

Step 2 - Set up the Java project in Eclipse


Launch Eclipse, and set your workspace folder as
C:\Training\SMART-SAP\train\project.
The items in your project folder include:
 The Java source files for the application. The files include the steplet classes used
in the Java step definitions, as well as the classes used by the data tables and
complex tables.
 The *.class files that make up the Agentry Java API. These are installed with the
application’s Server and are referenced from the Server’s location, or can be
copied to a location convenient to Eclipse.
 The sapjCo.jar file for the SAP Java connector toolkit.
 The junit.jar file provided with Eclipse. This is a library of Java classes used
for debugging purposes, several of which are implemented in the SMART Mobile
Suite application Java classes. If this is not included in your project, you will receive
warnings related to these classes at build time.

Step 3 - Import the Project to Eclipse from an Archive File


In Eclipse, from the main menu, select File | Import. The following dialog appears.
Importing and Exporting Java Source Code 181

Select Existing Projects into Workspace and click [Next].


182 Importing and Exporting Java Source Code

NOTE: It may seem counterintuitive to not select Archive File at this step. The Archive File
option is used for importing Eclipse resources into an existing Eclipse project. Since you are
importing an entire project, you must select Existing Projects.
The Import Projects window appears.

Click the Select archive file radio button and then click the [Browse] button. Browse to
the folder containing the class projects file; your instructor will give you the path if you do
not already know it.
If you have selected an archive file containing a project(s), the project name(s) will appear
in the box below, already checked. Click [Finish] to complete the import process.
Importing and Exporting Java Source Code 183
Step 4 - Exporting a Project from Eclipse as a JAR File
You do not have to follow these steps now for this class, but you will need to export your
project from Eclipse as a JAR file at the end of class in order to complete the take-home
exercises if desired.
From the main Eclipse menu, go to File | Export. The following dialog appears:

Select JAR file and click [Next]. The following dialog appears:
184 Importing and Exporting Java Source Code

Select the option to Export all output folders for checked projects. Then, click the
[Browse] button and browse to the export destination for the JAR file. Click [Next] to
continue. The JAR Packaging Options dialog appears:
Importing and Exporting Java Source Code 185

Leave the default boxes checked and click [Next] to continue. The JAR Manifest
Specification dialog appears:
186 Importing and Exporting Java Source Code

Leave the defaults set and click [Finish]. Eclipse automatically exports and zips your
project into an archive file and stores it in the location you specified. Congratulations!