commerce reference store - oracle...crs-iua components of the guided search integration, it is...

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


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:


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


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


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


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.


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


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


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


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.

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


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/


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.


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.


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.


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.


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


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


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.


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.


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.


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


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.



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

commerce reference store - oracle...crs-iua components of the guided search integration, it is...

Documents