Commerce Reference Store
Version 11.2
ASA Overview
ASA Overview
Product version: 11.2
Release date: 10-22-15
Document identifier: ASAOverview1603081515
Copyright © 1997, 2016 Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are
protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any
means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please
report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government,
the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the
hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable
Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or
documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended
for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures
to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are
trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services from third parties.
Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or
services, except as set forth in an applicable agreement between you and Oracle.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/
topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support: Oracle customers that have purchased support have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
if you are hearing impaired.
ASA Overview iii
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. What is Assisted Selling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Commerce Reference Store iOS Universal Application (CRS-IUA) and Assisted Selling Compared . . . . . . . . . . . 5
Oracle Commerce Platform Guided Search Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
ASA and Oracle Retail Mobile Point-of-Service Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
ASA and Oracle Store Inventory Manager (SIM) Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
ASA and CRS-IUA iBeacon Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. Version Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Installing Oracle Commerce Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Installing the Optional ORMPOS Integration Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
ORMPOS Integration Environmental Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Installing the Optional Oracle Store Inventory Manager Integration Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Oracle Store Inventory Manager Integration Environmental Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Two Commerce Reference Store Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Assisted Selling, CRS-IUA, CRS-M and Commerce Reference Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Setup and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
CIM Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Products and Options to Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Optional Steps to Install the ORMOS Integration Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Optional Steps to Install the SIM Integration Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Obtaining the iOS Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
iOS Client Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5. High-Level Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
File and Component Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Commerce/Guided Search Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Common Binding/Manager/Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ATGMobileClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ATGAgentClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
EMMobileClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ATGAgentPlugins (Optional plugin) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ATGAgentFulfillmentMenuInventoryPlugin (Optional plugin) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
UI/Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Oracle Commerce Guided Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Shared Code in Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Shared Code in Assisted Selling and CRS-IUA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6. Low-Level Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Store.Mobile.DCS-CSR Server Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
REST Security and AgentLoggedInAccessController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Extending Commerce Service Center web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Form Handler Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
MobileCSRCartModifierFormHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MobileCSRPaymentGroupFormHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MobileCSRShippingGroupFormHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
iv ASA Overview
MobileCSRCancelOrderFormHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MobileCSRCheckoutFormHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
REST Actors in Assisted Selling and their Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Learning about Actor Chains in Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Configuration Unique to Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Objective-C REST Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Objective-C JSONPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
JSON Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Oracle Retail Store Inventory Management (SIM) Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
SIM Commerce Sub-Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
SwitchingInventoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
SIMInventoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
InventoryManager Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
SIM web service request methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Other methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
SIM Webservices used by SIMInventoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
SIMInventoryActor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Inventory Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
InStoreSaleFulfiller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
ORMPOS, SIM, and SKUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
SIMExporter Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
ASA and CRS-IUA iBeacon implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Architecture and Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Requesting Help in IUA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
How iBeacon users and help requests are added to a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
iBeacon Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
mobileDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Query Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Beacon Ranging Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ASA-IUA Cross-over Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7. Low-level Architecture for ORMPOS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Technical Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Details on the iOS ORMPOS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Connection Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Making Calls to ORMPOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Store.Mobile.DCS-CSR.MPOS Server Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Store.Mobile.DCS-CSR.MPOS.REST Server Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
ORMPOS/ASA Login Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
ORMPOS Login into CSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
iOS Client Login API Structure for ORMPOS/ASA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Login to MPOS{*} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
loadExternalOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Open Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Keeping the Session Alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Closing the Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Add Tender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Add Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
ASA Overview v
Suspend Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Print Receipt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Suspend and Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Architecture and Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Suspending an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Displaying and Printing the Order/Transaction Barcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
iOS Plugin Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Plugin Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Signature Capture in iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
8. UI Features Unique to Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Associate and Shopper Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Associate Dashboard Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Layout and Cartridges Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Modules for the Dashboard Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Locating a Shopper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
High Level Cart Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Shopping Using an Anonymous Profile and Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Shopping Cart, Bar Code Scan, and Search and Browse Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Multiple Carts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Order History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Product Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Unique to Assisted Selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Discounts and Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
“In-Store” Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Scanning In Store Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
The ZXing library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
BarcodeScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9. The Assisted Selling iOS Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Agent Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
vi ASA Overview
1 Introduction 1
1 Introduction
The Oracle Commerce Assisted Selling Application (ASA) is an extension of Oracle Commerce Reference
Store which provides an interface to the existing Commerce Reference Store backend in the form of a new
Oracle Commerce Platform server module. This module is a concrete example of how you can leverage Oracle
Commerce Platform REST Web Services to make data available to a client application. It also provides an
example of a client in the form of an iOS iPad Application that consumes data provided by the server module.
Assisted Selling is geared toward retailers who have low to medium traffic and the ability to interact with
customers on an individual basis.
Benefits of Assisted Selling include:
• Customer insight for registered shoppers
• Insight into inventory availability by location
• Move POS onto the sales floor with engaged selling ability for store associate
• Enable associates with traditional shopper-facing commerce features
• Enable associates to access a subset of the traditional contact center (agent-facing) functionality
• Strengthen relationships with key clients
• Optionally, integrate some functions with the Oracle Retail Mobile Point-of-Service (ORMPOS) and a new
server sub-module Store.Mobile.DCS-CSR.MPOS which encapsulates logic associated with the ORMPOS
integration
• Optionally, integrate between the ASA and Oracle Store Inventory Manager (SIM) using a ATG sub-module
Store.Mobile.DCS-CSR.SIM
Assisted Selling provides a hybrid of agent/associate and customer functionality. This means that in-store
employees experience some of the same product catalog, shopping cart, and other traditional customer-facing
commerce functionality and also access enhanced agent-facing functionality to fully serve the needs of the
customer.
From a developer standpoint, Assisted Selling provides an Objective-C REST client that encapsulates the server
invocations made from the iOS client to the Oracle Commerce Core Platform. This encapsulation hides many of
apps inherent complexities from the implementer.
2 1 Introduction
About this Document
This document discusses the features of Assisted Selling and the tools used to implement them. Each chapter
builds on the information in previous chapters, so it is recommended that you read the chapters in order. The
document includes the following chapters and appendix:
What is Assisted Selling? (page 5)
Defines the Assisted Selling product.
Version Compatibility (page 9)
Provides a links to update to date version information for Assisted Selling
Installing Oracle Commerce Assisted Selling (page 11)
Describes how to install Assisted Selling
High-Level Architecture (page 19)
Broadly discusses the architecture of Assisted Selling at a high level
Low-Level Architecture (page 25)
Examines in more detail how different components are composed
Low-level Architecture for ORMPOS Integration (page 59)
Discusses the structure of the optional integration of ASA and ORMPOS functionality
UI Features Unique to Assisted Selling (page 81)
Examines the unique features in Assisted Selling that are different from Oracle Commerce
Service Center (CSC) and Commerce Reference Store iOS Universal App (CRS-IUA)
The Assisted Selling iOS Application (page 103)
Examines the Xcode project that makes up and help organize Assisted Selling
Assumptions
Since Assisted Selling is an extension of Commerce Reference Store, it is assumed that you are familiar with the
Commerce Reference Store and Commerce Service Center products. For more information see the Commerce
Reference Store Installation and Configuration Guide, and the Commerce Service Center User Guide. Similarly, while
the section of this book called the Oracle Commerce Platform - Guided Search Integration Guide discusses
CRS-IUA components of the Guided Search integration, it is assumed that you are familiar with the Oracle
Commerce Guided Search product suite. See the Platform-Guided Search Integration Guide and other related
Oracle Commerce Platform and installation documentation for more details. Since there are similarities and
some shared code with Oracle Commerce Reference Store iOS Universal Application (CRS-IUA) you should also
review the Commerce Reference Store IUA Overview.
If you are planning to install the optional ASA and ORMPOS integration, it is assumed that you are familiar
with the ORMPOS and POS products. For more information, see the Oracle retail documentation on the Oracle
Technology Network.
If you are planning on installing the ASA and Oracle Store Inventory Manager (SIM) integrations sub-module
Store.Mobile.DCS-CSR.SIMm For more information, see the Oracle Store Inventory Manager documentation
on the Oracle Technology Network.
Audience
This document was written for developers, mobile developers, and interested highly technical business control
persons. These people include:
1 Introduction 3
• Web Designer/Page Developer. Page developers create the content pages, integrating the scenario
elements created by business users and the code elements created by programmers. Page developers are also
responsible for overall Web site appearance.
• Site Producer or Business Analyst. These individuals are responsible for getting a site up and running,
maintaining it day to day, troubleshooting issues, and making administrative changes not performed by an
administrator or page developer.
• Application Developer. Programmers create the code elements that allow the system to provide dynamic,
personalized site content. They also configure repositories and perform database administration duties.
4 1 Introduction
2 What is Assisted Selling? 5
2 What is Assisted Selling?
The Oracle Web Commerce Assisted Selling Application (ASA) is an in-store reference application that merges
the functionality of the Oracle Commerce Platform with the Oracle Commerce Service Center server data on an
iPad tablet device. This app provides:
• A server module (Store.Mobile.DCS-CSR) with a set of REST configurations to allow invocation from any
JSON-consuming client.
• An Objective-C REST client for simplified invocation of server-side functionality by an iOS application.
• An iOS application providing Commerce Service Center functionality that consumes CRS JSON-formatted data
produced by the Store.Mobile.DCS-CSR module.
• The ability to leverage the Commerce Service Center’s out-of-the-box web services.
• The optional ability to integrate with Oracle Retail Mobile Point-of-Service (ORMPOS) to either tender
credit cards or to suspend a sale and transfer it to a store POS terminal. Two new server modules
Store.Mobile.DCS-CSR.MPOS and Store.Mobile.DCS-CSR.MPOS.REST help achieve this integration.
• The optional ability to integrate between the ASA and Oracle Store Inventory Manager (SIM) using a ATG sub-
module Store.Mobile.DCS-CSR.SIM
• Assisted Selling’s server module is based on the existing Commerce Reference Store application’s Nucleus
components and configuration. If you are not already familiar with this application, please refer to the
Commerce Reference Store IUA Overview which documents the iOS version of Commerce Reference Store.
Commerce Reference Store iOS Universal Application
(CRS-IUA) and Assisted Selling Compared
Commerce Reference Store iOS Universal Application (CRS-IUA) is a native iPhone and iPad application that
interacts with the web application’s backend to send and receive data. A Universal app runs on both the iPhone/
iPod Touch and the iPad. From a developer’s perspective, it is an iPhone and iPad app built as a single binary.
Assisted Selling is designed to run only on the iPad. Assisted Selling differs in that it is intended to be used by an
in-store associate who assists a shopper with his or her purchases.
6 2 What is Assisted Selling?
Oracle Commerce Platform Guided Search Integration
As with CRS-IUA, a key feature of this product is the integration of Oracle Commerce Platform-Guided Search
features into Assisted Selling, specifically:
• Oracle Commerce Guided Search is used in both the desktop and iOS applications.
• Business users can use the Oracle Commerce Experience Manager to drive the page content management
and layout of the search results and category pages.
• Business users can include additional Oracle Commerce storefront elements such as dimensions and
breadcrumbs.
• CRS-IUA and Assisted Selling demonstrate the usage of core Oracle Commerce cartridges.
• CRS-IUA and Assisted Selling deliver multiple Oracle Commerce-specific cartridges that can be leveraged
as-is or extended by customers in their own implementations. These cartridges provide product-supported
integration points in the Oracle Commerce Core Platform and help accelerate development at customer sites.
ASA and Oracle Retail Mobile Point-of-Service Integration
This optional integration lets the ASA application tender a credit card payment or suspend a transaction so that
it can be transferred to a POS terminal in the store, where sale is completed.
Technically, the tender is authorized and transacted by the ORMPOS functionality. In this flow, the fully priced
cart is sent by Oracle Commerce to ORMPOS, which authorizes the transaction, processes the receipt, and sends
the transaction details back to Oracle Commerce. ASA uses a simple manually configured 5% tax calculation for
testing purposes. This is a simple implementation of the atg.payment.tax.TaxProcessor interface which
returns a 5% tax calculation. In a real deployment, the merchant’s chosen tax service would perform the tax
calculation and the order totals, including tax, could then be sent to ORMPOS.
This functionality is installed as a separate client-side module during the CIM installation process. Depending on
the user’s selections in CIM, a set of server side modules are also installed.
The server-side aspects of the ORMPOS integration are encapsulated in the Store.Mobile.DCS-CSR.MPOS and
Store.Mobile.DCS-CSR.MPOS.REST modules, and the client-side pieces are managed through the plugin
manager:
B2CStore/Mobile/iOS/ATGMobileCommon/ATGMobileCommon/Plugin/ATGPluginManager.h
Note that the client-side functionality only appears on the UI when ORMPOS is installed is managed through the
plugin manager.
ASA and Oracle Store Inventory Manager (SIM) Integration
ASA includes a limited integration between the ASA and Oracle Store Inventory Manager (SIM) products,
providing a method for synchronizing the SIM application’s database schema with relevant data from the CRS
2 What is Assisted Selling? 7
application so that the SIM application has knowledge of CRS catalog and store assets. This SIM integration
returns and updates inventory information for SKUs and returns SKU inventory information for SIM buddy stores.
Note: This feature is intended purely for testing and demonstration purposes, and only for use with the CRS
sample data. It is not intended to be used as a general purpose method for synchronization of data between the
ATG and SIM applications, nor does it provide a means to maintain a constant synchronization between CRS and
SIM data once the initial export has completed.
ASA and CRS-IUA iBeacon Functionality
The CRS-IUA app implemented functionality using Apple’s iBeacon technology which can provide a shopper
who has opted-in, promotional or other information when the shopper comes into proximity of an RFID iBeacon
device. See the Apple website for specific details on the Apple iBeacon specification.
For ASA, this implementation alerts ASA when a CRS-IUA opted-in shopper enters a store and provides a method
to let an associate respond to a help request from that shopper. A server side framework provides information
on the beacons encountered and interprets these as unique events.
8 2 What is Assisted Selling?
3 Version Compatibility 9
3 Version Compatibility
For information on supported operating systems, application server versions, JDK versions, and Oracle
Commerce Guided Search versions, see the Oracle Commerce Supported Environments document in the My
Oracle Support knowledge base (https://support.oracle.com/).
10 3 Version Compatibility
4 Installing Oracle Commerce Assisted Selling 11
4 Installing Oracle Commerce Assisted
Selling
Oracle Commerce Assisted Selling is dependent on Oracle Commerce Reference Store and Oracle Commerce
Service Center.
The server module is at CommerceReferenceStore/Store/Mobile/DCS-CSR. The iOS source code is available
in a separate distribution you can find on the Oracle Software Delivery Cloud at:
https://edelivery.oracle.com/.
The CIM Configuration (page 15) section refers to the existing Platform Installation and Configuration Guide to
guide you through the setup and configuration of the server with which the iOS client interacts.
Licensing
Oracle Commerce Assisted Selling Application is provided to you as an iOS workspace file that you may choose
to use as a basic structure for creating your iOS application for your end users. If you choose to create an iOS
application, then you must separately enter into a license and distribution agreement with Apple. You must
complete and sign your finalized iOS application with your own iOS enterprise certificate. You bear all risks
associated with the development of an iOS application.
Platform
The Oracle Commerce Assisted Selling client application is represented by several Xcode projects which are
included in a workspace which the developer launches in Xcode. These projects are built on iOS version 7.1.x
and may be targeted for devices running iOS 7.1 or higher.
Installing the Optional ORMPOS Integration Plugin
During CIM configuration, you can install the ORMPOS integration plugin, which installs additional components
and identifies your Oracle Retail environment.
12 4 Installing Oracle Commerce Assisted Selling
ORMPOS Integration Environmental Requirements
The following are recommended when choosing the optional ORMPOS integration.
• Oracle Retail 14.0.1.1
• Supported Sled : Verifone e335
• Payment Authorizers: AJB (via Sled)
• FIPayEPS is AJB’s integrated payment processing client. This component is responsible for managing
cardholder interaction on the Verifone e335 Sled
• AJB Fipay software version 18220 and VMF Framework 1.0.4.25 are the libraries that are required to be added
to the /OCAssistedSellingiOS/ATGAgentPlugins/Lib directory for Sled integration
Installing the Optional Oracle Store Inventory Manager
Integration Plugin
During CIM configuration, you can install the SIM integration plugin, which installs additional components and
identifies your Oracle Retail environment. Optionally, you can use the SIM Exporter utility to perform a onetime
export of Commerce Reference Store (CRS) data, such as products, SKUs, stores, and inventory levels, to the
Oracle Store Inventory Manager (SIM) application. This utility is intended to support the limited integration
between the ASA and Oracle SIM products.
Oracle Store Inventory Manager Integration
Environmental Requirements
The following is recommended when choosing the optional SIM integration:
Oracle Store Inventory Manager (SIM) 14.1.
Configuration Options
There are several way to configure ASA.
Two Commerce Reference Store Sites
Commerce Reference Store provides two sites in its out-of-the-box configuration: CRS Mobile Home, and CRS
Mobile Store, each with a different skin. (Assisted Selling has only one skin).Assisted Selling provides a site
4 Installing Oracle Commerce Assisted Selling 13
switcher for switching between CRS Store and CRS Home. These sites are also available in Spanish. The German
version is not yet supported by Assisted Selling.
Internationalization
Assisted Selling currently supports Spanish and English, but the traditional Java resource bundle does not
apply to iOS. See the Commerce Reference Store IUA Overview for details on using Localizable.strings to
externalize strings in your iOS code.
Translations for the promotional content items that appear on Assisted Selling’s homepage are not located in
resource bundles, but rather in the Store.Storefront/data/catalog-i18n.xml file, leveraging the same
mechanism used in Commerce Reference Store.
In the associate settings popup, the associate is able to configure the catalog language, which changes the
language of all the strings returned from the Oracle Commerce Platform server. Changing the language in the
iOS Settings app only changes the client-side language.
Assisted Selling, CRS-IUA, CRS-M and Commerce Reference Store
Assisted Selling basically builds on top of what CRS-IUA and Commerce Service Center provides, which builds
on top of what Commerce Reference Store provides. This means that the Assisted Selling client relies in part on
CRS-IUA and the entire server-side structure is dependent on the Commerce Service Center server, including the
multisite setup, form handlers, droplets and so on -- what we do in the server part of Assisted Selling is expose
those things through REST.
Module Dependencies
The root Commerce Reference Store module is the Store module that you see under /
CommerceReferenceStore/Store when you first install the application. This establishes a hierarchy of
module dependency between the root module and the mobile and CRS-IUA/Assisted Selling modules, as shown
in the following figure:
14 4 Installing Oracle Commerce Assisted Selling
Module Dependencies
Learning About Dependencies
The dependencies that any given module has are specified in its MANIFEST.MF file. For example, in the manifest
for Store.Mobile.DCS-CSR we see:
Manifest-Version: 1.0ATG-Client-Class-Path: lib/classes.jarATG-Class-Path: lib/classes.jarATG-Config-Path: config/config.jarATG-Required: @[email protected] REST
Name: lib/classes.jarATG-Client-Update-File: true
This shows that Store.Mobile.DCS-CSR is dependent the module’s root parent’s Mobile module, and is also
dependent on REST, meaning the Store.Mobile and the ATG REST module.
Prerequisites
To install and configure Assisted Selling, first download and install the following products:
• Oracle Commerce Guided Search 11.1
4 Installing Oracle Commerce Assisted Selling 15
• Oracle Commerce Platform 11.1
• Oracle Commerce Service Center 11.1
• Oracle Commerce Reference Store11.1
• Oracle Web Commerce Assisted Selling 11.1
• (Optional) Oracle Retail 14.0.1.1
• (Optional) Oracle Store Inventory Manager (SIM) 14.1
See the Platform Installation and Configuration Guide, the Commerce Reference Store Installation and Configuration
Guide, and the Commerce Service Center Installation and Programming Guide for details.
The following section discusses the options you need to select during setup and configuration after the base
products are installed.
Setup and Configuration
Since Assisted Selling is dependent on Commerce Reference Store, the setup and configuration process for
Assisted Selling is very similar to that for Commerce Reference Store. Defined here are only the installation and
configuration steps that differ from the Commerce Reference Store steps that are detailed in the Commerce
Reference Store Installation and Configuration Guide. Follow all steps in that section for your chosen environment
and add-on options. There are some additional required steps in the Configuring Oracle Commerce Products
section of the Commerce Reference Store Installation and Configuration Guide, where CIM is used for setup. These
steps are:
1. Choosing Guided Search integration.
2. Choosing the Mobile Reference Store Add-On.
In the sections that follow, the steps required to build the Assisted Selling client application are provided.
CIM Configuration
CIM simplifies product configuration by providing scripts that configure Assisted Selling. The scripts allow you to
identify the components used within your environment, as well as to add on additional applications. Using CIM
ensures that all necessary steps are completed and are performed in the correct order.
CIM handles the following configuration steps:
• Creates data sources according to the database connection information you supplied, including those needed
for applications you may add.
• Creates database tables and imports initial data.
• Creates and configures Oracle Commerce Platform application servers, including a dedicated indexing server,
a lock manager, and required loader servers.
16 4 Installing Oracle Commerce Assisted Selling
• Assembles your application EAR files for each Oracle Commerce Platform server, including modules for the
Agent, Production and Data Warehouse load servers, as well as DCS-CSR, Fulfillment and UI modules.
• Deploys EAR files to your application server and allows you to start up the agent-facing, customer-facing and
load servers.
• Allows you to add custom modules.
Refer to the CIM script help and the Platform Installation and Configuration Guide for additional information on
CIM.
To install Assisted Selling using CIM, do the following:
1. Install your application server.
2. Install your application files.
3. To start CIM, go to /home/bin and launch the CIM script:
./cim.sh | bat
1. Select the products you want to install.
2. Select the add-ons that you want to install.
3. Follow the CIM script according to the prompts. You can type H at any prompt for additional information.
Products and Options to Install
Select the following products:
• Oracle Commerce REST
• Oracle Commerce Site Administration
• Oracle Commerce Platform-Guided Search Integration
• Oracle Commerce Service Center
• Oracle Commerce Reference Store
Then select the following Commerce Reference Store AddOns and Mobile Reference store web services:
• Storefront Demo Application
• International
• Fulfillment
• Mobile Reference Store
• REST Web Services for Native Applications
Optional Steps to Install the ORMOS Integration Plugin
The MPOS Integration option appears under the ASA Add-ons section within CIM. ASA functions with or
without ORMPOS Integration.
4 Installing Oracle Commerce Assisted Selling 17
Optional Steps to Install the SIM Integration Plugin
The Oracle Store Inventory Management (SIM) Integration option appears under the ASA Add-ons
section within CIM. ASA can function with or without SIM Integration.
When this option is selected, CIM prompts the user to create a new DataSource that refers to the SIM database
schema. Once this DataSource is created correctly and the user has started the ATG Production instance, they
can initiate a SIM export by navigating to
/atg/commerce/catalog/export/SIMExporter
and invoking the executeExport method. Once execution of the method completes successfully the necessary
CRS catalog information will have been exported to the SIM schema. For more information on the SIMExporter
utility, see the SIMExporter Utility (page 38) section of this document.
Obtaining the iOS Source
The iOS source code is available in a separate distribution you can find on the Oracle Software Delivery Cloud
site, edelivery.oracle.com.
iOS Client Setup
The preceding steps described how to configure the server side Store.Mobile.DCS-CSR module of Assisted
Selling. It is important that Assisted Selling’s iOS client is configured and built through Xcode so that the
configuration matches the server side setup.
To get started, open the AgentWorkspace Xcode Workspace located in the directory where you unzipped the
files, at:
/OCAssistedSellingiOS/AgentWorkspace.xcworkspace
Configuration
To get Assisted Selling up and running in your environment, configure the following Agent-Info.plist
entries:
• ATG_REST_SERVER_HOST is the hostname of the server running the Store.Mobile.DCS-CSR server module
that you wish to connect to.
• ATG_REST_SERVER_PORT is the port number of that server.
Additionally, for a release build intended for production ATG_USE_HTTPS should be set to “YES” in order
to enable SSL. This is strongly recommended and requires additional supporting configuration within your
infrastructure to fully enable SSL.
Use this method of configuration when distributing an app, since the values of the Agent-Info.plist are
used by default until they are manually overridden in the settings bundle.
If you install the optional ORMPOS Integration plugin
The file POSPlugin.plist, which is referred to in the Agent-Info.plist file has entries for:
• The MPOS_SERVER_SETTINGS which configures the locations of the running ORMPOS server, service root,
port number, etc.
18 4 Installing Oracle Commerce Assisted Selling
• The AJB/Payment server settings which configures the location of the running FiPay EPS server (payment
system) with a host and port number, and the connection timeout setting.
• The PLUGINS that you want to register with the PluginManager.
If you install the optional SIM Integration plugin
The Oracle Store Inventory Management (SIM) Integration option appears under a specific section
called ASA Add-ons within CIM. ASA function can with or without SIM Integration.
Settings Bundle
The iOS client includes a settings bundle located at /OCAssistedSellingiOS/Agent/Agent/
Settings.bundle, where is the directory where you extracted the distribution. This bundle manages
server settings, such as ports, host, and Site ID, from the Settings app. This bundle is included in Assisted Selling
for demonstration purposes. Once Assisted Selling is installed on the iOS device, touch Assisted Selling in
Settings and configure the Host and Port server settings to point to your dedicated server.
Use the Settings bundle for configuration when demonstrating the application since you can quickly change
server settings without rebuilding the app and reinstalling. You may want to remove the settings bundle when
releasing an app and use the values defined in Agent-Info.plist.
Build Settings and Related Warnings
ASA was developed for iOS 7.1, in Xcode 5.1. In Xcode 5.1 Apple added arm64 to the default Standard
Architecture build setting. However, 64-bit versions of the libraries required for the optional Sled hardware
integration for swiping a card were not available at the time of implementation and as a result the build settings
for the Agent project were changed from the default (which builds 64-bit binaries) to the setting that builds 32-
bit binaries. In Xcode, you will see many warnings related to this, such as Validate Project Settings and
Update to recommended settings.
If you do not require the Sled integration code, you can remove it and change your build settings back to the
default, standard architecture setting to resolve these warnings.
Third party libraries required for Sled integration
The ASA integration with Sled hardware lets a store associate swipe a credit or debit card using a payment Sled
connected to the iPad device to take payment for an order.
This Sled integration was implemented and tested with AJB software. For information about Oracle’s integration
with the AJB Framework, see the Oracle Retail Point-of-Service Installation Guide.
Note: The third-party AJB libraries are not included as part of ASA. Once you have acquired the AJB libraries:
1. Copy your AJB and VMF frameworks into ATGAgentPlugins/Lib directory.
2. Edit your Config.xcconfig file, appending framework AJB -framework VMF onto the OTHER_LDFLAGS
property.
ASA should now successfully build with these libraries.
5 High-Level Architecture 19
5 High-Level Architecture
At a high level, Assisted Selling consists of three parts that work together to provide remote communication
between server and client:
1. A server module (Store.Mobile.DCS-CSR)
2. An Objective-C REST client that communicates between web services and iOS clients
3. An iOS application that uses both of these components to demonstrate how commerce business logic can be
implemented on a mobile client
The following figure illustrates the components within the server and client in Assisted Selling.
Server and client structure
While the use cases and user experience (UX) design of Assisted Selling are different as those for CRS-M and CRS-
IUA, where the user in ASA is an associate and in CRS-M and IUA, the user is a shopper, many features, such as
the Product Display Page are similar. This allows the reuse of much of the backend configuration. For example,
the same custom mobile form handlers are used by Assisted Selling to provide the same address and credit card
functionality.
The architecture discussion in this document assumes familiarity with concepts related to Apple’s iOS, including
the Objective-C language.
20 5 High-Level Architecture
File and Component Structure
The following is a high-level discussion of the structure of Assisted Selling, which is discussed in greater detail in
the Low-Level Architecture (page 25) section. This high-level structure is shown in the following illustration:
File and Component Structure
Commerce/Guided Search Network Connection
The Commerce/Guided Search Network Connection:
• Contains the low-level network layer.
5 High-Level Architecture 21
• Contains ATG REST code and additional classes for connecting with an Oracle Commerce Assembler.
• Manages network connections, requests, and responses.
• Parses JSON responses into Apple NSObjects of type: NSDictionary, NSArray, NSString, NSInteger, etc.
Common Binding/Manager/Utilities
The Common Binding/Manager/Utilities:
• Contains interfaces for converting objects from NSObjects to typed objects.
• Contains base classes for managers which encapsulate non-(Commerce/Guided Search) specific concepts.
• Common utilities layer for putting non-(Commerce/Guided Search) specific utilities, categories, caching, etc.
• Does not contain UI level code, shared or otherwise.
• Contains style manager, style classes, and style configuration.
ATGMobileClient
The ATGMobileClient contains:
• ATG-specific managers and utilities.
• ATG base model classes.
• Shared UI code (between CRS-IUA and Assisted Selling), and (ATG) generic classes.
ATGAgentClient
ATGAgentClient performs the same basic function as ATGMobileClient, except that it is tailored for the data
returned from the Agent server, and configured to post to the Agent server instead of the Production server.
EMMobileClient
The EMMobileClient contains:
• Oracle Commerce Guided Search specific Managers, Utilities, etc.
• Oracle Commerce Guided Search base model classes.
• UI code and Oracle Commerce Guided Search generic classes.
ATGAgentPlugins (Optional plugin)
The ATGAgentPlugins project facilitates communication between ASA and ORMPOS and contains all the
ORMPOS web service client code. All the UI code will be contained within the Agent project, and all the specific
knowledge of ORMPOS is contained within ATGPOSClient.
The goal of this effort is to make the integration as generic as possible so that Oracle MPOS (ORMPOS) is not the
only MPOS/POS system that could be integrated with ASA.
22 5 High-Level Architecture
ATGPOSRestManager and related files are located in ATGAgentPlugins/POS/Rest directory to facilitate
communication between ASA and ORMPOS. The ORMPOS specific UI code is contained in ATGAgentPlugins/
POS/UI and the classes which initiate web service calls related to the POS integration are located in the POS/
Managers directory (within the ATGAgentPlugins project).
ORMPOS related files are contained within ATGAgenPlugins/POS.
Note: ATGAgentPlugins is intended to be a general purpose plugin not specific to POS related code. In this
release however, the only plugins are POS plugins.
ATGAgentFulfillmentMenuInventoryPlugin (Optional plugin)
There is an ATGAgentFulfillmentMenuInventoryPlugin in ATGAgentClient with these methods:
(void)getStoreInventoryInformationForSkuId:(NSString *)pSkuId success:(void (^) (NSArray *pStores))pSuccess error:(void (^)())pError;(NSString *)cellTitle;
These plugins are displayed in the fulfillment menu on the Product Details Page (PDP).
The two plugins used in ATGAgentPlugins Inventory are:
• ATGInventoryNearByStoresPlugin, which provides the previous “stock levels at nearby stores”
functionality.
• ATGInventorySIMBuddyStoresPlugin, which shows the stock levels for the SKU at the SIM-
configured buddy stores.
UI/Style
The UI/Style contains generic UI classes.
Oracle Commerce Guided Search
The iOS search tab is driven by Oracle Commerce Guided Search.
Shared Code in Assisted Selling
The code shared between CRS-IUA and Assisted Selling is in the ATGMobileClient project, in the
\OCAssistedSellingiOS\ATGMobileClient\ATGMobileClient\UI folder. This folder contains both
code and resources such as nibs and images. This code is accessible from the top-level projects Agent and
ATGMobileStore using this import syntax:
#import
5 High-Level Architecture 23
Resources are built as part of a special target named ATGMobileClientResources. To access these resources
from a top-level project, you must use this resource bundle instead of the main app bundle. To make this easier,
we provide two methods that offer access to this resource bundle:
+ (NSBundle *) atgResourceBundle;
This is part of the NSBundle category NSBundle+ATGAdditions, and is part of ATGMobileClient. It returns
the ATGMobileClientResources bundle, allowing for resources such as nibs to be loaded.
+ (UIImage *)locateImageNamed:(NSString *)pName;
This is part of the UIImage+ATGAdditions category in ATGMobileCommon. locateImageNamed looks for
images in any resource bundle specified in the ATG_RESOURCE_BUNDLES property in the application plist file.
Out of the box, ATGMobileClientResources is the only resource bundle specified in the application plist
files, meaning that the behavior of locateImageNamed is as follows:
• Calls UIImage imageNamed, if the image is found, returns it.
• If no image is found, looks in ATGMobileClientResources. If found, the image is returned, otherwise null
is returned.
The styling framework uses UIImage locateImageNamed and any images specified in the Theme.json file are
found automatically if contained inside ATGMobileClientResources.
Shared Code in Assisted Selling and CRS-IUA
There are two specific areas of shared code functionality:
• The Search and Browse code is shared between the two apps. There are some small differences in how these
features are presented in the two apps, but the actual features are fully shared.
• The Product Details page is shared, but with some differences. The CRS-IUA code presents the ability to
compare products, and to add to wish lists and gift lists, while the Assisted Selling version offers fulfillment
options. The Product Details Page is made up of a number of classes, and the general approach is that base
classes exist in ATGMobileClient, and the top-level projects contain subclasses where product-specific
features can be added.
Other Code Sharing
Assisted Selling and CRS-IUA share code in other areas. The ATG*Manager classes used in CRS-IUA that
are responsible for sending and receiving data to and from the server are re-used where possible. Assisted
Selling has some unique Manager classes, but most of these are subclasses of Manager classes found in
ATGMobileClient used in CRS-IUA. These subclasses simply modify the actors being used, and in some
cases introduce different caching rules. The subclasses may also add extra functionality in some cases, such as
overriding the path to a REST service.
24 5 High-Level Architecture
6 Low-Level Architecture 25
6 Low-Level Architecture
This chapter explores the major components of Assisted Selling in more detail. Information about the optional
ASA and ORMPOS integration appears in the section Low-level Architecture for ORMPOS Integration (page 59).
Store.Mobile.DCS-CSR Server Module
In Assisted Selling, the entire server side structure is dependent on the Commerce Service Center server,
including the multisite setup, form handlers, droplets, etc. By design, the server components of Assisted Selling
are exposed through REST using the Store.Mobile.DCS-CSR server module.
REST Security and AgentLoggedInAccessController
All of the secure REST calls are secured using the access controller AgentLoggedInAccessController, which
ensures that the user making the request is logged in and is an ‘Agent’ with the appropriate permissions.
/atg/rest/userprofiling/AgentLoggedInAccessController
Extending Commerce Service Center web services
Assisted Selling has been designed to extend many of the Commerce Service Center out-of-the-box web
services. For more information on these services, see the REST section of the Web Services Guide.
Form Handler Extensions
These are the form handlers that have been extended for Assisted Selling.
/B2CStore/Mobile/DCS-CSR/src/atg/projects/store/mobile/commerce/csr/order:
26 6 Low-Level Architecture
MobileCSRCartModifierFormHandler.java
MobileCSRPaymentGroupFormHandler.java
MobileCSRShippingGroupFormHandler.java
MobileCSRCancelOrderFormHandler.java
MobileCSRCheckoutFormHandler.java
MobileCSRCartModifierFormHandler.java
CSRCartModifierFormHandler was extended to add a shippingGroupNickname property, so that when
specified, it sets this form handler’s shipping group to the associated value from the shipping group container
map. This allows you to associate a commerce item with a shipping group when adding it to the order. For
example, by setting shippingGroupNickname="Home", the item is added to the “Home” shipping group
contained in the SG map container.
Note that the SG map container must have been initialized with the ShippingGroupDroplet.
MobileCSRPaymentGroupFormHandler.java
CSRPaymentGroupFormHandler was extended to suppress the ORDERAMOUNTREMAINING relationship so that
amounts less than the full invoice amount can be billed to any card, even the default card, without having the
full unpaid amount billed to the default card.
MobileCSRShippingGroupFormHandler.java
CSRShippingGroupFormHandler.Mobile was extended to allow you to apply shipping methods to by
shipping group ID.
MobileCSRCancelOrderFormHandler
The MobileCSRCancelOrderFormHandler extends CSRCancelOrderFormHandler to prevent a new order
from being created when an order has been cancelled.
MobileCSRCheckoutFormHandler
This class provides the same checkout functionality used by the Mobile CSR client, specifically, it ensures that
store credits are not automatically applied to an order that is checked out from ASA and only applying those
6 Low-Level Architecture 27
credits during checkout. It also specifies the state that an order should be set to during checkout and clears out
any existing payment groups that may be on the order in preparation for the checkout process.
REST Actors in Assisted Selling and their Structure
Like CRS-IUA, Assisted Selling encapsulates the REST configuration and customizations required for
communication between iOS applications and Oracle Commerce Platform server in JSON format. In Assisted
Selling, these extensions or configurations would be in the Store.Mobile.DSC-CSR module which depends on
Store.Mobile.REST module.
REST actors specific to the optional ORMPOS Integration are found in Store.Mobile.DCS-CSR.MPOS.REST.
For more information, see Low-level Architecture for ORMPOS Integration (page 59).
See the Commerce Reference Store IUA Overview for more information on the implementation of REST.
Learning about Actor Chains in Assisted Selling
You can learn more about how actors are used in Assisted Selling by examining the registry which configures
and enables all of the actors used by the apps.
Assisted Selling actors are registered here:
/atg/rest/registry/ActorChainRestRegistry
There is a properties file for this in Store.Mobile.DCS-CSR for the Assisted Selling app and one in
Store.Mobile.REST module for CRS-IUA.
A wealth of information about actors in your environment is available through the Dynamo Server Admin
browser view. Start by viewing the filtering configuration, which determines which properties output for each
component or repository item by using this URL, modified for your domain and configuration:
http://servername:serverport/dyn/admin/nucleus/atg/dynamo/service/filter/bean/XmlFilterService/
http://servername:serverport/dyn/admin/nucleus/atg/dynamo/service/filter/bean/XmlFilterService/http://servername:serverport/dyn/admin/nucleus/atg/dynamo/service/filter/bean/XmlFilterService/
28 6 Low-Level Architecture
Dynamo Server Admin browser view
Use this URL to view a list of registered actors:
http://servername:serverport/dyn/admin/nucleus/atg/rest/registry/ActorChainRestRegistry/?propertyName=registeredUrls
The list of registered actors is shown in the following illustration.
6 Low-Level Architecture 29
Dynamo Server Admin browser view – components
Then you can view a particular actor to see the available chains:
http://servername:serverport/dyn/admin/nucleus/atg/userprofiling/ProfileActor/
The browser view of actors and available views is shown in the following illustration.
30 6 Low-Level Architecture
Dynamo Server Admin browser view – Actor Chains
For example, for products:
http://servername:serverport/dyn/admin/nucleus/atg/commerce/catalog/ProductCatalogActor/?chainId=getProduct
The browser view of product actor catalog is shown in the following illustration.
6 Low-Level Architecture 31
Dynamo Server Admin browser view – Actor Catalog
Configuration Unique to Assisted Selling
There is an additional layer of configuration Assisted Selling which is captured in this file:
/atg/dynamo/service/filter/bean/beanFilteringConfiguration.xml
These configurations help return only the data that is relevant to the Assisted Selling app.
Filtering
You can use filter IDs with Assisted Selling actors to control how Assisted Selling data is returned. One filtering
approach is to layer in properties on top of those defined in Store.Mobile.REST in Store.Mobile.DCS-
CRS, using the same filter IDs, since properties added in Store.Mobile.DCS-CSR are only be added on the
Agent server. Also, since the same model objects are used on the client, it is helpful to have the same base
configuration.
Objective-C REST Client
The basic configuration of the REST client in Assisted Selling is the same as in CRS-IUA. See the Commerce
Reference Store IUA Overview for more information.
32 6 Low-Level Architecture
Objective-C JSONPath
The use of the Objective-C JSONPath in Assisted Selling is the same as in CRS-IUA, and is only used in places that
are common between CRS-IUA and Assisted Selling. See the Commerce Reference Store IUA Overview for more
information.
JSON Parsing
The basic use of JSON parsing in Assisted Selling is the same as in CRS-IUA. See the Commerce Reference Store IUA
Overview for more information.
Oracle Retail Store Inventory Management (SIM)
Integration
The following section details the design of the Oracle Commerce Inventory Managers to integrate with
Oracle Retail Store Inventory Management (SIM) . For more information on the Oracle Retail Store Inventory
Management product, see the Oracle Retail Store Inventory Management (SIM) Integration (page 32).
SIM Commerce Sub-Module
During installation, you can optionally create a SIM plugin module. This sub-module leverages the existing ASA
module to provide integration with SIM:
Store.Mobile.DCS-CSR.SIM
This sub-module contains classes and configurations for ASA’s integration with SIM.
CIM Configuration
During CIM configuration, you can select the SIM Integration add-on, which disables inventory updates when
the MPOS integration is also selected.
Importing ATG Data to SIM
A nucleus component populates the database tables used by SIM with data from your ATG repositories.
Nucleus Component Data
ProductCatalog Products, skus
6 Low-Level Architecture 33
Nucleus Component Data
LocationRepository Stores
SwitchingInventoryManager
The SwitchingInventoryManager component determines which InventoryManager to use
in ASA. If a location is not specified, the existing StoreInventoryManager that extends the
RepositoryInventoryManager is used. When a specific location is used and the inventory at a specific
location is requested, the SIMInventoryManager is used.
An example configuration:
# /atg/commerce/inventory/InventoryManager.properties$class=atg.projects.store.mobile.inventory.SwitchingInventoryManager
# in-store items will use the new SIMInventoryManagerinStoreInventoryManager=/atg/.../SIMInventoryManager
# online items will use the existing atg.projects.store.inventory.StoreInventoryManager componentonlineInventoryManager=/atg/.../RepositoryInventoryManager
A coding example:
LocationInventoryManager determineInventoryManager(String pID, String pLocationID) { // if a location is specified, use the SIMInventoryManager if (pLocationID != null) return getInStoreInventoryManager(); // no location specified means the item is being shipped from the "online warehouse" // return the return getOnlineInventoryManager();}public int purchase (String pId, long pHowMany, String pLocationId) { return determineInventoryManager(pId, pLocationId()).purchase(pId, pHowMany, pLocationId);}
SIMInventoryManager
The SIMInventoryManager makes SOAP web service requests to the SIM server, using the Java stubs
generated from the WSDL file.
SIM Server properties include:
Name Description
simServerHost The SIM server host name.
simServerPort The SIM server port
34 6 Low-Level Architecture
InventoryManager Methods
The following InventoryManager methods are implemented:
Method name Purpose Returns
queryAvailabilityStatus Returns the availability
status of a given item.
If requestAvailableInventory(pId,
pLocationId) > 0, return in stock else,
return out of stock
queryStockLevel Returns how many of
a given item are in the
system
returns
requestAvailableInventory(pId,
pLocationId)
SIM web service request methods
The following SIM web service request methods are implemented:
Method name SIM web service invoked Returns
requestAvailableInventory lookupAvailableInventory available_qty
requestInventoryForBuddyStores lookupInventoryForBuddyStores InventoryInfo[]
which contains
locationId, skuId
and methods to
return the stock
level
Other methods
Method name Parameters Description
lookupExternalIdForLocationId location ID Looks up the location ID in the location
repository, and returns its external ID for use by
SIM web service requests
SIM Webservices used by SIMInventoryManager
StoreInventoryService is a real-time inventory availability lookup facility is provided by SIM that can be
used by external systems, such as an online order capture (OOC) application and an order management system
(OMS), to retrieve item and location inventory based on SIM’s view of inventory at a point in time. You can use it
to lookup several items at one time and determine the locations the items.
6 Low-Level Architecture 35
SIM StoreInventory Web Service
Web service method Description Notes
lookupAvailableInventory Retrieves inventory
information for multiple items
at multiple locations. Only
transaction-level items are
processed and only current
inventory is returned.
Retrieves the available
quantity of an item at a
store. Fetches inventory
for a single item at a single
location since that is what
our InventoryManager
interface supports.
lookupInventoryInStore is
not used since it returns more
data than required.
lookupInventoryForBuddyStores Retrieves the inventory
information for items within a
group of buddy stores.
36 6 Low-Level Architecture
SIMInventoryActor
The SIMInventoryActor exposes the SIM buddy store feature. In SIM, buddy stores are stores within the same
transfer zone that frequently transfer items between stores. You configure which of your stores are considered
buddy stores in SIM.
Actor chain Parameters Returns Description
lookupInventoryForBuddyStoresSKU ID, store/
location ID
Available
inventory
for specified
SKU at each
buddy store of
specified store/
location
Invokes
requestInventoryForBuddyStores
on SIMInventoryManager
Inventory Updates
POSTransactionService
POSTransactionService is a near real time SIM service that accepts the sales and order information from the
POS or any external system. When the POS system invokes this service, it validates minimum information and
uploads the data into staging tables for processing the transactions and updating the inventory in SIM.
SIM POSTransaction Web Service
processPOSTransactions
processPOSTransactions are summarized in the following tables.
6 Low-Level Architecture 37
PosTrnDesc
Parameter Description Value/Notes
store_id The identifier of the store that is source
of the transaction
The store’s external ID
transaction_id The identifier of this Point-Of-Sale
transaction.
ATG order ID
transaction_timestamp Date and time of the transaction The submitted date of order
cust_order_id External customer order id. Required for customer order
related transactions
cust_order_comment Customer order comments
PosTrnItem
Parameter Description Value/Notes
item_id SKU number
Quantity Quantity of the item.
unit_of_measure Unit of measure of the
quantity
The unit of measure returned from the web service.
Examples of units of measure are pounds, kilograms,
quarts, bunches, yards, or feet. The quantity returned
is a measurement in the unit of measure. For example,
a quantity of 5 and unit of measure of feet is “5 feet”.
Optionally, EA (or eaches) indicates the quantity is in
number of units.
uin Universal identification
number.
reason_code Reason code associated
with this line item. .
Required when non-sellable sub-level inventory
tracking is active.
drop_ship True if this item is drop
ship, false if it is not. Drop
ship sales will not impact
stock.
comments Comments
fulfill_order_id External fulfillment order
id, if transaction is a
customer order.
38 6 Low-Level Architecture
Parameter Description Value/Notes
reservation_type Reservation type if item is
for a customer order.
Valid values are WEB_ORDER, SPECIAL_ORDER,
PICKUP_OR_DELIVERY, LAYAWAY, NO_VALUE
transaction_code A code that indicates the
transaction event that
took place on the item.
Valid values are SALE, RETURN, VOID_SALE,
VOID_RETURN, ORDER_NEW, ORDER_FULFILL,
ORDER_CANCEL, ORDER_CANCEL_FULFILL
InStoreSaleFulfiller
When orders that contain InStoreSaleShippingGroups are checked out, they are automatically fulfilled since
the item has been given to the customer. ASA invokes the SIM webservice to update the inventory.
ORMPOS, SIM, and SKUs
Oracle Retail MPOS (ORMPOS) expects SKU ids to be in uppercase when it interacts with SIM, and if lowercase
SKU ids are used, inventory items may not be correctly updated.
SIMExporter Utility
This SIMExporter utility can perform a onetime export of Commerce Reference Store (CRS) data, such as
products, SKUs, stores, and inventory levels, to the Oracle Store Inventory Manager (SIM) application. This
utility is intended to support the limited integration between the ASA and Oracle SIM products. As part of this
integration we will provide a method for synchronizing the SIM application’s database schema with relevant
data from the CRS application so that the SIM application has knowledge of CRS catalog and store assets.
Specifically, so that SIM returns and allows updates of inventory information for SKUs, returns SKU inventory